Skip to content
catalystcommunityPublic

About

Turn a local music collection into an internet jukebox experience

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Ichoi

Ichoi is a music player, library manager, and distributed jukebox server. One executable runs your library, streams to browsers and native clients, and turns speakers on other machines — a Raspberry Pi in the kitchen, a tablet by the door — into shared, controllable playback targets that anyone you permit can queue music to.

It is deliberately not a Subsonic clone. Ichoi has no passwords (identity is LinkKeys, or login-less on a trusted LAN), a real capability-negotiated media pipeline, and a CSIL-native API — the web UI, native apps, and satellites all speak the same transport. See docs/DESIGN.md for the full architecture and the reasoning behind every decision, and CONTRIBUTING.md for working conventions.

Status: design. The architecture is settled; implementation is in progress.

What it does

  • Streams full-quality or transcodes on demand. The client always runs the same Symphonia decoder; the core sends original packets (direct mode) or re-encodes to AAC-LC / MP3 (transcoded mode) based on what each consumer negotiates — bitrate cap, codec, or an undecodable source (Opus, HE-AAC). Transcoding shells out to a bundled static ffmpeg; it is never linked.
  • Distributed jukebox. Satellites connect out to a core and register their outputs as shared targets. Control and audio travel back down the connection the satellite opened, so NAT'd Pis just work. The core never connects to a satellite.
  • Multi-server clients. One client can browse several servers at once and, when permitted, copy albums and playlists between them (never delete).
  • Browser-first, served by the same binary over a WebSocket carrier, with a Symphonia→WASM decoder. Firefox is first-class. Themeable, i18n + a11y from day one.
  • Gapless, sample-accurate playback with time-based seeking.

The three roles

All three use the same source and command interface. Linux core and satellite releases use different libc build targets.

Role What it is
core Owns the library, database, ffmpeg, and TLS keys. Serves the API, indexes and transcodes, coordinates jukebox state, accepts client-mediated imports. May own local outputs.
satellite A dumb output node (typically a Pi). Connects out to one core, registers its speakers as shared targets, plays AAC-LC. No library access.
client A browser or native app carrying a LinkKeys identity. Browses one or more servers, plays locally, copies between servers, and may become a shared satellite of one server.

Quickstart

# Run a core over your music library.
ICHOI_MUSIC_DIR=/path/to/music ichoi serve

That serves the browser UI on http://localhost:4042 and the CSIL+TLS listener on :4043. On a trusted LAN this is login-less (guest); the first LinkKeys login promoted with ICHOI_ADMIN_TOKEN becomes the admin.

Browsers should reach Ichoi over HTTPS via a reverse proxy — the HTTP listener is plain HTTP by design. See deploy/ for a ready-to-edit Caddy example and a docker-compose that runs Ichoi behind it.

Configuration

Precedence is environment (ICHOI_-prefixed) → TOML config → defaults. The common settings:

Setting Env Default
Role ICHOI_ROLE core
Music directory ICHOI_MUSIC_DIR (required for a core)
Audiobook directory ICHOI_AUDIOBOOK_DIR unset
Flatten disc subfolders into parent albums ICHOI_ALBUM_SUBFOLDER_FLAT true
Disc-subfolder matching words ICHOI_ALBUM_SUBFOLDER_WORDS cd,disc,disk,bonus disc
Database directory ICHOI_DB_DIR music dir
Artwork cache size in MB ICHOI_ARTWORK_CACHE_MB 200 (0 disables caching)
HTTP listen ICHOI_HTTP_ADDR :4042
CSIL listen ICHOI_CSIL_ADDR :4043
Core address (satellite) ICHOI_CORE_ADDR (required for a satellite)
Core key fingerprints (satellite) ICHOI_CORE_KEYS (required for a satellite)
Node token (satellite) ICHOI_NODE_TOKEN (required for a satellite)
CSIL/TLS certificate (core) ICHOI_TLS_CERT <db-dir>/csil-cert.der
CSIL/TLS private key (core) ICHOI_TLS_KEY <db-dir>/csil-key.der
Admin bootstrap token ICHOI_ADMIN_TOKEN unset
Session lifetime in hours ICHOI_SESSION_LIFETIME_HOURS 720
DNS-less LinkKeys RP ICHOI_LINKKEYS_LOCAL_RP disabled; only exact true enables
Local RP name ICHOI_LINKKEYS_LOCAL_RP_NAME unset
Regular LinkKeys RP ICHOI_LINKKEYS_RP disabled; only exact true enables
RP TCP endpoint ICHOI_LINKKEYS_RP_ADDR unset
RP TLS fingerprints ICHOI_LINKKEYS_RP_FINGERPRINTS unset
RP API key ICHOI_LINKKEYS_RP_API_KEY or ICHOI_LINKKEYS_RP_API_KEY_FILE unset
RP domain ICHOI_LINKKEYS_RP_DOMAIN unset
RP application ID ICHOI_LINKKEYS_RP_APPLICATION_ID ichoi
Public HTTPS origin ICHOI_PUBLIC_URL unset
Trusted LinkKeys identities ICHOI_LINKKEYS_TRUSTED_IDENTITIES unset
Trusted stable LinkKeys user IDs ICHOI_LINKKEYS_TRUSTED_USER_IDS unset
Anonymous browser jukebox shares ICHOI_ANONYMOUS_JUKEBOX disabled
Elevated zero-account guest access ICHOI_ZERO_ACCOUNT_GUEST_ACCESS enabled
ffmpeg override ICHOI_FFMPEG bundled → PATH
Default transcode codec ICHOI_TRANSCODE_CODEC aac
Log level LOG_LEVEL warn

