tiny-essentials 1.28.6 → 1.28.8

package/dist/v1/libs/TinyMediaPlayer/Mock.mjs

@@ -0,0 +1,296 @@
+import { createCheckDestroyed } from '../utils.mjs';
+import { BaseMediaAdapter } from './index.mjs';
+import { isValidObj } from '../../basics/objChecker.mjs';
+/**
+ * @typedef {import('../../basics/mediaContent.mjs').PictureDataType} PictureDataType
+ * @typedef {import('../../basics/mediaContent.mjs').MediaContent<PictureDataType>} MediaContent
+ * @typedef {import('./index.mjs').ContentData} ContentData
+ * @typedef {import('./index.mjs').ContentTimeData} ContentTimeData
+ */
+const checkDestroy = createCheckDestroyed('MockMediaAdapter');
+const createdAt = new Date().toISOString();
+/**
+ * MOCK VERSION of BaseMediaAdapter
+ *
+ * This file simulates the behavior of the Media Adapter for testing purposes.
+ */
+class MockMediaAdapter extends BaseMediaAdapter {
+    get id() {
+        return 'mock';
+    }
+    #isReady = true;
+    #currentVolume = 1.0;
+    /** @type {string|null} */
+    #currentContentId = null;
+    #destroyed = false;
+    #isPlaying = false;
+    #isPaused = false;
+    #isEnded = false;
+    #isMuted = false;
+    #currentTime = 0; // in milliseconds
+    #totalDuration = 60000; // 60 seconds in milliseconds
+    /**
+     * @returns {boolean}
+     */
+    get destroyed() {
+        return this.#destroyed;
+    }
+    /**
+     * @returns {boolean}
+     */
+    get isPlaying() {
+        checkDestroy(this.#destroyed);
+        return this.#isPlaying;
+    }
+    /**
+     * @returns {string|null}
+     */
+    get currentContentId() {
+        checkDestroy(this.#destroyed);
+        return this.#currentContentId;
+    }
+    /**
+     * @returns {number}
+     */
+    get volume() {
+        checkDestroy(this.#destroyed);
+        return this.#currentVolume;
+    }
+    /**
+     * @param {number} value - O volume de 0.0 a 1.0.
+     * @throws {RangeError} Se o valor estiver fora do intervalo.
+     */
+    set volume(value) {
+        checkDestroy(this.#destroyed);
+        if (typeof value !== 'number' || value < 0 || value > 1) {
+            throw new RangeError('Volume must be a number between 0.0 and 1.0.');
+        }
+        this.#currentVolume = value;
+        this.emit('volumeChange', value);
+    }
+    constructor() {
+        super();
+    }
+    /**
+     * Checks whether the media adapter is fully initialized and ready.
+     * @returns {boolean} True if the adapter is ready, false otherwise.
+     */
+    isReady() {
+        checkDestroy(this.#destroyed);
+        return this.#isReady;
+    }
+    /**
+     * Checks whether the media adapter is paused.
+     * @returns {boolean} True if the adapter is ready, false otherwise.
+     */
+    isPaused() {
+        checkDestroy(this.#destroyed);
+        return this.#isPaused;
+    }
+    /**
+     * Checks whether the media adapter is ended.
+     * @returns {boolean} True if the adapter is ready, false otherwise.
+     */
+    isEnded() {
+        checkDestroy(this.#destroyed);
+        return this.#isEnded;
+    }
+    /**
+     * 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);
+        return Promise.resolve();
+    }
+    /**
+     * Retrieves a consolidated object containing all time-related metrics for the current media content.
+     * @returns {ContentTimeData} An object containing total, current, remaining time, and playback percentage.
+     */
+    getTimeData() {
+        checkDestroy(this.#destroyed);
+        const total = this.getTotalDuration();
+        const current = this.getCurrentTime();
+        const remaining = total > 0 ? total - current : 0;
+        const playbackPercentage = total > 0 ? (current / total) * 100 : 0;
+        return { total, current, remaining, playbackPercentage };
+    }
+    /**
+     * 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.
+     */
+    static canHandle(content) {
+        return content && typeof content.url === 'string';
+    }
+    /**
+     * 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) {
+        checkDestroy(this.#destroyed);
+        return MockMediaAdapter.canHandle(content);
+    }
+    /**
+     * Starts or resumes playback of the provided content.
+     * @param {MediaContent} content - The media content to play.
+     * @returns {Promise<void>}
+     */
+    async play(content) {
+        checkDestroy(this.#destroyed);
+        if (!isValidObj(content)) {
+            throw new TypeError('Invalid media content provided to play().');
+        }
+        this.#currentContentId = typeof content.url === 'string' ? content.url : 'mock';
+        this.#isPaused = false;
+        this.#isEnded = false;
+        this.#isPlaying = true;
+        // Simulate a small delay for loading
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        this.emit('play');
+    }
+    /**
+     * Pauses the current playback.
+     * @returns {Promise<void>}
+     */
+    async pause() {
+        checkDestroy(this.#destroyed);
+        this.#isPaused = true;
+        this.#isEnded = false;
+        this.#isPlaying = false;
+        this.emit('pause');
+    }
+    /**
+     * Stops the playback completely and resets the internal platform state.
+     * @returns {Promise<void>}
+     */
+    async stop() {
+        checkDestroy(this.#destroyed);
+        this.#isPaused = false;
+        this.#isEnded = true;
+        this.#isPlaying = false;
+        this.#currentTime = 0;
+        this.emit('ended');
+    }
+    /**
+     * Seeks to a specific time in the media timeline.
+     * @param {number} timeMs - The target time in milliseconds.
+     * @returns {Promise<void>}
+     */
+    async seek(timeMs) {
+        checkDestroy(this.#destroyed);
+        if (typeof timeMs !== 'number') {
+            throw new TypeError('Seek time must be a number.');
+        }
+        this.#currentTime = timeMs;
+        this.emit('seek', this.#currentTime);
+    }
+    /**
+     * Checks whether the player is currently muted.
+     * @returns {boolean|null} True if muted, false otherwise.
+     */
+    isMuted() {
+        checkDestroy(this.#destroyed);
+        return this.#isMuted;
+    }
+    /**
+     * Mutes the current playback.
+     * @returns {Promise<void>}
+     */
+    async mute() {
+        checkDestroy(this.#destroyed);
+        this.#isMuted = true;
+    }
+    /**
+     * Unmutes the current playback.
+     * @returns {Promise<void>}
+     */
+    async unMute() {
+        checkDestroy(this.#destroyed);
+        this.#isMuted = false;
+    }
+    /**
+     * Retrieves the current playback time from the underlying API.
+     * @returns {number} The current time in milliseconds.
+     */
+    getCurrentTime() {
+        checkDestroy(this.#destroyed);
+        return this.#currentTime;
+    }
+    /**
+     * Gets the total duration of the content.
+     * @returns {number} The total duration in milliseconds.
+     */
+    getTotalDuration() {
+        checkDestroy(this.#destroyed);
+        return this.#totalDuration;
+    }
+    /**
+     * Gets the remaining time until the content ends.
+     * @returns {number} The remaining time in milliseconds.
+     */
+    getRemainingTime() {
+        checkDestroy(this.#destroyed);
+        const total = this.getTotalDuration();
+        const current = this.getCurrentTime();
+        return total > 0 ? total - current : 0;
+    }
+    /**
+     * Gets the percentage of the content that has been played.
+     * @returns {number} The percentage from 0 to 100.
+     */
+    getPlaybackPercentage() {
+        checkDestroy(this.#destroyed);
+        const total = this.getTotalDuration();
+        const current = this.getCurrentTime();
+        return total > 0 ? (current / total) * 100 : 0;
+    }
+    /**
+     * Sets the playback volume for the underlying API.
+     * @param {number} volume - The volume level from 0.0 to 1.0.
+     * @returns {void}
+     */
+    setVolume(volume) {
+        checkDestroy(this.#destroyed);
+        this.volume = volume;
+    }
+    /**
+     * Gets the playback volume for the underlying API.
+     * @returns {number} - The volume level from 0.0 to 1.0.
+     */
+    getVolume() {
+        checkDestroy(this.#destroyed);
+        return this.volume;
+    }
+    /**
+     * 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);
+        return {
+            id: this.#currentContentId ?? 'mock',
+            createdAt,
+            artistId: 'mock-artist',
+            artistName: 'Mock Artist',
+            description: 'Mock description',
+            title: 'Mock Title',
+            duration: this.#totalDuration,
+            avatar: '',
+            url: '',
+        };
+    }
+    /**
+     * Cleans up the instance.
+     * @returns {void}
+     */
+    destroy() {
+        if (this.#destroyed)
+            return;
+        this.#destroyed = true;
+        super.destroy();
+    }
+}
+export { MockMediaAdapter };

package/dist/v1/libs/TinyMediaPlayer/SoundCloud.cjs

@@ -284,6 +284,18 @@ class SoundCloudMediaAdapter extends index.BaseMediaAdapter {
   /** @type {number} */
   #cachedPosition = 0;
 
+  /** @type {boolean} */
+  #isMuted = false;
+
+  /** @type {number} */
+  #preMuteVolume = 1.0;
+
+  /** @type {boolean} */
+  #isPaused = false;
+
+  /** @type {boolean} */
+  #isEnded = false;
+
   /**
    * Gets whether the adapter has been destroyed.
    * @returns {boolean}
@@ -363,6 +375,24 @@ class SoundCloudMediaAdapter extends index.BaseMediaAdapter {
     return this.#isReady;
   }
 
+  /**
+   * Checks whether the media adapter is paused.
+   * @returns {boolean} True if the adapter is ready, false otherwise.
+   */
+  isPaused() {
+    checkDestroy(this.#destroyed);
+    return this.#isPaused;
+  }
+
+  /**
+   * Checks whether the media adapter is ended.
+   * @returns {boolean} True if the adapter is ready, false otherwise.
+   */
+  isEnded() {
+    checkDestroy(this.#destroyed);
+    return this.#isEnded;
+  }
+
   /**
    * Asynchronously waits until the SoundCloud media adapter is fully initialized and ready.
    * @returns {Promise<void>} A promise that resolves once the adapter is ready.
@@ -449,7 +479,7 @@ class SoundCloudMediaAdapter extends index.BaseMediaAdapter {
 
         // Command to load the new song
         this.#widget?.load(`https://api.soundcloud.com/tracks/${targetId}`);
-        await promiseUtils.waitForTrue(() => true, 500);
+        await promiseUtils.waitForTrue(() => true, 700);
         /** @type {Partial<SoundObject>} */
         let sound = {};
 
@@ -508,6 +538,13 @@ class SoundCloudMediaAdapter extends index.BaseMediaAdapter {
 
       const eventSync = (/** @type {any} */ event, /** @type {string} */ eventName) => {
         if (!event) return;
+        if (this.#isMuted)
+          this.#widget?.getVolume((volume) => {
+            if (this.#isMuted && volume > 0) {
+              this.#isMuted = false;
+              this.volume = this.#preMuteVolume;
+            }
+          });
         if (typeof event.currentPosition === 'number') this.#cachedPosition = event.currentPosition;
         if (typeof event.loadedProgress === 'number') this.#loadedProgress = event.loadedProgress;
         if (typeof event.soundId === 'number') this.#currentContentId = String(event.soundId);
@@ -525,16 +562,22 @@ class SoundCloudMediaAdapter extends index.BaseMediaAdapter {
 
       this.#widget.bind(SoundCloudMediaAdapter.Events.PLAY, (/** @type {any} */ event) => {
         eventSync(event);
+        this.#isPaused = false;
+        this.#isEnded = false;
         this.#masterEmitter?.emit('play');
       });
 
       this.#widget.bind(SoundCloudMediaAdapter.Events.PAUSE, (/** @type {any} */ event) => {
         eventSync(event);
+        this.#isPaused = true;
+        this.#isEnded = false;
         this.#masterEmitter?.emit('pause');
       });
 
       this.#widget.bind(SoundCloudMediaAdapter.Events.FINISH, (/** @type {any} */ event) => {
         eventSync(event);
+        this.#isPaused = false;
+        this.#isEnded = true;
         this.#masterEmitter?.emit('ended');
       });
 
@@ -640,6 +683,47 @@ class SoundCloudMediaAdapter extends index.BaseMediaAdapter {
     this.#widget?.seekTo(timeMs);
   }
 
+  /**
+   * Checks whether the player is currently muted.
+   * @returns {boolean} True if muted, false otherwise.
+   */
+  isMuted() {
+    checkDestroy(this.#destroyed);
+    return this.#isMuted;
+  }
+
+  /**
+   * Mutes the current playback.
+   * @returns {Promise<void>}
+   */
+  async mute() {
+    checkDestroy(this.#destroyed);
+    if (this.#isMuted) return;
+
+    this.#isMuted = true;
+    this.#preMuteVolume = this.#currentVolume;
+
+    // We update the state directly to avoid the setter's logic
+    // overwriting preMuteVolume during the transition.
+    this.#currentVolume = 0;
+    if (this.#widget && typeof this.#widget.setVolume === 'function') {
+      this.#widget.setVolume(0);
+    }
+  }
+
+  /**
+   * Unmutes the current playback.
+   * @returns {Promise<void>}
+   */
+  async unMute() {
+    checkDestroy(this.#destroyed);
+    if (!this.#isMuted) return;
+
+    this.#isMuted = false;
+    // This will trigger the 'set volume' logic which applies the restored volume
+    this.volume = this.#preMuteVolume;
+  }
+
   /**
    * Retrieves the current playback time.
    * @returns {number} The current time in milliseconds.

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

@@ -187,6 +187,16 @@ declare class SoundCloudMediaAdapter extends BaseMediaAdapter {
      * @returns {boolean} True if the adapter is ready, false otherwise.
      */
     isReady(): boolean;
+    /**
+     * Checks whether the media adapter is paused.
+     * @returns {boolean} True if the adapter is ready, false otherwise.
+     */
+    isPaused(): boolean;
+    /**
+     * Checks whether the media adapter is ended.
+     * @returns {boolean} True if the adapter is ready, false otherwise.
+     */
+    isEnded(): boolean;
     /**
      * Asynchronously waits until the SoundCloud media adapter is fully initialized and ready.
      * @returns {Promise<void>} A promise that resolves once the adapter is ready.
@@ -237,6 +247,21 @@ declare class SoundCloudMediaAdapter extends BaseMediaAdapter {
      * @throws {TypeError} If timeMs is not a number.
      */
     seek(timeMs: number): Promise<void>;
+    /**
+     * Checks whether the player is currently muted.
+     * @returns {boolean} True if muted, false otherwise.
+     */
+    isMuted(): boolean;
+    /**
+     * Mutes the current playback.
+     * @returns {Promise<void>}
+     */
+    mute(): Promise<void>;
+    /**
+     * Unmutes the current playback.
+     * @returns {Promise<void>}
+     */
+    unMute(): Promise<void>;
     /**
      * Retrieves the current playback time.
      * @returns {number} The current time in milliseconds.

package/dist/v1/libs/TinyMediaPlayer/SoundCloud.mjs

@@ -249,6 +249,14 @@ class SoundCloudMediaAdapter extends BaseMediaAdapter {
     #cachedDuration = 0;
     /** @type {number} */
     #cachedPosition = 0;
+    /** @type {boolean} */
+    #isMuted = false;
+    /** @type {number} */
+    #preMuteVolume = 1.0;
+    /** @type {boolean} */
+    #isPaused = false;
+    /** @type {boolean} */
+    #isEnded = false;
     /**
      * Gets whether the adapter has been destroyed.
      * @returns {boolean}
@@ -314,6 +322,22 @@ class SoundCloudMediaAdapter extends BaseMediaAdapter {
         checkDestroy(this.#destroyed);
         return this.#isReady;
     }
+    /**
+     * Checks whether the media adapter is paused.
+     * @returns {boolean} True if the adapter is ready, false otherwise.
+     */
+    isPaused() {
+        checkDestroy(this.#destroyed);
+        return this.#isPaused;
+    }
+    /**
+     * Checks whether the media adapter is ended.
+     * @returns {boolean} True if the adapter is ready, false otherwise.
+     */
+    isEnded() {
+        checkDestroy(this.#destroyed);
+        return this.#isEnded;
+    }
     /**
      * Asynchronously waits until the SoundCloud media adapter is fully initialized and ready.
      * @returns {Promise<void>} A promise that resolves once the adapter is ready.
@@ -391,7 +415,7 @@ class SoundCloudMediaAdapter extends BaseMediaAdapter {
                 }, 10000);
                 // Command to load the new song
                 this.#widget?.load(`https://api.soundcloud.com/tracks/${targetId}`);
-                await waitForTrue(() => true, 500);
+                await waitForTrue(() => true, 700);
                 /** @type {Partial<SoundObject>} */
                 let sound = {};
                 // We registered the listener for the READY event before calling the load
@@ -444,6 +468,13 @@ class SoundCloudMediaAdapter extends BaseMediaAdapter {
             const eventSync = (/** @type {any} */ event, /** @type {string} */ eventName) => {
                 if (!event)
                     return;
+                if (this.#isMuted)
+                    this.#widget?.getVolume((volume) => {
+                        if (this.#isMuted && volume > 0) {
+                            this.#isMuted = false;
+                            this.volume = this.#preMuteVolume;
+                        }
+                    });
                 if (typeof event.currentPosition === 'number')
                     this.#cachedPosition = event.currentPosition;
                 if (typeof event.loadedProgress === 'number')
@@ -463,14 +494,20 @@ class SoundCloudMediaAdapter extends BaseMediaAdapter {
             });
             this.#widget.bind(SoundCloudMediaAdapter.Events.PLAY, (/** @type {any} */ event) => {
                 eventSync(event, 'PLAY');
+                this.#isPaused = false;
+                this.#isEnded = false;
                 this.#masterEmitter?.emit('play');
             });
             this.#widget.bind(SoundCloudMediaAdapter.Events.PAUSE, (/** @type {any} */ event) => {
                 eventSync(event, 'PAUSE');
+                this.#isPaused = true;
+                this.#isEnded = false;
                 this.#masterEmitter?.emit('pause');
             });
             this.#widget.bind(SoundCloudMediaAdapter.Events.FINISH, (/** @type {any} */ event) => {
                 eventSync(event, 'FINISH');
+                this.#isPaused = false;
+                this.#isEnded = true;
                 this.#masterEmitter?.emit('ended');
             });
             this.#widget.bind(SoundCloudMediaAdapter.Events.LOAD_PROGRESS, (/** @type {any} */ event) => {
@@ -561,6 +598,43 @@ class SoundCloudMediaAdapter extends BaseMediaAdapter {
             throw new TypeError('Time must be a number.');
         this.#widget?.seekTo(timeMs);
     }
+    /**
+     * Checks whether the player is currently muted.
+     * @returns {boolean} True if muted, false otherwise.
+     */
+    isMuted() {
+        checkDestroy(this.#destroyed);
+        return this.#isMuted;
+    }
+    /**
+     * Mutes the current playback.
+     * @returns {Promise<void>}
+     */
+    async mute() {
+        checkDestroy(this.#destroyed);
+        if (this.#isMuted)
+            return;
+        this.#isMuted = true;
+        this.#preMuteVolume = this.#currentVolume;
+        // We update the state directly to avoid the setter's logic
+        // overwriting preMuteVolume during the transition.
+        this.#currentVolume = 0;
+        if (this.#widget && typeof this.#widget.setVolume === 'function') {
+            this.#widget.setVolume(0);
+        }
+    }
+    /**
+     * Unmutes the current playback.
+     * @returns {Promise<void>}
+     */
+    async unMute() {
+        checkDestroy(this.#destroyed);
+        if (!this.#isMuted)
+            return;
+        this.#isMuted = false;
+        // This will trigger the 'set volume' logic which applies the restored volume
+        this.volume = this.#preMuteVolume;
+    }
     /**
      * Retrieves the current playback time.
      * @returns {number} The current time in milliseconds.

package/dist/v1/libs/TinyMediaPlayer/Youtube.cjs

@@ -300,6 +300,12 @@ class YoutubeMediaAdapter extends index.BaseMediaAdapter {
   /** @type {number} */
   #pollingTimeUpdateValue = 250;
 
+  /** @type {boolean} */
+  #isPaused = false;
+
+  /** @type {boolean} */
+  #isEnded = false;
+
   get pollingTimeUpdateValue() {
     checkDestroy(this.#destroyed);
     return this.#pollingTimeUpdateValue;
@@ -388,6 +394,24 @@ class YoutubeMediaAdapter extends index.BaseMediaAdapter {
     return this.#isReady;
   }
 
+  /**
+   * Checks whether the media adapter is paused.
+   * @returns {boolean} True if the adapter is ready, false otherwise.
+   */
+  isPaused() {
+    checkDestroy(this.#destroyed);
+    return this.#isPaused;
+  }
+
+  /**
+   * Checks whether the media adapter is ended.
+   * @returns {boolean} True if the adapter is ready, false otherwise.
+   */
+  isEnded() {
+    checkDestroy(this.#destroyed);
+    return this.#isEnded;
+  }
+
   /**
    * Asynchronously waits until the YouTube media adapter is fully initialized and ready.
    * @returns {Promise<void>} A promise that resolves once the adapter is ready.
@@ -507,9 +531,21 @@ class YoutubeMediaAdapter extends index.BaseMediaAdapter {
         if (ytEvent === 'onStateChange') {
           const state = args[0];
           if (objChecker.isValidObj(state)) {
-            if (state.data === YoutubeMediaAdapter.PlayerState.PLAYING) masterEmitter.emit('play');
-            if (state.data === YoutubeMediaAdapter.PlayerState.PAUSED) masterEmitter.emit('pause');
-            if (state.data === YoutubeMediaAdapter.PlayerState.ENDED) masterEmitter.emit('ended');
+            if (state.data === YoutubeMediaAdapter.PlayerState.PLAYING) {
+              this.#isPaused = false;
+              this.#isEnded = false;
+              masterEmitter.emit('play');
+            }
+            if (state.data === YoutubeMediaAdapter.PlayerState.PAUSED) {
+              this.#isPaused = true;
+              this.#isEnded = false;
+              masterEmitter.emit('pause');
+            }
+            if (state.data === YoutubeMediaAdapter.PlayerState.ENDED) {
+              this.#isPaused = false;
+              this.#isEnded = true;
+              masterEmitter.emit('ended');
+            }
           }
         }
         return result;
@@ -633,6 +669,33 @@ class YoutubeMediaAdapter extends index.BaseMediaAdapter {
     this.#player?.seekTo(targetTimeInSeconds, true);
   }
 
+  /**
+   * Checks whether the player is currently muted.
+   * @returns {boolean|null} True if muted, false otherwise.
+   */
+  isMuted() {
+    checkDestroy(this.#destroyed);
+    return this.#player?.isMuted() ?? null;
+  }
+
+  /**
+   * Mutes the current playback.
+   * @returns {Promise<void>}
+   */
+  async mute() {
+    checkDestroy(this.#destroyed);
+    this.#player?.mute();
+  }
+
+  /**
+   * Unmutes the current playback.
+   * @returns {Promise<void>}
+   */
+  async unMute() {
+    checkDestroy(this.#destroyed);
+    this.#player?.unMute();
+  }
+
   /**
    * Retrieves the current playback time.
    * @returns {number} The current time in milliseconds.