@signageos/front-applet 4.11.0

package/docs/js-api/js-sync-playback.md

@@ -0,0 +1,197 @@
+---
+title:  Synchronized playback
+author: Miroslav Behina
+date:   22.11.2018
+type:   js-api
+tags:
+- applet
+- applet_api
+- api
+- js_api
+description: "[Content JS API] Sync API enables multiple devices to communicate and coordinate their behavior with each other. The communication is facilitated by the server. At any given moment, one of the devices is chosen by the server to be the master and all other devices become slaves."
+---
+
+# Sync playback across multiple devices
+
+Sync API enables multiple devices to communicate and coordinate their behavior with each other. The communication is facilitated by the server. At any given moment, one of the devices is chosen by the server to be the master and all other devices become slaves.
+
+**Uses:**
+* **Play content** in sync on multiple devices
+* **Videowall** - gapless video playback still available
+
+## All methods
+
+::: table-responsive
+| Methods/Events  | Description | Supported since |
+| ----------------- | ----------- | :---------------: |
+| `connect()` 	 	| Connect to the sync server. |  1.0.32 |
+| `close()`	  		| Closes the connection to the sync server. |  1.0.32 |
+| `init()`	  		| Initialize of sync group |  1.0.32 |
+| `wait()`	  		| Method used when device must wait on other devices for proper sync |  1.0.32 |
+| `setValue()`		| Used for broadcast values for all master devices |  2.0.0 |
+| `onValue()`	    | Event called when device receives any value |  2.0.0 |
+:::
+
+## Examples
+<div class="row d-flex align-content-stretch force-padding-10">
+    <div class="col-12 d-flex">
+        <a class="wide-box wide-box--white d-flex align-content-stretch widebox-kb-color" target="_blank" href="https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/sync-video">
+            <div>
+                <div class="wide-box__image d-flex align-items-center">
+                    <i class="fab fa-github svg-black"></i>
+                </div>
+            <div>
+                <h3 class="wide-box__title wide-box__title__small pl-85">Synchronized video through applets</h3>
+                <div class="wide-box__description">Working example on our Github</div>
+            </div>
+            </div>
+        </a>
+    </div>
+</div>
+
+<div class="row d-flex align-content-stretch force-padding-10">
+    <div class="col-12 d-flex">
+        <a class="wide-box wide-box--white d-flex align-content-stretch widebox-kb-color" target="_blank" href="https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/sync-mixed-content">
+            <div>
+                <div class="wide-box__image d-flex align-items-center">
+                    <i class="fab fa-github svg-black"></i>
+                </div>
+            <div>
+                <h3 class="wide-box__title wide-box__title__small pl-85">Synchronization mixed content</h3>
+                <div class="wide-box__description">Working example on our Github</div>
+            </div>
+            </div>
+        </a>
+    </div>
+</div>
+
+## connect()
+Connect to the sync server. This initializes the connection and is mandatory to call, since synchronization is an optional feature and doesn’t get initialized by default to save resources and bandwidth. You can optionally specify a custom sync server URI in case you are running the sync server in a custom location.
+
+### Parameters
+::: table-responsive
+|      Param     | Type  | Required | Description   |
+| -------------- | ---------- | :----: | ---------------------------- |
+| `syncServerUri`| String  | <div class="yellow">No</div> | Address of sync server |
+:::
+
+### Javascript example
+```javascript
+await sos.sync.connect(syncServerUri).then(() => {
+	// do other things once connected
+})
+```
+
+## close()
+Closes the connection to the sync server. Recommended to call this method after the synchronization is not required any longer.
+
+### Javascript example
+```javascript
+await sos.sync.close().then(() => {
+	// do other things once closed
+})
+```
+
+## init()
+Once the user is connected to the server, the initialization of the sync group is required. Before any communication takes place, all participating devices have to be connected and recognize one another. Recommended to call this method early.
+
+### Parameters
+::: table-responsive
+|      Param     | Type    | Required | Description  |
+| -------------- | ------- | :-----: | ---------------------------- |
+| `groupName`  | String  | <div class="yellow">No</div> | By default, all devices will be synced together. To create Groups of devices, independent from each other, specify group name |
+:::
+
+### Javascript example
+```javascript
+await sos.sync.init('someRandomNameGroup');
+```
+
+## wait()
+One way to synchronize devices is to make them wait for each other at a certain moment. This would be most commonly used before the device hits “play” on a video, to make it wait for other devices so they all start playing the video at the same time.
+
+This method returns a promise that resolves once all the devices meet and are ready to continue together. Any action that results in visible synchronized behavior should be triggered immediately after and any related background preparations should be called before to prevent delays.
+
+Sometimes devices might go out of sync due to unpredictable conditions like loss of internet connection. To ensure re-sync of an out of sync device, you can pass some data as the first argument. This can be any data that informs the whole group about what content is about to play next. Once all devices are ready, data from the master device is passed to everyone and the rest of the data is ignored. Therefore, when implementing your applet you should rely on the result data and not the data that is passed to the wait method as an argument.
+
+### Parameters
+::: table-responsive
+|      Param     | Type  | Required | Description  |
+| -------------- | ------- | :-----: | ------- |
+| `data`    | Any | <div class="yellow">No</div>  | Information about what content is about to play so all the devices display the same content. |
+| `groupName` | String  | <div class="yellow">No</div> | If a custom group name in init call is specified, the same group name as the second argument has to be passed. |
+| `timeout` | Number | <div class="yellow">No</div> | Wait timeout on other devices |
+:::
+
+### Returns
+Promise that resolves to data picked from the first argument of the master device 
+
+## Option Broadcast values: 
+Another way to synchronize devices is to broadcast some values within the group so, in turn, all devices can react to it. Unlike option wait, this is more useful in use cases when the synchronization is based around the content itself, rather than timing.
+
+### All Methods
+::: table-responsive
+| Method  | Type | Description | Supported since |
+| ------ | ------ | -------- | ------------- |
+| `setValue()` | method | Used for broadcast values for all master devices | 2.0.0 |
+| `onValue()` | event | Event called when device receive any value | 2.0.0 |
+:::
+
+## setValue()
+This method can be called by any device to broadcast a value to the whole group, but only master devices’ values are broadcasted, while slave devices are ignored. Again, this is to ensure consistency and allow re-syncing of out of sync devices.
+
+### Parameters
+::: table-responsive
+|  Param   |Type  | Required | Description  |
+| -------------- | --------- | :------: | ------------------- |
+| `key`            | String   | <div class="red">Yes</div> | Values are recognized based their key so different types of values can be broadcasted independently within the group |
+| `value`          | Any       | <div class="red">Yes</div> | The value to be broadcasted   |
+| `groupName`      | String     | <div class="yellow">No</div> | If a custom group name in init call is specified, the same group name has to be passed as the third argument    |
+:::
+
+## Event onValue()
+Every device should register a listener to receive and process broadcasted values.
+
+### Javascript example
+```javascript
+await sos.sync.onValue((key, value, groupName) => {
+	// do something with the new value
+});
+```
+
+<br>
+
+::: alert alert--info
+Since you never know which device is the master at the moment, you should always rely only on the values received by the listener, not the values that the particular device itself is broadcasting.
+:::
+
+## Usage with Typescript
+You can also use all these methods with [signageOS TypeScript](/knowledge-base/dev-tools-cli-typescript).
+
+```typescript
+connect(syncServerUri?: string): Promise<void>;
+close(): Promise<void>;
+init(groupName?: string): Promise<void>;
+wait(data?: any, groupName?: string): Promise<any>;
+setValue(key: string, value: any, groupName?: string): Promise<void>;
+```
+```typescript
+onValue(listener: (
+	key: string, 
+	value: any,
+	groupName?: string
+) => void): void;
+```
+
+## Errors
+Although we are doing our best, following errors may occur when working with the synchronizer.
+
+::: table-responsive
+| Code | Type | Message |
+| ---- | ---- | ------- |
+| 51101 | InternalSynchronizerError | Synchronizer couldn't connect to the server. |
+| 51102 | InternalSynchronizerError | The connection wasn't closed correctly. |
+| 51103 | InternalSynchronizerError | The group initialization failed. |
+| 51104 | InternalSynchronizerError | Wait failed for unexpected reason. |
+| 51105 | InternalSynchronizerError | Synchronizer couldn't set the value. |
+:::