Setting ICHOI_AUDIOBOOK_DIR enables the Audiobooks view. The directory may be separate from the music collection or nested below it; a nested audiobook tree is excluded from the music catalog automatically. Signed-in users get independent per-chapter listening progress and resume positions. While the server has no accounts, guest playback uses one global progress profile shared by everyone browsing that server.

By default, disc-like subfolders such as CD1, CD2, Disc One, and Bonus Disc are fuzzy-matched and flattened into one album named after their parent folder. Track titles retain their source folder as a prefix, for example CD1 - Chapter 01. Set ICHOI_ALBUM_SUBFOLDER_FLAT=false to retain separate subfolder albums, or provide a comma-separated ICHOI_ALBUM_SUBFOLDER_WORDS list to replace the default matching vocabulary.

The database is a single SQLite file (WAL) in the database directory. ffmpeg is resolved bundled-next-to-the-binary first, then PATH; if neither is found, transcoding is disabled and the core serves direct mode only — Ichoi never fails to start for lack of ffmpeg.

Administrators can start a full library resync from Settings. Resync uses the same single-flight scanner as startup, updates changed metadata, and removes catalog rows for files that disappeared; starting another resync while one is active does not create a competing scan.

Chromebook and browser satellites

The default web UI is an installable PWA. An administrator (or anyone on a login-less guest instance) can create a named, one-time satellite token in Settings and enter it at /satellite. The token is stored only in that browser profile. While present, every other application route redirects to the restricted satellite console; leaving satellite mode and signing in normally are separate, explicit actions.

Satellite tokens define whether newly discovered audio outputs are shared and which access groups inherit them. The built-in Everyone group includes guests and every account. Administrators can create narrower groups, change an individual output's groups, or disable an output globally so it is not listed or controllable by anyone. The console supports Chrome's audio-output chooser when available, falls back to the system default, and offers a fullscreen action. ChromeOS still requires a user gesture through Enable audio before remote playback and a personal ChromeOS login after a reboot; session restore can reopen the installed PWA afterward.

DNS-less LinkKeys login on a LAN

Local-RP login is completely opt-in and gives Ichoi a key-fingerprint identity rather than a public DNS identity or RP sidecar. Enable it with all three settings:

ICHOI_LINKKEYS_LOCAL_RP=true
ICHOI_LINKKEYS_LOCAL_RP_NAME="Kitchen Ichoi"
ICHOI_LINKKEYS_TRUSTED_IDENTITIES="family.example,alice@friends.example"
# Optional stable identity admission when the public handle is not the login name:
ICHOI_LINKKEYS_TRUSTED_USER_IDS="user-uuid@friends.example"

Only the exact lowercase value true enables the mode. A domain entry accepts every verified handle at that LinkKeys domain; handle@domain accepts only that verified handle. Users normally enter handle@domain in Ichoi's sign-in dialog. Ichoi derives its callback from the browser's same-origin LAN address, so no public URL setting or public availability is required.

Native clients can send return_url: "ichoi://linkkeys" to either LinkKeys start endpoint. The server returns the one-time exchange code to that exact callback. The server rejects all other native return URLs. A browser login still returns to the selected server.

The first enabled start generates the local RP signing/encryption identity and stores the SDK's opaque key bundle in ichoi.db. It remains stable across restarts; changing the name does not silently rotate it. Backups of the database therefore contain private RP key material and must be protected. Approve the fingerprint reported in the log or /api/auth at each trusted LinkKeys domain before users log in.

Guest access policy

Guest access remains open by default. Public deployments can require LinkKeys login, while installations with split internal/public DNS can allow guests only from LAN addresses:

ICHOI_ACCESS_MODE=open
ICHOI_ACCESS_MODE=login-required
ICHOI_ACCESS_MODE=lan-guests

