@gcorevideo/player 2.8.2 → 2.10.0

package/dist/player.d.ts

@@ -0,0 +1,407 @@
+/**
+ * Video player for the GCore streaming platform
+ *
+ * @remarks
+ * This package provides a video player for the GCore streaming platform.
+ * It is built on top of the Clappr library and provides a framework for building custom integrations.
+ *
+ * @packageDocumentation
+ */
+
+import { setTracer } from '@gcorevideo/utils';
+
+/**
+ * @beta
+ * {@link https://cdn.dashjs.org/latest/jsdoc/module-Settings.html | DASH.js settings}
+ */
+export declare type DashSettings = Record<string, unknown>;
+
+/**
+ * @beta
+ */
+export declare type LangTag = string;
+
+/**
+ * @beta
+ */
+export declare type MediaTransport = 'dash' | 'hls' | 'mpegts';
+
+/**
+ * @beta
+ */
+export declare type PlaybackModule = 'dash' | 'hls' | 'native';
+
+/**
+ * Type of a stream playback
+ * @beta
+ */
+export declare type PlaybackType = 'live' | 'vod';
+
+/**
+ * The main component to use in the application code.
+ * @remarks
+ * The Player object provides very basic API to control playback.
+ * To build a sophisticated UI, use the plugins framework to tap into the Clappr core.
+ * {@link https://github.com/clappr/clappr/wiki/Architecture}
+ * @beta
+ */
+export declare class Player {
+    private config;
+    private emitter;
+    private player;
+    private ready;
+    private rootNode;
+    private tuneInTimerId;
+    private tunedIn;
+    constructor(config: PlayerConfig);
+    /**
+     * Adds a listener to a player event
+     * @param event - See {@link PlayerEvent}
+     * @param handler - See {@link PlayerEventHandler}
+     */
+    on<T extends PlayerEvent>(event: T, handler: PlayerEventHandler<T>): void;
+    /**
+     * Removes a listener from a player event
+     * @param event - See {@link PlayerEvent}
+     * @param handler - See {@link PlayerEventHandler}
+     */
+    off<T extends PlayerEvent>(event: T, handler: PlayerEventHandler<T>): void;
+    /**
+     * Configures the player.
+     *
+     * Can be called multiple times. Each consequent call extends the previous configuration.
+     * After a reconfiguration, if something significant has changed, the must be reinitialized (i.e, a `.destroy()` followed by an `.init()` call).
+     *
+     * @param config - complete or partial configuration
+     */
+    configure(config: Partial<PlayerConfig>): void;
+    /**
+     * Initializes the player at the given container element.
+     * @param playerElement - DOM element to host the player
+     */
+    attachTo(playerElement: HTMLElement): void;
+    /**
+     * Destroys the player, releasing all resources and removing any DOM elements added.
+     */
+    destroy(): void;
+    /**
+     * Current playback time in seconds, if appropriate.
+     * @returns For live streams, it returns the current time of the current segment.
+     */
+    getCurrentTime(): number;
+    /**
+     * Duration of the current media in seconds, if appropriate.
+     * @returns For live streams, it returns the duration of the current segment.
+     */
+    getDuration(): number;
+    /**
+     * Mutes the player.
+     */
+    mute(): void;
+    /**
+     * Unmutes the player.
+     */
+    unmute(): void;
+    /**
+     * Pauses playback.
+     */
+    pause(): void;
+    /**
+     * Starts playback.
+     */
+    play(): void;
+    /**
+     * Resizes the player container element and everything within it.
+     * @param newSize - new size of the player
+     */
+    resize(newSize: {
+        width: number;
+        height: number;
+    }): void;
+    /**
+     * Seeks to the given time.
+     * @param time - time to seek to in seconds
+     */
+    seek(time: number): void;
+    /**
+     * Stops playback.
+     */
+    stop(): void;
+    /**
+     * Registers a plugin.
+     * @param plugin - plugin to register
+     */
+    static registerPlugin(plugin: PlayerPlugin): void;
+    /**
+     * Unregisters a plugin.
+     * @param plugin - plugin to unregister
+     */
+    static unregisterPlugin(plugin: PlayerPlugin): void;
+    private setConfig;
+    private initPlayer;
+    private tuneIn;
+    private events;
+    private buildCoreOptions;
+    private configurePlaybacks;
+    private selectMediaSource;
+}
+
+/**
+ * Configuration options for the player
+ *
+ * @remarks
+ *  You can specify multiple sources, each in two forms: just a plain URL or a full object with `source` and `mimeType` fields {@link PlayerMediaSource}.
+ *  The player will pick the first viable media source according to the source availability, and either the transport preference or standard transport selection order.
+ *
+ * `priorityTransport` is used to specify the preferred transport protocol
+ * when multiple sources are available.
+ * It will first try to use the transport specified if it's supported (by a playback engine) and the source is available.
+ * Otherwise it will try the other transports in the regular order (dash, hls, mpegts).
+ *
+ * The `autoPlay` option should be used together with the {@link PlayerConfig.mute | mute} to avoid issues with the browsers' autoplay policies.
+ *
+ * Note that the `playbackType` is specified explicitly in the examle below, but a playback engine might be able to detect the type of the stream automatically.
+ *
+ * A plugin options can be specified in the configuration object under a unique key, typically corresponding to the plugin name.
+ * The plugin object will have access to the internal normalized configuration object that contains all the custom options.
+ * in the examle below, the `poster` field is the `Poster` plugin configuration options.
+ *
+ * @example
+ * ```ts
+ * {
+ *   autoPlay: true,
+ *   mute: true,
+ *   playbackType: 'live',
+ *   priorityTransport: 'dash',
+ *   sources: [{
+ *     source: 'https://example.com/myownair66.mpd',
+ *     mimeType: 'application/dash+xml',
+ *   }, {
+ *     source: 'https://example.com/myownair66.m3u8',
+ *     mimeType: 'application/x-mpegURL',
+ *   }],
+ *   poster: {
+ *     url: settings.poster,
+ *   },
+ * }
+ * ```
+ * @beta
+ */
+export declare interface PlayerConfig extends Record<string, unknown> {
+    /**
+     * Start playback automatically when the player is ready
+     * @defaultValue false
+     */
+    autoPlay?: boolean;
+    /**
+     * Configuration settings for the DASH playback engine
+     * @defaultValue \{\}
+     * {@link https://cdn.dashjs.org/latest/jsdoc/module-Settings.html}
+     */
+    dash?: DashSettings;
+    /**
+     * Controls the debug output level
+     * @defaultValue 'none'
+     */
+    debug?: PlayerDebugSettings;
+    /**
+     * A language code for the player UI, for example, `es`. Must reference a key in the {@link PlayerConfig.strings | strings} record.
+     * @defaultValue 'en'
+     */
+    language?: string;
+    /**
+     * Repeat playback when the media ends.
+     * Is used with the `vod` {@link PlayerConfig.playbackType | playbackType}
+     * @defaultValue false
+     */
+    loop?: boolean;
+    /**
+     * Mute the audio output in order to comply with browsers' autoplay policy.
+     * @defaultValue false
+     */
+    mute?: boolean;
+    /**
+     * The type of playback (live stream or video on demand).
+     *
+     * @defaultValue 'vod'
+     */
+    playbackType?: PlaybackType;
+    /**
+     * Preferred transport protocol when multiple sources are available.
+     * @defaultValue 'auto'
+     */
+    priorityTransport?: TransportPreference;
+    /**
+     * List of media sources, at least one is required.
+     */
+    sources: PlayerMediaSource[];
+    /**
+     * Localization strings for the player UI.
+     */
+    strings: TranslationSettings;
+}
+
+/**
+ * @remarks true is equivalent to 'all', false is equivalent to 'none'
+ * @beta
+ */
+export declare type PlayerDebugSettings = PlayerDebugTag | boolean;
+
+/**
+ * @beta
+ */
+export declare type PlayerDebugTag = 'all' | 'clappr' | 'dash' | 'hls' | 'none';
+
+/**
+ * A top-level event on the player object
+ * @beta
+ */
+export declare enum PlayerEvent {
+    /**
+     * The player is ready to use.
+     */
+    Ready = "ready",
+    /**
+     * Playback has started.
+     */
+    Play = "play",
+    /**
+     * Playback has been paused.
+     */
+    Pause = "pause",
+    /**
+     * Playback has been stopped.
+     */
+    Stop = "stop",
+    /**
+     * Playback has reached the end of the media.
+     */
+    Ended = "ended"
+}
+
+/**
+ * @beta
+ */
+export declare type PlayerEventHandler<T extends PlayerEvent> = () => void;
+
+/**
+ * A media source to fetch the media data from
+ * @beta
+ */
+export declare type PlayerMediaSource = string | PlayerMediaSourceDesc;
+
+/**
+ * Describes a media source with its MIME type and URL.
+ *
+ * @remarks
+ * When the MIME type is provided, it helps the player determine the appropriate playback engine.
+ * If omitted, the player will attempt to detect the type from the source URL extension.
+ * @beta
+ */
+export declare interface PlayerMediaSourceDesc {
+    /**
+     * The MIME type of the media source (e.g. "video/mp4", "application/x-mpegURL")
+     */
+    mimeType?: string;
+    /**
+     * URL of the media source
+     */
+    source: string;
+}
+
+/**
+ * @beta
+ * @see {@link https://clappr.github.io/classes/UIContainerPlugin.html}, {@link https://clappr.github.io/classes/ContainerPlugin.html}
+ */
+export declare type PlayerPlugin = {
+    new (...args: any[]): unknown;
+    type: 'core' | 'container';
+};
+
+/**
+ * @beta
+ */
+export declare type QualityLevel = {
+    level: number;
+    width: number;
+    height: number;
+    bitrate: number;
+};
+
+export { setTracer }
+
+/**
+ * For the plugin development
+ * @internal
+ */
+export declare type TimePosition = {
+    current: TimeValue;
+    total: TimeValue;
+};
+
+/**
+ * For the plugin development
+ * @internal
+ */
+export declare type TimeProgress = TimePosition & {
+    start: number;
+};
+
+/**
+ * For the plugin development
+ * @internal
+ */
+export declare type TimeUpdate = TimePosition & {
+    firstFragDateTime: number;
+};
+
+/**
+ * For the plugin development
+ * @internal
+ */
+export declare type TimeValue = number;
+
+/**
+ * @beta
+ */
+export declare type TranslationKey = string;
+
+/**
+ * [language][key] =\> string
+ * @example
+ * ```
+ * {
+ *   en: {
+ *     play: 'Play',
+ *     ...
+ *   },
+ *   es: {
+ *     play: 'Reproducir',
+ *     ...
+ *   },
+ *   ...
+ * }
+ * ```
+ *
+ * @beta
+ */
+export declare type TranslationSettings = Partial<Record<LangTag, Record<TranslationKey, string>>>;
+
+/**
+ * @beta
+ */
+export declare type TransportPreference = MediaTransport | 'auto';
+
+/**
+ * Version information about the gplayer and its main dependencies
+ * @returns Version information about the gplayer and its main dependencies
+ * @beta
+ */
+export declare function version(): {
+    gplayer: string;
+    clappr: string;
+    dashjs: string;
+    hlsjs: string;
+};
+
+export { }

package/docs/api/index.md

@@ -0,0 +1,31 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md)
+
+## API Reference
+
+## Packages
+
+<table><thead><tr><th>
+
+Package
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[@gcorevideo/player](./player.md)
+
+
+</td><td>
+
+Video player for the GCore streaming platform
+
+
+</td></tr>
+</tbody></table>

package/docs/api/player.dashsettings.md

@@ -0,0 +1,16 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@gcorevideo/player](./player.md) &gt; [DashSettings](./player.dashsettings.md)
+
+## DashSettings type
+
+> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+[DASH.js settings](https://cdn.dashjs.org/latest/jsdoc/module-Settings.html)
+
+**Signature:**
+
+```typescript
+export type DashSettings = Record<string, unknown>;
+```

package/docs/api/player.langtag.md

@@ -0,0 +1,15 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@gcorevideo/player](./player.md) &gt; [LangTag](./player.langtag.md)
+
+## LangTag type
+
+> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+
+**Signature:**
+
+```typescript
+export type LangTag = string;
+```