package/docs/js-api/js-timing.md

@@ -0,0 +1,54 @@
+---
+title:  Timing
+author: Miroslav Behina
+date:   22.11.2018
+type:   js-api
+tags:
+- applet
+- applet_api
+- api
+- js_api
+description: "[Content JS API] Timing applets are auto-switched based on FINISH events & data. In some cases it is possible to pause/resume this by switching triggers temporarily."
+---
+
+# Timing
+
+::: alert alert--danger
+THIS API IS DEPRECATED.
+:::
+
+Timing applets are auto-switched based on FINISH events & data. In some cases it is possible to pause/resume this by switching triggers temporarily.
+
+## All methods
+
+::: table-responsive
+| Method/Events  | Description                       | Supported since |
+| ----------------- | --------------------------------- | :---------------: |
+| `pause()` | Method pauses timing triggers.  | 1.0.29 |
+| `resume()` | Method resumes timing triggers. | 1.0.29 |
+:::
+
+### Javascript syntax
+```javascript
+// pause timing triggers
+await sos.timing.triggers.pause();
+ 
+// resume timing triggers
+await sos.timing.triggers.pause();
+```
+
+<div class="row d-flex align-content-stretch force-padding-20">
+    <div class="col-12 d-flex">
+        <a class="wide-box wide-box--white d-flex align-content-stretch widebox-kb-color" target="_blank" href="https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/timing-triggers">
+            <div>
+                <div class="wide-box__image d-flex align-items-center">
+                    <i class="fab fa-github svg-black"></i>
+                </div>
+            <div>
+                <h3 class="wide-box__title wide-box__title__small pl-85">Applet with timinig</h3>
+                <div class="wide-box__description">Working example on our Github</div>
+            </div>
+            </div>
+        </a>
+    </div>
+</div>

