@signageos/front-applet 7.2.0 → 8.0.1

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

@@ -1,384 +0,0 @@
----
-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
-
-| 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()`	  		 | Join sync group (**DEPRECATED**) |  1.0.32 |
-| `joinGroup()`		 | Join sync group |  5.7.0 |
-| `wait()`	  		 | Wait for other devices in the network for proper sync |  1.0.32 |
-| `cancelWait()`     | Cancel pending waits | 5.12.0 |
-| `setValue()`		 | Broadcast values for all master devices (**DEPRECATED**) |  2.0.0 |
-| `broadcastValue()` | Used for broadcast values for all master devices |  5.7.0 |
-| `isMaster()`       | Determine if device is master of the sync group | 6.7.0 |
-| `onValue()`	     | Event called when device receives value broadcasted by another device in the network |  2.0.0 |
-| `onStatus()`	     | Peridocally emits event with information about sync group - connected devices and master status |  2.1.0 |
-| `onClosed()`	     | Event called when synchronizer is closed |  5.12.0 |
-
-:::note[GitHub Example]
-- [Synchronized video through applets](https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/sync-video)
-- [Synchronization mixed content](https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/sync-mixed-content)
-:::
-
-## 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
-
-| Param    | Type   | Required                     | Description                   |
-| -------- | ------ | :--------------------------: | ----------------------------- |
-| `engine` | String | <div class="yellow">No</div> | Synchronization engine to use |
-| `uri`    | String | <div class="yellow">No</div> | Address of sync server. Only relevant for `sync-server`. If omitted, the default server will be used. 
-
-### Engine
-
-
-| Engine        | Description                                                                              |
-| ------------- | ---------------------------------------------------------------------------------------- |
-| `sync-server` | (**Default**) Use external sync server. Device will connect to the server via websocket. |
-| `p2p-local`   | Synchronize directly with other devices in the local network via UDP and TCP.            |
-| `udp`         | (**Deprecated - use p2p-local**) Synchronize directly with other devices in the local network via UDP. 
-
-:::info
-All devices, that should be synchronized together, must select the same engine.
-Otherwise they won't be able to communicate with each other.
-:::
-
-### Javascript example
-```javascript
-// use default engine
-await sos.sync.connect().then(() => {
-    // do other things once connected
-});
-
-// use sync-server engine and default server
-await sos.sync.connect({ engine: 'sync-server' }).then(() => {
-    // do other things once connected
-});
-
-// use sync-server engine and custom server
-await sos.sync.connect({
-    engine: 'sync-server',
-    uri: syncServerUri,
-}).then(() => {
-    // do other things once connected
-});
-
-// use sync-server engine and custom server
-await sos.sync.connect({
-    engine: 'sync-server',
-    uri: syncServerUri,
-}).then(() => {
-    // do other things once connected
-});
-
-// use p2p-local engine
-await sos.sync.connect({ engine: 'p2p-local' }).then(() => {
-    // do other things once connected
-});
-
-// call with syncServerUri as direct argument, now deprecated
-// this way it will automatically pick sync-server engine
-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()
-:::warning
-This method is deprecated and will be removed in the future. Use `joinGroup()` instead. These two methods function identically.
-:::
-
-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
-
-|      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 |
-| `deviceIdentification`  | String  | <div class="yellow">No</div> | Is identification of device connected to groupName. 
-
-### Javascript example
-```javascript
-await sos.sync.init('someRandomNameGroup', 'device1');
-```
-
-## joinGroup()
-Once we're connected, we have to join a sync group. Before any communication takes place, all participating devices have to be connected and recognize one another. Recommended to call this method early.
-
-### Parameters
-
-|      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 |
-| `deviceIdentification`  | String  | <div class="yellow">No</div> | Is identification of device connected to groupName. 
-
-### Javascript example
-```javascript
-await sos.sync.joinGroup({
-    groupName: 'someRandomNameGroup',
-    deviceIdentification: 'device1',
-});
-```
-
-## 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
-
-|      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 `joinGroup` is called with custom group name, 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 
-
-## cancelWait()
-Sometimes it's necessary to cancel a pending wait.
-One such situation would be when the group has to make a sudden change in content or another behavior but
-there's a risk that part of the group already called `wait()` and is waiting for the rest but the rest will never call it at this point.
-In order to gracefully cleanup any pending activity, use this method.
-
-Any pending wait will be canceled and the promise will be rejected with an error.
-
-### Parameters
-
-| Param       | Type    | Required                     | Description  |
-| ----------- | ------- | :--------------------------: | ------------ |
-| `groupName` | String  | <div class="yellow">No</div> | If `joinGroup` is called with custom group name, the same group name as the second argument has to be passed. 
-
-### Javascript example
-```javascript
-sos.sync.wait('someData', 'someRandomNameGroup').catch((err) => {
-    // this will happend once cancelWait is called
-    console.error('wait failed', err);
-});
-
-// this will cause above wait promise to reject
-await sos.sync.cancelWait('someRandomNameGroup');
-```
-
-## 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
-
-| 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 |
-| `onStatus()` | event | Event called when device is connected and periodic every 30s from sync server - report connected devices | 2.1.0 
-
-## setValue()
-:::warning
-This method is deprecated and will be removed in the future. Use `broadcastValue()` instead. These two methods function identically.
-:::
-
-This method can be called by any device to broadcast a value to the whole group.
-
-### Parameters
-
-|  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 `joinGroup` is called with custom group name, the same group name has to be passed as the third argument    
-
-### Javascript example
-```javascript
-await sos.sync.setValue('some-key', 'some-value', 'some-group');
-```
-
-## broadcastValue()
-This method can be called by any device to broadcast a value to the whole group.
-
-### Parameters
-
-|  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 `joinGroup` is called with custom group name, the same group name has to be passed as the third argument    
-
-### Javascript example
-```javascript
-await sos.sync.broadcastValue({
-    key: 'some-key',
-    value: 'some-value',
-    groupName: 'some-group'
-});
-```
-
-## 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/>
-
-## isMaster()
-Returns true, if device is master of the sync group.
-
-### Parameters
-
-|  Param   |Type  | Required | Description  |
-| -------------- | --------- | :------: | ------------------- |
-| `groupName`    | String    | <div class="yellow">No</div> | If `joinGroup` is called with custom group name, the same group name has to be passed as the third argument |
-
-### Javascript example
-```javascript
-const isMaster = await sos.sync.isMaster('some-group');
-```
-
-:::info
-Different devices can become masters at different times. Also the same device may be master in one group but slave in another.
-:::
-
-## Event onValue()
-Every device should register a listener to receive and process broadcasted values.
-
-### Javascript example
-```javascript
-sos.sync.onValue((key, value, groupName) => {
-	// do something with the new value
-});
-```
-
-<br/>
-
-## Event onStatus()
-Used for receiving information about the sync groups that the device is a member of. Emits periodically or whenever there is a change (i.e. new device connects/disconnects to/from the group).
-
-Status contains the following properties:
-- `status.groupName` - name of the group
-- `status.connectedPeers` - array of device identifications connected to the group
-- `status.isMaster` - boolean, true if device is currently master of the group (this may change over time)
-
-### Javascript example
-```javascript
-sos.sync.onStatus((status) => {
-	// do something with the new value
-    const connectedPeers = status.connectedPeers;
-    const groupName = status.groupName;
-    const isMaster = status.isMaster;
-});
-```
-
-## Event onClosed()
-Emitted when synchronizer is closed for whatever reason.
-
-If it closed because `close()` was called, it will emit without any arguments.
-if it closed because of an error, it will emit with an error object as the first argument.
-
-### Javascript example
-```javascript
-sos.sync.onClosed((error) => {
-	if (error) {
-        console.error('Synchronizer closed with an error', error);
-    } else {
-        console.info('Synchronizer closed');
-    }
-});
-```
-
-## 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
-connect(syncServerUri?: string): Promise<void>;
-
-close(): Promise<void>;
-
-/** @deprecated use joinGroup */
-init(groupName?: string, deviceIdentification?: string): Promise<void>;
-
-joinGroup(args: {
-    groupName?: string;
-    deviceIdentification?: string;
-}): Promise<void>;
-
-wait(data?: any, groupName?: string): Promise<any>;
-
-cancelWait(groupName?: string): Promise<void>;
-
-/** @deprecated use broadcastValue */
-setValue(key: string, value: any, groupName?: string): Promise<void>;
-
-broadcastValue(args: {
-    groupName?: string;
-    key: string;
-    value: any;
-}): Promise<void>;
-
-isMaster(groupName?: string): Promise<boolean>;
-
-onValue(listener: (
-	key: string, 
-	value: any,
-	groupName?: string
-) => void): void;
-
-onStatus(listener: (status: {
-    groupName: string;
-    connectedPeers: string[];
-    isMaster: boolean;
-}) => void): void;
-
-onClosed(listener: (
-	error?: Error;
-) => void): void;
-```
-
-## Errors
-Although we are doing our best, following errors may occur when working with the synchronizer.
-
-
-| 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/content/js-video-inputs-internal-ports.md

@@ -1,131 +0,0 @@
----
-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
-
-| 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](js-video-stream). Instead of URL (for stream), **specify an URI of the port** to display.
-
-### Parameters
-
-|      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);
-```
-
-:::note[GitHub Example]
-[Stream HDMI port Applet example](https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/stream-hdmi-port)
-:::
-
-## Valid URI values 
-
-
-|   Value                 |   Description                   |
-| ----------------------- | ------------------------------- |
-| `internal://hdmi<number>` | HDMI                            |
-| `internal://dp`          | DisplayPort                     |
-| `internal://dvi`          | DVI                             |
-| `internal://pc`           | PC or VGA                       
-
-:::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:
-
-|      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.
-
-
-| 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](https://docs.signageos.io/hc/en-us/articles/4405069154962#signageos-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.
-
-
-| Code | Type | Message |
-| ---- | ---- | ------- |
-| 51501 | InternalVideoError | Couldn't play the video. |
-| 51503 | InternalVideoError | Couldn't stop the video.