joshuafhigginsandClaude Opus 5.5 Verified f8e5dc7325 feat(desktop): ship the web UI as a static export
The static export now works away from the oTunes server. It picks a
server at /server (saved in localStorage), connects Convex to it, and
loads covers, avatars and streams from it. Streams and avatars pass the
session token as a `token` query parameter, which the song and avatar
routes accept alongside the cookie. The server allows any origin on /api.

Electron serves that export from 127.0.0.1:47836 and drops the bundled
Next.js server, the media gateway, symlink materializing and Sharp
pruning. The same export can ship in a Tauri app.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
f8e5dc7325 · 2026-11-20 00:15:35 -05:00
257 Commits
2026-11-03 14:30:38 -05:00
2026-06-14 14:19:07 -04:00
2026-05-29 23:13:32 -04:00
2026-06-14 14:19:07 -04:00
2026-06-14 14:19:07 -04:00
2026-11-03 14:30:38 -05:00

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/desktop apps/desktop Electron client for Windows and Linux
@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

Desktop builds

See the desktop build guide to package the web player for Windows or Linux. The UI is bundled locally, and users choose their oTunes server before signing in.

S
Description
No description provided
Readme
28 MiB
0 Stars 1 Watchers 0 Forks
Languages
TypeScript 90.4%
Swift 5.5%
JavaScript 2.1%
Kotlin 0.5%
Dockerfile 0.5%
Other 0.9%