stream

The sos.stream API groups together methods for streaming videos from different sources. There are various methods for preparing, playing, stopping, pausing, and resuming streams.

Streams are identified by their URI and their position on the screen (x, y, width, height).

This API allows you to play video stream from:

• URL (e.g., HTTP, RTSP, RTP, UDP, RTMP)
• HDMI (e.g., Picture-in-Picture, Internal ports) streams

warning

Are you using Samsung Tizen to play streams? Read more about limitation and Tizen-specific details.

danger

Be aware version of JS API (v6.0.0+) changed how stream functions play() and prepare() work. For using an options object you need to our latest core app versions. If you are using older core app versions, you need to use deprecated format.

Methods

getTracks()

The getTracks() method returns a list of subtitles, video, and audio tracks of a stream.

getTracks(videoId: IVideoProperties): Promise<ITrackInfo[]>;

Params

Name	Type	Required	Description
videoId	IVideoProperties	Yes	The video properties of the stream to get tracks for.

Return value

Returns array of object with information about subtitles, video, and audio tracks.

Example

// Example of getting tracks for a stream
await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080);
const tracks = await sos.stream.getTracks(streamId);
console.log(tracks); // Outputs an array of track information

onConnected()

The onConnected() method sets up a listener, which is called whenever a stream is connected.

onConnected(listener: (event: IStreamEvent<'connected'>) => void): void;

Params

Name	Type	Required	Description
listener	(event: IStreamEvent<"connected">) => void	Yes	The listener function to be called when the event occurs.

Return value

Resolves when the listener is successfully set up.

Example

// Example of setting up a listener for the connected event
await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080);
sos.stream.onConnected((event) => {
  console.log('Stream connected:', event.srcArguments.uri);
});

onDisconnected()

The onDisconnected() method sets up a listener, which is called whenever a stream gets disconnected. Usually when source URI is not available anymore or when the stream is stopped.

onDisconnected(listener: (event: IStreamEvent<'disconnected'>) => void): void;

Params

Name	Type	Required	Description
listener	(event: IStreamEvent<"disconnected">) => void	Yes	The listener function to be called when the event occurs.

Return value

Resolves when the listener is successfully set up.

Example

// Example of setting up a listener for the disconnected event
await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080);
sos.stream.onDisconnected((event) => {
    console.log('Stream disconnected:', event.srcArguments.uri);
});

onError()

The onError() method sets up a listener, which is called whenever an unexpected error occurs during a stream.

onError(listener: (event: IStreamErrorEvent) => void): void;

Params

Name	Type	Required	Description
listener	(event: IStreamErrorEvent) => void	Yes	The listener function to be called when the event occurs.

Return value

Resolves when the listener is successfully set up.

Example

// Example of setting up a listener for the error event
await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080);
sos.stream.onError((event) => {
    console.error('Stream error:', event.errorMessage);
});

onPause()

The onPause() method sets up a listener, which is called whenever a stream is paused.

onPause(listener: (event: IStreamEvent<'pause'>) => void): void;

Params

Name	Type	Required	Description
listener	(event: IStreamEvent<"pause">) => void	Yes	The listener function to be called when the event occurs.

Return value

Resolves when the listener is successfully set up.

Example

// Example of setting up a listener for the pause event
await sos.stream.pause('http://example.com/stream', 0, 0, 1920, 1080);
sos.stream.onPause((event) => {
    console.log('Stream paused:', event.srcArguments.uri);
});

onPlay()

The onPlay() method sets up a listener, which is called whenever a stream starts playing.

onPlay(listener: (event: IStreamEvent<'play'>) => void): void;

Params

Name	Type	Required	Description
listener	(event: IStreamEvent<"play">) => void	Yes	The listener function to be called when the event occurs.

Return value

Resolves when the listener is successfully set up.

Example

// Example of setting up a listener for the play event
await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080);
sos.stream.onPlay((event) => {
    console.log('Stream started playing:', event.srcArguments.uri);
});

onPrepare()

The onPrepare() method sets up a listener, which is called whenever a stream gets prepared.

onPrepare(listener: (event: IStreamEvent<'prepare'>) => void): void;

Params

Name	Type	Required	Description
listener	(event: IStreamEvent<"prepare">) => void	Yes	The listener function to be called when the event occurs.

Return value

Resolves when the listener is successfully set up.

Example

// Example of setting up a listener for the prepare event
await sos.stream.prepare('http://example.com/stream', 0, 0, 1920, 1080);
sos.stream.onPrepare((event) => {
    console.log('Stream prepared:', event.srcArguments.uri);
});

onResume()

The onResume() method sets up a listener, which is called whenever a stream is resumed.

onResume(listener: (event: IStreamEvent<'resume'>) => void): void;

Params

