# lodesong docs

> How to run lodesong next to Navidrome, use it, bring a Spotify library over with Lyterion, and build on its API.


- **start here**
- [Start to finish](/docs): From nothing to the whole setup: your music on your own server, a player that feels like Spotify on every computer you use, your Spotify library brought over, and the song in your Mac's notch. Each step links to the page with the details; this one is the route.
- [Getting started](/docs/getting-started)
- [Self-hosting](/docs/self-hosting)
- [Configuration](/docs/configuration): Everything is an environment variable. Only NAVIDROME_URL usually needs setting. A bad value stops the server at boot with a message naming the variable.
- Deploy
  - [Deploy](/docs/deploy): lodesong is one container (ghcr.io/findmalek/lodesong, amd64) that needs to reach your Navidrome. It keeps its state in one volume at /data, runs as an unprivileged user and works with a read-only root filesystem.
  - [Dokploy](/docs/deploy/dokploy)
- [Troubleshooting](/docs/troubleshooting): First stop: https://<your lodesong>/api/health. It says, per configured server, whether lodesong reaches it, how fast, and what it is.

- **using it**
- [Devices](/docs/devices): Every open lodesong of yours (a tab, another browser, another computer) joins one playback session, like Spotify Connect. One of them plays; the others are remotes.
- [Your phone](/docs/sync): lodesong and Arpeggi share one thing on the server: the Subsonic play queue (what's queued, which song is current, and how far into it). Each browser saves under its own client name, lodesong@<id>, so the app can tell its own saves from the phone's.
- [iPhone app](/docs/ios)
- [Android app](/docs/android)
- [Linux and Windows](/docs/desktop)
- [Listen together](/docs/listen-together): One person hosts, others on the same Navidrome server follow. Open the menu under your name → listen together.
- [Mixes](/docs/mixes): Everything here is made from your library and what you play in lodesong, and saved as ordinary Navidrome playlists, so your phone and every other Subsonic app have them too.
- [Search](/docs/search): ⌘K (or /) opens search from anywhere; ↵ on a result plays it, ⌘↵ opens the full results page.
- [Lyrics](/docs/lyrics): The lyrics panel (y), full-screen view (⇧F) and lyrics search all use the same lyrics, found in this order:
- [Shortcuts](/docs/shortcuts): Press ? in the app for this list, searchable, with what applies right now highlighted. Every shortcut can be rebound there (pencil icon); a rebound key shows everywhere the app shows the key.

- **your library**
- [Lyterion](/docs/lyterion)
- [Spotify import](/docs/spotify-import): Rebuild your Spotify playlists and liked songs from a Spotify data export. Settings → library → import from spotify (or /import).

- **building on it**
- [API](/docs/api): Everything the player does is one API, typed end to end: the procedures are defined once in packages/orpc (Zod schemas for every input and output), the server implements them, and the player calls them through a client typed from the same definitions.
- [Architecture](/docs/architecture): In production the web app is bundled, minified and precompressed (brotli, gzip) and embedded in the executable with the server (scripts/build.ts). The image is that executable on Alpine, multi-arch. - Devices (devices.ts): one in-memory hub per account over WebSockets (/api/devices): which device plays, its last state, commands from remotes routed to it, transfers. The remote API (remote.ts, /api/remote/) reads it with a Bearer session for the terminal mods. - Mixes (mixes.ts): daily mixes, discover weekly and the daylist from your plays (matched to the library by artist and title) and the index, seeded per day so every device gets the same picks. - Prompt playlists (ai-playlist.ts): a catalog of your artists to Groq, artists back, the list built from songs you own.
- [Security](/docs/security): lodesong is a thin client in front of your Navidrome. The server in this repo (apps/api/src) is the only thing that talks to Navidrome, and the browser never sees a credential.
- [Demo library](/docs/demo-library): A copyright-free library for screenshots, previews and trying the player without your own music. Everything is generated: synthesized tracks (small generative pieces), dithered monochrome covers, tags, some synced lyrics and a few playlists. It is deterministic, so the same seed gives the same library.
- [Previews](/docs/previews): Every pull request from this repo gets one, like Vercel: a build of the PR's player at player-pr-<n>.<PREVIEW_DOMAIN> (its API reference at /api), and one sticky comment on the PR (edited in place, never a new one per push): building as soon as the PR opens, deploying, ready or failed, with the build log, the Dokploy deploy log and, once it's up, the Preview link. Closing the PR deletes the app and marks the comment as deleted. The site (apps/web) is hosted on Vercel, which previews it on every PR with a comment of its own.
- CI
  - [Self-hosted runner](/docs/ci/self-hosted-runner): GitHub-hosted runner minutes are exhausted, so CI jobs run on the-keep itself. GitHub still schedules workflows and stores logs; the runner executes the jobs.
  - [Runner performance](/docs/ci/runner-performance): Blacksmith and other premium runners win on three things: bare-metal cores, fast NVMe storage, and aggressive caching. A homelab runner can match or beat them if you optimize the same three axes.