bvandeusen
fb95a462fb
Four related fixes to the player flow that together remove the audio↔UI lag on track change: 1. **Prefetcher pre-warms covers + palette for the next N tracks.** The existing prefetcher pinned audio files only. When auto-advance landed on the next track, the cover bytes were cold → mediaItem broadcast with artUri=null → now-playing screen stalled in _scheduleSwap awaiting precacheImage of a file that didn't exist yet. Each upcoming queue item now also fires AlbumCoverCache.getOrFetch (writes bytes to disk so _toMediaItem's peekCached returns the path) and AlbumColorCache.getOrExtract (memoizes the dominant color). Both fire-and-forget; idempotent if already cached. 2. **AlbumColorCache.peekColor sync getter** so the now-playing fast-path can read the memoized color without awaiting a Future. 3. **_scheduleSwap fast path** when cover bytes + palette are already cached (the common in-queue auto-advance case): commit _displayedMedia / _displayedDominant synchronously in setState without awaiting. The async preload remains as the slow-path fallback for genuine cold cache. This is what closes the gap the user reported: "art is loading and metadata hasn't updated but the new song is playing." 4. **setQueueFromTracks: build source before broadcasting queue / mediaItem.** Previously we broadcast immediately for snappy UI; if _buildAudioSource threw, the UI showed the new track while the player held the old source. Now: build first, broadcast only on success. Source build is sub-100ms on warm cache so the tap response cost is imperceptible. _suppressIndexUpdates is set around setAudioSources + broadcast so a transient currentIndex emission can't cross-broadcast the OLD queue's entry at the NEW index. 5. **playbackEventStream error handler skips past failing tracks.** Previously errors only logged. The player would go silent on a 404 / decoder failure but mediaItem stayed on the failed track — user saw "now playing X" with no audio. Now seekToNext on error; if at queue tail, pause cleanly so PlaybackState reflects idle.
Minstrel
A self-hosted music server that thinks for you. Smart shuffle, contextual likes, ListenBrainz-aware radio, and Lidarr automation — server-side, so every client (web, mobile, Subsonic third-party) gets the same intelligence.
State and intelligence belong on the server, not the client.
Highlights
- OpenSubsonic-compatible. Existing Subsonic clients (DSub, Symfonium, play:Sub, etc.) connect with no special configuration.
- Server-side smart shuffle. Track-similarity vectors, dual-like model (general + contextual), and session memory keep mixes coherent across devices.
- ListenBrainz radio. Session-aware "more like this" pulls from ListenBrainz similarity data, not a static genre tag.
- Lidarr integration. Triggered scans, request-driven album imports, and a quarantine flow when something doesn't fit.
- Built-in web SPA. Full-feature library, search, queue, playlists, and admin — no separate frontend container to deploy.
- Flutter mobile client in flight. Tracking issue #356.
Quickstart
# compose.yaml
services:
minstrel:
image: git.fabledsword.com/bvandeusen/minstrel:latest
ports: ['4533:4533']
volumes:
- ./music:/music:ro
- minstrel-data:/data
environment:
MINSTREL_DATABASE_URL: postgres://minstrel:minstrel@db:5432/minstrel?sslmode=disable
MINSTREL_LIBRARY_SCAN_PATHS: /music
depends_on: [db]
db:
image: postgres:17
environment:
POSTGRES_USER: minstrel
POSTGRES_PASSWORD: minstrel
POSTGRES_DB: minstrel
volumes: [pgdata:/var/lib/postgresql/data]
volumes:
minstrel-data:
pgdata:
docker compose up -d
After the stack is up, visit http://localhost:4533/register and create your admin account. The first user to register on a fresh instance is automatically marked as the administrator; subsequent users can register through the same form (or via invite tokens generated from the admin Users panel, depending on how you configure registration).
For the full configuration surface, see config.example.yaml.
Configuration
Most operators only need the env vars in the quickstart above. A few extras worth knowing:
MINSTREL_BRANDING_APP_NAME— rename the instance ("Family Jukebox", "Office Music"). Surfaces in the header, browser tab, and OG share previews.MINSTREL_STORAGE_DATA_DIR— defaults to./data. Holds playlist cover collages and other generated artefacts.MINSTREL_LIBRARY_SCAN_PATHS— colon-separated list of music library roots to scan. Supports multiple roots (/music:/podcasts).
ListenBrainz integration (per-user scrobble + similarity tokens) and Lidarr integration (URL + API key) are configured through the admin Settings UI rather than env vars or yaml — per Minstrel's "config in UI" rule, integration settings live where operators can edit them without restarting.
Most operational keys have a MINSTREL_<SECTION>_<FIELD> env override. Recommendation and events tuning are yaml-only. See config.example.yaml for the authoritative surface.
Updating
:main— rolling, follows the dev branch's tested tip. Recommended only for the operator who's running an upstream-watching deployment.:v1.0.x— pinned releases. Recommended default. Database migrations run automatically at startup; rollbacks require restoring a Postgres dump.
Specs
Authoritative scope lives under docs/:
- Server spec — current implementation focus.
- Client spec — Flutter companion app.
Development
Two concurrent dev processes:
- Backend:
docker compose up— Postgres + Minstrel on:4533. - Frontend:
cd web && npm install && npm run dev— Vite dev server on:5173with HMR. The Vite server proxies/api/*and/rest/*to:4533so session cookies work.
Production build
docker build -t minstrel . runs the SvelteKit build inside a node stage, copies the output into the golang stage, and //go:embeds it into the final binary. The container serves the SPA from / alongside the API surfaces; no separate static-file server is required.
Branches
- Day-to-day work happens on
dev(or feature branches merged intodev). mainis protected — changes land via PR fromdev.- Releases are cut by tagging
v*offmain; the release workflow builds and pushes the container image to the Forgejo registry.
Task and milestone tracking: Fable (Minstrel project, id 12).
License
See LICENSE.