StreamSwitchSmoothNode class

activeSource

Pins | undefined

The currently active source

endCurrentSource()

End the currently active source immediately. The engine fires a synthetic PreloadEnded for the active pin, which surfaces as the existing onSourceEnded(pin, lastSeenPts) 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 (e.g. an HSS downstream alternating between SSS- and SSQ-output — the SSS’s lastSeenPts becomes the SSQ’s anchorPts).

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.

Resolves true when there was a source to end (its source-ended callback follows), false when there was none (no callback will come).

releasePreloaded(pin, options)

Release held frames for a preloaded pin, allowing them to flow through with rebased timestamps.

options.anchorPts — optional video-display PTS anchor (in microseconds) overriding the engine’s internal per-pin videoPrevEndByTag tracking for this release. Used by clients needing cross-switch PTS continuity (e.g. when an HSS downstream alternates between SSS-output and SSQ-output and the boundary needs the OTHER switch’s last PTS as the anchor). Audio + DTS anchors still use internal tracking.

silence()

Park the switch in a silent state and forget all internal clock and audio-transition bookkeeping. The next switchSource will be processed as a cold-start switch — the new pin’s first emitted frame becomes the new PTS baseline rather than being interpreted as a continuation of the previously-active source’s timeline.

Use this when the switch is being parked between consumer windows — e.g. when an HSS downstream is routing to a sibling switch and this switch’s output is not on the wire. Without silence, the switch’s compose chain retains latestPts etc. from its previous activeSource; when it later resumes for an anchored cross-mode handoff, that stale anchor collides with the new pin’s intended one and produces a multi-second forward jump that downstream encoders / muxers report as a timestamp discontinuity.

After this call, until a subsequent switchSource or releasePreloaded: no video frames flow, and the audio output carries on as silence - no pin is heard. The switch remains subscribed to its inputs — no upstream teardown.

switchSource(newSource, options)

Switches the source used for the current output of this node.

The target pin must already be carrying streams. A pin whose source has not produced a context yet — a fileMp4 opened with start: 'paused' and not yet played, an SRT caller still connecting — is refused by the engine ("Source not present in subscribed pins" or "Source audio/video not active"), and the switcher stays where it was. The refusal is reported through StreamSwitchSmoothSettings.onSwitchError and returned as the StreamSwitchResult; the promise resolves either way once the engine has answered, never rejects. To switch to a source that is about to appear, sequence on the pin’s context rather than on the promise: play the source, wait for it in StreamSwitchSmoothSettings.onInboundContextChange (or StreamSwitchSmoothSettings.onSourceChanged), then switch. reflects the engine’s answer, not the request.