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
Are you using Samsung Tizen to play streams? Read more about limitation and Tizen-specific details.
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 | Description |
---|---|---|
videoId | IVideoProperties | 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 | Description |
---|---|---|
listener | (event: IStreamEvent<"connected">) => void | 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 | Description |
---|---|---|
listener | (event: IStreamEvent<"disconnected">) => void | 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 | Description |
---|---|---|
listener | (event: IStreamErrorEvent) => void | 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 | Description |
---|---|---|
listener | (event: IStreamEvent<"pause">) => void | 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 | Description |
---|---|---|
listener | (event: IStreamEvent<"play">) => void | 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 | Description |
---|---|---|
listener | (event: IStreamEvent<"prepare">) => void | 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 | Description |
---|---|---|
listener | (event: IStreamEvent<"resume">) => void | 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 | Description |
---|---|---|
listener | (event: IStreamEvent<"stop">) => void | 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 | Description |
---|---|---|
listener | (event: IStreamTracksChangedEvent) => void | 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 | Description |
---|---|---|
uri | string | Network address where the stream is available. |
x | number | Stream x-position on the screen |
y | number | Stream y-position on the screen |
width | number | Stream width on the screen |
height | number | 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.
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 | Description |
---|---|---|
uri | string | Network address where the stream is available. |
x | number | Stream x-position on the screen |
y | number | Stream y-position on the screen |
width | number | Stream width on the screen |
height | number | Stream 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.
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 | Description |
---|---|---|
uri | string | Network address where the stream is available. |
x | number | Stream x-position on the screen |
y | number | Stream y-position on the screen |
width | number | Stream width on the screen |
height | number | Stream 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
Name | Type | Description |
---|---|---|
videoId | IVideoProperties | The video properties of the stream to reset track for. |
trackType | TrackType | The type of the track to reset (e.g., 'TEXT', 'AUDIO', 'VIDEO'). |
groupId (optional) | string | 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>;