Enum AlignmentPolicy

pub enum AlignmentPolicy {
    None,
    DelayLower {
        maximum_difference: usize,
    },
}

Expand description

Optional latency alignment between the outgoing and incoming engines (see convolution_transition_with_continuity).

Under AlignmentPolicy::DelayLower the audio endpoint keeps two delay lines of maximum_difference + maximum_frames frames per channel, prepared at construction; each records its engine’s raw output. When a transition from latency a to latency b starts, the lower-latency path is delayed by |a - b| frames for the whole fade, so both paths are aligned at max(a, b):

b > a: the old path is delayed from the fade start; the output latency changes from a to b at the start frame (the old path repeats its last b - a output frames while its gain is near one).
b < a: the new path is delayed during the fade; the output latency stays a and changes to b at the frame where the fade completes (the delay is released while only the new path is audible, skipping a - b of its output frames).
a cut (frames == 0) changes the output latency at the start frame, with no delay (an unaligned jump).

Without PrimingPolicy::History the incoming engine has no output from before the fade start, so when b < a its delayed path reads zeros for the first a - b fade frames: it stays silent while its gain rises, and if a - b is at least the fade length it contributes nothing before the release, deepening the level dip. Priming fills those frames.

Each change is reported through TransitionStatus::output_latency_change and TransitionEvent::OutputLatencyChanged, and ConvolutionTransition::output_latency_samples gives the current value. Outside fades no delay is applied. A proposal whose latency differs from the current engine’s by more than maximum_difference is refused at the block boundary where it would start (only the audio endpoint knows the current engine): it is returned unused as ReturnReason::Refused with TransitionEvent::AlignmentRefused, through a reserved returned slot; if none is free it stays where it is and the boundary reports retirement_blocked. Under LatencyPolicy::RequireEqual no difference can arise and the policy has no effect.

Cost: every block copies each engine’s output through its line, proportional to the block. The boundary that takes a proposal forgets the incoming line and ConvolutionTransition::reset forgets both in constant time: each line tracks how many frames were written since it was forgotten and reads older positions as zero, so no clear proportional to the prepared size (channels * (maximum_difference + maximum_frames) samples) is performed. No allocation is performed.