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.
- 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.
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. |
# Run a core over your music library.
ICHOI_MUSIC_DIR=/path/to/music ichoi serveThat 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.
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.
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.
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 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-guestsA 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/32Do 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.
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.
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-fingerprintThen 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.tokenUse --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/LaunchAgentsand keeps its configuration under~/Library/Application Support/Ichoi. - Windows user scope installs an
ONLOGONscheduled 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-signinto a--scope systeminstallation. The installer creates the hidden standard local accountIchoiAudiowith 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 uninstallremoves the account and restores the previous sign-in settings. - The
--auto-signininstaller stops before it changes the machine if another account signs in automatically, if a sign-in legal notice is set, or if anIchoiAudioaccount exists that Ichoi did not create. Use--replace-auto-signinto replace the automatic sign-in of the other account or to use the existingIchoiAudioaccount. Use--dry-runto 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.
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.
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 satelliteDay-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)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:devPublished images live at containers.catalystsquad.com/public/catalystcommunity/ichoi.
For a full deployment behind TLS, see server/deploy/docker-compose.yml.
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/.
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).