@seydx/rtsp

Appearance

@seydx/rtsp / Relay

Class: Relay ​

Defined in: relay.ts:204

Single-source, multi-sink media relay.

Connects one upstream source and fans its packets out to many sinks while holding exactly one upstream connection regardless of how many consumers are attached. The upstream is lazy by default: it opens when the first sink is piped and, after the configured idle timeout, closes once the last sink leaves. Slow sinks are isolated by per-sink queues and re-synced at the next keyframe rather than stalling the whole fan-out.

Examples ​

typescript
import { Relay } from '@seydx/rtsp';

const relay = new Relay({ source });
relay.pipe(sink);
await relay.start();
typescript
import { Relay } from '@seydx/rtsp';

const relay = new Relay({ source, idleTimeout: 5000 });
const server = await relay.serveRtsp({ port: 8554, path: 'live' });

See ​

Extends ​

Constructors ​

Constructor ​

new Relay(options): Relay

Defined in: relay.ts:236

Create a relay around a single upstream source.

Stores the source and lifecycle tuning but does not open the upstream unless autoStart is set; otherwise the connection is deferred until the first sink is piped or Relay.start is called.

Parameters ​

options ​

RelayOptions

Relay configuration including the source and lifecycle options

Returns ​

Relay

Example ​

typescript
import { Relay } from '@seydx/rtsp';

const relay = new Relay({ source, autoStart: true });

Overrides ​

TypedEmitter<RelayEvents>.constructor

Accessors ​

info ​

Get Signature ​

get info(): StreamInfo | undefined

Defined in: relay.ts:276

Resolved stream layout of the open upstream, if any.

Populated once the upstream is open and undefined while the relay is idle.

Example ​
typescript
const tracks = relay.info?.tracks ?? [];
Returns ​

StreamInfo | undefined

sinkCount ​

Get Signature ​

get sinkCount(): number

Defined in: relay.ts:291

Number of sinks currently attached to the relay.

Counts every piped sink regardless of whether it has finished syncing to a keyframe and started receiving packets.

Example ​
typescript
console.log(`${relay.sinkCount} consumers attached`);
Returns ​

number

status ​

Get Signature ​

get status(): RelayState

Defined in: relay.ts:262

Current lifecycle phase of the relay.

Reflects whether the upstream is idle, opening, actively pumping, or being torn down.

Example ​
typescript
if (relay.status === 'running') {
  console.log('upstream is live');
}
Returns ​

RelayState

Methods ​

emit() ​

emit<E>(event, ...args): boolean

Defined in: util/emitter.ts:123

Emit an event, invoking all registered listeners synchronously.

The arguments are type-checked against the listener signature for the given event. Unlike a raw Node.js EventEmitter, emitting error without a registered listener does not throw — a consumer that opted out of error events must never crash the process over one.

Type Parameters ​

E ​

E extends keyof RelayEvents

Parameters ​

event ​

E

Name of the event to emit

args ​

...Parameters<RelayEvents[E]>

Payload forwarded to each listener, matching the event's signature

Returns ​

boolean

true if the event had listeners, false otherwise

Example ​

typescript
service.emit('ready');

Inherited from ​

TypedEmitter.emit

off() ​

off<E>(event, listener): this

Defined in: util/emitter.ts:99

Remove a previously registered listener for an event.

Only the exact listener reference passed to on or once is removed; passing a different function has no effect.

Type Parameters ​

E ​

E extends keyof RelayEvents

Parameters ​

event ​

E

Name of the event to unsubscribe from

listener ​

RelayEvents[E]

The exact listener reference to remove

Returns ​

this

This emitter, for chaining

Example ​

typescript
service.off('data', handler);

Inherited from ​

TypedEmitter.off

on() ​

on<E>(event, listener): this

Defined in: util/emitter.ts:55

Register a listener for an event.

The listener is invoked every time the event is emitted, until it is removed via off or removeAllListeners.

Type Parameters ​

E ​

E extends keyof RelayEvents

Parameters ​

event ​

E

Name of the event to subscribe to

listener ​

RelayEvents[E]

Callback invoked with the event's typed payload

Returns ​

this

This emitter, for chaining

Example ​

typescript
service.on('data', (chunk) => handle(chunk));

Inherited from ​

