Stream playback

Live streams are a big deal in digital signage — whether it's a news ticker on a lobby display or a live camera feed in a retail store. The sos.stream API makes it straightforward to play, pause, resume, and stop streams on any supported platform.

warning

The first 5 parameters (uri, x, y, width, height) uniquely identify a stream instance. Use the same values across play, stop, pause, and resume calls to control the same stream.

The sos.stream API provides these methods:

• play() — Starts stream playback at the given position and size. Accepts an optional options object to configure protocol, reconnection behavior, and low-latency mode.
• prepare() — Pre-loads the stream so playback can start instantly when play() is called. Supports the same options as play(), plus track selection and DRM configuration.
• stop() — Stops playback and releases the stream resources.
• pause() / resume() — Pauses and resumes a running stream.

Simple stream playback

await sos.stream.play('rtsp://example.com/live-feed', 0, 0, 1920, 1080, {
	protocol: 'RTSP',
});

// Stop the stream after 60 seconds
setTimeout(() => sos.stream.stop('rtsp://example.com/live-feed', 0, 0, 1920, 1080), 60_000);

Stream options

You can pass an options object as the last parameter to play() and prepare():

Option	Type	Default	Description
protocol	string	auto-detected	Stream protocol: HLS, RTP, HTTP, UDP, RTMP, RTSP
autoReconnect	boolean	false	Automatically reconnect when the stream disconnects
autoReconnectInterval	number	30000	Interval in milliseconds between reconnect attempts
lowLatency	boolean	false	Enable low-latency playback mode (see below)
background	boolean	false	Prepare the stream in the background
volume	number	100	Initial volume (0–100)

Low-latency stream playback

For use cases where minimal delay matters — such as live camera feeds or interactive kiosk streams — you can enable the lowLatency option. This tells the platform to minimize buffering and reduce the end-to-end latency of the stream.

await sos.stream.play('rtsp://example.com/live-camera', 0, 0, 1920, 1080, {
	protocol: 'RTSP',
	lowLatency: true,
});

Platform support

Low-latency mode is currently supported on BrightSign devices. On other platforms, the lowLatency option is safely ignored — no errors, no side effects. This means you can use it in your applets without worrying about cross-platform compatibility.

When to use low-latency mode

• Live camera feeds where real-time responsiveness is essential
• Interactive displays (e.g., touch-enabled kiosks) that play live content
• Any scenario where a few hundred milliseconds of delay makes a noticeable difference

When not to use it

• Pre-recorded streams or VOD — low-latency mode may reduce buffering stability for content that does not require real-time delivery
• Unreliable network connections — reduced buffering means less tolerance for network jitter

Stream events

The sos.stream API also provides event listeners for monitoring stream lifecycle:

// Stream connected to the source
sos.stream.onConnected((event) => {
	console.log('Stream connected', event);
});

// Stream disconnected
sos.stream.onDisconnected((event) => {
	console.log('Stream disconnected', event);
});

// Stream error
sos.stream.onError((event) => {
	console.error('Stream error', event);
});

Available events: onConnected, onDisconnected, onError, onPrepare, onPlay, onStop, onPause, onResume, onTracksChanged.

Supported protocols

Not all protocols are available on every device. Check the supported streaming protocols page for a per-platform breakdown.

Protocol	Description
HLS	HTTP Live Streaming
RTSP	Real-Time Streaming Protocol
RTP	Real-time Transport Protocol
UDP	User Datagram Protocol
RTMP	Real-Time Messaging Protocol
HTTP	HTTP progressive streaming

API reference

For the full API reference including prepare() options (track selection, DRM), see the SDK stream documentation.