tiny-essentials 1.28.4 → 1.28.6

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

@@ -1,4 +1,5 @@
 import { EventEmitter } from 'events';
+import { BaseMediaAdapter } from './TinyMediaPlayer/index.mjs';
 export type PictureDataType = import('../basics/mediaContent.mjs').PictureDataType;
 export type MediaContent = import('../basics/mediaContent.mjs').MediaContent<PictureDataType>;
 export type MediaContentBase = import('../basics/mediaContent.mjs').MediaContentBase;
@@ -7,6 +8,8 @@ export type ParseMediaContentMetadata = import('../basics/mediaContent.mjs').Par
 export type LoadingMediaProgress = import('../basics/mediaContent.mjs').LoadingMediaProgress;
 export type MediaLoadingErrorData = import('../basics/mediaContent.mjs').MediaLoadingErrorData;
 export type UnknownArtistGetter = import('../basics/mediaContent.mjs').UnknownArtistGetter;
+export type ContentTimeData = import('./TinyMediaPlayer/index.mjs').ContentTimeData;
+export type ContentData = import('./TinyMediaPlayer/index.mjs').ContentData;
 export type LoopModeType = 'NONE' | 'TRACK' | 'PLAYLIST';
 export type TinyMediaPlayerOptions = {
     /**
@@ -17,6 +20,28 @@ export type TinyMediaPlayerOptions = {
      * - The specific key name used for localStorage cache.
      */
     volumeStorageKey?: string;
+    /**
+     * - If true, clicking 'previous' repeats the current track on the first click.
+     */
+    repeatCurrentOnPrev?: boolean;
+    /**
+     * - If true, volume fades smoothly during play/pause transitions.
+     */
+    smoothPlayPauseVolume?: boolean;
+    /**
+     * - If true, volume fades smoothly to zero when stopping.
+     */
+    smoothStopVolume?: boolean;
+};
+export type SearchResult = {
+    /**
+     * - The matched media content.
+     */
+    track: MediaContent;
+    /**
+     * - The current index of the track in the playlist.
+     */
+    index: number;
 };
 /**
  * @typedef {import('../basics/mediaContent.mjs').PictureDataType} PictureDataType
@@ -27,74 +52,22 @@ export type TinyMediaPlayerOptions = {
  * @typedef {import('../basics/mediaContent.mjs').LoadingMediaProgress} LoadingMediaProgress
  * @typedef {import('../basics/mediaContent.mjs').MediaLoadingErrorData} MediaLoadingErrorData
  * @typedef {import('../basics/mediaContent.mjs').UnknownArtistGetter} UnknownArtistGetter
+ * @typedef {import('./TinyMediaPlayer/index.mjs').ContentTimeData} ContentTimeData
+ * @typedef {import('./TinyMediaPlayer/index.mjs').ContentData} ContentData
  */
 /**
  * The loop configuration modes.
  * @typedef {'NONE' | 'TRACK' | 'PLAYLIST'} LoopModeType
  */
 /**
- * Configuration options for initializing the UniversalMediaPlayer.
+ * Configuration options for initializing the TinyMediaPlayer.
  * @typedef {Object} TinyMediaPlayerOptions
  * @property {boolean} [persistVolume=false] - Whether to automatically save the volume in localStorage.
- * @property {string} [volumeStorageKey='universal_media_player_volume'] - The specific key name used for localStorage cache.
- */
-/**
- * Interface definition for a Media Provider Adapter.
- * All specific API wrappers must extend and implement this class.
- * @abstract
+ * @property {string} [volumeStorageKey='tiny_media_player_volume'] - The specific key name used for localStorage cache.
+ * @property {boolean} [repeatCurrentOnPrev=false] - If true, clicking 'previous' repeats the current track on the first click.
+ * @property {boolean} [smoothPlayPauseVolume=false] - If true, volume fades smoothly during play/pause transitions.
+ * @property {boolean} [smoothStopVolume=false] - If true, volume fades smoothly to zero when stopping.
  */
