Skip to main content
Version: Next

Video streams

Methods to play or stop video streams.

All methods

MethodsDescriptionSupported since
prepare()Prepare video stream in the background4.7.0
play()Start playing video stream1.0.18
stop()Stop video stream1.0.18
pause()Pause video stream6.4.0
resume()Resume video stream6.4.0
getTracks()Get all tracks of the stream6.1.0
selectTrack()Select track of the stream6.1.0
resetTrack()Reset track of the stream6.1.0
onConnected()Calls a listener callback when stream connects1.0.20
onDisconnected()Calls a listener callback when stream disconnects1.0.20
onError()Calls a listener callback when an unexpected stream error occurs1.0.20
onPlay()Calls a listener callback when stream starts playing5.12.0
onStop()Calls a listener callback when stream stops5.12.0
onPrepare()Calls a listener callback when stream prepares5.12.0
onTracksChanged()Calls a listener callback when stream tracks change6.1.0
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.

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.

Parameters

ParamTypeRequiredDescription
uriString
Yes
Network address where the stream is available
xNumber
Yes
Stream x-position on the screen
yNumber
Yes
Stream y-position on the screen
widthNumber
Yes
Stream width on the screen
heightNumber
Yes
Stream height on the screen
optionsObject
Yes
Additional options for the stream

Options object

KeyTypeRequiredDescription
protocolString
Yes
Protocol that the stream is using
^^^^^^Types: HLS, RTP, HTTP, UDP, RTMP, RTSP.
backgroundBoolean
No
Prepare stream in the background
trackSelectionObject
No
Track selection options
drmObject
No
DRM options

Track selection object

KeyTypeRequiredDescription
maxAudioChannelCountNumber
No
Maximum number of audio channels to play
minVideoSizeObject
No
Minimum video size to play
^^^^^^Object with width and height properties
maxVideoSizeObject
No
Maximum video size to play
^^^^^^Object with width and height properties
preferredAudioLanguagesArray of strings
No
Preferred audio languages to play
preferredTextLanguagesArray of strings
No
Preferred text languages to play

DRM object

KeyTypeRequiredDescription
schemeString
Yes
DRM scheme
^^^^^^Types: CommonPSSH, ClearKey, Widevine, PlayReady or own value
licenseUriString
Yes
DRM license URI
licenseRequestHeadersObject
No
DRM license request headers

Javascript syntax

// 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');

play()

Calls the internal player and starts a video stream in correct position.

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.

Parameters

ParamTypeRequiredDescription
uriString
Yes
Network address where the stream is available
xNumber
Yes
Stream x-position on the screen
yNumber
Yes
Stream y-position on the screen
widthNumber
Yes
Stream width on the screen
heightNumber
Yes
Stream height on the screen
optionsObject
Yes
Additional options for the stream

Options object

KeyTypeRequiredDescription
protocolString
Yes
Protocol that the stream is using
^^^^^^Types: HLS, RTP, HTTP, UDP, RTMP, RTSP.
autoReconnectBoolean
No
Automatically reconnect stream when it disconnects
^^^^^^Default value: false
autoReconnectIntervalNumber
No
Interval in miliseconds between reconnect attempts
^^^^^^Default value: 30000 ms
volumeNumber
No
Volume of the stream
trackSelectionObject
No
Track selection options
drmObject
No
DRM options

Javascript syntax

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

// Example with other options - enable auto reconnect
await sos.stream.play(uri, x, y, width, height, { protocol: 'HTTP', autoReconnect: true });

// Example with other options - reconnect every 10 seconds
await sos.stream.play(uri, x, y, width, height, { protocol: 'HTTP', autoReconnect: true, autoReconnectInterval: 10000 });

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

stop()

Stops the video stream playback.

Javascript syntax

await sos.stream.stop(uri, x, y, width, height);

Parameters:

ParamTypeRequiredDescription
uriString
Yes
Network address where the stream is available
xNumber
Yes
Stream x-position on the screen
yNumber
Yes
Stream y-position on the screen
widthNumber
Yes
Stream width on the screen
heightNumber
Yes
Stream height on the screen

