StreamSourceSequenceSettings interface

Settings for the StreamSourceSequence node. see NorskControl.streamSourceSequence()

Plays an ordered sequence of sources gaplessly. Companion to (and the recommended replacement for) the NorskControl.streamSwitchHard() playlist pattern. Downstream sees a single logical stream with stream keys stable across source turnover.

Unlike streamSwitchHard, SSQ has no per-pin hold/release/switch API surface — the client describes the sequence and the node runs it. The only client-driven action is advanceNow() to trigger an early cut at the next source’s next IDR.

Signature:

export interface StreamSourceSequenceSettings<Pins extends string> extends ProcessorNodeSettings<StreamSourceSequenceNode<Pins>>

Extends: ProcessorNodeSettings<StreamSourceSequenceNode<Pins>>

Properties

Property Type Description

Property	Type	Description
audioSilencePadGapThresholdMs?	number	(Optional) Audio silence-pad threshold. Audio gaps below this are sub-frame and not worth filling; the default 10 ms is appropriate for typical AAC frame durations.
audioSilencePadMaximumFillMs?	number	(Optional) Audio silence-pad cap. Gaps larger than this are almost certainly a bug (e.g. a wild PTS jump) and the node prefers to surface them as a gap rather than fill with arbitrary silence. Default 500 ms.
onAdvance?	(nowActive: Pins, lastSeenPts: number \| undefined) ⇒ void	(Optional) Fires when the node has handed off to a new active source. The pin in the callback is whichever source is now feeding the output. `lastSeenPts`, when present, is the last PTS (microseconds) the engine emitted from the PREVIOUS active pin — the source that just ended. Absent (`undefined`) on the very first Advance (no previous source). Clients use this for cross-switch PTS continuity: feed it back as `anchorPts` on a sibling switch’s `releasePreloaded` so the next pin’s video PTS picks up where the previous pin’s last PTS left off.
onPreloaded?	(pin: Pins, streamKeys: StreamKey[]) ⇒ void	(Optional) Fires when the engine holds a source pin (pre-warmed, queued, ready). Re-fires whenever the held pin’s stream complement changes so the client can wait for an expected shape (e.g. audio + video both present) before pausing the upstream and choosing release timing. Held pins remain held until the client calls `releasePreloaded(pin, { anchorPts })`. SSQ mirrors SSS in this respect — every pin (including the first one in the sequence) is held until explicitly released.
onSourceEnded?	(endedPin: Pins, lastSeenPts: number) ⇒ void	(Optional) Fires when the engine’s currently-active source has fully drained (natural EOF or synthetic via `endCurrentSource`). `endedPin` is the pin that just ended; `lastSeenPts` is the last PTS (microseconds) the engine emitted from it. Feed it back as `anchorPts` on the destination switch’s `releasePreloaded` for PTS-continuous handoff (same-mode SSQ→SSQ or cross-mode SSQ→SSS). SSQ no longer auto-advances from the declared sequence — every transition is the client’s responsibility. After `onSourceEnded` fires, no frames are being emitted until `releasePreloaded` is called.
onStreamsChanged?	(pin: Pins, streamKeys: StreamKey[]) ⇒ void	(Optional) Active-pin sibling of `onPreloaded`: fires when the currently- active pin’s seen-stream-key set changes — typically the first time each stream emits a frame on the active pin after a paused-then-resumed upstream. Distinct from `onAdvance` (source change only) and `onPreloaded` (held pins only). The most common scenario this signals is a passthrough preload that goes directly active (no holding window) because it was the only source in the sequence — when the client later resumes the paused upstream, this callback fires as each stream’s first frame arrives. Without it, downstream switches that gate on the active pin’s stream complement have no event to react to.
outputSource	string	The source name to give the unified output stream.
reorderWindowMs?	number	(Optional) Reorder window for the internal cross-source DTS sort. Default 200 ms — sized to cover B-frame ptsOffset plus cross-source jitter at the boundary, while staying small enough for sub-second steady-state latency.
sources	{ pin: Pins; transitionFromPrevious?: 'hardCutAtEof' \| 'hardCutAtIdr'; }[]	The ordered sequence of source pins to play. The first entry plays first; later entries activate as earlier ones reach EOF (or via the StreamSourceSequenceNode.advanceNow() trigger). May be empty at construction and appended to later via StreamSourceSequenceNode.appendSource().
startAncillaryStreamId?	number	(Optional) Starting stream ID for the unified output ancillary stream.
startAudioStreamId?	number	(Optional) Starting stream ID for the unified output audio stream.
startSubtitleStreamId?	number	(Optional) Starting stream ID for the unified output subtitle stream.
startVideoStreamId?	number	(Optional) Starting stream ID for the unified output video stream.
stripVolatileMetadata?	boolean	(Optional) When true, strip volatile metadata fields (currently `bitrate` on compressed audio/video) from the output context so downstream consumers don’t see spurious context changes when the active source’s instantaneous bitrate fluctuates. Defaults to false.