package/docs/js-api/js-video-inputs-internal-ports.md

@@ -0,0 +1,149 @@
+---
+title:  Video Inputs (PiP)
+author: Miroslav Behina
+date:   22.11.2018
+type:   js-api
+tags:
+- applet
+- applet_api
+- api
+- js_api
+description: "[Content JS API] Display content from another device over HDMI, Display Port, or other port. PIP (Picture in Picture) functionality allows you to display content from the internal port while keeping signageOS on."
+---
+
+# Video Inputs and Internal Ports
+Display content from another device over HDMI, Display Port, or other port. PIP (Picture in Picture) functionality allows you to display content from the internal port while keeping signageOS on.
+
+## All methods
+::: table-responsive
+| Methods  | Description | Supported since |
+| ----------------- | ----------- | :---------------: |
+| `play()` | Method for starting stream | 1.0.18 |
+| `stop()` | Method stops using the internal port. | 1.0.18 |
+:::
+
+## play() 
+Method uses the same API as [video streams](/api/js/content/js-video-stream). Instead of URL (for stream), **specify an URI of the port** to display.
+
+### Parameters
+::: table-responsive
+|      Param     | Type              | Required |Description                   |
+| -------------- | -------------------| :----------: | ---------------------------- |
+| `uri`          | String                     | <div class="red">Yes</div>  | Internal port URI            |
+| `x`            | Number                      | <div class="red">Yes</div> | x-position for video on screen |
+| `y`            | Number                      | <div class="red">Yes</div> | y-position for video on screen |
+| `width`        | Number                      | <div class="red">Yes</div> | Video width on screen 		|
+| `height`		 | Number                      | <div class="red">Yes</div> | Video height on screen 		|
+:::
+
+### Javascript example
+```javascript
+await sos.stream.play(uri,  x,  y,  width,  height);
+```
+
+<div class="row d-flex align-content-stretch force-padding-20">
+    <div class="col-12 d-flex">
+        <a class="wide-box wide-box--white d-flex align-content-stretch widebox-kb-color" target="_blank" href="https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/stream-hdmi-port">
+            <div>
+                <div class="wide-box__image d-flex align-items-center">
+                    <i class="fab fa-github svg-black"></i>
+                </div>
+            <div>
+                <h3 class="wide-box__title wide-box__title__small pl-85">Stream HDMI port Applet example</h3>
+                <div class="wide-box__description">Working example on our Github</div>
+            </div>
+            </div>
+        </a>
+    </div>
+</div>
+
+## Valid URI values 
+
+::: table-responsive
+|   Value                 |   Description                   |
+| ----------------------- | ------------------------------- |
+| `internal://hdmi<number>` | HDMI                            |
+| `internal://dp`          | DisplayPort                     |
+| `internal://dvi`          | DVI                             |
+| `internal://pc`           | PC or VGA                       |
+:::
+
+::: alert alert--warning
+`<number>` has to be a value between 1 - 4, depending on which of the available HDMI ports you want to use.
+:::
+
+## stop() 
+Method stops using the internal port.
+
+### Parameters:
+::: table-responsive
+|      Param     | Type            | Required |Description                   |
+| -------------- | -----------------| :------------: | ---------------------------- |
+| `uri`            | String                     | <div class="red">Yes</div>  | Internal port URI             |
+| `x`              | Number                     | <div class="red">Yes</div>  | x-position for video on screen |
+| `y`              | Number                      | <div class="red">Yes</div> | y-position for video on screen |
+| `width`          | Number                      | <div class="red">Yes</div> | Video width on screen 		|
+| `height`		 | Number                      | <div class="red">Yes</div> | Video height on screen 		|
+:::
+
+### Javascript example
+```javascript
+await sos.stream.stop(uri,  x,  y,  width,  height);
+```
+
+## Internal port events
+API reacts to events related to changes in internal port status. Events are only emitted for a currently playing internal port.
+
+::: table-responsive
+| Event                         | Description                                                                                     |
+| ----------------------------- | ----------------------------------------------------------------------------------------------- |
+| `disconnected()`              | Emmited when the port is disconnected or does not receive any signal                            |
+| `connected()`                 | Emmited when the port is re-connected or starts receiving signal again after being disconnected |
+| `error()`                     | Emmited when an error occurs, is emmited only once                                              |
+:::
+
+## Usage with Typescript
+You can also use all these methods with [signageOS TypeScript](/knowledge-base/dev-tools-cli-typescript).
+```typescript
+onDisconnected(listener: (event: {
+	type: 'disconnected';
+	srcArguments: {
+		uri: string;
+		x: number;
+		y: number;
+		width: number;
+		height: number;
+	};
+}) => void): void;
+onConnected(listener: (event: { 
+	type: 'connected'; 
+	srcArguments: { 
+		uri: string; 
+		x: number; 
+		y: number; 
+		width: number; 
+		height: number; 
+	};
+}) => void): void;
+onError(listener: (event: {
+	type: 'error';
+	srcArguments: {
+		uri: string;
+		x: number;
+		y: number;
+		width: number;
+		height: number;
+	};
+	errorMessage: string;
+}) => void): void;
+```
+
+## Errors
+Although we are doing our best, following errors may occur when playing content from the internal ports.
+
+::: table-responsive
+| Code | Type | Message |
+| ---- | ---- | ------- |
+| 51501 | InternalVideoError | Couldn't play the video. |
+| 51503 | InternalVideoError | Couldn't stop the video. |
+:::

