StreamSourceSequenceNode class

StreamSourceSequence — plays an ordered sequence of sources gaplessly.

Signature:

export declare class StreamSourceSequenceNode<Pins extends string> extends ProcessorMediaNode<Pins>

Extends: ProcessorMediaNode<Pins>

Methods

Method Modifiers Description

Method	Modifiers	Description
advanceNow()		Manually trigger an early cut to the next source in the sequence, at that source’s next IDR. The previous source’s frames after that IDR (in display order) are dropped.
appendSource(pin, transitionFromPrevious)		Append a source to the end of the sequence. The pin must be subscribed upstream (via `subscribeToPins`) for its frames to flow.
endCurrentSource()		End the currently active source immediately. The engine fires a synthetic `PreloadEnded` for the active pin, which surfaces as the existing `onAdvance` callback with `lastSeenPts` set to the source’s last rebased output PTS (engine’s `state.latestOutputPts` captured atomically at the synthetic-end moment). After this call, no further frames from the just-ended pin flow downstream — the engine inserts the tag into its `trimmedSources` map so any in-flight upstream frames are silently dropped at `processInput`. Useful for cross-node manual cuts where the caller wants to anchor the next node’s `releasePreloaded` at the just-ended source’s PTS (mirrors SSS’s `endCurrentSource` — symmetric API). If a `releasePreloaded(pin, ...)` was previously queued via `pendingRelease`, the `Advance` callback fires for that pin; otherwise it fires for the sequence-next pin. Idempotent — calling a second time while the tag is already ended is a silent no-op (logged engine-side, no callback re-fires). No-op when there is no active source.
endSequence()		Signal that no further sources will be released onto the output. The engine ends the current active source (synthetic `PreloadEnded`, mirroring `endCurrentSource`) and then emits a terminal empty context downstream. Consumers (HLS / CMAF / SRT muxers) take that empty context as their cue to flush the last segment and tag end-of-stream cleanly. Distinct from `close()`: `endSequence()` lets the SSQ keep running (e.g. for callers that want to observe downstream finalisation before tearing the node down). Idempotent and a no-op if a sequence-end is already in flight.
releasePreloaded(pin, options)		Tell the engine which pin to release on the NEXT source boundary, overriding the autopilot’s default "next-pin-from-sequence" pick for that single transition. Mirrors SSH’s `releasePreloaded` semantics: the client is responsible for any upstream pause/play around the release, and chooses when each held pin should advance onto the output. Pair with `onPreloaded` and an upstream `pause()` to backpressure long-lived held sources. `options.anchorPts` — optional video-display PTS anchor (in microseconds) for the released pin’s rebase. Used by clients that need cross-switch PTS continuity (e.g. when an HSS downstream is alternating between SSS-output and SSQ-output and the boundary needs the OTHER switch’s last PTS as the anchor). Phase 3a note: SSQ accepts this on the wire but does not yet apply it — the SSQ release path runs through the autopilot’s setHoldDecision, which isn’t anchor-aware yet. Phase 3b lands the full plumbing.

advanceNow()

Manually trigger an early cut to the next source in the sequence, at that source’s next IDR. The previous source’s frames after that IDR (in display order) are dropped.

appendSource(pin, transitionFromPrevious)

Append a source to the end of the sequence. The pin must be subscribed upstream (via subscribeToPins) for its frames to flow.

endCurrentSource()

End the currently active source immediately. The engine fires a synthetic PreloadEnded for the active pin, which surfaces as the existing onAdvance callback with lastSeenPts set to the source’s last rebased output PTS (engine’s state.latestOutputPts captured atomically at the synthetic-end moment).

After this call, no further frames from the just-ended pin flow downstream — the engine inserts the tag into its trimmedSources map so any in-flight upstream frames are silently dropped at processInput.

Useful for cross-node manual cuts where the caller wants to anchor the next node’s releasePreloaded at the just-ended source’s PTS (mirrors SSS’s endCurrentSource — symmetric API).

If a releasePreloaded(pin, ...) was previously queued via pendingRelease, the Advance callback fires for that pin; otherwise it fires for the sequence-next pin.

Idempotent — calling a second time while the tag is already ended is a silent no-op (logged engine-side, no callback re-fires). No-op when there is no active source.

endSequence()

Signal that no further sources will be released onto the output. The engine ends the current active source (synthetic PreloadEnded, mirroring endCurrentSource) and then emits a terminal empty context downstream. Consumers (HLS / CMAF / SRT muxers) take that empty context as their cue to flush the last segment and tag end-of-stream cleanly.

Distinct from close(): endSequence() lets the SSQ keep running (e.g. for callers that want to observe downstream finalisation before tearing the node down). Idempotent and a no-op if a sequence-end is already in flight.

releasePreloaded(pin, options)

Tell the engine which pin to release on the NEXT source boundary, overriding the autopilot’s default "next-pin-from-sequence" pick for that single transition. Mirrors SSH’s releasePreloaded semantics: the client is responsible for any upstream pause/play around the release, and chooses when each held pin should advance onto the output. Pair with onPreloaded and an upstream pause() to backpressure long-lived held sources.

options.anchorPts — optional video-display PTS anchor (in microseconds) for the released pin’s rebase. Used by clients that need cross-switch PTS continuity (e.g. when an HSS downstream is alternating between SSS-output and SSQ-output and the boundary needs the OTHER switch’s last PTS as the anchor). Phase 3a note: SSQ accepts this on the wire but does not yet apply it — the SSQ release path runs through the autopilot’s setHoldDecision, which isn’t anchor-aware yet. Phase 3b lands the full plumbing.