audioSilencePadGapThresholdMs?

number

(Optional) Audio silence-pad threshold. Audio gaps below this are sub-frame and not worth filling; the default 10 ms is appropriate for typical AAC frame durations.

audioSilencePadMaximumFillMs?

number

(Optional) Audio silence-pad cap. Gaps larger than this are almost certainly a bug (e.g. a wild PTS jump) and the node prefers to surface them as a gap rather than fill with arbitrary silence. Default 500 ms.

onAdvance?

(nowActive: Pins, lastSeenPts: number | undefined) ⇒ void

(Optional) Fires when the node has handed off to a new active source. The pin in the callback is whichever source is now feeding the output.

lastSeenPts, when present, is the last PTS (microseconds) the engine emitted from the PREVIOUS active pin — the source that just ended. Absent (undefined) on the very first Advance (no previous source). Clients use this for cross-switch PTS continuity: feed it back as anchorPts on a sibling switch’s releasePreloaded so the next pin’s video PTS picks up where the previous pin’s last PTS left off.

onPreloaded?

(pin: Pins, streamKeys: StreamKey[]) ⇒ void

(Optional) Fires when the engine holds a source pin (pre-warmed, queued, ready). Re-fires whenever the held pin’s stream complement changes so the client can wait for an expected shape (e.g. audio + video both present) before pausing the upstream and choosing release timing.

Held pins remain held until the client calls releasePreloaded(pin, { anchorPts }). SSQ mirrors SSS in this respect — every pin (including the first one in the sequence) is held until explicitly released.

onSourceEnded?

(endedPin: Pins, lastSeenPts: number) ⇒ void

(Optional) Fires when the engine’s currently-active source has fully drained (natural EOF or synthetic via endCurrentSource). endedPin is the pin that just ended; lastSeenPts is the last PTS (microseconds) the engine emitted from it. Feed it back as anchorPts on the destination switch’s releasePreloaded for PTS-continuous handoff (same-mode SSQ→SSQ or cross-mode SSQ→SSS).

SSQ no longer auto-advances from the declared sequence — every transition is the client’s responsibility. After onSourceEnded fires, no frames are being emitted until releasePreloaded is called.

onStreamsChanged?

(pin: Pins, streamKeys: StreamKey[]) ⇒ void

(Optional) Active-pin sibling of onPreloaded: fires when the currently- active pin’s seen-stream-key set changes — typically the first time each stream emits a frame on the active pin after a paused-then-resumed upstream. Distinct from onAdvance (source change only) and onPreloaded (held pins only).

The most common scenario this signals is a passthrough preload that goes directly active (no holding window) because it was the only source in the sequence — when the client later resumes the paused upstream, this callback fires as each stream’s first frame arrives. Without it, downstream switches that gate on the active pin’s stream complement have no event to react to.

outputSource

string

The source name to give the unified output stream.

reorderWindowMs?

number

(Optional) Reorder window for the internal cross-source DTS sort. Default 200 ms — sized to cover B-frame ptsOffset plus cross-source jitter at the boundary, while staying small enough for sub-second steady-state latency.

sources

{ pin: Pins; transitionFromPrevious?: 'hardCutAtEof' | 'hardCutAtIdr'; }[]

The ordered sequence of source pins to play. The first entry plays first; later entries activate as earlier ones reach EOF (or via the StreamSourceSequenceNode.advanceNow() trigger). May be empty at construction and appended to later via StreamSourceSequenceNode.appendSource().

startAncillaryStreamId?

number

(Optional) Starting stream ID for the unified output ancillary stream.

startAudioStreamId?

number

(Optional) Starting stream ID for the unified output audio stream.

startSubtitleStreamId?

number

(Optional) Starting stream ID for the unified output subtitle stream.

startVideoStreamId?

number

(Optional) Starting stream ID for the unified output video stream.

stripVolatileMetadata?

boolean

(Optional) When true, strip volatile metadata fields (currently bitrate on compressed audio/video) from the output context so downstream consumers don’t see spurious context changes when the active source’s instantaneous bitrate fluctuates. Defaults to false.