-declare class BaseMediaAdapter {
-    constructor();
-    /**
-     * Determines if this adapter can play the provided content.
-     * @param {MediaContent} content - The media content to evaluate.
-     * @returns {boolean} True if the adapter can handle the content, false otherwise.
-     */
-    canHandle(content: MediaContent): boolean;
-    /**
-     * Starts or resumes playback of the provided content.
-     * @param {MediaContent} content - The media content to play.
-     * @returns {Promise<void>}
-     */
-    play(content: MediaContent): Promise<void>;
-    /**
-     * Pauses the current playback.
-     * @returns {Promise<void>}
-     */
-    pause(): Promise<void>;
-    /**
-     * Stops the playback completely and resets the internal platform state.
-     * @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>}
-     */
-    seek(timeMs: number): Promise<void>;
-    /**
-     * Retrieves the current playback time from the underlying API.
-     * @returns {number} The current time in milliseconds.
-     */
-    getCurrentTime(): number;
-    /**
-     * Sets the playback volume for the underlying API.
-     * @param {number} volume - The volume level from 0.0 to 1.0.
-     * @returns {void}
-     */
-    setVolume(volume: number): void;
-}
-export type SearchResult = {
-    /**
-     * - The matched media content.
-     */
-    track: MediaContent;
-    /**
-     * - The current index of the track in the playlist.
-     */
-    index: number;
-};
 /**
  * Represents a search match containing the media object and its exact playlist index.
  * @typedef {Object} SearchResult
@@ -143,8 +116,48 @@ declare class TinyMediaPlayer extends EventEmitter {
         onError?: (error: MediaLoadingErrorData) => void;
     }): Promise<MediaContent>;
     get destroyed(): boolean;
+    /** @returns {number} The duration (ms) of the volume fade speed. */
+    get fadeVolumeSpeed(): number;
+    /**
+     * @param {number} value - The new duration in milliseconds.
+     * @throws {TypeError} If the value is not a number.
+     * @throws {RangeError} If the value is negative.
+     */
+    set fadeVolumeSpeed(value: number);
+    /** @returns {number} The duration (ms) before the prev click state resets. */
+    get prevClickTimeoutDuration(): number;
+    /**
+     * @param {number} value - The new duration in milliseconds.
+     * @throws {TypeError} If the value is not a number.
+     * @throws {RangeError} If the value is negative.
+     */
+    set prevClickTimeoutDuration(value: number);
+    /** @returns {boolean} True if clicking 'previous' repeats the current track on the first click. */
+    get repeatCurrentOnPrev(): boolean;
+    /**
+     * @param {boolean} value - The repeat mode state.
+     * @throws {TypeError} If the value is not a boolean.
+     */
+    set repeatCurrentOnPrev(value: boolean);
+    /** @returns {boolean} True if volume fades smoothly during play/pause transitions. */
+    get smoothPlayPauseVolume(): boolean;
+    /**
+     * @param {boolean} value - The smooth play/pause volume mode.
+     * @throws {TypeError} If the value is not a boolean.
+     */
+    set smoothPlayPauseVolume(value: boolean);
+    /** @returns {boolean} True if volume fades smoothly to zero when stopping. */
+    get smoothStopVolume(): boolean;
+    /**
+     * @param {boolean} value - The smooth stop volume mode.
+     * @throws {TypeError} If the value is not a boolean.
+     */
+    set smoothStopVolume(value: boolean);
     /**
      * @param {TinyMediaPlayerOptions} [options={}] - Configuration parameters for the player.
+     * @throws {TypeError} If options is not a valid object.
+     * @throws {TypeError} If option values do not match their expected types.
+     * @throws {RangeError} If numeric options are out of valid ranges.
      */
     constructor(options?: TinyMediaPlayerOptions);
     /**
@@ -207,13 +220,67 @@ declare class TinyMediaPlayer extends EventEmitter {
      * @throws {TypeError} If the value is not a string or is empty.
      */
     set volumeStorageKey(value: string);
+    get adapters(): BaseMediaAdapter[];
+    get adaptersSize(): number;
+    static get defaultAdapterEventNames(): string[];
+    /** @param {string[]} value */
+    static set defaultAdapterEventNames(value: string[]);
     /**
      * Registers a new media API adapter.
-     * @param {string} id - Unique identifier for the platform (e.g., 'youtube', 'spotify').
      * @param {BaseMediaAdapter} adapter - An instance extending BaseMediaAdapter.
-     * @throws {TypeError} If id is not a string or adapter is invalid.
+     * @throws {TypeError} If the adapter is invalid.
+     */
+    registerAdapter(adapter: BaseMediaAdapter): void;
+    /**
+     * Removes a media API adapter.
+     * @param {BaseMediaAdapter} adapter - An instance extending BaseMediaAdapter.
+     * @throws {TypeError} If adapter is invalid.
+     */
+    removeAdapter(adapter: BaseMediaAdapter): boolean;
+    /**
+     * Destroys and removes a media API adapter.
+     * @param {BaseMediaAdapter} adapter - An instance extending BaseMediaAdapter.
+     * @throws {TypeError} If adapter is invalid.
      */
-    registerAdapter(id: string, adapter: BaseMediaAdapter): void;
+    destroyAdapter(adapter: BaseMediaAdapter): boolean;
+    /**
+     * If exists a media API adapter.
+     * @param {BaseMediaAdapter} adapter - An instance extending BaseMediaAdapter.
+     * @throws {TypeError} If adapter is invalid.
+     */
+    hasAdapter(adapter: BaseMediaAdapter): boolean;
+    /**
+     * Destroys and removes all registered media adapters.
+     */
+    destroyAllAdapters(): void;
+    /**
+     * Clears all registered media adapters.
+     */
+    clearAdapters(): void;
+    /**
+     * Helper to find the correct API wrapper for the content.
+     * @param {MediaContent} content - The content to check.
+     * @returns {BaseMediaAdapter | null} The compatible adapter, or null if empty.
+     * @throws {TypeError} If the content is invalid.
+     */
+    getMediaAdapter(content: MediaContent): BaseMediaAdapter | null;
+    /**
+     * Adds a new event to be listened to on the adapters.
+     * @param {string} eventName - The name of the event to add.
+     * @throws {TypeError} If the event name is not a string.
+     */
+    addAdapterEvent(eventName: string): void;
+    /**
+     * Removes an event from the list of listened events.
+     * @param {string} eventName - The name of the event to remove.
+     * @throws {TypeError} If the event name is not a string.
+     */
+    removeAdapterEvent(eventName: string): void;
+    /**
+     * Resets the event list to the factory default state: ['timeupdate', 'ended'].
+     * @throws {TypeError} If the event name is not a string.
+     */
+    resetAdapterEvents(): void;
     /**
      * Adds a new item to the end of the playlist.
      * @param {MediaContent} content - The structured media content object.
@@ -224,7 +291,7 @@ declare class TinyMediaPlayer extends EventEmitter {
     /**
      * Checks if a track exists at the specified index.
      * @param {number} index - The target index.
-     * @returns {boolean} True if the track exists, false otherwise.
+     * @returns {boolean} True if the track exists at the specified index.
      * @throws {TypeError} If the index is not a number.
      */
     existsTrack(index: number): boolean;
@@ -233,7 +300,7 @@ declare class TinyMediaPlayer extends EventEmitter {
      * @param {number} index - The target index.
      * @returns {MediaContent} The media content object.
      * @throws {TypeError} If the index is not a number.
-     * @throws {RangeError} If the index is out of bounds.
+     * @throws {RangeError} If the index is out of the playlist bounds.
      */
     getTrack(index: number): MediaContent;
     /**
@@ -283,9 +350,9 @@ declare class TinyMediaPlayer extends EventEmitter {
     /**
      * Jumps to a specific absolute time in the timeline.
      * @param {number} timeMs - The target time in milliseconds.
+     * @returns {Promise<void>}
      * @throws {TypeError} If timeMs is not a number.
      * @throws {RangeError} If timeMs is negative.
-     * @returns {Promise<void>}
      */
     seek(timeMs: number): Promise<void>;
     /**
@@ -295,6 +362,37 @@ declare class TinyMediaPlayer extends EventEmitter {
      * @returns {Promise<void>}
      */
     step(stepMs: number): Promise<void>;
+    /**
+     * Gets the current playback time.
+     * @returns {number} The current time in milliseconds.
+     */
+    getCurrentTime(): number;
+    /**
+     * Gets the total duration of the current track.
+     * @returns {number} The total duration in milliseconds.
+     */
+    getTotalDuration(): number;
+    /**
+     * Gets the remaining time until the current track ends.
+     * @returns {number} The remaining time in milliseconds.
+     */
+    getRemainingTime(): number;
+    /**
+     * Gets the percentage of the current track that has been played.
+     * @returns {number} A value between 0 and 100.
+     */
+    getPlaybackPercentage(): number;
+    /**
+     * Retrieves the metadata of the currently loaded content, returning a structured
+     * object containing details such as the content ID, title, author, and duration.
+     * @returns {Promise<ContentData>}
+     */
+    getContentData(): Promise<ContentData>;
+    /**
+     * Asynchronously waits until the content media adapter is fully initialized and ready.
+     * @returns {Promise<void>} A promise that resolves once the adapter is ready.
+     */
+    waitIsReady(): Promise<void>;
     /**
      * Safely destroys the TinyMediaPlayer instance.
      * This method stops active playback, clears the internal playlist,