Name	Type	Required	Description
listener	(event: IStreamEvent<"resume">) => void	Yes	The listener function to be called when the event occurs.

Return value

Resolves when the listener is successfully set up.

Example

// Example of setting up a listener for the resume event
await sos.stream.pause('http://example.com/stream', 0, 0, 1920, 1080); // Pause the stream
// ... after some time
await sos.stream.resume('http://example.com/stream', 0, 0, 1920, 1080);
sos.stream.onResume((event) => {
    console.log('Stream resumed:', event.srcArguments.uri);
});

onStop()

The onStop() method sets up a listener, which is called whenever a stream stops.

onStop(listener: (event: IStreamEvent<'stop'>) => void): void;

Params

Name	Type	Required	Description
listener	(event: IStreamEvent<"stop">) => void	Yes	The listener function to be called when the event occurs.

Return value

Resolves when the listener is successfully set up.

Example

// Example of setting up a listener for the stop event
await sos.stream.stop('http://example.com/stream', 0, 0, 1920, 1080);
sos.stream.onStop((event) => {
    console.log('Stream stopped:', event.srcArguments.uri);
});

onTracksChanged()

The onTracksChanged() method sets up a listener, which is called whenever a track is changed from functions selectTrack() or resetTrack().

onTracksChanged(listener: (event: IStreamTracksChangedEvent) => void): void;

Params

Name	Type	Required	Description
listener	(event: IStreamTracksChangedEvent) => void	Yes	The listener function to be called when the event occurs.

Return value

Resolves when the listener is successfully set up.

Example

// Example of setting up a listener with starting a stream and selecting a track
await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080);
await sos.stream.selectTrack(videoId, 'AUDIO', 'audioGroup1', 0);

// Create the listener for tracks changed event
sos.stream.onTracksChanged((event) => {
    console.log('Track type:', event.tracks[0].trackType); // AUDIO
    console.log('Track group ID:', event.tracks[0].groupId); // audioGroup1
    console.log('Track index:', event.tracks[0].trackIndex); // 0
});

pause()

The pause() method pauses the active stream, it can be resumed with resume().

pause(uri: string, x: number, y: number, width: number, height: number): Promise<void>;

Params

Name	Type	Required	Description
uri	string	Yes	Network address where the stream is available.
x	number	Yes	Stream x-position on the screen
y	number	Yes	Stream y-position on the screen
width	number	Yes	Stream width on the screen
height	number	Yes	Stream height on the screen

Return value

Returns a promise that resolves when the stream is paused.

Possible errors

Error If parameters are invalid.

Example

// Example of pausing an active stream
await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080); // Start
// ... after some time
await sos.stream.pause('http://example.com/stream', 0, 0, 1920, 1080); // Pause

play()

The play() method starts the video stream based by uri or stream which was prepared by prepare() method.

Internal ports

This method use same functionality, instead of URL (for stream), specify a URI of the port to display.

Port URI value	Description
internal://hdmi<number>	HDMI
internal://dp	DisplayPort
internal://dvi	DVI
internal://pc	PC or VGA

<number> has to be a value between 1 - 4, depending on which of the available HDMI ports you want to use.

play(uri: string, x: number, y: number, width: number, height: number, options?: IStreamOptions | keyof typeof StreamProtocol): Promise<void>;

Params

Name	Type	Required	Description
uri	string	Yes	Network address where the stream is available.
x	number	Yes	Stream x-position on the screen
y	number	Yes	Stream y-position on the screen
width	number	Yes	Stream width on the screen
height	number	Yes	Stream height on the screen
options	IStreamOptions | "HLS" | "RTP" | "HTTP" | "UDP" | "RTMP" | "RTSP"	No	Additional options for the stream

Return value

Returns a promise that resolves when the stream is successfully started.

Possible errors

• AppletStreamError If the protocol is not a string or if the parameters are invalid.
• Error If parameters are invalid.
• Error If the device fails to prepare the stream.

Example

// Example with specific protocol type
await sos.stream.play(uri, x, y, width, height, { protocol: 'HTTP' });

// Example with options - reconnect stream when it disconnects after 60 seconds
await sos.stream.play(uri, x, y, width, height, { protocol: 'HTTP', autoReconnect: true, autoReconnectInterval: 60000 });

// Example for playing HDMI port
await sos.stream.play('internal://hdmi1', 0, 0, 1920, 1080, { protocol: 'RTP' });

GitHub Example

• How to create video Applet with for URL streams
• How to create video Applet with HDMI port

prepare()

Calls the internal player and prepares a video stream in memory, so it can later start playing instantaneously.

info

If you want to play a video stream in full screen mode, use x = y = 0 and width = document.documentElement.clientWidth and height = document.documentElement.clientHeight as setup parameters.

prepare(uri: string, x: number, y: number, width: number, height: number, options?: IStreamPrepareOptions | keyof typeof StreamProtocol): Promise<void>;

