Crossfades between rundown items

[robert-dean]

Crossfades between rundown items

Status (2026-10-10)

The plain rung is built, and this discussion is now about what is left above it. What shipped,
so nothing below has to re-derive it:

• The blend length is a property of the pair. apps/api/src/modules/playout/crossfade.ts sizes
  each boundary as min(outgoing.outro, incoming.intro) from the four measured cue points, and
  annotate.ts stamps it twice, as liq_cross_end_duration on the outgoing record and
  liq_cross_start_duration on the incoming one (annotate.ts:469-507). A boundary with no blend is
  stamped a tenth of a second rather than zero, because a zero-length cross never becomes ready
  and drops the station onto the local bed.
• stream/radio.liq holds the cross, with type="log", curve=6.4 rather than sin, which is
  a complementary pair and measured -3.08 dB at the midpoint. Whether a broadcast blends at all is a
  resolveRules field, so an album stays cold.
• The head and tail trim: the app stamps liq_cue_in / liq_cue_out.
• The cross does not move the voice clock. stream/voicecue.check.liq measured it: a cue armed
  six seconds into a record with a four second blend in and an eight second blend out lands at six
  seconds with no correction. The long argument that it did, and that kept this deferred for months,
  is in the discussion's history and is not repeated here.
• A long record fades out at a show boundary instead of being cut (Fade a long record out at the show boundary, instead of cutting it #406): /control/skip takes
  an optional x-fade-ms. The two crossfade harnesses in stream/ were re-synced with radio.liq
  in stream: re-sync the crossfade harnesses, and measure a blend whose stamps disagree #517.

What is left: the two rungs above the plain fade, the anchor quantising they want, the drift in
on_air_elapsed, and /control/unpush. Each has its own section below.

---

What the blend does inside the buffer

Added 2026-08-11. The built half decides how LONG the overlap is. This decides what happens
during it, and it is a separate question with a separate answer. Part of it needs the beat layer in
track-analysis rather than only the four cue points, and the plain fade
that shipped is the bottom rung of the ladder below rather than a different design.

Where the beat layer stands, 2026-10-10: beat_this is pinned and installed in
analysis/Dockerfile (licence reasoning in analysis/requirements.txt), but analysis/measure.py
emits no beats, downbeats or tempo yet, and nothing in apps/api reads a beat confidence. So the
beat-matched rung and the anchor quantising are still blocked on #45. The filtered handover is not
(see the correction below).

A ladder gated on evidence, not on preference

The station should attempt the most ambitious transition the measurement supports and no more.
Three rungs, checked most-disqualifying first:

Rung	What it does	Gate
Plain fade (BUILT)	equal-power blend over the buffer	anything below, or no analysis at all
Filtered handover	quantised anchors, filter sweep, bass handover	tempo ratio within about 4% after octave normalisation, and at least one side confident
Beat-matched	the above, plus a tempo nudge to lock the grids	both sides confidently measured

The numbers that work, from an implementation running against real libraries: a tempo outside
40-220 BPM disqualifies outright, beat confidence below about 0.2 on both sides drops to a plain
fade, and below about 0.55 on either side blocks beat-matching while still permitting the filtered
handover. Treat them as starting points rather than as findings, but keep the shape, because the
shape is the part that matters: missing evidence degrades to a defined behaviour instead of being
guessed at, and a tempo from metadata alone can never authorise beat-matching. That last rule is
why track-analysis stores provenance beside the value.

Corrected 2026-08-11: the middle rung does not need the beat layer, and the table above is wrong
to gate it on tempo. Read the three moves in "Three moves on the outgoing track" below and ask what
each one reads. The low-pass sweep is driven by position within the buffer. The mid-band duck is
driven by a level follower on the incoming track. The bass handover switches once at a fixed
fraction through the overlap. None of them reads a beat, a downbeat or a tempo. The tempo gate is
inherited from beat-matching, which is the rung above, and applying it here refuses a spectral
handover on precisely the pairs that most need one: two records at incompatible tempos, where a
level-only crossfade sounds worst.

So there is a rung between 1 and 2 that is available today, with no beat layer and no licence
question: everything in "Three moves" below, gated on nothing. It is not built because it is engine
work needing the filter chain per transition rather than on the bus, and because whether Liquidsoap
2.4 will modulate a filter cutoff inside a transition function is unverified. That wants a spike
before it wants a design. The bass handover is the part worth having: two basslines summing through a
six-second overlap is the one audible defect the plain rung cannot fix. radio.liq:790-795 says the
same thing where the transition is defined, and points here.

Two mechanics that are not obvious and are cheap once known:

• Normalise tempo into one octave before comparing. A 63 BPM record against a 126 BPM one is a
  match, counted the way a DJ counts it, and a naive ratio calls it a mismatch and drops a rung for
  no reason.
• The tempo nudge is a time-stretch, not a resample. Stretching without shifting pitch, inside
  the overlap only, is a beat-match. Changing playback rate is a detune, and it is audible on
  anything with a sustained note.

Quantise the anchor, do not just fade at a time

A blend that starts at an arbitrary instant sounds like a blend. One that starts on a bar line
sounds intentional. Snap the transition point to the nearest phrase boundary within about four
beats, failing that to the nearest downbeat within about two, failing both use the raw time. The
tolerances are what stop quantisation from dragging the anchor somewhere musically worse than where
it started.

This one does need the beat layer: a phrase boundary and a downbeat are both outputs of it.

Three moves on the outgoing track, and one of them is not a fade

For the filtered handover, the useful part is spectral rather than level:

• A low-pass sweep on the outgoing track, exponential in frequency, ending near the bass
  crossover. The record thins out and recedes rather than merely getting quieter.
• A mid-band duck, up to about 6 dB, scaled by the incoming track's own power, so the two do not
  compete where voices and guitars live.
• A bass handover that switches once, roughly 40% through the overlap, rather than crossfading.
  Two basslines summing is the classic mud, and this is the single cheapest fix for it. It is also
  the one move here that a level-only crossfade cannot approximate at all.

All three are engine work in radio.liq, not app work, and they need the filter chain to be per
transition rather than on the bus.

What this does to the length rule

buffer = min(outgoing.outro, incoming.intro) stays the rule for the plain rung. The other two
rungs want a length in BEATS rather than seconds, because the whole point is that the overlap lines
up with the music: roughly 8 beats for a compatible pair, 16 when the keys are distant or both sides
are singing, converted to seconds at the matched tempo and then clamped into the same 4-12 second
window the measurement produces. The clamp is what keeps the two rules from disagreeing, and the
min() above remains the ceiling in every case, so a blend still cannot eat a cold opening.

Engine constraints, so they are not rediscovered

Measured against Liquidsoap 2.4.x, which is what stream/Dockerfile pins. Any rung above the plain
fade is built on the same operator, so these bind it too:

• The low-level cross, not the crossfade wrapper. crossfade(smart=false) silently routes
  through its own internal simple transition and ignores a custom callback entirely, so a transition
  function passed to it appears to do nothing and there is no error to explain why.
• persist_override=true is required on 2.4. Without it the duration override is reset before
  it sizes the stamped track's own end-of-track buffer, so a per-item duration is accepted and then
  not used. The flip side is that a stamp lingers over later unstamped tracks, so every pushed item
  has to carry one, which for us is automatic, since every item goes through itemAnnotations.
• The fade must span the ENTIRE cross buffer. A fade shorter than the buffer leaves the outgoing
  track at full level while the incoming ramps in, which sums to about +6 dB and is audible as a
  lurch on every transition. To vary the blend, vary the buffer, never the fade inside it. A filter
  sweep is not a fade and is not bound by this, but the level envelope under it still is.
• cross presents its output as one never-ending track. Anything track_sensitive placed above
  it never sees another boundary. Our lease gate and bed fallback are both
  track_sensitive=false already, so they are unaffected, but this is the trap for anything added
  above the cross later.

on_air_elapsed runs about 3% slow

on_air_elapsed in radio.liq counts fixed ticks rather than measuring elapsed time: a thread adds
voice_tick (0.1s) on a thread run every=voice_tick (radio.liq:401-407), and the ticks arrive
less often than the count assumes. So a talk-up drifts later the further into a record it
sits: a fifth of a second at 6s, two thirds at 20s. Measured twice by voicecue.check.liq, and
still the code on 2026-10-10.

Fixing it trades away the clock-step immunity that construct exists for, so it is a decision rather
than a bug. Reading a wall clock at the hook and subtracting would be exact, and would also jump
whenever the host's clock is stepped, which is the failure the tick counter was chosen to be immune
to. A monotonic source would answer both, if Liquidsoap 2.4 exposes one to a script; that is the
thing to check first. Whatever replaces it must stay a WALL clock zeroed in the on_track hook, not
a source position: that is why the cross does not move it, and a source position would bring back
exactly the error the measurement above ruled out.

Retracting one queued item by request id

/control/push already answers with the rid Liquidsoap assigned, and drop_queued in radio.liq
already does per-request removal, so a /control/unpush taking a single rid is a small addition. It
is not built because nothing in the app wants it: the only retraction today is "drop the whole
running order", which /control/flush does (apps/api/src/modules/playout/liquidsoap.control.ts).
A caller would appear if the director ever edited a lineup that was already partly handed over.

---

Moved from docs/todo/crossfades.md. The file as it last stood: https://github.com/robert-dean/deadair/blob/71e431d45ce7b35a189c7d226832ec4a6247e9dc/docs/todo/crossfades.md. Rewritten 2026-10-10 down to what is still open; the full earlier text is in this discussion's edit history.

[robert-dean]

Status check, 2026-09-22 (main at 23b983e)

Done: the equal-power blend with its length taken from both records, and the head/tail trim (the app stamps liq_cue_in / liq_cue_out).

Still open: the filtered handover (low-pass sweep, mid duck, bass handover) and beat matching; the ~3% clock drift (on_air_elapsed still adds a fixed 0.1s per tick); /control/unpush.