tiny-essentials 1.28.4 → 1.28.6

package/dist/v1/libs/TinyMediaPlayer.cjs

@@ -3,6 +3,8 @@
 var events = require('events');
 var mediaContent = require('../basics/mediaContent.cjs');
 var utils = require('./utils.cjs');
+var index = require('./TinyMediaPlayer/index.cjs');
+var objChecker = require('../basics/objChecker.cjs');
 
 const checkDestroy = utils.createCheckDestroyed('TinyMediaPlayer');
 
@@ -15,6 +17,8 @@ const checkDestroy = utils.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
+ * @typedef {import('./TinyMediaPlayer/index.mjs').ContentData} ContentData
  */
 
 /**
@@ -23,85 +27,15 @@ const checkDestroy = utils.createCheckDestroyed('TinyMediaPlayer');
  */
 
 /**
- * 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
@@ -113,7 +47,7 @@ class BaseMediaAdapter {
  * A universal media player manager capable of orchestrating multiple API adapters.
  */
 class TinyMediaPlayer extends events.EventEmitter {
-  static BaseMediaAdapter = BaseMediaAdapter;
+  static BaseMediaAdapter = index.BaseMediaAdapter;
 
   /**
    * @type {UnknownArtistGetter}
@@ -136,7 +70,7 @@ class TinyMediaPlayer extends events.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;
   }
 
@@ -172,8 +106,11 @@ class TinyMediaPlayer extends events.EventEmitter {
     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 = [];
@@ -199,17 +136,183 @@ class TinyMediaPlayer extends events.EventEmitter {
   /** @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 (!objChecker.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();
   }
@@ -295,6 +398,48 @@ class TinyMediaPlayer extends events.EventEmitter {
     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
   // ==========================================
@@ -466,6 +611,9 @@ class TinyMediaPlayer extends events.EventEmitter {
     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);
@@ -539,21 +687,148 @@ class TinyMediaPlayer extends events.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(adapter) {
+    checkDestroy(this.#destroyed);
+    if (!(adapter instanceof index.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.
    */
-  registerAdapter(id, adapter) {
+  removeAdapter(adapter) {
     checkDestroy(this.#destroyed);
-    if (typeof id !== 'string') {
-      throw new TypeError('Adapter ID must be a string.');
+    if (!(adapter instanceof index.BaseMediaAdapter)) {
+      throw new TypeError('Adapter must be an instance of BaseMediaAdapter.');
     }
-    if (!(adapter instanceof 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 index.BaseMediaAdapter)) {
       throw new TypeError('Adapter must be an instance of BaseMediaAdapter.');
     }
-    this.#adapters.set(id, adapter);
+    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 index.BaseMediaAdapter)) {
+      throw new TypeError('Adapter must be an instance of BaseMediaAdapter.');
+    }
+    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 (!objChecker.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;
   }
 
   /**
@@ -564,13 +839,119 @@ class TinyMediaPlayer extends events.EventEmitter {
   #getActiveAdapter() {
     if (this.#currentIndex === -1 || this.#playlist.length === 0) return null;
     const currentContent = this.#playlist[this.#currentIndex];
+    const adapter = this.getMediaAdapter(currentContent);
+    if (adapter) return adapter;
+    throw new Error(`No compatible adapter found for content ID: ${currentContent.id}.`);
+  }
 
-    for (const adapter of this.#adapters.values()) {
-      if (adapter.canHandle(currentContent)) {
-        return adapter;
+  // ==========================================
+  // 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
+    }
   }
 
   // ==========================================
@@ -585,8 +966,9 @@ class TinyMediaPlayer extends events.EventEmitter {
    */
   addTrack(content) {
     checkDestroy(this.#destroyed);
-    if (!content || typeof content !== 'object' || typeof content.url !== 'string')
+    if (!objChecker.isValidObj(content) || typeof content.url !== 'string') {
       throw new TypeError('Track content must be a valid MediaContent object containing a URL.');
+    }
 
     /** @type {MediaContent} */
     const newContent = { ...mediaContent.getMediaContentBase(), ...mediaContent.getMediaContentMetadata(), ...content };
@@ -604,7 +986,7 @@ class TinyMediaPlayer extends events.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) {
@@ -620,7 +1002,7 @@ class TinyMediaPlayer extends events.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);
@@ -658,7 +1040,7 @@ class TinyMediaPlayer extends events.EventEmitter {
         this.#currentIndex = -1;
       } 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);
     } else {
@@ -736,7 +1118,12 @@ class TinyMediaPlayer extends events.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);
@@ -751,6 +1138,10 @@ class TinyMediaPlayer extends events.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);
@@ -765,6 +1156,10 @@ class TinyMediaPlayer extends events.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);
@@ -813,6 +1208,29 @@ class TinyMediaPlayer extends events.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) {
@@ -837,9 +1255,9 @@ class TinyMediaPlayer extends events.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);
@@ -881,6 +1299,107 @@ class TinyMediaPlayer extends events.EventEmitter {
     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;
+    }
+  }
+
+  /**
+   * 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>}
+   */
+  async getContentData() {
+    checkDestroy(this.#destroyed);
+    const defaultData = {
+      id: '',
+      createdAt: '',
+      artistId: '',
+      artistName: '',
+      description: '',
+      title: '',
+      duration: 0,
+      avatar: '',
+      url: '',
+    };
+    try {
+      const adapter = this.#getActiveAdapter();
+      return adapter ? adapter.getContentData() : defaultData;
+    } catch {
+      return defaultData;
+    }
+  }
+
+  /**
+   * Asynchronously waits until the content media adapter is fully initialized and ready.
+   * @returns {Promise<void>} A promise that resolves once the adapter is ready.
+   */
+  async waitIsReady() {
+    checkDestroy(this.#destroyed);
+    const adapter = this.#getActiveAdapter();
+    if (!adapter) return;
+    return adapter.waitIsReady();
+  }
+
+  // ==========================================
+  // DESTROYER
+  // ==========================================
+
   /**
    * Safely destroys the TinyMediaPlayer instance.
    * This method stops active playback, clears the internal playlist,
@@ -901,17 +1420,22 @@ class TinyMediaPlayer extends events.EventEmitter {
       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;
+    this.#prevClickedToRepeat = false;
 
-    // 3. Clear all registered API adapters
-    this.#adapters.clear();
+    // 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');
   }
 }