pause()

Pauses the video stream playback.

Javascript syntax

await sos.stream.pause(uri, x, y, width, height);

Parameters:

ParamTypeRequiredDescription
uriString
Yes
Network address where the stream is available
xNumber
Yes
Stream x-position on the screen
yNumber
Yes
Stream y-position on the screen
widthNumber
Yes
Stream width on the screen
heightNumber
Yes
Stream height on the screen

resume()

Resumes the video stream playback.

Javascript syntax

await sos.stream.resume(uri, x, y, width, height);

Parameters:

ParamTypeRequiredDescription
uriString
Yes
Network address where the stream is available
xNumber
Yes
Stream x-position on the screen
yNumber
Yes
Stream y-position on the screen
widthNumber
Yes
Stream width on the screen
heightNumber
Yes
Stream height on the screen

getTracks()

Get all tracks of the selected stream.

Javascript syntax

const videoId = {
uri: 'http://example.com/stream.m3u8',
x: 0,
y: 0,
width: 1920,
height: 1080,
};

const tracks = await sos.stream.getTracks(videoId); // Promise<ITrackInfo[]>

Parameters:

ParamTypeRequiredDescription
videoIdObject
Yes
Video ID object of selected stream

Example of returned value

[
{
trackType: 'VIDEO', // string - AUDIO, VIDEO, TEXT
mimeType: 'video/mp4', // string
videoSize: {
// object
width: 1920, // number
height: 1080, // number
},
groupId: '1', // string
trackIndex: 1, // number
selected: true, // boolean
language: 'en', // string
supported: true, // boolean
},
];

selectTrack()

Select track of the selected stream.

Javascript syntax

await sos.stream.selectTrack(videoId, trackType, groupId, trackIndex); // Promise<void>

Parameters:

ParamTypeRequiredDescription
videoIdObject
Yes
Video ID object of selected stream
trackTypeString
Yes
Track type - AUDIO, VIDEO, TEXT
groupIdString
Yes
Group ID of selected track
trackIndexNumber
Yes
Index of selected track

resetTrack()

Reset track of the selected stream.

Javascript syntax

await sos.stream.resetTrack(videoId, trackType); // Promise<void>
await sos.stream.resetTrack(videoId, trackType, groupId); // Promise<void>

Parameters:

ParamTypeRequiredDescription
videoIdObject
Yes
Video ID object of selected stream
trackTypeString
Yes
Track type - AUDIO, VIDEO, TEXT
groupIdString
No
Group ID of selected track

Event onConnected()

Calls a listener callback everytime connected event is emitted.

Javascript syntax

sos.stream.onConnected((event) => {
// do something
});

Event onDisconnected()

Calls a listener callback everytime disconnected event is emitted.

Javascript syntax

sos.stream.onDisconnected((event) => {
// do something
});

Event onError()

Calls a listener callback everytime error event is emitted.

Javascript syntax

sos.stream.onError((event) => {
// do something
});

Event onPlay()

Calls a listener callback everytime play event is emitted.

Javascript syntax

sos.stream.onPlay((event) => {
// do something
});

Event onStop()

Calls a listener callback everytime stop event is emitted.

Javascript syntax

sos.stream.onStop((event) => {
// do something
});

Event onPrepare()

Calls a listener callback everytime prepare event is emitted.

Javascript syntax

sos.stream.onPrepare((event) => {
// do something
});

Event onTracksChanged()

Calls a listener callback everytime tracks_changed event is emitted.

Javascript syntax

sos.stream.onTracksChanged((event) => {
// do something
});

Stream events

All stream events have the same format.

type property contains string with the event type. Type can be connected, disconnected, error or tracks_changed.

srcArguments property contains parameters of the source stream, that emitted the event. That way, if multiple streams are playing at once, you can associate the events with each stream instance.

Example of connected, disconnected event:

{
"type": "<type>",
"srcArguments": {
"uri": "<uri>",
"x": 0,
"y": 0,
"width": 1920,
"height": 1080,
"protocol": "HTTP"
}
}

Example of tracks_changed event:

{
"type": "tracks_changed",
"srcArguments": {
"uri": "<uri>",
"x": 0,
"y": 0,
"width": 1920,
"height": 1080,
"tracks": [] // Array of ITrackInfo
}
}

Example of error event:

{
"type": "error",
"srcArguments": {
"uri": "<uri>",
"x": 0,
"y": 0,
"width": 1920,
"height": 1080,
"protocol": "HTTP"
},
"errorMessage": "Some error message"
}

Usage with Typescript

You can also use all these methods with signageOS TypeScript.

type StreamProtocol = 'HLS' | 'RTP' | 'HTTP' | 'UDP' | 'RTMP' | 'RTSP';
type DrmScheme = "CommonPSSH" | "ClearKey" | "Widevine" | "PlayReady" | string;
interface StreamEvent {
type: 'connected' | 'disconnected' | 'error' | 'stop' | 'prepare' | 'play',
srcArguments: {
uri: string;
x: number;
y: number;
width: number;
height: number;
protocol?: StreamProtocol;
},
}
interface IVideoProperties {
uri: string;
x: number;
y: number;
width: number;
height: number;
}
type TrackType = 'AUDIO' | 'VIDEO' | 'TEXT';
type ITrackInfo = IVideoTrack | IAudioTrack | ITextTrack;
interface ITrack<T extends TrackType> {
trackType: T;
mimeType: string;
groupId: string;
trackIndex: number;
selected: boolean;
language: string | null;
supported: boolean;
}
interface IVideoTrack extends ITrack<'VIDEO'> {
videoSize: { width: number; height: number };
}
interface IAudioTrack extends ITrack<'AUDIO'> {
channelCount: number;
}
interface ITextTrack extends ITrack<'TEXT'> {
selection: 'default' | 'forced' | 'autoselect';
}
prepare(
uri: string;
x: number;
y: number;
width: number;
height: number;
options: {
protocol: StreamProtocol;
background?: boolean;
autoReconnect?: boolean;
autoReconnectInterval?: number;
trackSelection?: {
maxAudioChannelCount?: number;
minVideoSize?: { width: number; height: number };
maxVideoSize?: { width: number; height: number };
preferredAudioLanguages?: string[];
preferredTextLanguages?: string[];
};
drm?: {
scheme: DrmScheme;
licenseUri: string;
licenseRequestHeaders: { [key: string]: string };
};
}
): Promise<void>;
play(
uri: string;
x: number;
y: number;
width: number;
height: number;
options: {
protocol: StreamProtocol;
background?: boolean;
autoReconnect?: boolean;
autoReconnectInterval?: number;
}
): Promise<void>;
stop(
uri: string,
x: number,
y: number,
width: number,
height: number
): Promise<void>;
getTracks(videoId: IVideoProperties): Promise<ITrackInfo[]>;
selectTrack(videoId: IVideoProperties, trackType: TrackType, groupId: string, trackIndex: number): Promise<void>;
resetTrack(videoId: IVideoProperties, trackType: TrackType, groupId?: string): Promise<void>;
onConnected(listener: (event: StreamEvent) => void): void;
onDisconnected(listener: (event: StreamEvent) => void): void;
onError(listener: (event: StreamErrorEvent) => void): void;
onPlay(listener: (event: StreamEvent) => void): void;
onStop(listener: (event: StreamEvent) => void): void;
onPrepare(listener: (event: StreamEvent) => void): void;
onTracksChanged(listener: (event: StreamTracksChangedEvent) => void): void;

Errors

Although we are doing our best, following errors may occur when working with the video stream.

CodeTypeMessage
41401AppletStreamErrorInvalid stream protocol type: protocol
51301InternalStreamErrorCouldn't stop the stream before playing the new one.
51301InternalStreamErrorCouldn't stop the stream.
51302InternalStreamErrorCouldn't prepare the stream.
51303InternalStreamErrorCouldn't get stream tracks.
51304InternalStreamErrorCouldn't select stream track.
51305InternalStreamErrorCouldn't reset stream track.