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:v1.0.0
    ports: ['4533:4533']
    volumes:
      - ./music:/music:ro
      - minstrel-data:/data
    environment:
      SMARTMUSIC_DATABASE_URL: postgres://minstrel:minstrel@db:5432/minstrel?sslmode=disable
      SMARTMUSIC_LIBRARY_ROOT: /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

Open http://localhost:4533 and complete the first-run admin setup.

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:

SMARTMUSIC_BRANDING_APP_NAME — rename the instance ("Family Jukebox", "Office Music"). Surfaces in the header, browser tab, and OG share previews.
SMARTMUSIC_STORAGE_DATA_DIR — defaults to ./data. Holds playlist cover collages and other generated artefacts.
SMARTMUSIC_LISTENBRAINZ_TOKEN — enables ListenBrainz scrobble + similarity. Per-user tokens override the server default in Settings.
SMARTMUSIC_LIDARR_URL / SMARTMUSIC_LIDARR_API_KEY — Lidarr integration. Configure once at the server level; per-user request flows are exposed in the admin UI.

Every yaml key has an equivalent env var (SMARTMUSIC_<SECTION>_<FIELD>). See config.example.yaml for the full list.

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 :5173 with HMR. The Vite server proxies /api/* and /rest/* to :4533 so 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 into dev).
main is protected — changes land via PR from dev.
Releases are cut by tagging v* off main; 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.

4.2 KiB Raw Blame History