The mixer knobs that are still constants

[robert-dean]

Written: 2026-08-09, when VOICE_GAIN_DB became the fourth of them.
Updated: 2026-08-11, when the containers learned to restart themselves onto a re-rendered config,
which removes the reason this was deferred.
Updated: 2026-10-10, when #421 made the duck a level rather than an amount and added two more.
State of the tree: six values that decide how a break sounds are hardcoded in
apps/api/src/modules/stream/stream.service.ts, materialized into radio.env, and changed only by
editing code and deploying.

---

What they are

Constant	radio.env key	What it decides
TALK_OVER_TRACKS	TALK_OVER_TRACKS	whether the DJ talks over the record or between records in silence
DUCK_GAIN_DB	DUCK_GAIN_DB	the DEEPEST the bed may go under the voice, however loud it is (it was the whole duck before #421)
DUCK_MIN_DB	DUCK_MIN_DB	the SHALLOWEST: a quiet intro already under the target still dips this far
DUCK_BED_LUFS	DUCK_BED_LUFS	the level the bed is ducked TO, for a cue that does not carry its own
DUCK_FADE_MS	DUCK_FADE_MS	how long that ramp takes
VOICE_GAIN_DB	VOICE_GAIN_DB	trim on the voice after the mic chain

Two of the six are not as constant as the table makes them look. DUCK_BED_LUFS is only a fallback:
the app stamps every cue it arms with its own figure (deadair_duck_bed_lufs, from duckBedLufsFor
in playout/gain.ts), so the bed already follows playout.targetLufs and the speech trim without a
restart. Making it a setting changes only what an unstamped cue gets. And DUCK_FADE_MS is exported,
because the talk-up allows for the bed coming back up after the last word, so a setting for it has to
reach the talk-up as well as radio.env, or the two ends disagree about how long the ramp is.

Every one of them is something an operator tunes by ear, over several listens, on their own library
and their own speech engine. That is exactly the profile of a setting and exactly not the profile of
a constant.

The seam

STREAM_KEYS in apps/api/src/modules/stream/stream.settings.ts
and resolveStreamSettings beside it. Every other value the materializer writes already comes
through there — the mount, the bitrate, the station name, all five secrets — so these six are the
only stream values that bypass a mechanism already built for them. Adding them is a STREAM_KEYS
entry, a field on StreamSettings, a default, and passing them through playoutConfig instead of
reading a module constant.

Why it is not just that

radio.liq reads all six at startup. So a settings row that changed while Liquidsoap was
running would re-render radio.env (the app already does that on a settings write) and change
nothing anyone can hear until the container restarts. A console knob that silently does nothing is
worse than no knob.

Which made the real work the restart trigger — and that trigger was built on 2026-08-11, for a
different reason, and this file is smaller because of it. stream/config-watch.sh runs inside each
stream container, polls the mtime of the file it was started from, and stops its own container when
it moves; the compose restart policy brings it back on the new config. No Docker socket anywhere,
and nothing can restart anything but itself, which is why the authority could live there and not
here. stream.staleness.ts is the second line behind it: it warns only once the drift has outlived
DRIFT_GRACE_MS, by which point the self-restart demonstrably did not happen.

So the remaining work is the small half after all: six STREAM_KEYS entries, six fields on
StreamSettings, six defaults, and passing them through playoutConfig. Writing the setting
re-renders radio.env, the watch sees the mtime move, and Liquidsoap comes back on the new value
without anybody being asked to restart anything.

One decision is left, and it is about cost rather than mechanism. A restart takes the station off
air for as long as the container takes to come back, which is audible to anyone listening. Three
answers, still undecided:

• Let it restart immediately, and have the console say plainly that saving these six interrupts the
  broadcast. Honest, and puts the cost in front of the person choosing it.
• Hold the re-render until the audience gate closes, so the restart is spent on an empty mount. Free
  when nobody is listening, and means a saved change can sit unapplied for hours with no visible
  reason why.
• Make the values live in radio.liq — read per use from a ref, refreshed by a /control/* call —
  so no restart is needed at all. The most work, and the only answer with no cost to a listener.
  Check how duck_gain_db is used before assuming it is possible: lin_of_dB is evaluated once,
  when the ramp closure is built.

What must NOT move

CONTROL_TTL_S and PLAYOUT_PREFETCH look like they belong on the same list and do not. Both come
from constants in
apps/api/src/modules/playout/liquidsoap.control.ts
that the app uses for its own behaviour as well: the TTL is what the pusher renews against, and the
prefetch is the same number as its push lead. They are shared deliberately, so the two ends of the
bridge cannot disagree. Splitting either into a setting gives it two owners and one place for them
to drift, and the failure — a lease that expires between renewals, a skip that lands on an unfetched
item — is intermittent and hard to attribute.

---

Moved from docs/todo/mixer-settings-in-db.md. The file as it last stood: https://github.com/robert-dean/deadair/blob/71e431d45ce7b35a189c7d226832ec4a6247e9dc/docs/todo/mixer-settings-in-db.md

[robert-dean]

Closing: built in #808, and the deciding question turned out not to need answering.

The duck was already live in radio.liq: ducked() recomputes its depth and step every 25 ms tick, and the bed level already rode each cue as deadair_duck_bed_lufs. So none of the three restart answers was needed. The duck's figures ride the cue too, and a change is heard on the next break with no restart.

• Settings, under Playout: playout.duckUnderVoiceDb (10), playout.duckDeepestDb (-18), playout.duckShallowestDb (-3) and playout.duckFadeMs (300). Each is clamped to a declared range. A shallowest set deeper than the deepest is answered by the deepest.
• The bounds ride the cue as deadair_duck_gain_db and deadair_duck_min_db. The fade rides the arm as X-Voice-Fade-Ms, because the cue fires that long before its tags are read.
• The fade has two readers, as this discussion warned. The director reads it once per pass, times every talk-up and talk-out with it, and carries it on the cue (RundownItem.voice.duckFadeMs) to the arm. A change made while a cue waits for its record cannot split the timing from the mixer.
• The radio.env keys of the same names are now only what a cue armed without them gets, and they take the settings' defaults.

Three of the six went differently:

• DUCK_BED_LUFS is not a setting. Every cue is stamped, so it is a fallback nothing reaches. The knob an operator actually wants is the distance under the voice, which is now playout.duckUnderVoiceDb.
• VOICE_GAIN_DB is retired. playout.speechTrimDb moves the voice on both routes a break takes, and the distance under the voice moves the record. Removing the key costs one Liquidsoap restart on that upgrade.
• TALK_OVER_TRACKS stays a constant. Only the mixing half of false was ever built: nothing in the app pauses playout to leave the gap that mode assumes, so a switch would cut the voice over a record that keeps playing underneath. The comments that claimed otherwise are corrected. Building the gap, or removing the mode, would be an idea of its own.

CONTROL_TTL_S and PLAYOUT_PREFETCH were left alone, as asked. stream/duck.check.py gained a break whose cue carries its own deepest bound and reads it holding.