tiny-essentials 1.28.4 → 1.28.6

package/dist/v1/libs/TinyMediaPlayer/Youtube.d.mts

@@ -0,0 +1,355 @@
+/**
+ * @typedef {import('../../basics/mediaContent.mjs').PictureDataType} PictureDataType
+ * @typedef {import('../../basics/mediaContent.mjs').MediaContent<PictureDataType>} MediaContent
+ * @typedef {import('./index.mjs').ContentTimeData} ContentTimeData
+ * @typedef {import('./index.mjs').ContentData} ContentData
+ *
+ * @typedef {import('./docs/YouTubePlayer.mjs').YTPlayerState} YTPlayerState
+ * @typedef {import('./docs/YouTubePlayer.mjs').YTPlayerErrors} YTPlayerErrors
+ * @typedef {import('./docs/YouTubePlayer.mjs').YTQuality} YTQuality
+ * @typedef {import('./docs/YouTubePlayer.mjs').YTSphericalProperties} YTSphericalProperties
+ * @typedef {import('./docs/YouTubePlayer.mjs').YouTubePlayerEventBase} YouTubePlayerEventBase
+ * @typedef {import('./docs/YouTubePlayer.mjs').YTPlayerOptionsEvents} YTPlayerOptionsEvents
+ * @typedef {import('./docs/YouTubePlayer.mjs').YTPlayerOptionsEvents} YTPlayerOptions
+ * @typedef {import('./docs/YouTubePlayer.mjs').EventNames} EventNames
+ * @typedef {import('./docs/YouTubePlayer.mjs').YTPlaylistOptions} YTPlaylistOptions
+ * @typedef {import('./docs/YouTubePlayer.mjs').VideoByUrlOptions} VideoByUrlOptions
+ * @typedef {import('./docs/YouTubePlayer.mjs').VideoByIdOptions} VideoByIdOptions
+ *
+ * @typedef {import('./docs/YouTubePlayer.mjs').OnReadyEvent} OnReadyEvent
+ * @typedef {import('./docs/YouTubePlayer.mjs').OnStateChangeEvent} OnStateChangeEvent
+ * @typedef {import('./docs/YouTubePlayer.mjs').OnErrorEvent} OnErrorEvent
+ * @typedef {import('./docs/YouTubePlayer.mjs').OnPlaybackQualityChangeEvent} OnPlaybackQualityChangeEvent
+ * @typedef {import('./docs/YouTubePlayer.mjs').OnPlaybackRateChangeEvent} OnPlaybackRateChangeEvent
+ * @typedef {import('./docs/YouTubePlayer.mjs').OnApiChangeEvent} OnApiChangeEvent
+ * @typedef {import('./docs/YouTubePlayer.mjs').OnAutoplayBlockedEvent} OnAutoplayBlockedEvent
+ */
+export type PictureDataType = import('../../basics/mediaContent.mjs').PictureDataType;
+export type MediaContent = import('../../basics/mediaContent.mjs').MediaContent<PictureDataType>;
+export type ContentTimeData = import('./index.mjs').ContentTimeData;
+export type ContentData = import('./index.mjs').ContentData;
+export type YTPlayerState = import('./docs/YouTubePlayer.mjs').YTPlayerState;
+export type YTPlayerErrors = import('./docs/YouTubePlayer.mjs').YTPlayerErrors;
+export type YTQuality = import('./docs/YouTubePlayer.mjs').YTQuality;
+export type YTSphericalProperties = import('./docs/YouTubePlayer.mjs').YTSphericalProperties;
+export type YouTubePlayerEventBase = import('./docs/YouTubePlayer.mjs').YouTubePlayerEventBase;
+export type YTPlayerOptionsEvents = import('./docs/YouTubePlayer.mjs').YTPlayerOptionsEvents;
+export type YTPlayerOptions = import('./docs/YouTubePlayer.mjs').YTPlayerOptionsEvents;
+export type EventNames = import('./docs/YouTubePlayer.mjs').EventNames;
+export type YTPlaylistOptions = import('./docs/YouTubePlayer.mjs').YTPlaylistOptions;
+export type VideoByUrlOptions = import('./docs/YouTubePlayer.mjs').VideoByUrlOptions;
+export type VideoByIdOptions = import('./docs/YouTubePlayer.mjs').VideoByIdOptions;
+export type OnReadyEvent = import('./docs/YouTubePlayer.mjs').OnReadyEvent;
+export type OnStateChangeEvent = import('./docs/YouTubePlayer.mjs').OnStateChangeEvent;
+export type OnErrorEvent = import('./docs/YouTubePlayer.mjs').OnErrorEvent;
+export type OnPlaybackQualityChangeEvent = import('./docs/YouTubePlayer.mjs').OnPlaybackQualityChangeEvent;
+export type OnPlaybackRateChangeEvent = import('./docs/YouTubePlayer.mjs').OnPlaybackRateChangeEvent;
+export type OnApiChangeEvent = import('./docs/YouTubePlayer.mjs').OnApiChangeEvent;
+export type OnAutoplayBlockedEvent = import('./docs/YouTubePlayer.mjs').OnAutoplayBlockedEvent;
+export type HandlerFunc = (...args: any[]) => boolean;
+export type IframeContainerOptions = {
+    /**
+     * - The YouTube video ID to be loaded.
+     */
+    videoId: string;
+    /**
+     * - The iframe width in pixels or a string (e.g., '100%').
+     */
+    width?: number | string;
+    /**
+     * - The iframe height in pixels or a string (e.g., '100%').
+     */
+    height?: number | string;
+    /**
+     * - If true, the iframe will be invisible (opacity 0) and will not respond to clicks (pointer-events none) and appends it to the document body.
+     */
+    hidden?: boolean;
+    /**
+     * - If true, the video will start automatically upon loading.
+     */
+    autoplay?: boolean;
+    /**
+     * - The ID of a playlist to load.
+     */
+    list?: string | null;
+    /**
+     * - The type of list to load (e.g., 'playlist').
+     */
+    listType?: string | null;
+    /**
+     * - The preferred language for closed captions.
+     */
+    ccLangPref?: string | null;
+    /**
+     * - Whether to load closed captions by default (0 for off, 1 for on).
+     */
+    ccLoadPolicy?: boolean;
+    /**
+     * - The color of the player controls (e.g., 'red', 'white').
+     */
+    color?: string | null;
+    /**
+     * - Whether to display the player controls.
+     */
+    controls?: boolean;
+    /**
+     * - Whether to disable keyboard controls.
+     */
+    disableKb?: boolean;
+    /**
+     * - Whether the video should loop.
+     */
+    loop?: boolean;
+    /**
+     * - The time in seconds when the video should end.
+     */
+    end?: number | string | null;
+    /**
+     * - The time in seconds when the video should start.
+     */
+    start?: number | string | null;
+    /**
+     * - A comma-separated list of video IDs to be played as a playlist.
+     */
+    playlist?: string | string[] | null;
+    /**
+     * - Whether to play the video inline on mobile devices.
+     */
+    playsinline?: boolean;
+    /**
+     * - The URL of the page where the player is embedded.
+     */
+    widgetReferrer?: string | null;
+    /**
+     * - Whether to show related videos from the same channel.
+     */
+    rel?: boolean;
+    /**
+     * - The language of the player interface.
+     */
+    hl?: string | null;
+    /**
+     * - Whether to allow the player to enter fullscreen mode.
+     */
+    fs?: boolean;
+    /**
+     * - The policy for showing video annotations (1 to show, 3 to hide).
+     */
+    ivLoadPolicy?: boolean;
+};
+import { BaseMediaAdapter } from './index.mjs';
+import YouTubePlayer from './docs/YouTubePlayer.mjs';
+/**
+ * Method to ensure the YouTube IFrame API script is loaded.
+ */
+declare const loadYoutubeApi: () => Promise<any>;
+/**
+ * Returns a deep clone of the current YouTube player state values.
+ * This ensures the returned object is a copy and does not maintain a reference to the original state.
+ * @returns {Record<string, number>} A copy of the PlayerState object.
+ */
+declare const getPlayerStateValues: () => Record<string, number>;
+/**
+ * Retrieves the YouTube Player constructor from the global window object.
+ * @returns {typeof YouTubePlayer} The YouTube Player constructor.
+ * @throws {Error} If the YouTube API is not detected in the global scope.
+ */
+declare const getYtPlayer: () => typeof YouTubePlayer;
+/**
+ * Implementation of BaseMediaAdapter for the YouTube IFrame Player API.
+ * This adapter manages the lifecycle of a YouTube player embedded in a container.
+ * @extends BaseMediaAdapter
+ */
+declare class YoutubeMediaAdapter extends BaseMediaAdapter {
+    #private;
+    /**
+     * Mapping YouTube API events for internal adapter events.
+     * Includes semantic events triggered by state changes.
+     * @type {Record<string, string>}
+     * @private
+     */
+    private static EVENT_MAPPING;
+    /**
+     * Represents the current state of the player.
+     * @type {Record<string, number>}
+     */
+    static PlayerState: Record<string, number>;
+    /**
+     * Safety lock: If true, multiple instances can share the same player/iframe via WeakMap.
+     * If false, only one instance can be bound to a specific container at a time.
+     * @type {boolean}
+     */
+    static allowInstanceSharing: boolean;
+    /**
+     * Gets the globally configured default container for YouTube players.
+     * @returns {HTMLIFrameElement|null}
+     */
+    static get defaultContainer(): HTMLIFrameElement | null;
+    /**
+     * Sets the globally configured default container for YouTube players.
+     * @param {HTMLIFrameElement|null} element - The element to be used as the default container.
+     * @throws {TypeError} If the provided element is not an instance of HTMLIFrameElement.
+     */
+    static set defaultContainer(element: HTMLIFrameElement | null);
+    /**
+     * Creates a YouTube iframe element.
+     * This element can be used as the `defaultContainer` for the adapter.
+     *
+     * @param {IframeContainerOptions} options - Configuration for the iframe creation.
+     * @returns {HTMLIFrameElement} The created iframe element.
+     * @throws {TypeError} If the `videoId` is not a valid string.
+     */
+    static createIframeContainer(options: IframeContainerOptions): HTMLIFrameElement;
+    /**
+     * Returns the URL for a YouTube video thumbnail with a specified quality.
+     * @param {string} videoId - The YouTube video ID.
+     * @param {string} [quality='maxresdefault'] - The thumbnail quality (e.g., 'default', 'mqdefault', 'hqdefault', 'sddefault', 'maxresdefault').
+     * @returns {string} The thumbnail URL.
+     * @throws {TypeError} If the videoId is not a valid string.
+     */
+    static getThumbnailUrl(videoId: string, quality?: string): string;
+    get id(): string;
+    get currentContentId(): string | null;
+    get pollingTimeUpdateValue(): number;
+    set pollingTimeUpdateValue(timeMs: number);
+    /**
+     * Gets whether the adapter has been destroyed.
+     * @returns {boolean}
+     */
+    get destroyed(): boolean;
+    /**
+     * Initializes the YouTube Media Adapter.
+     * @throws {Error} If allowInstanceSharing is false and the container is already in use.
+     */
+    constructor();
+    /**
+     * @returns {YouTubePlayer} The current YouTube player instance.
+     * @throws {Error} If the player has not been initialized.
+     */
+    get player(): YouTubePlayer;
+    /**
+     * @param {number} value - The volume level from 0.0 to 1.0.
+     * @throws {RangeError} If the volume is not between 0.0 and 1.0.
+     */
+    set volume(value: number);
+    /**
+     * @returns {number} The current volume level from 0.0 to 1.0.
+     */
+    get volume(): number;
+    /**
+     * Synchronously checks whether the YouTube media adapter is fully initialized and ready.
+     * @returns {boolean} True if the adapter is ready, false otherwise.
+     */
+    isReady(): boolean;
+    /**
+     * Asynchronously waits until the YouTube media adapter is fully initialized and ready.
+     * @returns {Promise<void>} A promise that resolves once the adapter is ready.
+     */
+    waitIsReady(): Promise<void>;
+    /**
+     * Retrieves a consolidated object containing all time-related metrics for the current media content.
+     * @returns {ContentTimeData} An object containing total, current, remaining time, and playback percentage.
+     */
+    getTimeData(): ContentTimeData;
+    /**
+     * Determines if the content is a valid YouTube URL or ID.
+     * @param {MediaContent} content - The media content to evaluate.
+     * @returns {boolean} True if the content is a YouTube link/ID, false otherwise.
+     */
+    static canHandle(content: MediaContent): boolean;
+    /**
+     * Determines if the content is a valid YouTube URL or ID.
+     * @param {MediaContent} content - The media content to evaluate.
+     * @returns {boolean} True if the content is a YouTube link/ID, false otherwise.
+     */
+    canHandle(content: MediaContent): boolean;
+    /**
+     * Plays the media content. If the player is already initialized with a different video,
+     * it will load the new video automatically.
+     *
+     * Example: https://www.youtube.com/watch?v=XXXXXXXXXXX
+     * @param {MediaContent} content - The media content to play.
+     * @returns {Promise<void>}
+     * @throws {TypeError} If the content data is invalid.
+     */
+    play(content: MediaContent): Promise<void>;
+    /**
+     * Pauses the current playback.
+     * @returns {Promise<void>}
+     */
+    pause(): Promise<void>;
+    /**
+     * Stops the playback completely.
+     * @returns {Promise<void>}
+     */
+    stop(): Promise<void>;
+    /**
+     * Seeks to a specific time in the media timeline.
+     * @param {number} timeMs - The target time in milliseconds.
+     * @returns {Promise<void>}
+     * @throws {TypeError} If timeMs is not a number.
+     */
+    seek(timeMs: number): Promise<void>;
+    /**
+     * Retrieves the current playback time.
+     * @returns {number} The current time in milliseconds.
+     */
+    getCurrentTime(): number;
+    /**
+     * Gets the total duration of the YouTube video.
+     * @returns {number} The total duration in milliseconds.
+     */
+    getTotalDuration(): number;
+    /**
+     * Gets the remaining time until the YouTube video ends.
+     * @returns {number} The remaining time in milliseconds.
+     */
+    getRemainingTime(): number;
+    /**
+     * Gets the percentage of the YouTube video that has been played.
+     * @returns {number} The percentage from 0 to 100.
+     */
+    getPlaybackPercentage(): number;
+    /**
+     * Sets the playback volume.
+     * @param {number} volume - The volume level from 0.0 to 1.0.
+     * @returns {void}
+     * @throws {RangeError} If volume is outside [0.0, 1.0].
+     */
+    setVolume(volume: number): void;
+    /**
+     * Gets the playback volume.
+     * @returns {number}
+     * @throws {RangeError} If volume is outside [0.0, 1.0].
+     */
+    getVolume(): number;
+    /**
+     * Retrieves the thumbnail URL for the currently loaded video with a specified quality.
+     * @param {string} [quality='maxresdefault'] - The thumbnail quality.
+     * @returns {string|null} The thumbnail URL or null if no video is loaded.
+     */
+    getThumbnailUrl(quality?: string): string | null;
+    /**
+     * Retrieves the metadata of the currently loaded YouTube video, returning a structured
+     * object containing details such as the video ID, title, author, and duration.
+     * @returns {Promise<ContentData>}
+     */
+    getContentData(): Promise<ContentData>;
+    /**
+     * Cleans up the instance and disconnects from the shared player.
+     */
+    destroy(): void;
+}
+/**
+ * Asynchronously ensures the YouTube IFrame API is loaded and returns
+ * the YouTube Player constructor and the current player state mapping.
+ *
+ * @returns {Promise<{ Player: typeof YouTubePlayer, PlayerState: Record<string, number> }>}
+ * An object containing the Player constructor and the current player state mapping.
+ */
+declare const getYT: () => Promise<{
+    Player: typeof YouTubePlayer;
+    PlayerState: Record<string, number>;
+}>;
+export { YoutubeMediaAdapter, getYtPlayer, loadYoutubeApi, getPlayerStateValues, getYT };
+//# sourceMappingURL=Youtube.d.mts.map