Skip to content
zorcererPublic

About

Server-rendered music player for Navidrome/Subsonic and Jellyfin libraries

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

10 stars

Watchers

0 watching

Forks

Latest commit

 

History

638 Commits

Folders and files

Repository files navigation

Heddohon, a self-hosted music player for Navidrome, Subsonic and Jellyfin

Release Build Docker pulls License

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.

What it does differently

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).

Also

  • 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.

Quick start

git clone https://github.com/zorcerer/heddohon.git && cd heddohon
docker compose up -d
docker compose logs heddohon

The 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.

Install on Unraid from Community Applications

FAQ

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.

Documentation

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.

AI disclosure

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.

License

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.

Support Heddohon on Ko-fi

About

Server-rendered music player for Navidrome/Subsonic and Jellyfin libraries

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

10 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages