@signageos/front-applet 8.1.1 → 8.1.3

package/docs/sos/video.md

@@ -4,36 +4,132 @@ sidebar_position: 0
 
 # video
 
-<Admonition type="info" icon="" title="">
-  Learn more about using this API [here](https://developers.signageos.io/docs/applets/api-guides/video)
-</Admonition>
+We know how crucial video is for digital signage. So we made it easy. This guide will walk you through playing video using the sos.video API. This allows you to play video natively on any platform.
 
-The `sos.video` API groups together methods for video playback.
+The `sos.video` provides you 4 methods to handle the playback:
+- `prepare()` - Prepare will load the video into memory and prepare it for immediate playback.
+- `play()` - This method loads the video into memory (if it hasn't been loaded previously) and starts the video playback.
+- `pause()` / `resume()` - This method pauses the video that was previously started to play, it is possible to resume the playback with `resume()`.
+- `stop()` - This method stops the playback and unloads the video from memory.
 
-:::warning
-First 5 parameters (uri, x, y, width, height) are unique identifiers for playing the video using play, stop, resume and pause methods.
+:::warning Video identification
+First 5 parameters (uri, x, y, width, and height) are unique identifiers for playing the video using play, stop, resume, and pause methods.
 :::
 
+## Gapless video playback
+It is often desirable to be able to play different videos consecutively without "black" frames. To achieve this next video in the queue needs to be loaded before the current video ends. How to achieve this may differ from platform to platform. Applet JS SDK handles this under the hood and provides you with `prepare()`, `play()` and `stop()` methods.
+Each video has to be pre-loaded with `prepare()` while the previous video is still playing, and after the video ends it should be unloaded immediately with `stop()`. This is because some (especially older ones) platforms support that only 2 videos are loaded into memory at any time (one playing and one ready to play).
+
+![](https://docs.signageos.io/hc/article_attachments/9093558407708)
+
+```ts
+const { filePath } = await sos.offline.cache.loadOrSaveFile(
+ 'video-1.mp4',
+ 'https://static.signageos.io/assets/video-test-1_e07fc21a7a72e3d33478243bd75d7743.mp4',
+);
+
+const video = [filePath, 0, 0, 1280, 720];
+
+await sos.video.play(...video);
+
+// pause the video after 2s
+setTimeout(() => sos.video.pause(...video), 2000);
+
+// resume the paused video
+setTimeout(() => sos.video.resume(...video), 2500);
+
+// stop and unload the video
+setTimeout(() => sos.video.stop(...video), 4000);
+```
+
 ## Methods
 
 ### onceEnded()
 
-The `onceEnded()` method returns a promise which is resolved after the specified video ended.
+The `onceEnded()` method returns a promise that is resolved after the specified video ends.
 
 ```ts expandable
 onceEnded(uri: string, x: number, y: number, width: number, height: number): Promise<void>;
 ```
 
+#### Params
+
+| Name     | Type     | Description                                    |
+|----------|----------|------------------------------------------------|
+| `uri`    | `string` | Address to remote (online) or local video file |
+| `x`      | `number` | x-position for video on screen                 |
+| `y`      | `number` | y-position for video on screen                 |
+| `width`  | `number` | Video width on screen                          |
+| `height` | `number` | Video height on screen                         |
+
+#### Return value
+
+Returns a promise that resolves when the video ends.
+
+#### Possible errors
+
+
+- Error If the parameters are not valid.
+- Error If the video was not played yet.
+
+#### Example
+
+```ts
+// Example of using onceEnded to wait for a video to end
+await sos.video.prepare('https://example.com/video.mp4', 0, 0, 1920, 1080);
+while (true) {
+  await sos.video.play('https://example.com/video.mp4', 0, 0, 1920, 1080);
+  // Wait for the video to stop to start playing it again
+  await sos.video.onceEnded('https://example.com/video.mp4', 0, 0, 1920, 1080);
+}
+```
+
 <Separator />
 
 ### onceStop()
 
-The `onceEnded()` method returns a promise which is resolved after the specified video have been stopped.
+The `onceStop()` method returns a promise that is resolved after the specified video has been stopped.
 
 ```ts expandable
 onceStop(uri: string, x: number, y: number, width: number, height: number): Promise<void>;
 ```
 
+#### Params
+
+| Name     | Type     | Description                                    |
+|----------|----------|------------------------------------------------|
+| `uri`    | `string` | Address to remote (online) or local video file |
+| `x`      | `number` | x-position for video on screen                 |
+| `y`      | `number` | y-position for video on screen                 |
+| `width`  | `number` | Video width on screen                          |
+| `height` | `number` | Video height on screen                         |
+
+#### Return value
+
+Returns a promise that resolves when the video is stopped.
+
+#### Possible errors
+
+
+- Error If the parameters are not valid.
+- Error If the video was not played yet.
+
+#### Example
+
+```ts
+// Example of using onceStop to wait for a video to stop
+await sos.video.prepare('https://example.com/video.mp4', 0, 0, 1920, 1080);
+while (true) {
+  await sos.video.play('https://example.com/video.mp4', 0, 0, 1920, 1080);
+  // Wait few seconds for the video to play
+  await new Promise((resolve) => setTimeout(resolve, 5000));
+  // Stop the video and wait for it to stop
+  await sos.video.stop('https://example.com/video.mp4', 0, 0, 1920, 1080);
+  await sos.video.onceStop('https://example.com/video.mp4', 0, 0, 1920, 1080);
+  // Now the video is stopped, and we can play it again
+}
+```
+
 <Separator />
 
 ### onEnded()
@@ -43,13 +139,24 @@ The `onEnded()` method sets up a listener, which is called whenever a video fini
 ```ts expandable
 onEnded(listener: (event: IVideoEvent) => void): void;
 // show-more
+/**
+ * Represents an event related to video playback.
+ */
 interface IVideoEvent {
+    /** The type of the video event. */
     type: VideoEventType;
+    /** Properties of video that created the event */
     srcArguments: IVideoProperties;
 }
 
+/**
+ * Represents the types of video events that can occur.
+ */
 type VideoEventType = 'prepare' | 'play' | 'stop' | 'pause' | 'resume' | 'ended' | 'error';
 
+/**
+ * Video properties interface for defining the properties of a played video.
+ */
 interface IVideoProperties {
     uri: string;
     x: number;
@@ -60,6 +167,26 @@ interface IVideoProperties {
 
 ```
 
+#### Params
+
+| Name       | Type                           | Description                                                    |
+|------------|--------------------------------|----------------------------------------------------------------|
+| `listener` | `(event: IVideoEvent) => void` | The listener function to be called when an ended event occurs. |
+
+#### Return value
+
+Resolves when the listener is successfully set up.
+
+#### Example
+
+```ts
+// Play a video and handle the end of playback
+await sos.video.play('https://example.com/video.mp4', 0, 0, 1920, 1080);
+sos.video.onEnded((event) => {
+    console.log('Video ended:', event);
+});
+```
+
 <Separator />
 
 ### onError()
@@ -69,13 +196,24 @@ The `onError()` method sets up a listener, which is called whenever a video fail
 ```ts expandable
 onError(listener: (event: IVideoEvent) => void): void;
 // show-more
+/**
+ * Represents an event related to video playback.
+ */
 interface IVideoEvent {
+    /** The type of the video event. */
     type: VideoEventType;
+    /** Properties of video that created the event */
     srcArguments: IVideoProperties;
 }
 
+/**
+ * Represents the types of video events that can occur.
+ */
 type VideoEventType = 'prepare' | 'play' | 'stop' | 'pause' | 'resume' | 'ended' | 'error';
 
+/**
+ * Video properties interface for defining the properties of a played video.
+ */
 interface IVideoProperties {
     uri: string;
     x: number;
@@ -86,22 +224,53 @@ interface IVideoProperties {
 
 ```
 
+#### Params
+
+| Name       | Type                           | Description                                              |
+|------------|--------------------------------|----------------------------------------------------------|
+| `listener` | `(event: IVideoEvent) => void` | The listener function to be called when an error occurs. |
+
+#### Return value
+
+Resolves when the listener is successfully set up.
+
+#### Example
+
+```ts
+// Play a video and handle errors
+await sos.video.play('https://example.com/video.mp4', 0, 0, 1920, 1080);
+sos.video.onError((event) => {
+    console.error('Video error:', event);
+});
+```
+
 <Separator />
 
 ### onPause()
 
-The `onPause()` method sets up a listener, which is called whenever a video is paused
+The `onPause()` method sets up a listener, which is called whenever a video is paused with `pause()` method.
 
 ```ts expandable
 onPause(listener: (event: IVideoEvent) => void): void;
 // show-more
+/**
+ * Represents an event related to video playback.
+ */
 interface IVideoEvent {
+    /** The type of the video event. */
     type: VideoEventType;
+    /** Properties of video that created the event */
     srcArguments: IVideoProperties;
 }
 
+/**
+ * Represents the types of video events that can occur.
+ */
 type VideoEventType = 'prepare' | 'play' | 'stop' | 'pause' | 'resume' | 'ended' | 'error';
 
+/**
+ * Video properties interface for defining the properties of a played video.
+ */
 interface IVideoProperties {
     uri: string;
     x: number;
@@ -112,6 +281,26 @@ interface IVideoProperties {
 
 ```
 
+#### Params
+
+| Name       | Type                           | Description                                                   |
+|------------|--------------------------------|---------------------------------------------------------------|
+| `listener` | `(event: IVideoEvent) => void` | The listener function to be called when a pause event occurs. |
+
+#### Return value
+
+Resolves when the listener is successfully set up.
+
+#### Example
+
+```ts
+// Play a video and handle the pause event
+await sos.video.play('https://example.com/video.mp4', 0, 0, 1920, 1080);
+sos.video.onPause((event) => {
+    console.log('Video paused:', event); // Logs the pause event
+});
+```
+
 <Separator />
 
 ### onPlay()
@@ -121,13 +310,24 @@ The `onPlay()` method sets up a listener, which is called whenever a video start
 ```ts expandable
 onPlay(listener: (event: IVideoEvent) => void): void;
 // show-more
+/**
+ * Represents an event related to video playback.
+ */
 interface IVideoEvent {
+    /** The type of the video event. */
     type: VideoEventType;
+    /** Properties of video that created the event */
     srcArguments: IVideoProperties;
 }
 
+/**
+ * Represents the types of video events that can occur.
+ */
 type VideoEventType = 'prepare' | 'play' | 'stop' | 'pause' | 'resume' | 'ended' | 'error';
 
+/**
+ * Video properties interface for defining the properties of a played video.
+ */
 interface IVideoProperties {
     uri: string;
     x: number;
@@ -138,22 +338,54 @@ interface IVideoProperties {
 
 ```
 
+#### Params
+
+| Name       | Type                           | Description                                                  |
+|------------|--------------------------------|--------------------------------------------------------------|
+| `listener` | `(event: IVideoEvent) => void` | The listener function to be called when a play event occurs. |
+
+#### Return value
+
+Resolves when the listener is successfully set up.
+
+#### Example
+
+```ts
+// Play a video and handle the play event
+await sos.video.prepare('https://example.com/video.mp4', 0, 0, 1920, 1080);
+sos.video.onPlay((event) => {
+    console.log('Video started playing:', event);
+});
+await sos.video.play('https://example.com/video.mp4', 0, 0, 1920, 1080);
+```
+
 <Separator />
 
 ### onPrepare()
 
-The `onPrepare()` method sets up a listener, which is called whenever a video started to be prepared.
+The `onPrepare()` method sets up a listener, which is called whenever a video starts to be prepared.
 
 ```ts expandable
 onPrepare(listener: (event: IVideoEvent) => void): void;
 // show-more
+/**
+ * Represents an event related to video playback.
+ */
 interface IVideoEvent {
+    /** The type of the video event. */
     type: VideoEventType;
+    /** Properties of video that created the event */
     srcArguments: IVideoProperties;
 }
 
+/**
+ * Represents the types of video events that can occur.
+ */
 type VideoEventType = 'prepare' | 'play' | 'stop' | 'pause' | 'resume' | 'ended' | 'error';
 
+/**
+ * Video properties interface for defining the properties of a played video.
+ */
 interface IVideoProperties {
     uri: string;
     x: number;
@@ -164,22 +396,53 @@ interface IVideoProperties {
 
 ```
 
+#### Params
+
+| Name       | Type                           | Description                                                     |
+|------------|--------------------------------|-----------------------------------------------------------------|
+| `listener` | `(event: IVideoEvent) => void` | The listener function to be called when a prepare event occurs. |
+
+#### Return value
+
+Resolves when the listener is successfully set up.
+
+#### Example
+
+```ts
+// Play a video and handle the prepare event
+await sos.video.prepare('https://example.com/video.mp4', 0, 0, 1920, 1080);
+sos.video.onPrepare((event) => {
+    console.log('Video prepared:', event);
+});
+```
+
 <Separator />
 
 ### onResume()
 
-The `onResume()` method sets up a listener, which is called whenever a video is resumed
+The `onResume()` method sets up a listener, which is called whenever a video is resumed with the `resume()` method.
 
 ```ts expandable
 onResume(listener: (event: IVideoEvent) => void): void;
 // show-more
+/**
+ * Represents an event related to video playback.
+ */
 interface IVideoEvent {
+    /** The type of the video event. */
     type: VideoEventType;
+    /** Properties of video that created the event */
     srcArguments: IVideoProperties;
 }
 
+/**
+ * Represents the types of video events that can occur.
+ */
 type VideoEventType = 'prepare' | 'play' | 'stop' | 'pause' | 'resume' | 'ended' | 'error';
 
+/**
+ * Video properties interface for defining the properties of a played video.
+ */
 interface IVideoProperties {
     uri: string;
     x: number;
@@ -190,22 +453,55 @@ interface IVideoProperties {
 
 ```
 
+#### Params
+
+| Name       | Type                           | Description                                                    |
+|------------|--------------------------------|----------------------------------------------------------------|
+| `listener` | `(event: IVideoEvent) => void` | The listener function to be called when a resume event occurs. |
+
+#### Return value
+
+Resolves when the listener is successfully set up.
+
+#### Example
+
+```ts
+// Play a video and handle the resume event
+await sos.video.play('https://example.com/video.mp4', 0, 0, 1920, 1080);
+sos.video.onResume((event) => {
+    console.log('Video resumed:', event); // Logs the resume event
+});
+await sos.video.pause('https://example.com/video.mp4', 0, 0, 1920, 1080);
+await sos.video.resume('https://example.com/video.mp4', 0, 0, 1920, 1080);
+```
+
 <Separator />
 
 ### onStop()
 
-The `onStop()` method sets up a listener, which is called whenever a video has been stopped.
+The `onStop()` method sets up a listener, which is called whenever a video has been stopped with `stop()` method.
 
 ```ts expandable
 onStop(listener: (event: IVideoEvent) => void): void;
 // show-more
+/**
+ * Represents an event related to video playback.
+ */
 interface IVideoEvent {
+    /** The type of the video event. */
     type: VideoEventType;
+    /** Properties of video that created the event */
     srcArguments: IVideoProperties;
 }
 
+/**
+ * Represents the types of video events that can occur.
+ */
 type VideoEventType = 'prepare' | 'play' | 'stop' | 'pause' | 'resume' | 'ended' | 'error';
 
+/**
+ * Video properties interface for defining the properties of a played video.
+ */
 interface IVideoProperties {
     uri: string;
     x: number;
@@ -216,31 +512,124 @@ interface IVideoProperties {
 
 ```
 
+#### Params
+
+| Name       | Type                           | Description                                                  |
+|------------|--------------------------------|--------------------------------------------------------------|
+| `listener` | `(event: IVideoEvent) => void` | The listener function to be called when a stop event occurs. |
+
+#### Return value
+
+Resolves when the listener is successfully set up.
+
+#### Example
+
+```ts
+// Play a video and handle the stop event
+await sos.video.play('https://example.com/video.mp4', 0, 0, 1920, 1080);
+sos.video.onStop((event) => {
+    console.log('Video stopped:', event);
+});
+// Stop the video later...
+await sos.video.stop('https://example.com/video.mp4', 0, 0, 1920, 1080);
+```
+
 <Separator />
 
 ### pause()
 
-The `pause()` method pauses the video, playback can be resumed with `resume()`.
+The `pause()` method pauses the video; playback can be resumed with `resume()`. Stopped video can't be paused.
 
 ```ts expandable
 pause(uri: string, x: number, y: number, width: number, height: number): Promise<void>;
 ```
 
+#### Params
+
+| Name     | Type     | Description                                    |
+|----------|----------|------------------------------------------------|
+| `uri`    | `string` | Address to remote (online) or local video file |
+| `x`      | `number` | x-position for video on screen                 |
+| `y`      | `number` | y-position for video on screen                 |
+| `width`  | `number` | Video width on screen                          |
+| `height` | `number` | Video height on screen                         |
+
+#### Return value
+
+Returns a promise that resolves when the video is paused.
+
+#### Possible errors
+
+
+- Error If the parameters are not valid.
+- Error If any error occurs during the pausing of the video.
+
+#### Example
+
+```ts
+// Example of resuming a paused video
+const { filePath } = await sos.offline.cache.loadOrSaveFile('video-1.mp4', 'https://static.signageos.io/assets/video-test-1_e07fc21a7a72e3d33478243bd75d7743.mp4');
+const video = [filePath, 0, 0, 1920, 1080];
+// Prepare the video
+await sos.video.prepare(...video);
+// Play the video
+await sos.video.play(...video);
+// Pause the video after 2 seconds
+setTimeout(() => sos.video.pause(...video), 2000);
+```
+
 <Separator />
 
 ### play()
 
-The `play()` method starts the playback of a video previously prepared by `prepare()` method.
+The `play()` method starts the playback of a video or video that has been previously prepared by the `prepare()` method.
 
 ```ts expandable
 play(uri: string, x: number, y: number, width: number, height: number): Promise<void>;
 ```
 
+#### Params
+
+| Name     | Type     | Description                                    |
+|----------|----------|------------------------------------------------|
+| `uri`    | `string` | Address to remote (online) or local video file |
+| `x`      | `number` | x-position for video on screen                 |
+| `y`      | `number` | y-position for video on screen                 |
+| `width`  | `number` | Video width on screen                          |
+| `height` | `number` | Video height on screen                         |
+
+#### Return value
+
+Returns a promise that resolves when the video starts playing.
+
+#### Possible errors
+
+
+- Error If the parameters are not valid.
+- Error If any error occurs during the playback of the video.
+
+#### Example
+
+```ts
+const { filePath } = await sos.offline.cache.loadOrSaveFile('fileName', 'https://example.com/video.mp4');
+const video = [filePath, 0, 0, 1920, 1080];
+// Play the video
+await sos.video.play(...video);
+```
+
+:::note[GitHub Example]
+
+- [ Play one video in infinite loop](https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/video-loop-one)
+- [ Play multiple videos in infinite loop](https://github.com/signageos/applet-examples/tree/master/examples/content-js-api/video-multiple)
+- [ Switching video and images in infinite loop](https://github.com/signageos/applet-examples/tree/master/examples/content-js-api/video-and-images)
+
+:::
+
 <Separator />
 
 ### prepare()
 
-The `play()` method loads the video into memory and prepares it for a playback.
+The `prepare()` method loads the video into memory and prepares it for a playback, this is useful for gapless playback.
 
 ```ts expandable
 prepare(uri: string, x: number, y: number, width: number, height: number, options?: IOptions): Promise<void>;
@@ -248,7 +637,15 @@ prepare(uri: string, x: number, y: number, width: number, height: number, option
 interface IOptions {
     /** @deprecated */
     '4k'?: boolean;
+    /**
+     * Prepare stream or video in background.
+     * @default false
+     */
     background?: boolean;
+    /**
+     * Initial volume value of the stream.
+     * @default 100
+     */
     volume?: number;
 }
 
@@ -256,11 +653,38 @@ interface IOptions {
 
 #### Params
 
-| Name                              | Type      | Description                                                                   |
-|-----------------------------------|-----------|-------------------------------------------------------------------------------|
-| `options.`                        | `boolean` | 4k Support for 4k video (Deprecated since Tizen Core App v2.1.0)              |
-| `options.background` *(optional)* | `boolean` | Bring video behind the applet html (similar to z-index: -1)                   |
-| `options.volume` *(optional)*     | `number`  | Adjust volume of playing video itself (doesn't adjust display speaker volume) |
+| Name                              | Type       | Description                                    |
+|-----------------------------------|------------|------------------------------------------------|
+| `uri`                             | `string`   | Address to remote (online) or local video file |
+| `x`                               | `number`   | x-position for video on screen                 |
+| `y`                               | `number`   | y-position for video on screen                 |
+| `width`                           | `number`   | Video width on screen                          |
+| `height`                          | `number`   | Video height on screen                         |
+| `options` *(optional)*            | `IOptions` | Optional options for preparing the video.      |
+| `options.background` *(optional)* | `boolean`  | If view should be prepared in background.      |
+| `options.volume` *(optional)*     | `number`   | Initial volume value of the video.             |
+
+#### Return value
+
+Returns a promise which resolves when the video is prepared.
+
+#### Possible errors
+
+
+- Error If the parameters are not valid.
+- Error If any error occurs during the preparation of the video.
+
+#### Example
+
+```ts
+// Example of preparing and playing a video
+const { filePath } = await sos.offline.cache.loadOrSaveFile('video-1.mp4', 'https://static.signageos.io/assets/video-test-1_e07fc21a7a72e3d33478243bd75d7743.mp4');
+const video = [filePath, 0, 0, 1920, 1080];
+// Prepare the video
+await sos.video.prepare(...video);
+// Play the video
+await sos.video.play(...video);
+```
 
 <Separator />
 
@@ -276,18 +700,87 @@ removeEventListeners(): void;
 
 ### resume()
 
-The `resume()` method resumes the video paused by `pause()`.
+The `resume()` method resumes the video paused by `pause()` function. Stopped video can't be resumed.
 
 ```ts expandable
 resume(uri: string, x: number, y: number, width: number, height: number): Promise<void>;
 ```
 
+#### Params
+
+| Name     | Type     | Description                                    |
+|----------|----------|------------------------------------------------|
+| `uri`    | `string` | Address to remote (online) or local video file |
+| `x`      | `number` | x-position for video on screen                 |
+| `y`      | `number` | y-position for video on screen                 |
+| `width`  | `number` | Video width on screen                          |
+| `height` | `number` | Video height on screen                         |
+
+#### Return value
+
+Returns a promise that resolves when the video is resumed.
+
+#### Possible errors
+
+
+- Error If the parameters are not valid.
+- Error If any error occurs during the resuming of the video.
+
+#### Example
+
+```ts
+// Example of resuming a paused video
+const { filePath } = await sos.offline.cache.loadOrSaveFile('video-1.mp4', 'https://static.signageos.io/assets/video-test-1_e07fc21a7a72e3d33478243bd75d7743.mp4');
+const video = [filePath, 0, 0, 1920, 1080];
+// Prepare the video
+await sos.video.prepare(...video);
+// Play the video
+await sos.video.play(...video);
+// Pause the video after 2 seconds
+setTimeout(() => sos.video.pause(...video), 2000);
+// Resume the video after 3 seconds
+setTimeout(() => sos.video.resume(...video), 5000);
+```
+
 <Separator />
 
 ### stop()
 
-The `stop()` method stops the video, it can't be resumed with `resume()`.
+The `stop()` method stops the video; it can't be resumed with the `resume()` method.
 
 ```ts expandable
 stop(uri: string, x: number, y: number, width: number, height: number): Promise<void>;
+```
+
+#### Params
+
+| Name     | Type     | Description                                    |
+|----------|----------|------------------------------------------------|
+| `uri`    | `string` | Address to remote (online) or local video file |
+| `x`      | `number` | x-position for video on screen                 |
+| `y`      | `number` | y-position for video on screen                 |
+| `width`  | `number` | Video width on screen                          |
+| `height` | `number` | Video height on screen                         |
+
+#### Return value
+
+Returns a promise which resolves when the video is stopped.
+
+#### Possible errors
+
+
+- Error If the parameters are not valid.
+- Error If any error occurs during the stopping of the video.
+
+#### Example
+
+```ts
+// Example of stopping a video
+const { filePath } = await sos.offline.cache.loadOrSaveFile('video-1.mp4', 'https://static.signageos.io/assets/video-test-1_e07fc21a7a72e3d33478243bd75d7743.mp4');
+const video = [filePath, 0, 0, 1920, 1080];
+// Prepare and play the video
+await sos.video.prepare(...video);
+await sos.video.play(...video);
+// Stop the video after 5 seconds
+setTimeout(() => sos.video.stop(...video), 5000);
 ```