tiny-essentials 1.28.4 → 1.28.5

package/dist/v1/libs/TinyMediaPlayer.mjs

@@ -1,6 +1,8 @@
 import { EventEmitter } from 'events';
 import { getMediaContentBase, getMediaContentMetadata, parseMediaMetadata, valMediaContentMetadata, } from '../basics/mediaContent.mjs';
 import { createCheckDestroyed } from './utils.mjs';
+import { BaseMediaAdapter } from './TinyMediaPlayer/index.mjs';
+import { isValidObj } from '../basics/objChecker.mjs';
 const checkDestroy = createCheckDestroyed('TinyMediaPlayer');
 /**
  * @typedef {import('../basics/mediaContent.mjs').PictureDataType} PictureDataType
@@ -11,82 +13,21 @@ const checkDestroy = createCheckDestroyed('TinyMediaPlayer');
  * @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
  */
 /**
  * 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.
+ * @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.
  */
-/**
- * Interface definition for a Media Provider Adapter.
- * All specific API wrappers must extend and implement this class.
- * @abstract
- */
-class BaseMediaAdapter {
-    constructor() {
-        if (new.target === BaseMediaAdapter) {
-            throw new Error('BaseMediaAdapter is an abstract class and cannot be instantiated directly.');
-        }
-    }
-    /**
-     * 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) {
-        throw new Error('Method "canHandle" must be implemented by the subclass.');
-    }
-    /**
-     * Starts or resumes playback of the provided content.
-     * @param {MediaContent} content - The media content to play.
-     * @returns {Promise<void>}
-     */
-    async play(content) {
-        throw new Error('Method "play" must be implemented by the subclass.');
-    }
-    /**
-     * Pauses the current playback.
-     * @returns {Promise<void>}
-     */
-    async pause() {
-        throw new Error('Method "pause" must be implemented by the subclass.');
-    }
-    /**
-     * Stops the playback completely and resets the internal platform state.
-     * @returns {Promise<void>}
-     */
-    async stop() {
-        throw new Error('Method "stop" must be implemented by the subclass.');
-    }
-    /**
-     * Seeks to a specific time in the media timeline.
-     * @param {number} timeMs - The target time in milliseconds.
-     * @returns {Promise<void>}
-     */
-    async seek(timeMs) {
-        throw new Error('Method "seek" must be implemented by the subclass.');
-    }
-    /**
-     * Retrieves the current playback time from the underlying API.
-     * @returns {number} The current time in milliseconds.
-     */
-    getCurrentTime() {
-        throw new Error('Method "getCurrentTime" must be implemented by the subclass.');
-    }
-    /**
-     * Sets the playback volume for the underlying API.
-     * @param {number} volume - The volume level from 0.0 to 1.0.
-     * @returns {void}
-     */
-    setVolume(volume) {
-        throw new Error('Method "setVolume" must be implemented by the subclass.');
-    }
-}
 /**
  * Represents a search match containing the media object and its exact playlist index.
  * @typedef {Object} SearchResult
@@ -117,7 +58,7 @@ class TinyMediaPlayer extends EventEmitter {
      */
     static set unknownArtist(value) {
         if (typeof value !== 'string' && typeof value !== 'function')
-            throw new TypeError('unknownArtist must have an string or function.');
+            throw new TypeError('unknownArtist must be a string or a function.');
         TinyMediaPlayer.#unknownArtist = value;
     }
     /**
@@ -142,8 +83,10 @@ class TinyMediaPlayer extends EventEmitter {
     get destroyed() {
         return this.#destroyed;
     }
-    /** @type {Map<string, BaseMediaAdapter>} */
-    #adapters = new Map();
+    /** @type {Set<BaseMediaAdapter>} */
+    #adapters = new Set();
+    /** @type {WeakMap<BaseMediaAdapter, Map<string, (...args: any[]) => any>>} */
+    #adapterHandlers = new WeakMap();
     /** @type {MediaContent[]} */
     #playlist = [];
     /** @type {number} */
