tiny-essentials/dist/v1/libs/TinyMediaPlayer.d.mts

Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.

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 EventEmitter<any> {
    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 { EventEmitter } from 'events';
/**
 * @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