package/docs/js-api/js-video-stream.md

@@ -0,0 +1,230 @@
+---
+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
+::: table-responsive
+| 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          |
+| `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          |
+:::
+
+::: alert alert--warning
+Are you using **Samsung Tizen** to play streams? [Read more about limitation and Tizen-specific details](knowledge-base/stream-playback-on-tizen).
+:::
+
+## prepare()
+Calls the internal player and prepares a video stream in memory, so it can later start playing instantaneously.
+
+::: alert alert--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
+::: table-responsive
+|      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 	              |
+| `protocol`     | String                      | <div class="red">Yes</div> | Protocol that the stream is using             |
+|^^|^^|^^| Types: `HLS`, `RTP`, `HTTP`, `UDP`, `RTMP`, `RTSP`. |
+:::
+
+### Javascript syntax
+```javascript
+await sos.stream.prepare(uri,  x,  y,  width,  height,  protocol);
+```
+
+<div class="row d-flex align-content-stretch force-padding-20">
+    <div class="col-12 d-flex">
+        <a class="wide-box wide-box--white d-flex align-content-stretch widebox-kb-color" target="_blank" href="https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/stream">
+            <div>
+                <div class="wide-box__image d-flex align-items-center">
+                    <i class="fab fa-github svg-black"></i>
+                </div>
+            <div>
+                <h3 class="wide-box__title wide-box__title__small pl-85">Working example on our Github</h3>
+                <div class="wide-box__description">Stream video Applet example</div>
+            </div>
+            </div>
+        </a>
+    </div>
+</div>
+
+## play()
+Calls the internal player and starts a video stream in correct position.
+
+::: alert alert--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
+::: table-responsive
+|      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 	              |
+| `protocol`     | String                      | <div class="red">Yes</div> | Protocol that the stream is using             |
+|^^|^^|^^| Types: `HLS`, `RTP`, `HTTP`, `UDP`, `RTMP`, `RTSP`. |
+:::
+
+### Javascript syntax
+```javascript
+await sos.stream.play(uri,  x,  y,  width,  height,  protocol);
+```
+
+<div class="row d-flex align-content-stretch force-padding-20">
+    <div class="col-12 d-flex">
+        <a class="wide-box wide-box--white d-flex align-content-stretch widebox-kb-color" target="_blank" href="https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/stream">
+            <div>
+                <div class="wide-box__image d-flex align-items-center">
+                    <i class="fab fa-github svg-black"></i>
+                </div>
+            <div>
+                <h3 class="wide-box__title wide-box__title__small pl-85">Working example on our Github</h3>
+                <div class="wide-box__description">Stream video Applet example</div>
+            </div>
+            </div>
+        </a>
+    </div>
+</div>
+
+## stop()
+Stops the video stream playback. 
+
+### Javascript syntax
+```javascript
+await sos.stream.stop(uri,  x,  y,  width,  height);
+```
+
+### Parameters:
+::: table-responsive
+|      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 	                |
+:::
+
+## 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
+});
+```
+
+## Stream events
+All stream events have the same format.
+
+`type` property contains string with the event type. Type can be `connected`, `disconnected` or `error`.
+
+`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 event:
+```json
+{
+  "type": "connected",
+  "srcArguments": {
+    "uri": "<uri>",
+    "x": 0,
+    "y": 0,
+    "width": 1920,
+    "height": 1080,
+    "protocol": "RTP"
+  }
+}
+```
+
+## Usage with Typescript
+You can also use all these methods with [signageOS TypeScript](/knowledge-base/dev-tools-cli-typescript).
+```typescript
+interface StreamEvent {
+    type: 'connected' | 'disconnected' | 'error',
+    srcArguments: {
+        uri: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        protocol: string;
+    }
+}
+play(
+	uri:  string,
+	x:  number,
+	y:  number,
+	width:  number,
+	height:  number,
+	protocolType:  'HLS'  |  'RTP'  |  'HTTP'  |  'UDP'  |  'RTMP'  |  'RTSP'
+): Promise<void>;
+stop(
+	uri:  string,
+	x:  number,
+	y:  number,
+	width:  number,
+	height:  number
+): Promise<void>;
+onConnected(listener: (event: StreamEvent) => void): void;
+onDisconnected(listener: (event: StreamEvent) => void): void;
+onError(listener: (event: StreamEvent) => void): void;
+```
+
+## Errors
+Although we are doing our best, following errors may occur when working with the video stream.
+
+::: table-responsive
+| 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. |
+:::