Note
dev is unreleased work; releases are on main.
The :dev image is built from dev daily and can break. Use
docker-compose.dev.yml, which keeps its data apart.
Heddohon is a web music player you host yourself, in front of the Navidrome, Subsonic or Jellyfin server you already run. Screenshots and a tour are on heddohon.app.
Your music server stays private. The browser only talks to Heddohon, which fetches every byte from the music server and keeps the credentials on the server. The music server needs no public address.
Listen together, like a Spotify Jam. Send a link, and everyone who opens it hears what you play, as you play it, in their own browser and without an account. Friends with an account on your music server can add tracks to the shared queue.
Share a song, an album or a playlist with anyone. The link plays the original file without an account, until it expires or you withdraw it.
Your listening, kept on your server. Every play is recorded: top artists and albums, the hours you listen, what you played on this day in earlier years, and daily mixes made from it.
One player across your devices. The queue and settings follow the account, and one browser can control another.
Play anything from the keyboard. In Terminal, Cmd+K or Ctrl+K opens a
command line: play and the name of an album, an artist or a song starts the
best match. Queueing, mixes,
seeking and the volume work the same way. cd goes to a page or a section of
Settings (cd settings/security), and eq sets the equaliser (eq bass).
Four themes, coloured by the artwork. Terminal, Liquid, Paper and Phosphor, and colour schemes for any of them from files an administrator adds (Configuration).
- Original files up to FLAC 24/192, or transcoded to MP3, Opus or AAC.
- Crossfade, ReplayGain, a sleep timer and an equaliser with AutoEq headphone corrections.
- Synced lyrics, instant mixes, internet radio, and casting to Chromecast and AirPlay.
- Scrobbling to Last.fm and ListenBrainz.
- Two-step sign-in with an authenticator app or passkeys, and single sign-on through an OpenID Connect provider (Authelia, Authentik, Keycloak, Pocket ID).
- Desktop apps for Linux and Windows, and an experimental Android app (Android 14 and later).
- AI assistants that speak MCP, such as Claude Code.
git clone https://github.com/zorcerer/heddohon.git && cd heddohon
docker compose up -d
docker compose logs heddohonThe log shows a setup code. Open http://localhost:3000, enter the code and
the address of your music server, and sign in with your account on it.
SETUP.md has the rest in order: moving the secret out of the data directory, and putting Heddohon on the internet behind a reverse proxy.
Configuration by environment variables, Unraid, running without Docker, and the image tags are in Configuration. The Android app is on each release, and Obtainium keeps it updated.
Does Heddohon replace Navidrome or Jellyfin?
No. It is a player in front of the music server you already run, which keeps the library: scanning, tags, users and what each user may see. Heddohon adds the player, sharing, listening together and the history around it.
Will it change my music files or my library?
No. It reads music through the music server's API, as any player does, and never writes tags, file names or ReplayGain values back. What it keeps (your settings, queue and listening history) is in its own database.
Does my music server have to be on the internet?
No. The browser only talks to Heddohon, which fetches every byte from the music server itself, so the music server can stay on your home network. Only Heddohon needs an address you can reach, and only if you listen away from home. SETUP.md covers putting it behind a reverse proxy.
Is my music server password safe?
It is kept on the Heddohon server, never in the browser, sealed with AES-256-GCM under a key derived from your secret. A copy of the database alone opens no account. SECURITY.md has the threat model and the audits.
Can I use Navidrome and Jellyfin at the same time?
Yes. Give Heddohon the address of each, and the sign-in page asks which one to sign in to. Each account uses its own server.
Is there an app for my phone?
On iPhone and iPad, open Heddohon in Safari and add it to the home screen: it runs full screen, as an app. On Android there is an experimental app for Android 14 and later on each release, and desktop apps for Linux and Windows. See Apps.
Does it transcode?
It plays the original file by default, up to FLAC 24/192. You can ask the music server to transcode to MP3, Opus or AAC instead, to save data on a slow connection; the music server does the transcoding, not Heddohon.
Do the people I share with need an account?
No. A shared link plays in any browser until it expires or you withdraw it, and anyone with a listen-together link hears what you play without signing in. Adding songs to a shared queue needs an account on your music server.
| Setup | Starting it, the setup page, and putting it on the internet |
| Configuration | Environment variables, reverse proxies, PostgreSQL, Unraid |
| Apps | The desktop and Android apps |
| Security | Threat model, known gaps, reporting a vulnerability |
| Contributing | Reporting bugs, suggesting features, and sending pull requests |
More in the wiki: audio, architecture and design notes.
Written with agentic assistance from Claude. The code and security posture have been reviewed by me and by multiple AI-assisted audits, documented in SECURITY.md.
MIT. Music and covers in the header image: Stellardrone, Light Years (CC BY 3.0); Lezet, Accumulation (CC BY 3.0); Grove of Whispers, The Sheltering Sky and Vast (CC BY 4.0); and the unfound88 compilation happy in novi sad (CC BY 4.0).
The animated controls in src/lib/components/bits/ are from
Svelte Bits by David Haz, under the MIT licence with
the Commons Clause (its text): they come
with Heddohon, and may not be sold or passed on by themselves.
