# Internals: analyzer, Icecast rendering and state layout Why the sidecars, the Icecast config rendering and the state directory are shaped the way they are. The short invariants are in the root `CLAUDE.md`; read the matching section here before changing any of them. **Controller startup readiness.** The HTTP socket opens before asynchronous initialization, but `middleware/startup.ts` returns uncached HTTP 503 with `Retry-After: 1` until persisted settings, blocklist, session/queue recovery, orphaned tagger recovery and listener initialization have completed. `/health` uses the same barrier as the API, so Docker cannot advertise a ready controller that still accepts jobs ahead of its recovery pass. CORS preflight remains available. Do not open only the job routes early: settings writes and reads of privacy defaults also race hydration. Startup recovery must still terminate an actual old worker; ignoring a live pidfile would permit two writers. A held-read integration test in `scripts/startup-readiness.test.ts` proves early requests leave that pidfile alone and a post-ready managed reconciliation completes. The recurring trap: **`docker/broadcast-entrypoint.sh` and the AIO supervisor's `render_icecast()` / `bootstrap_state_dirs` must stay in lockstep.** Six things live in both — per-mount burst/queue sizing (with the `stream-mounts.json` marker recording it and the bitrate handoff to liquidsoap), the listener-auth blocks, the trusted-proxy list (and the marker recording it), the state-dir bootstrap, `resolve_max_clients`, and the Icecast secrets resolver — and a fix applied to one is a bug in the other. The burst sizing is one function, `render_stream_mounts`, in each, and `scripts/stream-mounts.test.ts` drives both from one table and compares the two copies' shared functions as `declare -f` prints them. It also pins what that comparison cannot see, the lines outside the shared functions that carry the handoff: `RADIO_LIQ=`, the `render_stream_mounts` call and the `liquidsoap` launch. Both markers are written by one helper, `write_state_marker`. Covers: the analyzer service and its two flavours, public persona disclosure, real listener IPs, the non-fatal state bootstrap, and multi-station profiles. `settings.stream.bufferSeconds` is the single source of truth for listener delay. Both Icecast renderers read the controller-written handoff file; neither accepts an environment override. One would silently outrank the operator's saved setting, and a controller older than the `stream-mounts.json` marker below would keep advertising the stored value, so every listener-facing timestamp would drift. **What listeners are told is what was rendered, not what was saved (#2142).** `` is rendered when the broadcast pair starts, while the setting saves at once, so between a save and the next mixer restart the two disagree. `render_stream_mounts` (the same function in both renderers) therefore records each mount's burst in `state/stream-mounts.json` on every render: `{mounts: {"/stream.mp3": {kbps, burstSeconds, burstBytes}, …}, at}`, written through a fresh `mktemp` file and a rename, mode 644, so a symlink planted ahead of the write, at a temp path or at the marker, is not written through. `broadcast/stream-mounts.ts` reads it (2 s memo) and `/now-playing`'s `stream.bufferSeconds` and the voice webhooks' `streamBufferSeconds` advertise the MP3 mount's `burstSeconds`. An absent, malformed or self-contradicting marker (bytes that are not seconds x kbps x 125) is unknown and falls back to the setting, which is exactly the pre-marker behaviour on a broadcast image older than it. A failed write warns, never aborts, and removes the previous render's marker, so a stale one does not outlive the mounts it describes unless that removal fails too, as on a read-only state mount, where the controller keeps trusting it until a render can write. The file lives in the active station's dir, like `trusted-proxies.json`, and `duplicateAction` leaves it behind: a new station has not been rendered yet. The Opus mount's entry also carries `encoding`: `cbr` only when every `%opus` encoder in the `radio.liq` liquidsoap is about to load says `vbr="none"` and none sets `dtx` to anything but a literal `false` (DTX can drop silent frames in any mode), `vbr` otherwise, and absent when there is no encoder to read (`opus_encoding`). It is read from the encoder line itself rather than declared beside it, so the edit that changes the encoder (#2138) changes the answer, and a later image cannot carry a stale claim. It exists for the web idle skip, which may treat a byte-sized Opus burst as seconds only on a running mount that says `cbr`. `opus_encoding` and `controller/scripts/opus-cbr.test.ts` read a file the same way, and `scripts/test-utils/opus-cbr-table.ts` holds both to one table of edits to the real `radio.liq` (#2164): both comment forms are cut, whichever starts first, and `vbr='none'` and `%opus (…)` count. Every doubt reads as not `cbr`. That covers no `vbr` at all or a bare `%opus` (2.4.6 defaults to constrained VBR, byte for byte), `vbr` given twice (the last one wins), a `(` inside the call (the first `)` then need not close it, and `bitrate=(96), dtx=true` is DTX on 2.4.6), a `#<` that never closes (2.4.6 refuses that file unless the `#<` sat in a string, and then what follows is real code), an `%ffmpeg` libopus encoder, and a no-break or em space, which 2.4.6 takes as whitespace: both readers work in ASCII, and `opus_encoding` in the C locale, so no `LC_ALL` changes the answer. Neither reader is a lexer. A `#` or `#<` in a string reads as a comment, a block comment's nesting is ignored, though 2.4.6 nests them, and an `%ffmpeg` encoder that names its codec any way but `libopus` goes unseen. **The bitrate each burst is sized for is the bitrate liquidsoap encodes at (#2143).** The renderer used to read `liquidsoap_stream_bitrate.txt` to size the burst and liquidsoap read the same file seconds later, so a save in between sized the burst for the old encoder (320 → 64 kbps at 60 s is a ~300 s burst). `render_stream_mounts` now reads each setting once and exports the MP3, Opus and AAC bitrates as `SUBWAVE_{STREAM,OPUS,AAC}_BITRATE`, which `radio.liq`'s `burst_bitrate` takes before its own file read; run without them (by hand, or by an older supervisor) it reads the file as before. What the renderer hands on replaces radio.liq's own read, so everything the controller writes reads the same in both: surrounding whitespace is trimmed (radio.liq's `string.trim`, so a CRLF hand-edit keeps its bitrate rather than handing on the fallback), a bitrate radio.liq would refuse (0) falls back to the default, and leading zeros read as decimal, never as bash's octal. `read_state_uint`'s trim is quadratic and a padded file must not hold a boot back, so it squeezes whitespace runs and reads at most 64 bytes of the result. Padding cannot push a value out of those bytes or cut one in half, as a plain `head -c` of the file would. Some hand-edits still part ways, because it takes plain digits only: `0x80`, `+128`, `1_000` and 7+ digits are the fallback there, though radio.liq's `int_of_string` would read them. `ICECAST_{STREAM,OPUS,AAC}_BITRATE` still re-size only the burst and are never handed on: the encoder has always taken the setting, and handing it the override would change a configured station's audio on upgrade. `burst_kbps` normalises them so the marker is always valid JSON, and it keeps bash arithmetic's reading, which is what sizes the burst: `0100` is octal 64, as it always was, because reading it as decimal would change `icecast.xml`. `0128`, which arithmetic refuses and which used to abort the render, reads as decimal. `settings.stream.maxListeners` takes the **opposite** precedence, deliberately. Both renderers resolve it through `resolve_max_clients`, which prefers `ICECAST_MAX_CLIENTS` and only falls back to the handoff file (`liquidsoap_icecast_max_clients.txt`, default 100). The asymmetry with `bufferSeconds` is the point: nothing the controller publishes depends on the listener ceiling, so an env override cannot desynchronise a clock — while the var predates the setting and rides all three compose files, so demoting it would silently re-ceiling a station on upgrade. What that costs is a setting that can save and do nothing, so **the winning source is logged on every boot** (`max listeners N (from ICECAST_MAX_CLIENTS|settings|fallback:…)`) and the admin hint says so. Junk from either source falls back to 100 rather than rendering invalid XML — or a `0` that would serve a station nobody can connect to. The setting exists for the AIO image, which is where the gap was: the Unraid template exposes no `ICECAST_MAX_CLIENTS` and there is no `.env` in that container, so the ceiling was literally unsettable there. Licensing bodies in some countries calculate fees on simultaneous listener capacity, which is what made it worth a setting rather than a docs line (#1300 FR 15). Both copies of the function are driven from one table by `scripts/max-listeners.test.ts`. **Default-on `analyzer` service** — the acoustic-analysis sidecar (`subwave-analyzer` image, `docker/Dockerfile.analyzer` + `docker/analyzer/server.py`). **Starts by default** in all three composes (no profile gate — like controller/web); only `tts-heavy` (voices) stays opt-in. It's the librosa (+ optional CLAP + Demucs) analyzer **split out of tts-heavy**: bpm/key/intro/loudness always, plus **outro analysis** on every tier (last ~20s of each *complete* file → `tracks.outro_json`: fade-vs-cold ending, tail LUFS/tempo/bars; a byte-capped download skips it — the completeness flag rides the analyze request). The outro is what makes transitions ending-aware: `queue.applyMixTransition` stamps each DJ-mode track's OWN exit canvas from its measured ending via `mix.endingCrossSecondsFor` (a fade rides out 8–12s, a cold end cuts ~4s; washout/loop overwrite it) — the per-track answer to #749, which blocks the pair-sized `crossSecondsFor` from ever being applied — and a measured fade vetoes the `chop` effect (`effectAllowedFor`). **Vocal-aware transitions** (heavy tier, vocal detection on): the outro window gets its own Demucs pass → `outro.vocalRanges` (absolute ms, `[]` = instrumental tail; backfill widened via the `tail_vocal` capability flag so stale analyzer images never churn; lyric-decided tracks skip the tail Demucs pass like the head one — their tail ranges are clipped from the synced-lyric timing instead, `lyric-vocal.clipRangesToTail`) — a sung fade pulls its exit canvas to the 8s floor (`Analysis.vocalTail`), a sung ending vetoes `chop`, and a *measured* first-vocal entry under 2.5s drops the DJ link outright (`enforceIntroBudget` — see `docs/stem-transitions-research.md`); "sounds-like" embeddings (multi-window CLAP — start/mid/late windows averaged, so quiet intros don't misrepresent the track), vocal ranges, and the CLAP **text tower** (`POST /embed-text`, capability-flagged in `/health`) are the heavy tier. Text and audio vectors share one 512-d space, which powers the picker's `searchBySound` tool (describe a sound in words → audio KNN) and zero-shot audio moods (`music/audio-moods.ts`: mood-vocab prompts scored against stored audio vectors at the end of every analysis pass → `tracks.audio_moods`, blended into `songsByMood`/`trackMoods`; vocab/prompt changes re-score via `mood_vocab_hash`; the sound descriptors in `music/audio-descriptors.ts` ride the same pass). **Two published flavours**: `subwave-analyzer` — **LEAN, multi-arch** (~1.1GB — librosa + ffmpeg, no torch — the default everyone pulls), `WITH_CLAP=0 WITH_DEMUCS=0`; and `subwave-analyzer-heavy` — CLAP+Demucs baked (~1.9GB, amd64-only), `WITH_CLAP=1 WITH_DEMUCS=1`. **Opt-in switch is `ANALYZER_HEAVY=1` in `.env`** — the compose `analyzer` service resolves `image: …/subwave-analyzer${ANALYZER_HEAVY:+-heavy}:…` and its `build.args` key off the same var (so pull and local build agree). No `platform` pin (lean is native arm64; heavy on arm64 needs `DOCKER_DEFAULT_PLATFORM=linux/amd64`). Uses the **same `analyze_worker.py`** as the offline CLI (single source of truth). The controller resolves its analysis backend from `config.analyzer.urls` — **`ANALYZE_URL`** (`music/analyzer.ts` probes `/health`), then a local venv (`ANALYZE_PYTHON`). `ANALYZE_URL` **defaults to `http://analyzer:8080`**, the compose service name, the same way `NAVIDROME_URL` defaults to `http://navidrome:4533`: a controller created from a compose file that predates the `ANALYZE_URL` line found an EMPTY candidate list and reported no analysis engine with a healthy sidecar one DNS name away (#1636). An unresolvable candidate is an ordinary probe miss, so the AIO (no such service) and `ANALYZER_REPLICAS=0` still fall through to the local venv or to nothing. tts-heavy is TTS-only now and is **not** an analysis backend (no `TTS_HEAVY_URL` fallback). **AIO (`Dockerfile.aio`) bundles the analyzer in-process** (local venv, `ANALYZE_PYTHON` + `HF_HOME` under the state dir) rather than a service; `subwave-aio` is lean, `subwave-aio-heavy` bakes CLAP+Demucs. The analyze worker lives in the analyzer image(s) and the AIO. **Remote path fallback (#1331)**: the controller still prefers its one-ahead shared-path handoff, but a sidecar's typed `path_unavailable` response earns exactly one retry by URL; `complete` and `stems_dir` are removed because they describe controller-local files. Never retry generic DSP/decode failures. **Stale keep-alive sockets**: every sidecar request (`/health`, `/analyze`, `/embed-text`, `/render-transition`) passes `retryStaleSocket` to `fetchWithTimeout`, which sends again, in at most `STALE_SOCKET_ATTEMPTS` (3) attempts in all (so two resends), a request that died with `UND_ERR_SOCKET`/`ECONNRESET`/`EPIPE` before any response. A tagger that holds the event loop for a few seconds misses the analyzer's idle close and sends its next POST on the dead socket, which undici does not retry for a POST; that skipped a whole sound-descriptor pass. Only a fast failure before a response qualifies, one within `STALE_SOCKET_RETRY_MS` (2 s) of the attempt's start: a connection that drops halfway through a long request is not resent, because the analyzer may already be computing it. An HTTP status, a timeout or a refused connection is never resent, and the opt-in stays off for requests that are not safe to send twice. `subsonic.ts`'s `boundedFetch` shares only that window constant with it; its rule is its own (any fast transport failure, `ECONNREFUSED` included, retried once after 250 ms, for the calls that opt in with `retryFastTransport`), and the two loops are not merged. Each resend logs one line naming the origin (never the path or query) and the socket error, at most once a minute (`STALE_SOCKET_WARN_EVERY_MS`) with a count of the ones held back, so a recurring socket problem is visible even when every request ends up answered. `embedTexts` still degrades to null but logs the cause (`describeFetchError`), at most once a minute (`EMBED_WARN_EVERY_MS`) with a count of the failures in between (both limits are `util/warn-limiter.ts`), so an analyzer outage during a tagger run is one line, not one per track. Pinned by `scripts/fetch-stale-socket.test.ts` and `scripts/embed-warning.test.ts`. Shared state remains required for remote stem output and recommended for prefetch throughput. **The off switch is `ANALYZER_REPLICAS=0` (#1570)**, rendered as `deploy.replicas: ${ANALYZER_REPLICAS:-1}` on the service — the next `up -d` stops AND removes the container, and it stays gone across restarts, which `docker compose stop analyzer` (the old advice) did not: `up` restarts a hand-stopped service. **A profile could not express this** and the reason is measured, not stylistic: profiles are opt-in only, so gating the analyzer behind one forces every existing install to add `COMPOSE_PROFILES=analyzer` to keep what it has, and the inverted trick — `profiles: ["${ANALYZER_DISABLED:+off}"]`, empty by default — drops the service for anyone who sets `COMPOSE_PROFILES` **at all**, because a non-empty `COMPOSE_PROFILES` switches compose from the default set to the named set and an empty-string profile is in neither. `docs/tts-heavy.md` tells every Unraid/Portainer operator to set `COMPOSE_PROFILES=tts-heavy`, so that population would silently lose analysis on upgrade. `deploy.replicas` has neither failure: unset and empty both render `1`, so a default-on install is byte-identical, and the `deploy` map merges key-wise with `docker-compose.analyzer-gpu.yml`'s `deploy.resources` reservation rather than replacing it. Three consequences worth knowing. **Only `0` and `1` are valid**: the service pins `container_name: sub-wave-analyzer`, and compose refuses a fixed container name for more than one replica, so `ANALYZER_REPLICAS=2` fails *every* compose command (`can't set container_name and analyzer as container name must be unique`) rather than scaling — a non-integer (`false`) is likewise a hard interpolation error rather than a silent fallback, which is why the var is named for a count and not a boolean. `docker compose config` still LISTS the service at `replicas: 0` (unlike a profile, which omits it), so verify with the rendered `replicas:` line or `docker compose ps`, never `config --services`. And the variable is **inert on the AIO**, which runs the analyzer in-process (`ANALYZE_PYTHON`) rather than as a service — so `docker/aio/supervisor.sh` `warn_if_analyzer_replicas_ignored` warns at boot when it is set to `0` there, for the same reason `warn_if_analyzer_heavy_ignored` exists (#1300 bug 9: a compose-only var that an operator sets, watches do nothing, and concludes the feature is broken). This one fails worse than `ANALYZER_HEAVY` did — an operator setting `0` to reclaim RAM keeps paying for analysis it believes it switched off — so the warning names the AIO's real off switch, an **empty `ANALYZE_PYTHON`** (`config.ts` reads an empty path as no local backend). `scripts/aio-analyzer-heavy.test.ts` pins the warning, and `scripts/analyzer-replicas-compose.test.ts` drives all three composes from one table so the `deploy.replicas` line cannot drift between them. **Analyzer torch and maintenance commands (#1340, #1738).** Heavy CPU builds and the primary CUDA build of both `subwave-analyzer-cuda` and `subwave-aio-cuda` share torch/torchaudio **2.7.1**, the CUDA ones from the **cu128** index (Turing sm_75 through Blackwell sm_120). Each CUDA image has a second build, `TORCH_CUDA=cu124`, which pins torch **2.6.0** because that cu124 wheel still ships Maxwell (sm_50), Pascal (sm_60) and Volta (sm_70) SASS. cu128 dropped those three, and CUDA 13 cannot emit them. The split stack's cu124 build came after the AIO's (#2280). Both indexes publish cp313 wheels for the AIO's system Python 3.13 and cp311 for the standalone image. The two Dockerfiles share one `TORCH_CUDA` case. Keep the shared pins in lockstep (Demucs 4.0.1, transformers 5.13.0, CPU onnxruntime 1.27.0); the cu124 torch pin is the one exception. Neither ships diffq, so a quantised `DEMUCS_MODEL=*_q` loads `htdemucs` instead (`analyze_worker.py` `demucs_model()`). Chatterbox runs in a separate venv with its own upstream torch pin and Blackwell override, described in `docs/gpu-tts.md`. The AIO appends `/opt/analyzer/venv/bin` to PATH so `docker exec subwave pip` targets analyzer packages while system `python3` keeps precedence. Its analyzer and Kokoro workers use explicit interpreter paths. The standalone analyzer puts the analyzer venv first so pip targets it instead of the server venv, and starts FastAPI with `/opt/server/venv/bin/uvicorn` to preserve that isolation. **CUDA tags: an architecture tag names a GPU, not a wheel (#2265, #2280).** `subwave-aio-cuda` and `subwave-analyzer-cuda` are each published once per torch wheel, and operators pick one by their card's architecture: the AIO by its container tag, the split stack by `ANALYZER_CUDA_TAG`, which `docker-compose.analyzer-gpu.yml` reads ahead of `SUBWAVE_VERSION`, so an install that leaves it unset pulls exactly the image it did before. Both images carry the same tags with the same builds behind them. This table is the one place that maps a tag to a build; the README, `docs/unraid.md`, `docs/tts-heavy.md` and the in-app guides link here or name a tag by its card rather than restate it. The analyze worker names a card's tag too, when its CUDA self-test fails and it falls back to cpu (`cuda_arch_tag` in `analyze_worker.py`). The card is tested once per worker process, and cpu stays until the process exits, whatever the failure. When the card was out of memory under a co-resident TTS or LLM, the warning says so: restarting the analyzer once that memory is free puts it back on the GPU. The worker never moves to cuda mid-process, because a tiny op can pass while the real model still does not fit. | Tag | GPU (compute capability) | For example | Build today | | --- | --- | --- | --- | | `:maxwell` | sm_50–52 | GTX 750, GTX 900-series | cu124 | | `:pascal` | sm_60–61 | GTX 10-series, P40 | cu124 | | `:volta` | sm_70 | Titan V, V100 | cu124 | | `:turing` | sm_75 | RTX 20-series, GTX 16-series, T4 | cu128 | | `:ampere` | sm_80–86 | RTX 30-series, A100 | cu128 | | `:ada` | sm_89 | RTX 40-series, L4 | cu128 | | `:hopper` | sm_90 | H100 | cu128 | | `:blackwell` | sm_100–120 | RTX 50-series, B200 | cu128 | The build tags `:cu124` and `:cu128`, and the release pins `:-cu124` and `:-cu128`, name a wheel instead. `:latest` and the plain `:` tags follow the **primary** build, today cu128, so they work only on Turing and newer. An architecture tag floats with each stable release, so `subwave update` needs nothing more; a `:-cu124` pin in `ANALYZER_CUDA_TAG` stays where it is until the operator moves it. An architecture tag points at the newest build that still supports its GPU, which is why each GPU has its own: a later wheel can move one without the others (a cu130 that only adds Blackwell moves `:blackwell` and leaves `:hopper` on cu128), whereas a tag shared by several GPUs, or `:latest`, would strand the older cards the day a newer wheel drops them. Never point an architecture tag at a build that dropped its GPU, and never fold several GPUs into one tag. `publish-images.yml` encodes this per matrix entry. Each `subwave-aio-cuda` and `subwave-analyzer-cuda` entry sets `cuda_family`, `primary` and `arch_tags`, so moving a GPU to another build moves one word between two `arch_tags` lines, on both images together: otherwise the AIO and the split stack disagree about a card. `cuda_family` is also the wheel: the build step passes it to `Dockerfile.aio` or `Dockerfile.analyzer` as `TORCH_CUDA`, whose `case` fails on a family it has no index for, so a build's tags and its wheel can't disagree. Each job sees only its own entry, so the `tagplan` step checks only that entry's shape (a `cuda_family` build says `primary: true` or `false`, and `arch_tags` needs a `cuda_family`). The rules across entries run in `lint.yml` on every PR: `controller/scripts/check-publish-matrix.ts` fails an image with no primary or two, and a build or architecture tag on more than one entry, because either races two jobs for one tag on a release. It also fails the two CUDA images out of lockstep: a tag one carries and the other lacks, or a tag (`:latest` included) on a different `cuda_family` in each. Only the primary build takes `:latest`, the plain version tags and the plain `sha-` commit tag; another build's commit tag is `sha--`. A non-primary build also sets the metadata-action flavor `latest=false`. The action adds `:latest` by itself for any enabled stable semver rule, whatever that rule's suffix, so without it the cu124 build's `:-cu124` rule raced the primary for `:latest` on every release. The build and architecture tags move on a stable release tag (`refs/tags/v*` with no `-`), pushed or dispatched, and on a dispatch from the default branch; never on a prerelease tag or a dispatch from another branch. `tagplan` decides this from the ref, not the event, because the action's semver rules (`:latest` among them) key on the ref too. Deciding on the event let a dispatch on a release tag move `:latest` but leave `:pascal` and the other shortcuts on the previous build. **Analyzer concurrency (`ANALYZE_CONCURRENCY`, #1538).** One env var, read on BOTH sides and bounded `1-8` with a fall-back-to-1 (not a clamp) on anything empty, non-integer or out of range — `envInt` in `controller/src/config.ts`, `_bounded_int_env` in `docker/analyzer/server.py`. **The default of 1 is the pre-change station, byte for byte**, which is the whole reason the two code paths are kept side by side rather than unified: `music/analyze.ts` keeps its original one-ahead `prefetch()` loop verbatim at 1 and only takes `music/analyze-dispatch.ts` above it. Above 1 the pass admits jobs in **source order** through `dispatchAnalysis`, bounded by live count, and commits every outcome back **in source order too** — the systemic-failure guard (`failureCountsAgainstTrack`, the buffered `pendingFailureStamps`) reads a run of consecutive failures, so out-of-order commits would condemn tracks over a bad *pass*. The quiet gate is evaluated **before every admission and before that job's download** (`beforeStart`), so a paused pass never keeps pulling audio for work it isn't going to compute; its fail-open direction is untouched, and it still resolves through the one `analyze-quiet-pure.ts` decision. The win is specifically the **share-less remote topology**, where the path probe 422s and the analyzer fetches each track itself; a local shared-mount setup already overlapped via the prefetch, and **local `ANALYZE_PYTHON` stays single-flight regardless** (`backend === 'sidecar' ? requested : 1`) because one line-protocol stdio worker cannot multiplex. **The download cap (`ANALYZE_MAX_BYTES`, #1549) is the other two-sided env var**, and it is parsed with the same posture for the same reason: `envInt` in `music/analyzer.ts` for the controller's own prefetch, `_env_int` in `scripts/analyze_worker.py` when the worker fetches the audio itself, both falling back to the shared 12 MB default on anything empty, non-integer or below 1. The two used to disagree on a typo — TS `parseInt` produced **NaN**, which is false in both comparisons (cap off AND every file flagged incomplete, so outro analysis went off library-wide with nothing logged), while Python's bare `int()` RAISED and killed the download. `_env_int` matches `envInt`'s grammar rather than deferring to `int()`, which is looser (`1_000`, non-ASCII digits) and would put the two fetch paths back on different caps. Pinned by `scripts/analyzer-max-bytes.test.ts`, which drives both sides from one table. **The whole-file lane's vars are two-sided as well, with the same warn-and-fall-back posture** (`docs/internals/music.md`, the whole-file facets). `ANALYZE_WHOLE_FILE_CONCURRENCY` is bounded `1-32` on both sides (`envInt`, `_bounded_int_env`), and the sidecar advertises its own figure on `/health` for the controller to take the smaller. `ANALYZE_WHOLE_FILE_TIMEOUT_S` is bounded `30-7200` seconds by the sidecar (`_bounded_float_env`) and the worker (`_env_float`) alike. The sidecar hands its reading to every one-shot worker, so the two cannot disagree. The controller's `ANALYZE_WHOLE_FILE_TIMEOUT_MS` (`90000-7260000`) is the wait on the other side and is kept 60 s above it, so the analyzer reports its own timeout rather than the controller abandoning a run that is still going. **An incomplete native FLAC prefix gets one bounded PCM recovery (#1670).** A byte-capped FLAC can still describe hours of highly compressible audio, so decoding the whole prefix to a temporary WAV can expand a 12 MB input until it fills the analyzer's writable layer. Every one-shot predecode now gives ffmpeg a 63 MiB `-fs` stop target (one MiB of packet-boundary headroom) and accepts no finalized WAV above a hard 64 MiB ceiling. A known-incomplete FLAC may use the valid audio ffmpeg finalized at that stop; a complete/unknown input on the older libsndfile fallback may not, because accepting a shortened file would falsify its duration, CLAP placement and outro. That path instead retains its old per-load decoder when it reaches the byte target. FLAC recovery deliberately has **no time cap**: baseline analysis and the heavy vocal head still receive their full `ANALYZE_SECONDS`, and CLAP can still place start/middle/late windows across all recovered audio under the byte ceiling. If the decodable prefix would exceed that ceiling, CLAP's middle/late positions are taken from the bounded recovered span rather than the entire compressed prefix; that loss of far-prefix coverage is the deliberate cost of the disk bound. Outro and tail-vocal analysis were already disabled for `complete: false`, so their duration semantics do not change. Recovery keeps the native channel layout: loudness sees it unchanged and CLAP performs its established mono decode. Demucs is the one exception because its model accepts exactly stereo, so mono is duplicated and wider WAVEX layouts are folded across every channel into its private two-channel detection mix. The same URL-owned source file is removed if recovery or any later analysis step is interrupted, and `fetch_audio` owns its descriptor through `fdopen` so cleanup never closes a stale descriptor another thread may have reused. Pinned by `scripts/analyzer_decode_test.py`, including real frame-truncated FLAC, multichannel WAVEX and opt-in actual-model integration fixtures. The sidecar half is **N independent single-flight worker processes**, not one worker with a bigger queue — same `analyze_worker.py`, each with its own stdio lock, fronted by `AnalyzerWorkerPool`. Three rules that are expensive to rediscover: - **A recycling member is "coming back", not "gone".** `_acquire_worker` raises `WorkerUnavailableError` (→ the controller's clean fall-through, analysis row stays NULL) only when nothing is ready AND nothing is recycling. When a member is mid-recycle it **waits on the condition** instead, bounded by `recycle_loop`'s own 180s respawn budget and its `finally` that always clears the claim. At the default concurrency of 1 that recycle window is the entire pool, and failing fast there would 500 every request for up to three minutes — the single worker used to hold its request lock across the respawn for exactly this reason. Selection failing is therefore **not** retryable in `pool.request` (it would spin on the same verdict); a worker going bad *after* selection is, and picks another member. - **Reservation and the recycle claim are each taken without yielding**, which is what makes them mutually exclusive on the event loop: `reserve_if_available()` tests `available` and sets `_reserved` with no `await` between, and `recycle_loop` tests `_reserved` and sets `_recycling` the same way. Whichever lands first wins — admitted work finishes on that member, or the pool routes past it. Inserting an `await` into either sequence reintroduces the race. - **Capability aggregation reads the SELECTABLE members only, and only unanimity earns a `False`.** Iterating every configured member instead makes one booting or recycling worker report `None` for the whole pool, and the controller's tail-vocal backfill requires `=== true` — a healthy heavy pool would intermittently read as a stale analyzer image. And because `capability_errors` deliberately survives its own worker's respawn (#1300 bug 3), a single member's bad load hour would otherwise latch `False` pool-wide until the container restarts; a split verdict is `None` (some member can still serve it) and only an all-members loss — the lean-image case, where they share one build — is `False`. `/health`'s other aggregates follow the same shape: `analyze_models_resident` is an `all()` over ready members, `analyze_heavy_idle_s` the least-idle of them, `analyze_worker_recycles` a sum. `analyze_idle_s` is the recycle's own clock and is NOT the heavy one: seconds since the newest request of any kind on a ready member. The model release counts heavy use only (lean traffic every few seconds must not keep models resident), while the recycle counts every completed request, because a lean bpm/key pass leaves the same librosa/numba scratch behind and nothing but a respawn returns it. All of it is identical to the old single-worker answers at N=1. Pinned by `controller/scripts/analyzer_sidecar_contract_test.py`, which drives the real `StdioWorker` state transitions (not a stand-in) for the recycle cases. **Private station mode (#478).** `settings.privacy` holds two independent locks over ONE shared `password`: `privatePlayer` (the web player pages ask for it before rendering — shell-level in `PlayerShell`, rides `/state`, applies live) and `listenerAuth` (Icecast listener auth on every stream mount). Either lock being on requires a password — `settings.update()` throws otherwise, because a lock with no password behind it either fails every listener closed or renders a prompt nobody can satisfy. Listener auth uses Icecast **URL auth**, not htpasswd: `settings.update()` writes `state/icecast_listener_auth.txt`, and the broadcast entrypoint (+ AIO supervisor's `render_icecast()`, re-run on every pair relaunch) renders per-mount `` blocks pointing at `POST /listener-auth`. External clients send basic auth (`user:pass@`), the web player rides `?auth=` on the mount query (Icecast forwards the query string in the auth callback; Chromium ignores a `user:pass@` in an `