Skip to main content
Version: 8.1.3

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

NameTypeDescription
videoIdIVideoPropertiesThe 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

NameTypeDescription
listener(event: IStreamEvent<"connected">) => voidThe 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

NameTypeDescription
listener(event: IStreamEvent<"disconnected">) => voidThe 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

NameTypeDescription
listener(event: IStreamErrorEvent) => voidThe 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

NameTypeDescription
listener(event: IStreamEvent<"pause">) => voidThe 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

NameTypeDescription
listener(event: IStreamEvent<"play">) => voidThe 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

NameTypeDescription
listener(event: IStreamEvent<"prepare">) => voidThe 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

NameTypeDescription
listener(event: IStreamEvent<"resume">) => voidThe 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

NameTypeDescription
listener(event: IStreamEvent<"stop">) => voidThe 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

NameTypeDescription
listener(event: IStreamTracksChangedEvent) => voidThe 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

NameTypeDescription
uristringNetwork address where the stream is available.
xnumberStream x-position on the screen
ynumberStream y-position on the screen
widthnumberStream width on the screen
heightnumberStream 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 valueDescription
internal://hdmi<number>HDMI
internal://dpDisplayPort
internal://dviDVI
internal://pcPC 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

NameTypeDescription
uristringNetwork address where the stream is available.
xnumberStream x-position on the screen
ynumberStream y-position on the screen
widthnumberStream width on the screen
heightnumberStream height on the screen
options (optional)IStreamOptions | "HLS" | "RTP" | "HTTP" | "UDP" | "RTMP" | "RTSP"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' });

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

NameTypeDescription
uristringNetwork address where the stream is available.
xnumberStream x-position on the screen
ynumberStream y-position on the screen
widthnumberStream width on the screen
heightnumberStream height on the screen
options (optional)IStreamPrepareOptions | "HLS" | "RTP" | "HTTP" | "UDP" | "RTMP" | "RTSP"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');

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

NameTypeDescription
videoIdIVideoPropertiesThe video properties of the stream to reset track for.
trackTypeTrackTypeThe type of the track to reset (e.g., 'TEXT', 'AUDIO', 'VIDEO').
groupId (optional)stringThe 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

NameTypeDescription
uristringNetwork address where the stream is available.
xnumberStream x-position on the screen
ynumberStream y-position on the screen
widthnumberStream width on the screen
heightnumberStream 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

NameTypeDescription
videoIdIVideoPropertiesThe video properties of the stream to select track for.
trackTypeTrackTypeThe type of the track to select (e.g., 'TEXT', 'AUDIO', 'VIDEO').
groupIdstringThe group ID of the track to select.
trackIndexnumberThe 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);

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

NameTypeDescription
uristringNetwork address where the stream is available.
xnumberStream x-position on the screen
ynumberStream y-position on the screen
widthnumberStream width on the screen
heightnumberStream 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