TypedEmitter.on

once() ​

once<E>(event, listener): this

Defined in: util/emitter.ts:77

Register a one-time listener for an event.

The listener is invoked at most once, on the next emission of the event, and is then automatically removed.

Type Parameters ​

E ​

E extends keyof RelayEvents

Parameters ​

event ​

E

Name of the event to subscribe to

listener ​

RelayEvents[E]

Callback invoked once with the event's typed payload

Returns ​

this

This emitter, for chaining

Example ​

typescript
service.once('ready', () => console.log('ready'));

Inherited from ​

TypedEmitter.once

pipe() ​

pipe<T>(sink): T

Defined in: relay.ts:314

Attach a sink to the relay.

Wraps the sink in an isolated channel, lazily starts the upstream if it is not already running, and syncs the sink at the next keyframe before it begins receiving packets. The same sink instance is returned for convenient chaining.

Type Parameters ​

T ​

T extends Sink

Parameters ​

sink ​

T

The consumer to attach to the relayed stream

Returns ​

T

The same sink instance that was passed in

Example ​

typescript
const attached = relay.pipe(new CallbackSink({ onPacket: (packet) => handle(packet) }));

See ​

Relay.unpipe To detach a sink

removeAllListeners() ​

removeAllListeners(): this

Defined in: util/emitter.ts:143

Remove all listeners for every event.

Typically used during teardown to ensure no callbacks fire after the owning object has been disposed.

Returns ​

this

This emitter, for chaining

Example ​

typescript
service.removeAllListeners();

Inherited from ​

TypedEmitter.removeAllListeners

serveRtsp() ​

serveRtsp(options?): Promise<RtspServerSink>

Defined in: relay.ts:384

Expose this relay as a multi-client RTSP endpoint.

Creates and starts an RTSP server sink bound to this relay. The returned sink begins listening immediately and lazily attaches to the relay when the first client connects. When a backchannel is requested, inbound viewer talkback is either forwarded straight to the source (pass-through) or transcoded to the camera's codec, depending on the option shape.

Parameters ​

options? ​

RtspServerSinkOptions

RTSP server sink options such as host, port, path, auth, and backchannel

Returns ​

Promise<RtspServerSink>

A promise resolving to the listening RTSP server sink

Examples ​

typescript
const server = await relay.serveRtsp({ port: 8554, path: 'cam' });
typescript
// Advertise a backchannel; relay transcodes viewer audio to the camera codec.
const server = await relay.serveRtsp({
  port: 8554,
  backchannel: { codec: 'opus', payloadType: 96, clockRate: 48000, channels: 1 },
});

See ​

start() ​

start(): Promise<void>

Defined in: relay.ts:418

Open the upstream and begin pumping packets.

Resolves the stream layout, initializes any already-attached sinks, emits start, and kicks off the pump loop. Idempotent and safe to call concurrently: repeated calls share the same in-flight start, and calling it while already running resolves immediately.

Returns ​

Promise<void>

A promise that resolves once the upstream is running

Throws ​

If the upstream source fails to open

Example ​

typescript
await relay.start();

See ​

Relay.stop To tear the upstream down

stop() ​

stop(): Promise<void>

Defined in: relay.ts:443

Tear down the upstream and every attached sink.

Aborts the pump loop, closes all sink channels immediately (without draining their backlog), closes the source, resets internal state to idle, and emits stop. Safe to call while a start is still in flight: the pending open is aborted (via the source's close()) and awaited before teardown, so the relay can never transition to running after this resolves. A no-op when the relay is already idle or stopping.

Returns ​

Promise<void>

A promise that resolves once teardown is complete

Example ​

typescript
await relay.stop();

See ​

Relay.start To open the upstream

unpipe() ​

unpipe(sink): Promise<void>

Defined in: relay.ts:348

Detach a previously piped sink.

Closes the sink's channel, which flushes and releases it and emits sink:removed. If the detached sink was the last one and the relay is running, the idle teardown timer is scheduled. Detaching a sink that is not attached is a no-op.

Parameters ​

sink ​

Sink

The sink to detach

Returns ​

Promise<void>

A promise that resolves once the sink has been closed

Example ​

typescript
await relay.unpipe(sink);

See ​

Relay.pipe To attach a sink