A signed-in person who shares a browser device selects who can use it: everyone who is signed in, or only the accounts they select. An admin sets the starting access for new shares with the share_default_access server setting (everyone by default, or private).

Set ICHOI_ANONYMOUS_JUKEBOX=true to let guests create and control ownerless browser jukebox shares. This setting does not expose native outputs or account-owned browser shares. Set ICHOI_ZERO_ACCOUNT_GUEST_ACCESS=false on a public server that must require login for persistent changes before its first account exists. This setting blocks guest administration, playlist saves, progress saves, media copies, and guest control of shared devices such as server and satellite speakers. It does not block guest browsing, playback in the guest's own browser, or the anonymous jukebox setting.

LAN mode recognizes loopback, link-local, RFC1918 IPv4, and unique-local IPv6 addresses. When a reverse proxy terminates TLS, Ichoi uses X-Forwarded-For only when the immediate peer is explicitly trusted. For example, when Caddy is 10.19.81.5:

ICHOI_ACCESS_MODE=lan-guests
ICHOI_TRUSTED_PROXY_CIDRS=10.19.81.5/32

Do not trust a proxy CIDR containing untrusted clients. Without a matching trusted proxy, Ichoi deliberately classifies the proxy itself rather than accepting a spoofable forwarded address.

Regular LinkKeys RP login

For a public deployment backed by an existing DNS-pinned LinkKeys RP service, enable regular-RP mode instead. It is mutually exclusive with DNS-less mode:

ICHOI_LINKKEYS_RP=true
ICHOI_LINKKEYS_RP_ADDR="linkkeys.example.com:4987"
ICHOI_LINKKEYS_RP_FINGERPRINTS="fingerprint1,fingerprint2"
ICHOI_LINKKEYS_RP_API_KEY_FILE="/run/secrets/linkkeys_rp_api_key"
ICHOI_LINKKEYS_RP_DOMAIN="ichoi.example.com"
ICHOI_LINKKEYS_RP_APPLICATION_ID="ichoi"
ICHOI_PUBLIC_URL="https://ichoi.example.com"
ICHOI_LINKKEYS_TRUSTED_IDENTITIES="family.example,alice@friends.example"

The environment value is the deployment-managed portion of the trust set. It is reconciled at startup; administrators can add and revoke additional domain or exact-handle entries in Settings, and those database-managed entries are unioned with configured entries.

Use ICHOI_LINKKEYS_TRUSTED_USER_IDS when admission must follow a login account instead of its public handle. Each entry is the stable verified LinkKeys user UUID and domain. Ichoi can start login for that domain, but it completes login only for the configured user UUID.

The API key must belong to an RP service account with LinkKeys' api_access relation. The file form is preferred for containers because it keeps the key out of Compose interpolation and the container environment. Ichoi pins the RP server's TLS certificate to the configured fingerprints, requests and verifies the handle claim, and applies the same domain/handle admission selectors used by DNS-less mode.

Ichoi uses LinkKeys v0.16.7. Regular-RP requests include a stable application ID. Set ICHOI_LINKKEYS_RP_APPLICATION_ID, or linkkeys_rp_application_id in TOML, to override ichoi. Use 1 to 128 ASCII letters, digits, -, _, or .. Keep this value stable. Use different IDs for applications that share an API-key account but need separate consent. Give the RP service account a display name that users can recognize. LinkKeys shows that name on its consent screen.

LinkKeys now records consent for the API-key account, RP domain, and application ID. Old domain-only grants do not cover the new application. Users must approve the claims once more after the upgrade. Ichoi still requires handle and asks for display_name as an optional claim. If an existing application already has consent under the RP account username, set the application ID to that username to keep the same application identity. If act-as grants are added, use the same application ID that those grants use.

ICHOI_PUBLIC_URL can use a host outside ICHOI_LINKKEYS_RP_DOMAIN. It must be an HTTPS origin with no credentials, path, query, or fragment. Both the RP service and the user's IDP must support v0.16.7 for this callback behavior. An older IDP can reject it with callback_off_domain. DNS-less local-RP login continues to use its stored key identity. It now requests only handle and display_name; it no longer inherits the SDK's unused email request. The mobile callback and exchange-code flow do not change.

Native satellite installation

Satellites authenticate with a node token only after establishing rustls TLS to a pinned core key. No DNS name or public CA is involved. On the core, print the fingerprint that must be provisioned out of band:

ichoi core-fingerprint

Then install the same binary on the output machine. Reading the token from a file or stdin keeps it out of shell history and process listings:

ichoi install satellite \
  --core 192.168.1.20:4043 \
  --core-key sha256:<fingerprint> \
  --node-token-file ./theater-node.token

Use --dry-run to print every file and service-manager command without changing the host. --scope user selects a per-user installation; the defaults are a system service on Linux and a user service on macOS and Windows.

