tiny-essentials 1.26.3 → 1.27.0

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

@@ -0,0 +1,306 @@
+export default TinyMediaPlayer;
+export type MediaContent = import("../basics/mediaContent.mjs").MediaContent;
+export type MediaContentBase = import("../basics/mediaContent.mjs").MediaContentBase;
+export type MediaContentMetadata = import("../basics/mediaContent.mjs").MediaContentMetadata;
+export type ParseMediaContentMetadata = import("../basics/mediaContent.mjs").ParseMediaContentMetadata;
+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 LoopModeType = "NONE" | "TRACK" | "PLAYLIST";
+/**
+ * Configuration options for initializing the UniversalMediaPlayer.
+ */
+export type TinyMediaPlayerOptions = {
+    /**
+     * - Whether to automatically save the volume in localStorage.
+     */
+    persistVolume?: boolean | undefined;
+    /**
+     * - The specific key name used for localStorage cache.
+     */
+    volumeStorageKey?: string | undefined;
+};
+/**
+ * Represents a search match containing the media object and its exact playlist index.
+ */
+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
+ * @property {MediaContent} track - The matched media content.
+ * @property {number} index - The current index of the track in the playlist.
+ */
+/**
+ * A universal media player manager capable of orchestrating multiple API adapters.
+ */
+declare class TinyMediaPlayer extends TinyEvents {
+    static BaseMediaAdapter: typeof BaseMediaAdapter;
+    /**
+     * @type {UnknownArtistGetter}
+     * The default identifier or function used when an artist cannot be determined.
+     */
+    static #unknownArtist: UnknownArtistGetter;
+    /**
+     * Sets the value used to represent unknown artists.
+     * @param {UnknownArtistGetter} value - A string or a function that returns a string.
+     * @throws {TypeError} If the value is neither a string nor a function.
+     */
+    static set unknownArtist(value: UnknownArtistGetter);
+    /**
+     * Gets the current value used to represent unknown artists.
+     * @returns {UnknownArtistGetter}
+     */
+    static get unknownArtist(): UnknownArtistGetter;
+    /**
+     * A Static Factory Method that prepares a MediaContent object by
+     * extracting metadata from an audio source.
+     *
+     * @param {string | HTMLMediaElement} source - A URL string or an existing Audio object.
+     * @param {Partial<MediaContentBase & MediaContentMetadata> & { id?: string; weight?: number }} [defaultMetadata={}] - Optional default metadata that overrides automatic extraction.
+     * @param {Partial<MediaContentBase & MediaContentMetadata> & { id?: string; weight?: number }} [metadata={}] - Optional manual metadata that overrides automatic extraction.
+     * @param {ParseMediaContentMetadata} [parseFile] - Private helper to interface with parseFile.
+     * @param {Object} [callbacks={}] - Callbacks for monitoring the loading process.
+     * @param {(progress: LoadingMediaProgress) => void} [callbacks.onProgress] - Callback triggered on stage changes.
+     * @param {(error: MediaLoadingErrorData) => void} [callbacks.onError] - Callback triggered when a non-fatal or fatal error occurs.
+     * @returns {Promise<MediaContent>} A promise that resolves to a valid MediaContent object.
+     * @throws {MediaLoadingError} If the preparation process fails at any stage.
+     */
+    static parseContent(source: string | HTMLMediaElement, defaultMetadata?: Partial<MediaContentBase & MediaContentMetadata> & {
+        id?: string;
+        weight?: number;
+    }, metadata?: Partial<MediaContentBase & MediaContentMetadata> & {
+        id?: string;
+        weight?: number;
+    }, parseFile?: ParseMediaContentMetadata, callbacks?: {
+        onProgress?: ((progress: LoadingMediaProgress) => void) | undefined;
+        onError?: ((error: MediaLoadingErrorData) => void) | undefined;
+    }): Promise<MediaContent>;
+    /**
+     * @param {TinyMediaPlayerOptions} [options={}] - Configuration parameters for the player.
+     */
+    constructor(options?: TinyMediaPlayerOptions);
+    /**
+     * Calculates a random index based on the weighted probability of each track,
+     * strictly excluding the currently active track to prevent immediate repetition.
+     * @returns {number} The selected index.
+     * @private
+     */
+    private _getWeightedRandomIndex;
+    /**
+     * @param {MediaContent[]} value - The new playlist array.
+     * @throws {TypeError} If the value is not an array.
+     */
+    set playlist(value: MediaContent[]);
+    /** @returns {MediaContent[]} A shallow copy of the current playlist. */
+    get playlist(): MediaContent[];
+    /**
+     * @param {number} value - The index to set as current.
+     * @throws {TypeError} If the value is not a number.
+     * @throws {RangeError} If the index is out of the playlist bounds (unless -1 for empty).
+     */
+    set currentIndex(value: number);
+    /** @returns {number} The current active index in the playlist. */
+    get currentIndex(): number;
+    /**
+     * @param {LoopModeType} value - The desired loop mode.
+     * @throws {TypeError} If the value is not a valid LoopModeType.
+     */
+    set loopMode(value: LoopModeType);
+    /** @returns {LoopModeType} The current loop configuration. */
+    get loopMode(): LoopModeType;
+    /**
+     * @param {boolean} value - True to enable random playback, false otherwise.
+     * @throws {TypeError} If the value is not a boolean.
+     */
+    set isRandom(value: boolean);
+    /** @returns {boolean} The current random mode status. */
+    get isRandom(): boolean;
+    /** @returns {boolean} True if media is actively playing. */
+    get isPlaying(): boolean;
+    /**
+     * @param {number} value - The volume level to set.
+     * @throws {TypeError} If the value is not a number.
+     * @throws {RangeError} If the value is outside the 0.0 to 1.0 range.
+     */
+    set volume(value: number);
+    /** @returns {number} The current volume level (0.0 to 1.0). */
+    get volume(): number;
+    /**
+     * @param {boolean} value - True to save volume dynamically to localStorage.
+     * @throws {TypeError} If the value is not a boolean.
+     */
+    set persistVolume(value: boolean);
+    /** @returns {boolean} Whether the volume cache is currently enabled. */
+    get persistVolume(): boolean;
+    /**
+     * @param {string} value - The custom storage key string.
+     * @throws {TypeError} If the value is not a string or is empty.
+     */
+    set volumeStorageKey(value: string);
+    /** @returns {string} The localStorage key used for volume caching. */
+    get volumeStorageKey(): 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.
+     */
+    registerAdapter(id: string, adapter: BaseMediaAdapter): void;
+    /**
+     * Adds a new item to the end of the playlist.
+     * @param {MediaContent} content - The structured media content object.
+     * @returns {number} The new length of the playlist.
+     * @throws {TypeError} If content is invalid or missing required base properties.
+     */
+    addTrack(content: MediaContent): number;
+    /**
+     * Checks if a track exists at the specified index.
+     * @param {number} index - The target index.
+     * @returns {boolean} True if the track exists, false otherwise.
+     * @throws {TypeError} If the index is not a number.
+     */
+    existsTrack(index: number): boolean;
+    /**
+     * Retrieves the track at the specified index.
+     * @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.
+     */
+    getTrack(index: number): MediaContent;
+    /**
+     * Removes the track at the specified index and manages playback state accordingly.
+     * @param {number} index - The index of the track to remove.
+     * @returns {Promise<void>}
+     * @throws {TypeError} If the index is not a number.
+     * @throws {RangeError} If the index is out of bounds.
+     */
+    removeTrack(index: number): Promise<void>;
+    /**
+     * Searches the playlist for tracks matching a string query or a custom evaluation function.
+     * @param {string | function(MediaContent): boolean} query - The search string (checked against title, artist, album) or a callback returning a boolean.
+     * @returns {SearchResult[]} An array containing the matched tracks and their corresponding indices.
+     * @throws {TypeError} If the query is neither a string nor a function.
+     */
+    searchTrack(query: string | ((arg0: MediaContent) => boolean)): SearchResult[];
+    /**
+     * Clears the entire playlist and stops playback.
+     */
+    clearPlaylist(): Promise<void>;
+    /**
+     * Starts or resumes playback of the current track.
+     * @returns {Promise<void>}
+     */
+    play(): Promise<void>;
+    /**
+     * Pauses the current track.
+     * @returns {Promise<void>}
+     */
+    pause(): Promise<void>;
+    /**
+     * Stops playback completely.
+     * @returns {Promise<void>}
+     */
+    stop(): Promise<void>;
+    /**
+     * Advances to the next track based on random and loop modes.
+     * @returns {Promise<void>}
+     */
+    next(): Promise<void>;
+    /**
+     * Returns to the previous track.
+     * @returns {Promise<void>}
+     */
+    prev(): Promise<void>;
+    /**
+     * Jumps to a specific absolute time in the timeline.
+     * @param {number} timeMs - The target time in milliseconds.
+     * @throws {TypeError} If timeMs is not a number.
+     * @throws {RangeError} If timeMs is negative.
+     * @returns {Promise<void>}
+     */
+    seek(timeMs: number): Promise<void>;
+    /**
+     * Moves the timeline forwards or backwards by a specified step amount.
+     * @param {number} stepMs - The amount of milliseconds to step (positive for forward, negative for backward).
+     * @throws {TypeError} If stepMs is not a number.
+     * @returns {Promise<void>}
+     */
+    step(stepMs: number): Promise<void>;
+    #private;
+}
+import TinyEvents from './TinyEvents.mjs';
+/**
+ * @typedef {import('../basics/mediaContent.mjs').MediaContent} MediaContent
+ * @typedef {import('../basics/mediaContent.mjs').MediaContentBase} MediaContentBase
+ * @typedef {import('../basics/mediaContent.mjs').MediaContentMetadata} MediaContentMetadata
+ * @typedef {import('../basics/mediaContent.mjs').ParseMediaContentMetadata} ParseMediaContentMetadata
+ * @typedef {import('../basics/mediaContent.mjs').LoadingMediaProgress} LoadingMediaProgress
+ * @typedef {import('../basics/mediaContent.mjs').MediaLoadingErrorData} MediaLoadingErrorData
+ * @typedef {import('../basics/mediaContent.mjs').UnknownArtistGetter} UnknownArtistGetter
+ */
+/**
+ * @typedef {'NONE' | 'TRACK' | 'PLAYLIST'} LoopModeType
+ */
+/**
+ * Configuration options for initializing the UniversalMediaPlayer.
+ * @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
+ */
+declare class BaseMediaAdapter {
+    /**
+     * 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;
+}
+//# sourceMappingURL=TinyMediaPlayer.d.mts.map