npm - @signageos/front-applet - Versions diffs - 7.2.0 → 8.0.0 - Mend

@signageos/front-applet 7.2.0 → 8.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (420) hide show

package/docs/content/js-video-stream.md DELETED Viewed

@@ -1,618 +0,0 @@
----
-title: Video Streams
-author: Miroslav Behina
-date: 22.11.2018
-type: js-api
-tags:
-  - applet
-  - applet_api
-  - api
-  - js_api
-description: '[Content JS API] Methods to play or stop video streams.'
----
-# 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](https://docs.signageos.io/hc/en-us/articles/4405387373458).
-:::
-:::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 | <div class="red">Yes</div> | Network address where the stream is available |
-| `x`       | Number | <div class="red">Yes</div> | Stream x-position on the screen               |
-| `y`       | Number | <div class="red">Yes</div> | Stream y-position on the screen               |
-| `width`   | Number | <div class="red">Yes</div> | Stream width on the screen                    |
-| `height`  | Number | <div class="red">Yes</div> | Stream height on the screen                   |
-| `options` | Object | <div class="red">Yes</div> | Additional options for the stream             |
-### Options object
-| Key              | Type    |           Required           | Description                                         |
-| ---------------- | ------- | :--------------------------: | --------------------------------------------------- |
-| `protocol`       | String  |  <div class="red">Yes</div>  | Protocol that the stream is using                   |
-| ^^               | ^^      |              ^^              | Types: `HLS`, `RTP`, `HTTP`, `UDP`, `RTMP`, `RTSP`. |
-| `background`     | Boolean | <div class="yellow">No</div> | Prepare stream in the background                    |
-| `trackSelection` | Object  | <div class="yellow">No</div> | Track selection options                             |
-| `drm`            | Object  | <div class="yellow">No</div> | DRM options                                         |
-### Track selection object
-| Key                       | Type             |           Required           | Description                                 |
-| ------------------------- | ---------------- | :--------------------------: | ------------------------------------------- |
-| `maxAudioChannelCount`    | Number           | <div class="yellow">No</div> | Maximum number of audio channels to play    |
-| `minVideoSize`            | Object           | <div class="yellow">No</div> | Minimum video size to play                  |
-| ^^                        | ^^               |              ^^              | Object with `width` and `height` properties |
-| `maxVideoSize`            | Object           | <div class="yellow">No</div> | Maximum video size to play                  |
-| ^^                        | ^^               |              ^^              | Object with `width` and `height` properties |
-| `preferredAudioLanguages` | Array of strings | <div class="yellow">No</div> | Preferred audio languages to play           |
-| `preferredTextLanguages`  | Array of strings | <div class="yellow">No</div> | Preferred text languages to play            |
-### DRM object
-| Key                     | Type   |           Required           | Description                                                           |
-| ----------------------- | ------ | :--------------------------: | --------------------------------------------------------------------- |
-| `scheme`                | String |  <div class="red">Yes</div>  | DRM scheme                                                            |
-| ^^                      | ^^     |              ^^              | Types: `CommonPSSH`, `ClearKey`, `Widevine`, `PlayReady` or own value |
-| `licenseUri`            | String |  <div class="red">Yes</div>  | DRM license URI                                                       |
-| `licenseRequestHeaders` | Object | <div class="yellow">No</div> | DRM license request headers                                           |
-### Javascript syntax
-```javascript
-// 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');
-```
-:::note[GitHub Example]
-[Stream video Applet example](https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/stream)
-:::
-## 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 | <div class="red">Yes</div> | Network address where the stream is available |
-| `x`       | Number | <div class="red">Yes</div> | Stream x-position on the screen               |
-| `y`       | Number | <div class="red">Yes</div> | Stream y-position on the screen               |
-| `width`   | Number | <div class="red">Yes</div> | Stream width on the screen                    |
-| `height`  | Number | <div class="red">Yes</div> | Stream height on the screen                   |
-| `options` | Object | <div class="red">Yes</div> | Additional options for the stream             |
-### Options object
-| Key                     | Type    |           Required           | Description                                         |
-| ----------------------- | ------- | :--------------------------: | --------------------------------------------------- |
-| `protocol`              | String  |  <div class="red">Yes</div>  | Protocol that the stream is using                   |
-| ^^                      | ^^      |              ^^              | Types: `HLS`, `RTP`, `HTTP`, `UDP`, `RTMP`, `RTSP`. |
-| `autoReconnect`         | Boolean | <div class="yellow">No</div> | Automatically reconnect stream when it disconnects  |
-| ^^                      | ^^      |              ^^              | Default value: false                                |
-| `autoReconnectInterval` | Number  | <div class="yellow">No</div> | Interval in miliseconds between reconnect attempts  |
-| ^^                      | ^^      |              ^^              | Default value: 30000 ms                             |
-| `volume`                | Number  | <div class="yellow">No</div> | Volume of the stream                                |
-### Javascript syntax
-```javascript
-// 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');
-```
-:::note[GitHub Example]
-[Stream video Applet example](https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/stream)
-:::
-## stop()
-Stops the video stream playback.
-### Javascript syntax
-```javascript
-await sos.stream.stop(uri, x, y, width, height);
-```
-### Parameters:
-| Param    | Type   |          Required          | Description                                   |
-| -------- | ------ | :------------------------: | --------------------------------------------- |
-| `uri`    | String | <div class="red">Yes</div> | Network address where the stream is available |
-| `x`      | Number | <div class="red">Yes</div> | Stream x-position on the screen               |
-| `y`      | Number | <div class="red">Yes</div> | Stream y-position on the screen               |
-| `width`  | Number | <div class="red">Yes</div> | Stream width on the screen                    |
-| `height` | Number | <div class="red">Yes</div> | Stream height on the screen                   |
-## pause()
-Pauses the video stream playback.
-### Javascript syntax
-```javascript
-await sos.stream.pause(uri, x, y, width, height);
-```
-### Parameters:
-| Param    | Type   |          Required          | Description                                   |
-| -------- | ------ | :------------------------: | --------------------------------------------- |
-| `uri`    | String | <div class="red">Yes</div> | Network address where the stream is available |
-| `x`      | Number | <div class="red">Yes</div> | Stream x-position on the screen               |
-| `y`      | Number | <div class="red">Yes</div> | Stream y-position on the screen               |
-| `width`  | Number | <div class="red">Yes</div> | Stream width on the screen                    |
-| `height` | Number | <div class="red">Yes</div> | Stream height on the screen                   |
-## resume()
-Resumes the video stream playback.
-### Javascript syntax
-```javascript
-await sos.stream.resume(uri, x, y, width, height);
-```
-### Parameters:
-| Param    | Type   |          Required          | Description                                   |
-| -------- | ------ | :------------------------: | --------------------------------------------- |
-| `uri`    | String | <div class="red">Yes</div> | Network address where the stream is available |
-| `x`      | Number | <div class="red">Yes</div> | Stream x-position on the screen               |
-| `y`      | Number | <div class="red">Yes</div> | Stream y-position on the screen               |
-| `width`  | Number | <div class="red">Yes</div> | Stream width on the screen                    |
-| `height` | Number | <div class="red">Yes</div> | Stream height on the screen                   |
-## getTracks()
-Get all tracks of the selected stream.
-### Javascript syntax
-```javascript
-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 | <div class="red">Yes</div> | Video ID object of selected stream |
-### Example of returned value
-```javascript
-[
-	{
-		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
-```javascript
-await sos.stream.selectTrack(videoId, trackType, groupId, trackIndex); // Promise<void>
-```
-### Parameters:
-| Param        | Type   |          Required          | Description                           |
-| ------------ | ------ | :------------------------: | ------------------------------------- |
-| `videoId`    | Object | <div class="red">Yes</div> | Video ID object of selected stream    |
-| `trackType`  | String | <div class="red">Yes</div> | Track type - `AUDIO`, `VIDEO`, `TEXT` |
-| `groupId`    | String | <div class="red">Yes</div> | Group ID of selected track            |
-| `trackIndex` | Number | <div class="red">Yes</div> | Index of selected track               |
-## resetTrack()
-Reset track of the selected stream.
-### Javascript syntax
-```javascript
-await sos.stream.resetTrack(videoId, trackType); // Promise<void>
-await sos.stream.resetTrack(videoId, trackType, groupId); // Promise<void>
-```
-### Parameters:
-| Param       | Type   |           Required           | Description                           |
-| ----------- | ------ | :--------------------------: | ------------------------------------- |
-| `videoId`   | Object |  <div class="red">Yes</div>  | Video ID object of selected stream    |
-| `trackType` | String |  <div class="red">Yes</div>  | Track type - `AUDIO`, `VIDEO`, `TEXT` |
-| `groupId`   | String | <div class="yellow">No</div> | Group ID of selected track            |
-## Event onConnected()
-Calls a listener callback everytime `connected` event is emitted.
-### Javascript syntax
-```javascript
-sos.stream.onConnected((event) => {
-	// do something
-});
-```
-## Event onDisconnected()
-Calls a listener callback everytime `disconnected` event is emitted.
-### Javascript syntax
-```javascript
-sos.stream.onDisconnected((event) => {
-	// do something
-});
-```
-## Event onError()
-Calls a listener callback everytime `error` event is emitted.
-### Javascript syntax
-```javascript
-sos.stream.onError((event) => {
-	// do something
-});
-```
-## Event onPlay()
-Calls a listener callback everytime `play` event is emitted.
-### Javascript syntax
-```javascript
-sos.stream.onPlay((event) => {
-	// do something
-});
-```
-## Event onStop()
-Calls a listener callback everytime `stop` event is emitted.
-### Javascript syntax
-```javascript
-sos.stream.onStop((event) => {
-	// do something
-});
-```
-## Event onPrepare()
-Calls a listener callback everytime `prepare` event is emitted.
-### Javascript syntax
-```javascript
-sos.stream.onPrepare((event) => {
-	// do something
-});
-```
-## Event onTracksChanged()
-Calls a listener callback everytime `tracks_changed` event is emitted.
-### Javascript syntax
-```javascript
-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:
-```json
-{
-	"type": "<type>",
-	"srcArguments": {
-		"uri": "<uri>",
-		"x": 0,
-		"y": 0,
-		"width": 1920,
-		"height": 1080,
-		"protocol": "HTTP"
-	}
-}
-```
-Example of **tracks_changed** event:
-```json
-{
-	"type": "tracks_changed",
-	"srcArguments": {
-		"uri": "<uri>",
-		"x": 0,
-		"y": 0,
-		"width": 1920,
-		"height": 1080,
-		"tracks": [] // Array of ITrackInfo
-	}
-}
-```
-Example of **error** event:
-```json
-{
-	"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](https://docs.signageos.io/hc/en-us/articles/4405069154962#signageos-typescript).
-```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.                         |
-## Platform-specific notes
-### BrightSign
-BrightSign allows the configuration of [buffering](https://support.brightsign.biz/hc/en-us/articles/218067097-Customizing-the-size-of-the-streaming-buffer), [latency and jitter](https://support.brightsign.biz/hc/en-us/articles/218067127-Modifying-the-latency-and-jitter-of-audio-video-streams) by adding additional query parameters to stream `uri`.
-#### Buffering
-You can modify the default buffer size by appending optional parameters to the end of a streaming URL in a BrightAuthor Video Stream or Audio Stream state (this method also applies to custom scripts). The URL parameters must be formatted as follows:
-```
-<streaming_url>?buffersize=<number>&vcdbsize=<number>&acdbsize=<number>
-```
-Example: `http://www.example.com/stream1?buffersize=10000000&vcdbsize=10000000&acdbsize=256000`
-Note that all buffer sizes are specified in bytes.
-buffersize: The size of the main buffer. Once streaming data comes into the main buffer, it is immediately split into the audio and video buffers. The default size of the main buffer is 1.5MB for HD models, 3MB for XD models, and 6MB for 4K models.
-vcdbsize: The size of the video-coded data buffer. The default size of this buffer is 3MB for HD models, 3MB for XD models, and 6MB for 4K models.
-acdbsize: The size of the audio-coded data buffer.  The default size of this buffer is 256KB for all models.
-#### Latency and Jitter
-You can modify the amount of time it takes for audio/video streams to begin playback by formatting the stream URL as follows:
-```
-<streaming_url>?latency=<value_in_ms>&jitter=<value_in_ms>
-```
-Example: `http://www.example.com/stream1?latency=-450&jitter=50`
-### Samsung
-UDP and RTP streams are only available if you use specific version of signageOS Tizen CoreApp.
-Details are documented in Docs: [[Tizen] Stream playback issues & limitation](https://docs.signageos.io/hc/en-us/articles/4405387373458--Tizen-Stream-playback-issues-limitation)