Params

Name	Type	Required	Description
uri	string	Yes	Network address where the stream is available.
x	number	Yes	Stream x-position on the screen
y	number	Yes	Stream y-position on the screen
width	number	Yes	Stream width on the screen
height	number	Yes	Stream height on the screen
options	IStreamPrepareOptions | "HLS" | "RTP" | "HTTP" | "UDP" | "RTMP" | "RTSP"	No	Additional options for the stream

Return value

Returns a promise that resolves when the stream is prepared.

Possible errors

• AppletStreamError If the protocol is not a string or if the parameters are invalid.
• Error If parameters are invalid.
• Error If device fail to prepare the stream.

Example

// Example with specific protocol type
await sos.stream.prepare(uri, x, y, width, height, { protocol: 'HTTP' });

// Example with options - prepare stream in the background
await sos.stream.prepare(uri, x, y, width, height, { protocol: 'HTTP', background: true });

// Deprecated format
await sos.stream.prepare(uri, x, y, width, height, 'HTTP');

GitHub Example

• How to create video Applet with for streams

removeEventListeners()

The removeEventListeners() removes all listeners set up on sos.stream.

removeEventListeners(): void;

resetTrack()

The resetTrack() method resets a selected track of a stream.

resetTrack(videoId: IVideoProperties, trackType: TrackType, groupId?: string): Promise<void>;

Params

Name	Type	Required	Description
videoId	IVideoProperties	Yes	The video properties of the stream to reset track for.
trackType	TrackType	Yes	The type of the track to reset (e.g., 'TEXT', 'AUDIO', 'VIDEO').
groupId	string	No	The group ID of the track to reset. If not provided, the first track in the group will be reset.

Return value

Resolves when the track is successfully reset.

Possible errors

Error If parameters are invalid or if the track type is not supported.

Example

// Example of resetting a track for a stream
await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080);
// Reset the audio track in the group with ID 'audioGroup1'
await sos.stream.resetTrack(videoId, 'AUDIO', 'audioGroup1');

resume()

The resume() method resumes the paused stream by pause() function.

resume(uri: string, x: number, y: number, width: number, height: number): Promise<void>;

Params

Name	Type	Required	Description
uri	string	Yes	Network address where the stream is available.
x	number	Yes	Stream x-position on the screen
y	number	Yes	Stream y-position on the screen
width	number	Yes	Stream width on the screen
height	number	Yes	Stream height on the screen

Return value

Returns a promise that resolves when the stream is successfully resumed.

Possible errors

Error If parameters are invalid.

Example

// Example of resuming a paused stream
await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080); // Start
await sos.stream.pause('http://example.com/stream', 0, 0, 1920, 1080); // Pause
// ... after some time
await sos.stream.resume('http://example.com/stream', 0, 0, 1920, 1080); // Resume

selectTrack()

The selectTrack() method selects a text (subtitles), video or audio track of a stream.

selectTrack(videoId: IVideoProperties, trackType: TrackType, groupId: string, trackIndex: number): Promise<void>;

Params

Name	Type	Required	Description
videoId	IVideoProperties	Yes	The video properties of the stream to select track for.
trackType	TrackType	Yes	The type of the track to select (e.g., 'TEXT', 'AUDIO', 'VIDEO').
groupId	string	Yes	The group ID of the track to select.
trackIndex	number	Yes	The index of the track to select within the group.

Return value

Resolves when the track is successfully selected.

Possible errors

Error If parameters are invalid or if the track type is not supported.

Example

// Example of selecting a track for a stream
await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080);

// Select the first audio track in the group with ID 'audioGroup1'
await sos.stream.selectTrack(videoId, 'AUDIO', 'audioGroup1', 0);
// Select the first text track in the group with ID 'subtitlesGroup1'
await sos.stream.selectTrack(videoId, 'TEXT', 'subtitlesGroup1', 0);
// Select the first video track in the group with ID 'videoGroup1'
await sos.stream.selectTrack(videoId, 'VIDEO', 'videoGroup1', 0);

GitHub Example

• How to set subtitles for a stream

stop()

The stop() method stops the active stream, it can't be later resumed with resume().

stop(uri: string, x: number, y: number, width: number, height: number): Promise<void>;

Params

Name	Type	Required	Description
uri	string	Yes	Network address where the stream is available.
x	number	Yes	Stream x-position on the screen
y	number	Yes	Stream y-position on the screen
width	number	Yes	Stream width on the screen
height	number	Yes	Stream height on the screen

Return value

Returns a promise that resolves when the stream is stopped.

Possible errors

Error If parameters are invalid.

Example

// Example of stopping an active stream
await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080); // Start
// ... after some time
await sos.stream.stop('http://example.com/stream', 0, 0, 1920, 1080); // Stop