@signageos/front-applet 7.2.0 → 8.0.0

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

@@ -1,35 +1,150 @@
 import IPostMessage from '../IPostMessage';
-import StreamProtocol from './StreamProtocol';
-import IStreamMessage from './IStreamMessage';
-import { IStreamOptions, IStreamPrepareOptions } from '../Video/IOptions';
-import { ITrackInfo, TrackType } from './IStreamTrackInfo';
-import { IStreamErrorEventListener, IStreamEventListener, IStreamTracksChangedEventListener } from './streamListeners';
-import IVideoProperties from '../Video/IVideoProperties';
+import { IStreamOptions, type IStreamPrepareOptions } from '../Video/IOptions';
+import type IVideoProperties from '../Video/IVideoProperties';
 import IStream from './IStream';
+import IStreamMessage from './IStreamMessage';
+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.
+ *
+ * :::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 {
     private messagePrefix;
     private postMessage;
     static MESSAGE_PREFIX: string;
     private eventEmitter;
+    /** @internal */
     constructor(messagePrefix: string, postMessage: IPostMessage<any>);
+    /**
+     * The `prepare()` method prepares the stream in the background.
+     *
+     * :::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.
+     *
+     * :::
+     *
+     * @since 4.7.0
+     *
+     * @example // {@link https://github.com/signageos/applet-examples/tree/master/examples/content-js-api/stream}
+     */
     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.
+     *
+     * @since 1.0.18
+     */
     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()`.
+     *
+     * @since 1.0.18
+     */
     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()`.
+     *
+     * @since 6.4.0
+     */
     pause(uri: string, x: number, y: number, width: number, height: number): Promise<void>;
+    /**
+     * The `resume()` method resumes the stream paused by `pause()`.
+     *
+     * @since 6.4.0
+     */
     resume(uri: string, x: number, y: number, width: number, height: number): Promise<void>;
+    /**
+     * The `getTracks()` method returns a track list of a stream.
+     *
+     * @since 6.1.0
+     */
     getTracks(videoId: IVideoProperties): Promise<ITrackInfo[]>;
+    /**
+     * The `selectTrack()` method selects a track of a stream.
+     *
+     * @since 6.1.0
+     */
     selectTrack(videoId: IVideoProperties, trackType: TrackType, groupId: string, trackIndex: number): Promise<void>;
+    /**
+     * The `resetTrack()` method resets a track of a stream.
+     *
+     * @since 6.1.0
+     */
     resetTrack(videoId: IVideoProperties, trackType: TrackType, groupId?: string): Promise<void>;
-    onTracksChanged(listener: IStreamTracksChangedEventListener): void;
-    onError(listener: IStreamErrorEventListener): void;
-    onConnected(listener: IStreamEventListener<'connected'>): void;
-    onDisconnected(listener: IStreamEventListener<'disconnected'>): void;
-    onPrepare(listener: IStreamEventListener<'prepare'>): void;
-    onPlay(listener: IStreamEventListener<'play'>): void;
-    onStop(listener: IStreamEventListener<'stop'>): void;
-    onPause(listener: IStreamEventListener<'pause'>): void;
-    onResume(listener: IStreamEventListener<'resume'>): void;
+    /**
+     * The `onTracksChanged()` method sets up a listener, which is called whenever a track is changed.
+     *
+     * @since 6.1.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.
+     *
+     * @since 1.0.20
+     */
+    onError(listener: (event: IStreamErrorEvent) => void): void;
+    /**
+     * The `onConnected()` method sets up a listener, which is called whenever a stream is connected.
+     *
+     * @since 1.0.20
+     */
+    onConnected(listener: (event: IStreamEvent<'connected'>) => void): void;
+    /**
+     * The `onDisconnected()` method sets up a listener, which is called whenever a stream gets disconnected.
+     *
+     * @since 1.0.20
+     */
+    onDisconnected(listener: (event: IStreamEvent<'disconnected'>) => void): void;
+    /**
+     * The `onPrepare()` method sets up a listener, which is called whenever a stream gets prepared.
+     *
+     * @since 5.12.0
+     */
+    onPrepare(listener: (event: IStreamEvent<'prepare'>) => void): void;
+    /**
+     * The `onPlay()` method sets up a listener, which is called whenever a stream starts playing.
+     *
+     * @since 5.12.0
+     */
+    onPlay(listener: (event: IStreamEvent<'play'>) => void): void;
+    /**
+     * The `onStop()` method sets up a listener, which is called whenever a stream stops.
+     *
+     * @since 5.12.0
+     */
+    onStop(listener: (event: IStreamEvent<'stop'>) => void): void;
+    /**
+     * The `onStop()` method sets up a listener, which is called whenever a stream is paused.
+     *
+     * @since 5.12.0
+     */
+    onPause(listener: (event: IStreamEvent<'pause'>) => void): void;
+    /**
+     * The `onStop()` method sets up a listener, which is called whenever a stream is resumed.
+     *
+     * @since 5.12.0
+     */
+    onResume(listener: (event: IStreamEvent<'resume'>) => void): void;
+    /** @internal */
     handleMessageData(data: IStreamMessage): void;
+    /**
+     * The `removeEventListeners()` removes all listeners set up on `sos.stream`.
+     */
     removeEventListeners(): void;
     private createAndEmitEvent;
     private getMessage;

package/es6/FrontApplet/Stream/Stream.js

@@ -8,144 +8,182 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const events_1 = require("events");
 const debugDecorator_1 = require("../Debug/debugDecorator");
-const AppletStreamError_1 = require("../Error/AppletStreamError");
-const ErrorCodes_1 = require("../Error/ErrorCodes");
-const Validate_1 = require("../Validate/Validate");
 const coordinationsHelper_1 = require("../Dimensions/coordinationsHelper");
+const AppletStreamError_1 = __importDefault(require("../Error/AppletStreamError"));
+const ErrorCodes_1 = __importDefault(require("../Error/ErrorCodes"));
+const Validate_1 = __importDefault(require("../Validate/Validate"));
 const DEBUG_NAMESPACE = '@signageos/front-applet:FrontApplet:Stream';
+/**
+ * The `sos.video` API groups together methods for streaming videos.
+ *
+ * :::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.
+ *
+ * :::
+ */
 class Stream {
+    messagePrefix;
+    postMessage;
+    static MESSAGE_PREFIX = 'stream';
+    eventEmitter;
+    /** @internal */
     constructor(messagePrefix, postMessage) {
         this.messagePrefix = messagePrefix;
         this.postMessage = postMessage;
         this.eventEmitter = new events_1.EventEmitter();
     }
-    prepare(uri, x, y, width, height, options) {
-        return __awaiter(this, void 0, void 0, function* () {
-            let streamOptions;
-            if (typeof options === 'string') {
-                streamOptions = { protocol: options };
-            }
-            else {
-                streamOptions = options;
-            }
-            let protocol = undefined;
-            if (streamOptions === null || streamOptions === void 0 ? void 0 : streamOptions.protocol) {
-                protocol = streamOptions.protocol;
-            }
-            if (protocol && typeof protocol !== 'string') {
-                throw new AppletStreamError_1.default({
-                    kind: 'appletStreamError',
-                    message: 'Invalid format of protocol, must be string.',
-                    code: ErrorCodes_1.default.STREAM_INVALID_PROTOCOL_TYPE,
-                });
-            }
-            this.checkParamsValidity(uri, x, y, width, height);
-            this.createAndEmitEvent('prepare', {
-                type: 'prepare',
-                srcArguments: {
-                    uri,
-                    x,
-                    y,
-                    width,
-                    height,
-                    protocol,
-                },
+    /**
+     * The `prepare()` method prepares the stream in the background.
+     *
+     * :::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.
+     *
+     * :::
+     *
+     * @since 4.7.0
+     *
+     * @example // {@link https://github.com/signageos/applet-examples/tree/master/examples/content-js-api/stream}
+     */
+    async prepare(uri, x, y, width, height, options) {
+        let streamOptions;
+        if (typeof options === 'string') {
+            streamOptions = { protocol: options };
+        }
+        else {
+            streamOptions = options;
+        }
+        let protocol = undefined;
+        if (streamOptions?.protocol) {
+            protocol = streamOptions.protocol;
+        }
+        if (protocol && typeof protocol !== 'string') {
+            throw new AppletStreamError_1.default({
+                kind: 'appletStreamError',
+                message: 'Invalid format of protocol, must be string.',
+                code: ErrorCodes_1.default.STREAM_INVALID_PROTOCOL_TYPE,
             });
-            return this.postMessage({
-                type: this.getMessage('prepare'),
+        }
+        this.checkParamsValidity(uri, x, y, width, height);
+        this.createAndEmitEvent('prepare', {
+            type: 'prepare',
+            srcArguments: {
                 uri,
                 x,
                 y,
                 width,
                 height,
                 protocol,
-                options: streamOptions,
-            });
+            },
+        });
+        return this.postMessage({
+            type: this.getMessage('prepare'),
+            uri,
+            x,
+            y,
+            width,
+            height,
+            protocol,
+            options: streamOptions,
         });
     }
-    play(uri, x, y, width, height, options) {
-        return __awaiter(this, void 0, void 0, function* () {
-            let streamOptions;
-            if (typeof options === 'string') {
-                // Legacy format
-                streamOptions = { protocol: options };
-            }
-            else {
-                // New format
-                streamOptions = options;
-            }
-            let protocol = undefined;
-            if (streamOptions === null || streamOptions === void 0 ? void 0 : streamOptions.protocol) {
-                protocol = streamOptions.protocol;
-            }
-            this.checkParamsValidity(uri, x, y, width, height);
-            ({ x, y, width, height } = (0, coordinationsHelper_1.sanitizeCoordinations)({ x, y, width, height }));
-            if (protocol && typeof protocol !== 'string') {
-                throw new AppletStreamError_1.default({
-                    kind: 'appletStreamError',
-                    message: 'Invalid format of protocol, must be string.',
-                    code: ErrorCodes_1.default.STREAM_INVALID_PROTOCOL_TYPE,
-                });
-            }
-            this.createAndEmitEvent('play', {
-                type: 'play',
-                srcArguments: {
-                    uri,
-                    x,
-                    y,
-                    width,
-                    height,
-                    protocol,
-                },
+    /**
+     * The `play()` method starts the streaming of a streaming previously prepared by `prepare()` method.
+     *
+     * @since 1.0.18
+     */
+    async play(uri, x, y, width, height, options) {
+        let streamOptions;
+        if (typeof options === 'string') {
+            // Legacy format
+            streamOptions = { protocol: options };
+        }
+        else {
+            // New format
+            streamOptions = options;
+        }
+        let protocol = undefined;
+        if (streamOptions?.protocol) {
+            protocol = streamOptions.protocol;
+        }
+        this.checkParamsValidity(uri, x, y, width, height);
+        ({ x, y, width, height } = (0, coordinationsHelper_1.sanitizeCoordinations)({ x, y, width, height }));
+        if (protocol && typeof protocol !== 'string') {
+            throw new AppletStreamError_1.default({
+                kind: 'appletStreamError',
+                message: 'Invalid format of protocol, must be string.',
+                code: ErrorCodes_1.default.STREAM_INVALID_PROTOCOL_TYPE,
             });
-            return this.postMessage({
-                type: this.getMessage('play'),
+        }
+        this.createAndEmitEvent('play', {
+            type: 'play',
+            srcArguments: {
                 uri,
                 x,
                 y,
                 width,
                 height,
                 protocol,
-                options: streamOptions,
-            });
+            },
+        });
+        return this.postMessage({
+            type: this.getMessage('play'),
+            uri,
+            x,
+            y,
+            width,
+            height,
+            protocol,
+            options: streamOptions,
         });
     }
-    stop(uri, x, y, width, height) {
-        return __awaiter(this, void 0, void 0, function* () {
-            this.checkParamsValidity(uri, x, y, width, height);
-            ({ x, y, width, height } = (0, coordinationsHelper_1.sanitizeCoordinations)({ x, y, width, height }));
-            this.createAndEmitEvent('stop', {
-                type: 'stop',
-                srcArguments: {
-                    uri,
-                    x,
-                    y,
-                    width,
-                    height,
-                },
-            });
-            return this.postMessage({
-                type: this.getMessage('stop'),
+    /**
+     * The `stop()` method stops the stream, it can't be resumed with `resume()`.
+     *
+     * @since 1.0.18
+     */
+    async stop(uri, x, y, width, height) {
+        this.checkParamsValidity(uri, x, y, width, height);
+        ({ x, y, width, height } = (0, coordinationsHelper_1.sanitizeCoordinations)({ x, y, width, height }));
+        this.createAndEmitEvent('stop', {
+            type: 'stop',
+            srcArguments: {
                 uri,
                 x,
                 y,
                 width,
                 height,
-            });
+            },
+        });
+        return this.postMessage({
+            type: this.getMessage('stop'),
+            uri,
+            x,
+            y,
+            width,
+            height,
         });
     }
+    /**
+     * The `pause()` method pauses the stream, it can be resumed with `resume()`.
+     *
+     * @since 6.4.0
+     */
     pause(uri, x, y, width, height) {
         this.checkParamsValidity(uri, x, y, width, height);
         ({ x, y, width, height } = (0, coordinationsHelper_1.sanitizeCoordinations)({ x, y, width, height }));
@@ -168,6 +206,11 @@ class Stream {
             height,
         });
     }
+    /**
+     * The `resume()` method resumes the stream paused by `pause()`.
+     *
+     * @since 6.4.0
+     */
     resume(uri, x, y, width, height) {
         this.checkParamsValidity(uri, x, y, width, height);
         ({ x, y, width, height } = (0, coordinationsHelper_1.sanitizeCoordinations)({ x, y, width, height }));
@@ -190,70 +233,124 @@ class Stream {
             height,
         });
     }
-    getTracks(videoId) {
-        return __awaiter(this, void 0, void 0, function* () {
-            (0, Validate_1.default)({ videoId }).required().object();
-            const { tracks } = yield this.postMessage({ type: this.getMessage('get_tracks'), videoId });
-            return tracks;
-        });
+    /**
+     * The `getTracks()` method returns a track list of a stream.
+     *
+     * @since 6.1.0
+     */
+    async getTracks(videoId) {
+        (0, Validate_1.default)({ videoId }).required().object();
+        const { tracks } = await this.postMessage({ type: this.getMessage('get_tracks'), videoId });
+        return tracks;
     }
-    selectTrack(videoId, trackType, groupId, trackIndex) {
-        return __awaiter(this, void 0, void 0, function* () {
-            (0, Validate_1.default)({ videoId }).required().object();
-            (0, Validate_1.default)({ trackType }).required().string();
-            (0, Validate_1.default)({ groupId }).required().string();
-            (0, Validate_1.default)({ trackIndex }).required().number();
-            return this.postMessage({ type: this.getMessage('select_track'), videoId, trackType, groupId, trackIndex });
-        });
+    /**
+     * The `selectTrack()` method selects a track of a stream.
+     *
+     * @since 6.1.0
+     */
+    async selectTrack(videoId, trackType, groupId, trackIndex) {
+        (0, Validate_1.default)({ videoId }).required().object();
+        (0, Validate_1.default)({ trackType }).required().string();
+        (0, Validate_1.default)({ groupId }).required().string();
+        (0, Validate_1.default)({ trackIndex }).required().number();
+        return this.postMessage({ type: this.getMessage('select_track'), videoId, trackType, groupId, trackIndex });
     }
-    resetTrack(videoId, trackType, groupId) {
-        return __awaiter(this, void 0, void 0, function* () {
-            (0, Validate_1.default)({ videoId }).required().object();
-            (0, Validate_1.default)({ trackType }).required().string();
-            if (groupId) {
-                (0, Validate_1.default)({ groupId }).string();
-            }
-            return this.postMessage({ type: this.getMessage('reset_track'), videoId, trackType, groupId });
-        });
+    /**
+     * The `resetTrack()` method resets a track of a stream.
+     *
+     * @since 6.1.0
+     */
+    async resetTrack(videoId, trackType, groupId) {
+        (0, Validate_1.default)({ videoId }).required().object();
+        (0, Validate_1.default)({ trackType }).required().string();
+        if (groupId) {
+            (0, Validate_1.default)({ groupId }).string();
+        }
+        return this.postMessage({ type: this.getMessage('reset_track'), videoId, trackType, groupId });
     }
+    /**
+     * The `onTracksChanged()` method sets up a listener, which is called whenever a track is changed.
+     *
+     * @since 6.1.0
+     */
     onTracksChanged(listener) {
         (0, Validate_1.default)({ listener }).required().function();
         this.eventEmitter.on('tracks_changed', listener);
     }
+    /**
+     * The `onTracksChanged()` method sets up a listener, which is called whenever an unexpected error occurs during a stream.
+     *
+     * @since 1.0.20
+     */
     onError(listener) {
         (0, Validate_1.default)({ listener }).required().function();
         this.eventEmitter.on('error', listener);
     }
+    /**
+     * The `onConnected()` method sets up a listener, which is called whenever a stream is connected.
+     *
+     * @since 1.0.20
+     */
     onConnected(listener) {
         (0, Validate_1.default)({ listener }).required().function();
         this.eventEmitter.on('connected', listener);
     }
+    /**
+     * The `onDisconnected()` method sets up a listener, which is called whenever a stream gets disconnected.
+     *
+     * @since 1.0.20
+     */
     onDisconnected(listener) {
         (0, Validate_1.default)({ listener }).required().function();
         this.eventEmitter.on('disconnected', listener);
     }
+    /**
+     * The `onPrepare()` method sets up a listener, which is called whenever a stream gets prepared.
+     *
+     * @since 5.12.0
+     */
     onPrepare(listener) {
         (0, Validate_1.default)({ listener }).required().function();
         this.eventEmitter.on('prepare', listener);
     }
+    /**
+     * The `onPlay()` method sets up a listener, which is called whenever a stream starts playing.
+     *
+     * @since 5.12.0
+     */
     onPlay(listener) {
         (0, Validate_1.default)({ listener }).required().function();
         this.eventEmitter.on('play', listener);
     }
+    /**
+     * The `onStop()` method sets up a listener, which is called whenever a stream stops.
+     *
+     * @since 5.12.0
+     */
     onStop(listener) {
         (0, Validate_1.default)({ listener }).required().function();
         this.eventEmitter.on('stop', listener);
     }
+    /**
+     * The `onStop()` method sets up a listener, which is called whenever a stream is paused.
+     *
+     * @since 5.12.0
+     */
     onPause(listener) {
         (0, Validate_1.default)({ listener }).required().function();
         this.eventEmitter.on('pause', listener);
     }
+    /**
+     * The `onStop()` method sets up a listener, which is called whenever a stream is resumed.
+     *
+     * @since 5.12.0
+     */
     onResume(listener) {
         (0, Validate_1.default)({ listener }).required().function();
         this.eventEmitter.on('resume', listener);
     }
+    /** @internal */
     handleMessageData(data) {
-        var _a, _b, _c, _d, _e, _f;
         switch (data.type) {
             case this.getMessage('error'):
                 this.createAndEmitEvent('error', {
@@ -264,7 +361,7 @@ class Stream {
                         y: data.y,
                         width: data.width,
                         height: data.height,
-                        protocol: (_b = (_a = data.options) === null || _a === void 0 ? void 0 : _a.protocol) !== null && _b !== void 0 ? _b : data.protocol,
+                        protocol: data.options?.protocol ?? data.protocol,
                     },
                     errorMessage: data.errorMessage,
                 });
@@ -278,7 +375,7 @@ class Stream {
                         y: data.y,
                         width: data.width,
                         height: data.height,
-                        protocol: (_d = (_c = data.options) === null || _c === void 0 ? void 0 : _c.protocol) !== null && _d !== void 0 ? _d : data.protocol,
+                        protocol: data.options?.protocol ?? data.protocol,
                     },
                 });
                 break;
@@ -291,7 +388,7 @@ class Stream {
                         y: data.y,
                         width: data.width,
                         height: data.height,
-                        protocol: (_f = (_e = data.options) === null || _e === void 0 ? void 0 : _e.protocol) !== null && _f !== void 0 ? _f : data.protocol,
+                        protocol: data.options?.protocol ?? data.protocol,
                     },
                 });
                 break;
@@ -311,6 +408,9 @@ class Stream {
             default:
         }
     }
+    /**
+     * The `removeEventListeners()` removes all listeners set up on `sos.stream`.
+     */
     removeEventListeners() {
         this.eventEmitter.removeAllListeners();
     }
@@ -328,7 +428,7 @@ class Stream {
         (0, Validate_1.default)({ height }).required().number();
     }
 }
-Stream.MESSAGE_PREFIX = 'stream';
+exports.default = Stream;
 __decorate([
     (0, debugDecorator_1.debug)(DEBUG_NAMESPACE),
     __metadata("design:type", Function),
@@ -431,5 +531,4 @@ __decorate([
     __metadata("design:paramtypes", [Function]),
     __metadata("design:returntype", void 0)
 ], Stream.prototype, "onResume", null);
-exports.default = Stream;
 //# sourceMappingURL=Stream.js.map