Reads lyrics tags (plain, LRC, word-timed LRC) during library scans and backfills songs scanned before. Search matches lyric lines, and the players show synced lyrics on web, phone, and tablet. Downloaded songs read lyrics from their own file. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
oTunes
Your music, my music, our music. Self-hosted music streaming app and server.
Monorepo
This project uses pnpm workspaces:
| Package | Path | Description |
|---|---|---|
@otunes/web |
apps/web |
Next.js web app |
@otunes/mobile |
apps/mobile |
Expo React Native mobile app |
@otunes/convex |
packages/convex |
Shared Convex backend and client types |
Development
Install dependencies from the repository root:
pnpm install
Run the web app:
pnpm dev
# or
pnpm dev:web
Run the mobile app:
pnpm dev:mobile
Run the Convex backend (from the shared package):
pnpm dev:convex
Point the dev deployment at your music folder (it defaults to /data):
cd packages/convex && npx convex env set DATA "/path/to/Music"
Other commands:
pnpm build # build web app
pnpm lint # lint all packages
pnpm typecheck # typecheck all packages
pnpm format # format with Prettier
Hosting with Docker
The image runs both the web app and its Convex backend, so there is nothing to configure. Here's an example docker-compose.yml:
name: music
services:
otunes:
image: git.abunchofknowitalls.com/joshuafhiggins/otunes:latest
ports:
- "3000:3000" # web app
- "3210:3210" # Convex
volumes:
- ./otunes-data:/convex/data
- /SomeAttachedStorage/Music:/data
stop_grace_period: 10s
restart: unless-stopped
Change /SomeAttachedStorage/Music to the folder containing your lossless, normal, and atmos libraries, then run docker compose up -d. The first account you create becomes the admin.
On first boot the container generates its own Convex instance secret and sign-in keys and stores them in ./otunes-data, so no two installs share secrets. Back up that folder: it holds your database and keys.
Reverse proxy
The web app finds Convex from the address you open it at:
| You open | Convex is expected at |
|---|---|
https://music.example.com |
https://convex.music.example.com |
http://192.168.1.5:3000 or http://localhost:3000 |
port 3210 on the same host |
So for a domain, point music.example.com at port 3000 and convex.music.example.com at port 3210 (WebSockets must be allowed). The mobile app uses the same convention.
If Convex has to live somewhere else, set PUBLIC_CONVEX_URL on the container to its public URL.
Downloads
Check the releases tab for the latest downloads for apps: Releases