Source Blend

Definition

Source Blend is a confidence modifier that tells the engine how cleanly the current audio signal can be attributed to a single source.

It answers:

“How much is a DJ mix currently compromising the model’s readings?”

Source Blend is a continuous value from 0.0 to 1.0:

  0.0   Single clean source.
        One track playing. The model's readings are fully reliable.

  0.5   Two sources equally present.
        Incoming and outgoing tracks are at similar level.
        The model is measuring a composite signal.

  1.0   Maximum blend (reserved upper bound).
        In practice engines usually stay below this.

Source Blend does not directly change reported story state. It annotates how much to trust rapid state changes while a mix is in progress.

Why This Exists

During a DJ mix, the summed output contains two overlapping kick sources. The engine correctly measures the composite signal, but this introduces ambiguity:

Presence gate instability near threshold crossings
Weight and variance distortion during overlap windows

Source Blend gives consumers and engine logic a confidence context for these moments.

Derivation

Primary source:

Pro DJ Link crossfader position (preferred, reliable)

Fallback:

Audio-only competing transient heuristic (best effort)

When fallback mode is used, emit source_blend_reliable: false.

Temporal Threshold Effect

Source Blend widens confirmation windows dynamically:

effective_threshold = base_threshold * (1 + blend * threshold_scale_factor)

Default:

threshold_scale_factor = 1.5

Scaling policy:

presence_open_beats: scaled
presence_close_beats: scaled
variance_confirm_bars: scaled, capped at 2x base
sustain_confirm_bars: scaled, capped at 2x base (for dry|mid|wet)
reverse sustain confirmation: intentionally not widened by source blend
weight_band_confirm_bars: not scaled

The design intent is conservative transitions during active mixes, while still allowing genuine weight-band changes to confirm at normal speed.

Stream Output

Added in stream.frame:

source_blend: number [0..1]
source_blend_reliable: boolean

stream.transition schema is unchanged. Blend context is carried by preceding stream.frame events.

Song Spec Integration

For source=spec, segments may include:

source_blend_start
source_blend_end
source_blend_peak_beat
source_blend_reliable

Defaults when omitted:

source_blend_start: 0.0
source_blend_end: 0.0
source_blend_peak_beat: unset
source_blend_reliable: true

See Song Spec Sheet.

Engine Configuration

engine:
  source_blend:
    enabled: true
    threshold_scale_factor: 1.5
    crossfader_curve: aggressive    # aggressive | linear | gentle
    audio_fallback: true

Reactive Audio-Only Mode

When crossfader data is unavailable, source blend can be estimated from competing kick transients.

In this mode:

emit source_blend
emit source_blend_reliable: false
keep transition logic conservative through threshold scaling

Implementation Notes

Compute source blend before temporal threshold checks.
Apply light smoothing to blend output to reduce micro-jitter.
Return to base thresholds when blend stabilizes back at 0.0.
Edge case: reverse sustain confirmation is intentionally not widened by source blend.
Rationale: reverse swells are short-lived transitional cues and should remain detectable during crossfades.
1-2 beat reverse events may still fail to confirm at a 1-bar reverse threshold by design; 4-beat reverse events should confirm reliably.
For deterministic track timing, prefer source=spec playback where reverse windows and blend ramps are authored explicitly.

enter passphrase