@signageos/front-applet 8.1.0 → 8.1.2

package/es6/FrontApplet/Stream/Stream.d.ts

@@ -7,20 +7,22 @@ import type { ITrackInfo, TrackType } from './IStreamTrackInfo';
 import { IStreamErrorEvent, IStreamEvent, IStreamTracksChangedEvent } from './streamEvents';
 import StreamProtocol from './StreamProtocol';
 /**
- * The `sos.video` API groups together methods for streaming videos.
+ * The `sos.stream` API groups together methods for streaming videos from different sources. There are various methods for preparing, playing, stopping, pausing, and resuming streams.
  *
- * :::warning
+ * Streams are identified by their URI and their position on the screen (x, y, width, height).
+ *
+ * This API allows you to play video stream from:
+ * - URL (e.g., HTTP, RTSP, RTP, UDP, RTMP)
+ * - HDMI (e.g., Picture-in-Picture, Internal ports) streams
  *
+ * :::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.
- *
  * :::
  */
 export default class Stream implements IStream {
@@ -31,113 +33,336 @@ export default class Stream implements IStream {
     /** @internal */
     constructor(messagePrefix: string, postMessage: IPostMessage<any>);
     /**
-     * The `prepare()` method prepares the stream in the background.
+     * 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.
-     *
      * :::
      *
+     * @param uri Network address where the stream is available.
+     * @param x Stream x-position on the screen
+     * @param y Stream y-position on the screen
+     * @param width Stream width on the screen
+     * @param height Stream height on the screen
+     * @param options Additional options for the stream
+     *
+     * @returns {Promise<void>} Returns a promise that resolves when the stream is prepared.
+     * @throws AppletStreamError If the protocol is not a string or if the parameters are invalid.
+     * @throws Error If parameters are invalid.
+     * @throws Error If device fail to prepare the stream.
      * @since 4.7.0
      *
-     * @example // {@link https://github.com/signageos/applet-examples/tree/master/examples/content-js-api/stream}
+     * @example // {@link https://github.com/signageos/applet-examples/tree/master/examples/content-js-api/stream | How to create video Applet with for streams}
+     * @example
+     * // 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');
      */
     prepare(uri: string, x: number, y: number, width: number, height: number, options?: IStreamPrepareOptions | keyof typeof StreamProtocol): Promise<void>;
     /**
-     * The `play()` method starts the streaming of a streaming previously prepared by `prepare()` method.
+     * The `play()` method starts the video stream based by uri or stream which was prepared by `prepare()` method.
+     *
+     * :::note Internal ports
+     * This method use same functionality, instead of URL (for stream), specify a URI of the port to display.
+     *
+     * | Port URI value | Description |
+     * |-----------------|-------------|
+     * | `internal://hdmi<number>` | HDMI |
+     * | `internal://dp` | DisplayPort |
+     * | `internal://dvi` | DVI |
+     * | `internal://pc` | PC or VGA |
+     *
+     * `<number>` has to be a value between 1 - 4, depending on which of the available HDMI ports you want to use.
+     * :::
      *
+     * @param uri Network address where the stream is available.
+     * @param x Stream x-position on the screen
+     * @param y Stream y-position on the screen
+     * @param width Stream width on the screen
+     * @param height Stream height on the screen
+     * @param options Additional options for the stream
+     *
+     * @returns {Promise<void>} Returns a promise that resolves when the stream is successfully started.
+     * @throws AppletStreamError If the protocol is not a string or if the parameters are invalid.
+     * @throws Error If parameters are invalid.
+     * @throws Error If the device fails to prepare the stream.
      * @since 1.0.18
+     *
+     * @example // {@link https://github.com/signageos/applet-examples/tree/master/examples/content-js-api/stream | How to create video Applet with for URL streams}
+     * @example // {@link https://github.com/signageos/applet-examples/tree/master/examples/content-js-api/stream-hdmi-port | How to create video Applet with HDMI port}
+     * @example
+     * // Example with specific protocol type
+     * await sos.stream.play(uri, x, y, width, height, { protocol: 'HTTP' });
+     *
+     * // Example with options - reconnect stream when it disconnects after 60 seconds
+     * await sos.stream.play(uri, x, y, width, height, { protocol: 'HTTP', autoReconnect: true, autoReconnectInterval: 60000 });
+     *
+     * // Example for playing HDMI port
+     * await sos.stream.play('internal://hdmi1', 0, 0, 1920, 1080, { protocol: 'RTP' });
      */
     play(uri: string, x: number, y: number, width: number, height: number, options?: IStreamOptions | keyof typeof StreamProtocol): Promise<void>;
     /**
-     * The `stop()` method stops the stream, it can't be resumed with `resume()`.
+     * The `stop()` method stops the active stream, it can't be later resumed with `resume()`.
      *
+     * @param uri Network address where the stream is available.
+     * @param x Stream x-position on the screen
+     * @param y Stream y-position on the screen
+     * @param width Stream width on the screen
+     * @param height Stream height on the screen
+     * @returns {Promise<void>} Returns a promise that resolves when the stream is stopped.
+     * @throws Error If parameters are invalid.
      * @since 1.0.18
+     *
+     * @example
+     * // Example of stopping an active stream
+     * await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080); // Start
+     * // ... after some time
+     * await sos.stream.stop('http://example.com/stream', 0, 0, 1920, 1080); // Stop
      */
     stop(uri: string, x: number, y: number, width: number, height: number): Promise<void>;
     /**
-     * The `pause()` method pauses the stream, it can be resumed with `resume()`.
+     * The `pause()` method pauses the active stream, it can be resumed with `resume()`.
      *
+     * @param uri Network address where the stream is available.
+     * @param x Stream x-position on the screen
+     * @param y Stream y-position on the screen
+     * @param width Stream width on the screen
+     * @param height Stream height on the screen
+     * @returns {Promise<void>} Returns a promise that resolves when the stream is paused.
+     * @throws Error If parameters are invalid.
      * @since 6.4.0
+     *
+     * @example
+     * // Example of pausing an active stream
+     * await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080); // Start
+     * // ... after some time
+     * await sos.stream.pause('http://example.com/stream', 0, 0, 1920, 1080); // Pause
      */
     pause(uri: string, x: number, y: number, width: number, height: number): Promise<void>;
     /**
-     * The `resume()` method resumes the stream paused by `pause()`.
+     * The `resume()` method resumes the paused stream by `pause()` function.
      *
+     * @param uri Network address where the stream is available.
+     * @param x Stream x-position on the screen
+     * @param y Stream y-position on the screen
+     * @param width Stream width on the screen
+     * @param height Stream height on the screen
+     * @returns {Promise<void>} Returns a promise that resolves when the stream is successfully resumed.
+     * @throws Error If parameters are invalid.
      * @since 6.4.0
+     *
+     * @example
+     * // Example of resuming a paused stream
+     * await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080); // Start
+     * await sos.stream.pause('http://example.com/stream', 0, 0, 1920, 1080); // Pause
+     * // ... after some time
+     * await sos.stream.resume('http://example.com/stream', 0, 0, 1920, 1080); // Resume
      */
     resume(uri: string, x: number, y: number, width: number, height: number): Promise<void>;
     /**
-     * The `getTracks()` method returns a track list of a stream.
+     * The `getTracks()` method returns a list of subtitles, video, and audio tracks of a stream.
      *
+     * @param videoId The video properties of the stream to get tracks for.
+     * @returns {Promise<ITrackInfo[]>} Returns array of object with information about subtitles, video, and audio tracks.
      * @since 6.1.0
+     *
+     * @example
+     * // Example of getting tracks for a stream
+     * await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080);
+     * const tracks = await sos.stream.getTracks(streamId);
+     * console.log(tracks); // Outputs an array of track information
      */
     getTracks(videoId: IVideoProperties): Promise<ITrackInfo[]>;
     /**
-     * The `selectTrack()` method selects a track of a stream.
+     * The `selectTrack()` method selects a text (subtitles), video or audio track of a stream.
      *
+     * @param videoId The video properties of the stream to select track for.
+     * @param trackType The type of the track to select (e.g., 'TEXT', 'AUDIO', 'VIDEO').
+     * @param groupId The group ID of the track to select.
+     * @param trackIndex The index of the track to select within the group.
+     * @throws Error If parameters are invalid or if the track type is not supported.
+     * @returns {Promise<void>} Resolves when the track is successfully selected.
      * @since 6.1.0
+     *
+     * @example // {@link https://github.com/signageos/applet-examples/tree/master/examples/content-js-api/stream-subtitles | How to set subtitles for a stream}
+     *
+     * @example
+     * // Example of selecting a track for a stream
+     * await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080);
+     *
+     * // Select the first audio track in the group with ID 'audioGroup1'
+     * await sos.stream.selectTrack(videoId, 'AUDIO', 'audioGroup1', 0);
+     * // Select the first text track in the group with ID 'subtitlesGroup1'
+     * await sos.stream.selectTrack(videoId, 'TEXT', 'subtitlesGroup1', 0);
+     * // Select the first video track in the group with ID 'videoGroup1'
+     * await sos.stream.selectTrack(videoId, 'VIDEO', 'videoGroup1', 0);
      */
     selectTrack(videoId: IVideoProperties, trackType: TrackType, groupId: string, trackIndex: number): Promise<void>;
     /**
-     * The `resetTrack()` method resets a track of a stream.
+     * The `resetTrack()` method resets a selected track of a stream.
+     *
+     * @param videoId The video properties of the stream to reset track for.
+     * @param trackType The type of the track to reset (e.g., 'TEXT', 'AUDIO', 'VIDEO').
+     * @param groupId The group ID of the track to reset. If not provided, the first track in the group will be reset.
+     * @throws Error If parameters are invalid or if the track type is not supported.
+     * @returns {Promise<void>} Resolves when the track is successfully reset.
      *
      * @since 6.1.0
+     *
+     * @example
+     * // Example of resetting a track for a stream
+     * await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080);
+     * // Reset the audio track in the group with ID 'audioGroup1'
+     * await sos.stream.resetTrack(videoId, 'AUDIO', 'audioGroup1');
      */
     resetTrack(videoId: IVideoProperties, trackType: TrackType, groupId?: string): Promise<void>;
     /**
-     * The `onTracksChanged()` method sets up a listener, which is called whenever a track is changed.
+     * The `onTracksChanged()` method sets up a listener, which is called whenever a track is changed
+     * from functions `selectTrack()` or `resetTrack()`.
      *
+     * @param listener The listener function to be called when the event occurs.
+     * @returns {void} Resolves when the listener is successfully set up.
      * @since 6.1.0
+     *
+     * @example
+     * // Example of setting up a listener with starting a stream and selecting a track
+     * await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080);
+     * await sos.stream.selectTrack(videoId, 'AUDIO', 'audioGroup1', 0);
+     *
+     * // Create the listener for tracks changed event
+     * sos.stream.onTracksChanged((event) => {
+     *     console.log('Track type:', event.tracks[0].trackType); // AUDIO
+     *     console.log('Track group ID:', event.tracks[0].groupId); // audioGroup1
+     *     console.log('Track index:', event.tracks[0].trackIndex); // 0
+     * });
      */
     onTracksChanged(listener: (event: IStreamTracksChangedEvent) => void): void;
     /**
-     * The `onTracksChanged()` method sets up a listener, which is called whenever an unexpected error occurs during a stream.
+     * The `onError()` method sets up a listener, which is called whenever an unexpected error occurs during a stream.
      *
+     * @param listener The listener function to be called when the event occurs.
+     * @returns {void} Resolves when the listener is successfully set up.
      * @since 1.0.20
+     *
+     * @example
+     * // Example of setting up a listener for the error event
+     * await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080);
+     * sos.stream.onError((event) => {
+     *     console.error('Stream error:', event.errorMessage);
+     * });
      */
     onError(listener: (event: IStreamErrorEvent) => void): void;
     /**
      * The `onConnected()` method sets up a listener, which is called whenever a stream is connected.
      *
+     * @param listener The listener function to be called when the event occurs.
+     * @returns {void} Resolves when the listener is successfully set up.
      * @since 1.0.20
+     *
+     * @example
+     * // Example of setting up a listener for the connected event
+     * await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080);
+     * sos.stream.onConnected((event) => {
+     *   console.log('Stream connected:', event.srcArguments.uri);
+     * });
      */
     onConnected(listener: (event: IStreamEvent<'connected'>) => void): void;
     /**
      * The `onDisconnected()` method sets up a listener, which is called whenever a stream gets disconnected.
+     * Usually when source URI is not available anymore or when the stream is stopped.
      *
+     * @param listener The listener function to be called when the event occurs.
+     * @returns {void} Resolves when the listener is successfully set up.
      * @since 1.0.20
+     *
+     * @example
+     * // Example of setting up a listener for the disconnected event
+     * await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080);
+     * sos.stream.onDisconnected((event) => {
+     *     console.log('Stream disconnected:', event.srcArguments.uri);
+     * });
      */
     onDisconnected(listener: (event: IStreamEvent<'disconnected'>) => void): void;
     /**
      * The `onPrepare()` method sets up a listener, which is called whenever a stream gets prepared.
      *
+     * @param listener The listener function to be called when the event occurs.
+     * @returns {void} Resolves when the listener is successfully set up.
      * @since 5.12.0
+     *
+     * @example
+     * // Example of setting up a listener for the prepare event
+     * await sos.stream.prepare('http://example.com/stream', 0, 0, 1920, 1080);
+     * sos.stream.onPrepare((event) => {
+     *     console.log('Stream prepared:', event.srcArguments.uri);
+     * });
      */
     onPrepare(listener: (event: IStreamEvent<'prepare'>) => void): void;
     /**
      * The `onPlay()` method sets up a listener, which is called whenever a stream starts playing.
      *
+     * @param listener The listener function to be called when the event occurs.
+     * @returns {void} Resolves when the listener is successfully set up.
      * @since 5.12.0
+     *
+     * @example
+     * // Example of setting up a listener for the play event
+     * await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080);
+     * sos.stream.onPlay((event) => {
+     *     console.log('Stream started playing:', event.srcArguments.uri);
+     * });
      */
     onPlay(listener: (event: IStreamEvent<'play'>) => void): void;
     /**
      * The `onStop()` method sets up a listener, which is called whenever a stream stops.
      *
+     * @param listener The listener function to be called when the event occurs.
+     * @returns {void} Resolves when the listener is successfully set up.
      * @since 5.12.0
+     *
+     * @example
+     * // Example of setting up a listener for the stop event
+     * await sos.stream.stop('http://example.com/stream', 0, 0, 1920, 1080);
+     * sos.stream.onStop((event) => {
+     *     console.log('Stream stopped:', event.srcArguments.uri);
+     * });
      */
     onStop(listener: (event: IStreamEvent<'stop'>) => void): void;
     /**
-     * The `onStop()` method sets up a listener, which is called whenever a stream is paused.
+     * The `onPause()` method sets up a listener, which is called whenever a stream is paused.
      *
+     * @param listener The listener function to be called when the event occurs.
+     * @returns {void} Resolves when the listener is successfully set up.
      * @since 5.12.0
+     *
+     * @example
+     * // Example of setting up a listener for the pause event
+     * await sos.stream.pause('http://example.com/stream', 0, 0, 1920, 1080);
+     * sos.stream.onPause((event) => {
+     *     console.log('Stream paused:', event.srcArguments.uri);
+     * });
      */
     onPause(listener: (event: IStreamEvent<'pause'>) => void): void;
     /**
-     * The `onStop()` method sets up a listener, which is called whenever a stream is resumed.
+     * The `onResume()` method sets up a listener, which is called whenever a stream is resumed.
      *
+     * @param listener The listener function to be called when the event occurs.
+     * @returns {void} Resolves when the listener is successfully set up.
      * @since 5.12.0
+     *
+     * @example
+     * // Example of setting up a listener for the resume event
+     * await sos.stream.pause('http://example.com/stream', 0, 0, 1920, 1080); // Pause the stream
+     * // ... after some time
+     * await sos.stream.resume('http://example.com/stream', 0, 0, 1920, 1080);
+     * sos.stream.onResume((event) => {
+     *     console.log('Stream resumed:', event.srcArguments.uri);
+     * });
      */
     onResume(listener: (event: IStreamEvent<'resume'>) => void): void;
     /** @internal */