Inspect or remove the same installation with:

ichoi status --scope user
ichoi uninstall --scope user --keep-config
  • Linux installs a systemd system or user unit. System scope uses /etc/ichoi/ichoi.toml; user scope follows $XDG_CONFIG_HOME.
  • macOS installs a LaunchAgent under ~/Library/LaunchAgents and keeps its configuration under ~/Library/Application Support/Ichoi.
  • Windows user scope installs an ONLOGON scheduled task. System scope installs a native Windows Service and stores configuration under %PROGRAMDATA%\Ichoi.
  • Windows 11 plays audio from a service only while a user is signed in. A locked session is sufficient. For a headless Windows satellite, add --auto-signin to a --scope system installation. The installer creates the hidden standard local account IchoiAudio with a random password. It keeps the password only as an LSA secret, signs in the account at boot, and locks the session immediately. Other users can sign in with "Other user" on the lock screen. ichoi uninstall removes the account and restores the previous sign-in settings.
  • The --auto-signin installer stops before it changes the machine if another account signs in automatically, if a sign-in legal notice is set, or if an IchoiAudio account exists that Ichoi did not create. Use --replace-auto-signin to replace the automatic sign-in of the other account or to use the existing IchoiAudio account. Use --dry-run to see each change first.

Linux retains its runtime-loaded ALSA backend. macOS and Windows builds compile only their native CoreAudio/WASAPI backend, so those dependencies never enter Linux artifacts.

Repository layout

Each independently versioned target lives in its own top-level directory (the multiple-directory release strategy — a future mobile app would be a sibling mobile/). The server target is under server/; the repo root holds only shared CI (.reactorcide/), project docs, and the ./tools.sh helper.

Building

Ichoi has two Linux build types. The core uses static musl and runs in a scratch container. The native satellite uses GNU libc and loads the host ALSA library at run time. SQLite is compiled in, and ffmpeg is a separate program.

cd server
cargo build --release --target x86_64-unknown-linux-musl   # amd64
cargo build --release --target aarch64-unknown-linux-musl  # arm64 core
cargo zigbuild --release --target x86_64-unknown-linux-gnu.2.17   # amd64 satellite
cargo zigbuild --release --target aarch64-unknown-linux-gnu.2.17  # arm64 satellite

Day-to-day, use ./tools.sh from the repo root (it drives the server target for you), which mirrors what CI runs:

./tools.sh build     # cargo build --workspace
./tools.sh test      # TEST_DATABASE_BACKEND=sqlite cargo test --workspace
./tools.sh fmt       # cargo fmt --all
./tools.sh clippy    # cargo clippy --workspace --all-targets -- -D warnings
./tools.sh check     # csil-validate + fmt + clippy + test (the full local gate)
./tools.sh gen       # regenerate CSIL bindings (server + all client languages)

Docker

The server/Dockerfile produces a minimal scratch image (multi-arch, linux/amd64 + linux/arm64) containing the ichoi binary, a bundled static LGPL ffmpeg, and the web UI. The static core build does not load audio libraries. It reports audio_outputs: none.

SQLite needs a writable temporary directory for large sorts and grouping queries. The image provides /tmp with mode 1777, including access for a non-root UID. If the container root filesystem is read only, mount a writable directory or tmpfs at /tmp. Without it, SQLite can report disk I/O error with extended code 6410 (SQLITE_IOERR_GETTEMPPATH), even when the database passes its integrity check. The core Compose examples mount a 256 MiB tmpfs at /tmp. Increase this limit if queries need more temporary storage. The mount is created again each time the container is created.

docker buildx build --platform linux/amd64,linux/arm64 -t ichoi:dev server
docker run --rm -e ICHOI_MUSIC_DIR=/music -v /path/to/music:/music -p 4043:4043 ichoi:dev

Published images live at containers.catalystsquad.com/public/catalystcommunity/ichoi. For a full deployment behind TLS, see server/deploy/docker-compose.yml.

Testing & CI

Tests hit a real SQLite database inside a transaction that rolls back — no mocks for the data layer, every test isolated in its own transaction. CI runs on Reactorcide (not GitHub Actions): conventional commits gate PRs and fan out to build (amd64 + arm64), the SQLite suite, and CSIL validation; semver-tags cuts per-target releases (server/vX.Y.Z) on merge to main. A tag workflow builds four archives in parallel. It seals the archives in the asset cache before it publishes the GitHub Release. ./tools.sh check reproduces the PR gate locally. Definitions live in .reactorcide/.

License

Apache-2.0. See LICENSE. Nothing copyleft or patent-encumbered lives inside the Ichoi binary; the bundled ffmpeg is a separate LGPL program, subprocessed (see docs/ffmpeg.md).

About

Turn a local music collection into an internet jukebox experience

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages