Video streams

Methods to play or stop video streams.

All methods

Methods	Description	Supported since
prepare()	Prepare video stream in the background	4.7.0
play()	Start playing video stream	1.0.18
stop()	Stop video stream	1.0.18
pause()	Pause video stream	6.4.0
resume()	Resume video stream	6.4.0
getTracks()	Get all tracks of the stream	6.1.0
selectTrack()	Select track of the stream	6.1.0
resetTrack()	Reset track of the stream	6.1.0
onConnected()	Calls a listener callback when stream connects	1.0.20
onDisconnected()	Calls a listener callback when stream disconnects	1.0.20
onError()	Calls a listener callback when an unexpected stream error occurs	1.0.20
onPlay()	Calls a listener callback when stream starts playing	5.12.0
onStop()	Calls a listener callback when stream stops	5.12.0
onPrepare()	Calls a listener callback when stream prepares	5.12.0
onTracksChanged()	Calls a listener callback when stream tracks change	6.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

Param	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	Object	Yes	Additional options for the stream

Options object

Key	Type	Required	Description
protocol	String	Yes	Protocol that the stream is using
^^	^^	^^	Types: HLS, RTP, HTTP, UDP, RTMP, RTSP.
background	Boolean	No	Prepare stream in the background
trackSelection	Object	No	Track selection options
drm	Object	No	DRM options

Track selection object

Key	Type	Required	Description
maxAudioChannelCount	Number	No	Maximum number of audio channels to play
minVideoSize	Object	No	Minimum video size to play
^^	^^	^^	Object with width and height properties
maxVideoSize	Object	No	Maximum video size to play
^^	^^	^^	Object with width and height properties
preferredAudioLanguages	Array of strings	No	Preferred audio languages to play
preferredTextLanguages	Array of strings	No	Preferred text languages to play

DRM object

Key	Type	Required	Description
scheme	String	Yes	DRM scheme
^^	^^	^^	Types: CommonPSSH, ClearKey, Widevine, PlayReady or own value
licenseUri	String	Yes	DRM license URI
licenseRequestHeaders	Object	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');

GitHub Example

Stream video Applet example

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

Param	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	Object	Yes	Additional options for the stream

Options object

Key	Type	Required	Description
protocol	String	Yes	Protocol that the stream is using
^^	^^	^^	Types: HLS, RTP, HTTP, UDP, RTMP, RTSP.
autoReconnect	Boolean	No	Automatically reconnect stream when it disconnects
^^	^^	^^	Default value: false
autoReconnectInterval	Number	No	Interval in miliseconds between reconnect attempts
^^	^^	^^	Default value: 30000 ms
volume	Number	No	Volume of the stream
trackSelection	Object	No	Track selection options
drm	Object	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');

GitHub Example

Stream video Applet example

stop()

Stops the video stream playback.

Javascript syntax

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

Parameters:

Param	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

pause()

Pauses the video stream playback.

Javascript syntax

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

Parameters:

Param	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

resume()

Resumes the video stream playback.

Javascript syntax

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

Parameters:

Param	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

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:

Param	Type	Required	Description
videoId	Object	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:

Param	Type	Required	Description
videoId	Object	Yes	Video ID object of selected stream
trackType	String	Yes	Track type - AUDIO, VIDEO, TEXT
groupId	String	Yes	Group ID of selected track
trackIndex	Number	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:

Param	Type	Required	Description
videoId	Object	Yes	Video ID object of selected stream
trackType	String	Yes	Track type - AUDIO, VIDEO, TEXT
groupId	String	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.

Code	Type	Message
41401	AppletStreamError	Invalid stream protocol type: protocol
51301	InternalStreamError	Couldn't stop the stream before playing the new one.
51301	InternalStreamError	Couldn't stop the stream.
51302	InternalStreamError	Couldn't prepare the stream.
51303	InternalStreamError	Couldn't get stream tracks.
51304	InternalStreamError	Couldn't select stream track.
51305	InternalStreamError	Couldn't reset stream track.