@@ -160,17 +103,168 @@ class TinyMediaPlayer extends EventEmitter {
     #persistVolume;
     /** @type {string} */
     #volumeStorageKey;
+    /** @type {boolean} */
+    #repeatCurrentOnPrev;
+    /** @type {boolean} */
+    #prevClickedToRepeat = false;
+    /** @type {boolean} */
+    #smoothPlayPauseVolume;
+    /** @type {boolean} */
+    #smoothStopVolume;
+    /** @type {AbortController | null} */
+    #fadeController = null;
+    /** @type {ReturnType<typeof setTimeout> | null} */
+    #prevClickTimer = null;
+    /** @type {number} */
+    #fadeVolumeSpeed = 300;
+    /** @returns {number} The duration (ms) of the volume fade speed. */
+    get fadeVolumeSpeed() {
+        checkDestroy(this.#destroyed);
+        return this.#fadeVolumeSpeed;
+    }
+    /**
+     * @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) {
+        checkDestroy(this.#destroyed);
+        if (typeof value !== 'number')
+            throw new TypeError('fadeVolumeSpeed must be a number.');
+        if (value < 0)
+            throw new RangeError('fadeVolumeSpeed cannot be negative.');
+        this.#fadeVolumeSpeed = value;
+        this.emit('fadeVolumeSpeedChange', this.#fadeVolumeSpeed);
+    }
+    /** @type {number} */
+    #prevClickTimeoutDuration = 2000;
+    /** @returns {number} The duration (ms) before the prev click state resets. */
+    get prevClickTimeoutDuration() {
+        checkDestroy(this.#destroyed);
+        return this.#prevClickTimeoutDuration;
+    }
+    /**
+     * @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) {
+        checkDestroy(this.#destroyed);
+        if (typeof value !== 'number')
+            throw new TypeError('prevClickTimeoutDuration must be a number.');
+        if (value < 0)
+            throw new RangeError('prevClickTimeoutDuration cannot be negative.');
+        this.#prevClickTimeoutDuration = value;
+        this.emit('prevClickTimeoutDurationChange', this.#prevClickTimeoutDuration);
+    }
+    /** @returns {boolean} True if clicking 'previous' repeats the current track on the first click. */
+    get repeatCurrentOnPrev() {
+        checkDestroy(this.#destroyed);
+        return this.#repeatCurrentOnPrev;
+    }
+    /**
+     * @param {boolean} value - The repeat mode state.
+     * @throws {TypeError} If the value is not a boolean.
+     */
+    set repeatCurrentOnPrev(value) {
+        checkDestroy(this.#destroyed);
+        if (typeof value !== 'boolean') {
+            throw new TypeError('repeatCurrentOnPrev must be a boolean.');
+        }
+        this.#repeatCurrentOnPrev = value;
+        this.emit('repeatCurrentOnPrevChange', this.#repeatCurrentOnPrev);
+    }
+    /** @returns {boolean} True if volume fades smoothly during play/pause transitions. */
+    get smoothPlayPauseVolume() {
+        checkDestroy(this.#destroyed);
+        return this.#smoothPlayPauseVolume;
+    }
+    /**
+     * @param {boolean} value - The smooth play/pause volume mode.
+     * @throws {TypeError} If the value is not a boolean.
+     */
+    set smoothPlayPauseVolume(value) {
+        checkDestroy(this.#destroyed);
+        if (typeof value !== 'boolean') {
+            throw new TypeError('smoothPlayPauseVolume must be a boolean.');
+        }
+        this.#smoothPlayPauseVolume = value;
+        this.emit('smoothPlayPauseVolumeChange', this.#smoothPlayPauseVolume);
+    }
+    /** @returns {boolean} True if volume fades smoothly to zero when stopping. */
+    get smoothStopVolume() {
+        checkDestroy(this.#destroyed);
+        return this.#smoothStopVolume;
+    }
+    /**
+     * @param {boolean} value - The smooth stop volume mode.
+     * @throws {TypeError} If the value is not a boolean.
+     */
+    set smoothStopVolume(value) {
+        checkDestroy(this.#destroyed);
+        if (typeof value !== 'boolean') {
+            throw new TypeError('smoothStopVolume must be a boolean.');
+        }
+        this.#smoothStopVolume = value;
+        this.emit('smoothStopVolumeChange', this.#smoothStopVolume);
+    }
     /**
      * @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 = {}) {
         super();
+        if (!isValidObj(options)) {
+            throw new TypeError('Options must be a non-null object.');
+        }
         // Volume configuration
-        this.#persistVolume = Boolean(options.persistVolume);
-        this.#volumeStorageKey =
-            typeof options.volumeStorageKey === 'string'
-                ? options.volumeStorageKey
-                : 'tiny_media_player_volume';
+        if (options.persistVolume !== undefined) {
+            if (typeof options.persistVolume !== 'boolean') {
+                throw new TypeError('persistVolume must be a boolean.');
+            }
+            this.#persistVolume = options.persistVolume;
+        }
+        else {
+            this.#persistVolume = false;
+        }
+        if (options.volumeStorageKey !== undefined) {
+            if (typeof options.volumeStorageKey !== 'string')
+                throw new TypeError('volumeStorageKey must be a string.');
+            this.#volumeStorageKey = options.volumeStorageKey;
+        }
+        else {
+            this.#volumeStorageKey = 'tiny_media_player_volume';
+        }
+        // UX Options
+        if (options.repeatCurrentOnPrev !== undefined) {
+            if (typeof options.repeatCurrentOnPrev !== 'boolean') {
+                throw new TypeError('repeatCurrentOnPrev must be a boolean.');
+            }
+            this.#repeatCurrentOnPrev = options.repeatCurrentOnPrev;
+        }
+        else {
+            this.#repeatCurrentOnPrev = false;
+        }
+        if (options.smoothPlayPauseVolume !== undefined) {
+            if (typeof options.smoothPlayPauseVolume !== 'boolean') {
+                throw new TypeError('smoothPlayPauseVolume must be a boolean.');
+            }
+            this.#smoothPlayPauseVolume = options.smoothPlayPauseVolume;
+        }
+        else {
+            this.#smoothPlayPauseVolume = false;
+        }
+        if (options.smoothStopVolume !== undefined) {
+            if (typeof options.smoothStopVolume !== 'boolean') {
+                throw new TypeError('smoothStopVolume must be a boolean.');
+            }
+            this.#smoothStopVolume = options.smoothStopVolume;
+        }
+        else {
+            this.#smoothStopVolume = false;
+        }
         if (this.#persistVolume)
             this.#loadVolumeFromStorage();
     }
@@ -248,6 +342,44 @@ class TinyMediaPlayer extends EventEmitter {
         // Fallback in case of floating point inaccuracies
         return this.#currentIndex === this.#playlist.length - 1 ? 0 : this.#playlist.length - 1;
     }
+    /**
+     * Handles smooth volume transitions for the active adapter.
+     * @param {number} targetVolume - The volume to transition to.
+     * @returns {Promise<void>}
+     */
+    async #fadeAdapterVolume(targetVolume) {
+        if (this.#fadeController) {
+            this.#fadeController.abort();
+        }
+        this.#fadeController = new AbortController();
+        const { signal } = this.#fadeController;
+        const adapter = this.#getActiveAdapter();
+        if (!adapter)
+            return;
+        const startVolume = adapter.getVolume();
+        const startTime = performance.now();
+        const duration = this.#fadeVolumeSpeed;
+        return new Promise((resolve) => {
+            /** @param {number} currentTime */
+            const step = (currentTime) => {
+                if (signal.aborted)
+                    return resolve();
+                const elapsed = currentTime - startTime;
+                const progress = Math.min(elapsed / duration, 1);
+                const calculatedVolume = startVolume + (targetVolume - startVolume) * progress;
+                const clampedVolume = Math.max(0, Math.min(1, calculatedVolume));
+                adapter.setVolume(clampedVolume);
+                if (progress < 1) {
+                    requestAnimationFrame(step);
+                }
+                else {
+                    adapter.setVolume(targetVolume);
+                    resolve();
+                }
+            };
+            requestAnimationFrame(step);
+        });
+    }
     // ==========================================
     // GETTERS & STRICT SETTERS
     // ==========================================
@@ -408,6 +540,9 @@ class TinyMediaPlayer extends EventEmitter {
             throw new TypeError('Volume must be a number.');
         if (value < 0 || value > 1)
             throw new RangeError('Volume must be tightly constrained between 0.0 and 1.0.');
+        // Abort any ongoing fade to ensure manual control is immediate
+        if (this.#fadeController)
+            this.#fadeController.abort();
         this.#volume = value;
         this.#saveVolumeToStorage();
         this.emit('volumeChange', this.#volume);
@@ -475,21 +610,135 @@ class TinyMediaPlayer extends EventEmitter {
     // ==========================================
     // ADAPTER MANAGEMENT
     // ==========================================
+    get adapters() {
+        return Array.from(this.#adapters);
+    }
+    get adaptersSize() {
+        return this.#adapters.size;
+    }
+    /** @type {string[]} */
+    static #defaultAdapterEventNames = ['timeupdate', 'ended'];
+    static get defaultAdapterEventNames() {
+        return structuredClone(TinyMediaPlayer.#defaultAdapterEventNames);
+    }
+    /** @param {string[]} value */
+    static set defaultAdapterEventNames(value) {
+        if (!Array.isArray(value) || !value.every((v) => typeof v === 'string'))
+            throw new TypeError('TinyMediaPlayer.defaultAdapterEventNames must be an array of strings.');
+        TinyMediaPlayer.#defaultAdapterEventNames = [...value];
+    }
+    #adapterEventNames = new Set(TinyMediaPlayer.defaultAdapterEventNames);
+    /**
+     * Removes the timeupdate on adapter emitter.
+     * @param {BaseMediaAdapter} adapter
+     */
+    #removeHandler(adapter) {
+        const data = this.#adapterHandlers.get(adapter);
+        if (!data)
+            return;
+        this.#adapterEventNames.forEach((eventName) => {
+            const handler = data.get(eventName);
+            if (handler)
+                adapter.off(eventName, handler);
+        });
+        data.clear();
+        this.#adapterHandlers.delete(adapter);
+    }
     /**
      * 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(id, adapter) {
+    registerAdapter(adapter) {
         checkDestroy(this.#destroyed);
-        if (typeof id !== 'string') {
-            throw new TypeError('Adapter ID must be a string.');
+        if (!(adapter instanceof BaseMediaAdapter)) {
+            throw new TypeError('Adapter must be an instance of BaseMediaAdapter.');
         }
+        const events = new Map();
+        this.#adapterHandlers.set(adapter, events);
+        // Use the controlled helper to ensure each event is registered
+        // and correctly mapped in #adapterHandlers from the start.
+        this.#adapterEventNames.forEach((eventName) => {
+            this.#attachEventToAdapter(adapter, eventName);
+        });
+        this.#adapters.add(adapter);
+    }
+    /**
+     * Removes a media API adapter.
+     * @param {BaseMediaAdapter} adapter - An instance extending BaseMediaAdapter.
+     * @throws {TypeError} If adapter is invalid.
+     */
+    removeAdapter(adapter) {
+        checkDestroy(this.#destroyed);
+        if (!(adapter instanceof BaseMediaAdapter)) {
+            throw new TypeError('Adapter must be an instance of BaseMediaAdapter.');
+        }
+        this.#removeHandler(adapter);
+        return this.#adapters.delete(adapter);
+    }
+    /**
+     * Destroys and removes a media API adapter.
+     * @param {BaseMediaAdapter} adapter - An instance extending BaseMediaAdapter.
+     * @throws {TypeError} If adapter is invalid.
+     */
+    destroyAdapter(adapter) {
+        checkDestroy(this.#destroyed);
+        if (!(adapter instanceof BaseMediaAdapter)) {
+            throw new TypeError('Adapter must be an instance of BaseMediaAdapter.');
+        }
+        this.#removeHandler(adapter);
+        const result = this.#adapters.delete(adapter);
+        if (result)
+            adapter.destroy();
+        return result;
+    }
+    /**
+     * If exists a media API adapter.
+     * @param {BaseMediaAdapter} adapter - An instance extending BaseMediaAdapter.
+     * @throws {TypeError} If adapter is invalid.
+     */
+    hasAdapter(adapter) {
+        checkDestroy(this.#destroyed);
         if (!(adapter instanceof BaseMediaAdapter)) {
             throw new TypeError('Adapter must be an instance of BaseMediaAdapter.');
         }
-        this.#adapters.set(id, adapter);
+        return this.#adapters.has(adapter);
+    }
+    /**
+     * Destroys and removes all registered media adapters.
+     */
+    destroyAllAdapters() {
+        checkDestroy(this.#destroyed);
+        this.#adapters.forEach((adapter) => {
+            this.#removeHandler(adapter);
+            adapter.destroy();
+        });
+        this.#adapters.clear();
+    }
+    /**
+     * Clears all registered media adapters.
+     */
+    clearAdapters() {
+        checkDestroy(this.#destroyed);
+        this.#adapters.forEach((adapter) => this.#removeHandler(adapter));
+        this.#adapters.clear();
+    }
+    /**
+     * 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) {
+        if (!isValidObj(content)) {
+            throw new TypeError('Content must be a valid object.');
+        }
+        for (const adapter of this.#adapters.values()) {
+            if (adapter.canHandle(content)) {
+                return adapter;
+            }
+        }
+        return null;
     }
     /**
      * Internal helper to find the correct API wrapper for the current content.
@@ -500,12 +749,106 @@ class TinyMediaPlayer extends EventEmitter {
         if (this.#currentIndex === -1 || this.#playlist.length === 0)
             return null;
         const currentContent = this.#playlist[this.#currentIndex];
-        for (const adapter of this.#adapters.values()) {
-            if (adapter.canHandle(currentContent)) {
-                return adapter;
+        const adapter = this.getMediaAdapter(currentContent);
+        if (adapter)
+            return adapter;
+        throw new Error(`No compatible adapter found for content ID: ${currentContent.id}.`);
+    }
+    // ==========================================
+    // EVENT MANAGEMENT (CONTROLLED)
+    // ==========================================
+    /**
+     * 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) {
+        checkDestroy(this.#destroyed);
+        if (typeof eventName !== 'string') {
+            throw new TypeError('Event name must be a string.');
+        }
+        // If the event is already in the list, do nothing to avoid duplicates
+        if (this.#adapterEventNames.has(eventName))
+            return;
+        this.#adapterEventNames.add(eventName);
+        // Synchronize: Add the listener to all already registered adapters
+        this.#adapters.forEach((adapter) => {
+            this.#attachEventToAdapter(adapter, eventName);
+        });
+    }
+    /**
+     * 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) {
+        checkDestroy(this.#destroyed);
+        if (typeof eventName !== 'string') {
+            throw new TypeError('Event name must be a string.');
+        }
+        if (!this.#adapterEventNames.has(eventName))
+            return;
+        this.#adapterEventNames.delete(eventName);
+        // Synchronize: Remove the listener from all registered adapters
+        this.#adapters.forEach((adapter) => {
+            this.#detachEventFromAdapter(adapter, eventName);
+        });
+    }
+    /**
+     * Resets the event list to the factory default state: ['timeupdate', 'ended'].
+     * @throws {TypeError} If the event name is not a string.
+     */
+    resetAdapterEvents() {
+        checkDestroy(this.#destroyed);
+        const defaultEvents = TinyMediaPlayer.defaultAdapterEventNames;
+        // Convert to Array to avoid issues when deleting items during iteration
+        const currentEvents = Array.from(this.#adapterEventNames);
+        // 1. Remove events that are not part of the factory default
+        for (const eventName of currentEvents) {
+            if (!defaultEvents.includes(eventName)) {
+                this.removeAdapterEvent(eventName);
+            }
+        }
+        // 2. Ensure default events exist (in case they were previously removed)
+        for (const defaultEvent of defaultEvents) {
+            if (!this.#adapterEventNames.has(defaultEvent)) {
+                this.addAdapterEvent(defaultEvent);
             }
         }
-        throw new Error(`No compatible adapter found for content ID: ${currentContent.id}.`);
+    }
+    /**
+     * Private helper to attach an event to a specific adapter and save the handler.
+     * @param {BaseMediaAdapter} adapter - The destination adapter.
+     * @param {string} eventName - The event name.
+     */
+    #attachEventToAdapter(adapter, eventName) {
+        const handlersMap = this.#adapterHandlers.get(adapter);
+        if (!handlersMap)
+            return;
+        // Create an encapsulated handler to maintain security (checkDestroy)
+        /** @type {(...args: any[]) => any} */
+        const handler = (...args) => {
+            if (!this.#destroyed) {
+                this.emit(eventName, ...args);
+            }
+        };
+        adapter.on(eventName, handler);
+        handlersMap.set(eventName, handler); // Mandatory synchronization with the WeakMap
+    }
+    /**
+     * Private helper to remove an event from a specific adapter using the saved handler.
+     * @param {BaseMediaAdapter} adapter - The destination adapter.
+     * @param {string} eventName - The event name.
+     */
+    #detachEventFromAdapter(adapter, eventName) {
+        const handlersMap = this.#adapterHandlers.get(adapter);
+        if (!handlersMap)
+            return;
+        const handler = handlersMap.get(eventName);
+        if (handler) {
+            adapter.off(eventName, handler);
+            handlersMap.delete(eventName); // Mandatory synchronization with the WeakMap
+        }
     }
     // ==========================================
     // PLAYLIST MANAGEMENT
@@ -518,8 +861,9 @@ class TinyMediaPlayer extends EventEmitter {
      */
     addTrack(content) {
         checkDestroy(this.#destroyed);
-        if (!content || typeof content !== 'object' || typeof content.url !== 'string')
+        if (!isValidObj(content) || typeof content.url !== 'string') {
             throw new TypeError('Track content must be a valid MediaContent object containing a URL.');
+        }
         /** @type {MediaContent} */
         const newContent = { ...getMediaContentBase(), ...getMediaContentMetadata(), ...content };
         valMediaContentMetadata(newContent);
@@ -534,7 +878,7 @@ 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) {
@@ -549,7 +893,7 @@ 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) {
         checkDestroy(this.#destroyed);
@@ -585,7 +929,7 @@ class TinyMediaPlayer extends EventEmitter {
             }
             else if (this.#currentIndex >= this.#playlist.length) {
                 // If we removed the last item and others exist, reset index safely
-                this.#currentIndex = 0;
+                this.#currentIndex = 0; // Reset to start if out of bounds
             }
             this.emit('trackChange', this.#currentIndex);
         }
@@ -655,7 +999,12 @@ class TinyMediaPlayer extends EventEmitter {
         if (!adapter)
             return;
         // Ensure the adapter aligns with the global volume before playing
-        adapter.setVolume(this.#volume);
+        if (this.#smoothPlayPauseVolume) {
+            await this.#fadeAdapterVolume(this.#volume);
+        }
+        else {
+            adapter.setVolume(this.#volume);
+        }
         await adapter.play(this.#playlist[this.#currentIndex]);
         this.#isPlaying = true;
         this.emit('play', this.#currentIndex);
@@ -669,6 +1018,9 @@ class TinyMediaPlayer extends EventEmitter {
         const adapter = this.#getActiveAdapter();
         if (!adapter)
             return;
+        if (this.#smoothPlayPauseVolume) {
+            await this.#fadeAdapterVolume(0);
+        }
         await adapter.pause();
         this.#isPlaying = false;
         this.emit('pause', this.#currentIndex);
@@ -682,6 +1034,9 @@ class TinyMediaPlayer extends EventEmitter {
         const adapter = this.#getActiveAdapter();
         if (!adapter)
             return;
+        if (this.#smoothStopVolume) {
+            await this.#fadeAdapterVolume(0);
+        }
         await adapter.stop();
         this.#isPlaying = false;
         this.emit('stop', this.#currentIndex);
@@ -727,6 +1082,26 @@ class TinyMediaPlayer extends EventEmitter {
         checkDestroy(this.#destroyed);
         if (this.#playlist.length === 0)
             return;
+        // UX: Repeat current track if "repeat on prev" is enabled and it's the first click
+        if (this.#repeatCurrentOnPrev && !this.#prevClickedToRepeat) {
+            this.#prevClickedToRepeat = true;
+            // Reset the "repeat" state after 2 seconds of inactivity to prevent glitches
+            if (this.#prevClickTimer)
+                clearTimeout(this.#prevClickTimer);
+            this.#prevClickTimer = setTimeout(() => {
+                this.#prevClickedToRepeat = false;
+                this.#prevClickTimer = null;
+            }, 2000);
+            await this.stop();
+            await this.play();
+            return;
+        }
+        // If we reached here, it's either the second click or repeat is disabled
+        if (this.#prevClickTimer) {
+            clearTimeout(this.#prevClickTimer);
+            this.#prevClickTimer = null;
+        }
+        this.#prevClickedToRepeat = false;
         await this.stop();
         if (this.#isRandom) {
             this.#currentIndex = this._getWeightedRandomIndex();
@@ -750,9 +1125,9 @@ 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>}
      */
     async seek(timeMs) {
         checkDestroy(this.#destroyed);
@@ -789,6 +1164,68 @@ class TinyMediaPlayer extends EventEmitter {
             targetTime = 0;
         await this.seek(targetTime);
     }
+    // ==========================================
+    // TIME UTILITIES (DELEGATED TO ADAPTERS)
+    // ==========================================
+    /**
+     * Gets the current playback time.
+     * @returns {number} The current time in milliseconds.
+     */
+    getCurrentTime() {
+        checkDestroy(this.#destroyed);
+        try {
+            const adapter = this.#getActiveAdapter();
+            return adapter ? adapter.getCurrentTime() : 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /**
+     * Gets the total duration of the current track.
+     * @returns {number} The total duration in milliseconds.
+     */
+    getTotalDuration() {
+        checkDestroy(this.#destroyed);
+        try {
+            const adapter = this.#getActiveAdapter();
+            return adapter ? adapter.getTotalDuration() : 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /**
+     * Gets the remaining time until the current track ends.
+     * @returns {number} The remaining time in milliseconds.
+     */
+    getRemainingTime() {
+        checkDestroy(this.#destroyed);
+        try {
+            const adapter = this.#getActiveAdapter();
+            return adapter ? adapter.getRemainingTime() : 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /**
+     * Gets the percentage of the current track that has been played.
+     * @returns {number} A value between 0 and 100.
+     */
+    getPlaybackPercentage() {
+        checkDestroy(this.#destroyed);
+        try {
+            const adapter = this.#getActiveAdapter();
+            return adapter ? adapter.getPlaybackPercentage() : 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    // ==========================================
+    // DESTROYER
+    // ==========================================
     /**
      * Safely destroys the TinyMediaPlayer instance.
      * This method stops active playback, clears the internal playlist,
@@ -809,15 +1246,20 @@ class TinyMediaPlayer extends EventEmitter {
         catch (error) {
             console.warn('[TinyMediaPlayer] Non-fatal error during playback termination:', error);
         }
+        if (this.#prevClickTimer)
+            clearTimeout(this.#prevClickTimer);
         // 2. Clear internal state variables
         this.#playlist = [];
         this.#currentIndex = -1;
         this.#isPlaying = false;
-        // 3. Clear all registered API adapters
-        this.#adapters.clear();
+        this.#prevClickedToRepeat = false;
+        // 3. Clears and destroys all registered API adapters
+        this.destroyAllAdapters();
         // 4. Remove all event listeners inherited from EventEmitter
         this.removeAllListeners();
+        this.#adapterEventNames.clear();
         this.#destroyed = true;
+        this.emit('destroyed');
     }
 }
 export default TinyMediaPlayer;