tiny-essentials 1.28.6 → 1.28.7

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

@@ -110,6 +110,21 @@ declare class BaseMediaAdapter extends EventEmitter {
      * @returns {Promise<void>}
      */
     seek(timeMs: number): Promise<void>;
+    /**
+     * Checks whether the player is currently muted.
+     * @returns {boolean|null} True if muted, false otherwise.
+     */
+    isMuted(): boolean | null;
+    /**
+     * 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 from the underlying API.
      * @returns {number} The current time in milliseconds.

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

@@ -109,6 +109,30 @@ class BaseMediaAdapter extends EventEmitter {
         checkDestroy(this.#destroyed);
         throw new Error('Method "seek" must be implemented by the subclass.');
     }
+    /**
+     * Checks whether the player is currently muted.
+     * @returns {boolean|null} True if muted, false otherwise.
+     */
+    isMuted() {
+        checkDestroy(this.#destroyed);
+        throw new Error('Method "isMuted" must be implemented by the subclass.');
+    }
+    /**
+     * Mutes the current playback.
+     * @returns {Promise<void>}
+     */
+    async mute() {
+        checkDestroy(this.#destroyed);
+        throw new Error('Method "mute" must be implemented by the subclass.');
+    }
+    /**
+     * Unmutes the current playback.
+     * @returns {Promise<void>}
+     */
+    async unMute() {
+        checkDestroy(this.#destroyed);
+        throw new Error('Method "unMute" must be implemented by the subclass.');
+    }
     /**
      * Retrieves the current playback time from the underlying API.
      * @returns {number} The current time in milliseconds.

package/dist/v1/libs/TinyMediaPlayer.cjs

@@ -127,6 +127,9 @@ class TinyMediaPlayer extends events.EventEmitter {
   /** @type {boolean} */
   #isPlaying = false;
 
+  /** @type {boolean} */
+  #isMuted = false;
+
   /** @type {number} */
   #volume = 1.0;
 
@@ -683,6 +686,39 @@ class TinyMediaPlayer extends events.EventEmitter {
     }
   }
 
+  /** @returns {boolean} True if the player is currently muted. */
+  get isMuted() {
+    checkDestroy(this.#destroyed);
+    return this.#isMuted;
+  }
+
+  /**
+   * Sets the mute state of the player.
+   * This state is synchronized with the active adapter and respected when playing new tracks.
+   * @param {boolean} value - True to mute, false to unMute.
+   * @throws {TypeError} If the value is not a boolean.
+   */
+  set isMuted(value) {
+    checkDestroy(this.#destroyed);
+    if (typeof value !== 'boolean') {
+      throw new TypeError('isMuted must be a boolean.');
+    }
+
+    this.#isMuted = value;
+
+    // Synchronize with the active adapter immediately
+    try {
+      const adapter = this.#getActiveAdapter();
+      if (adapter) {
+        value ? adapter.mute() : adapter.unMute();
+      }
+    } catch (error) {
+      // If no active adapter, we just wait for the next play() call to apply the state
+    }
+
+    this.emit('muteChange', this.#isMuted);
+  }
+
   // ==========================================
   // ADAPTER MANAGEMENT
   // ==========================================
@@ -1125,6 +1161,7 @@ class TinyMediaPlayer extends events.EventEmitter {
     }
 
     await adapter.play(this.#playlist[this.#currentIndex]);
+    if (this.#isMuted) await adapter.mute();
     this.#isPlaying = true;
     this.emit('play', this.#currentIndex);
   }

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

@@ -220,6 +220,15 @@ declare class TinyMediaPlayer extends EventEmitter {
      * @throws {TypeError} If the value is not a string or is empty.
      */
     set volumeStorageKey(value: string);
+    /** @returns {boolean} True if the player is currently muted. */
+    get isMuted(): boolean;
+    /**
+     * Sets the mute state of the player.
+     * This state is synchronized with the active adapter and respected when playing new tracks.
+     * @param {boolean} value - True to mute, false to unMute.
+     * @throws {TypeError} If the value is not a boolean.
+     */
+    set isMuted(value: boolean);
     get adapters(): BaseMediaAdapter[];
     get adaptersSize(): number;
     static get defaultAdapterEventNames(): string[];

package/dist/v1/libs/TinyMediaPlayer.mjs

@@ -98,6 +98,8 @@ class TinyMediaPlayer extends EventEmitter {
     #isRandom = false;
     /** @type {boolean} */
     #isPlaying = false;
+    /** @type {boolean} */
+    #isMuted = false;
     /** @type {number} */
     #volume = 1.0;
     /** @type {boolean} */
@@ -608,6 +610,35 @@ class TinyMediaPlayer extends EventEmitter {
             console.warn('[TinyMediaPlayer] Failed to migrate volume storage key.', error);
         }
     }
+    /** @returns {boolean} True if the player is currently muted. */
+    get isMuted() {
+        checkDestroy(this.#destroyed);
+        return this.#isMuted;
+    }
+    /**
+     * Sets the mute state of the player.
+     * This state is synchronized with the active adapter and respected when playing new tracks.
+     * @param {boolean} value - True to mute, false to unMute.
+     * @throws {TypeError} If the value is not a boolean.
+     */
+    set isMuted(value) {
+        checkDestroy(this.#destroyed);
+        if (typeof value !== 'boolean') {
+            throw new TypeError('isMuted must be a boolean.');
+        }
+        this.#isMuted = value;
+        // Synchronize with the active adapter immediately
+        try {
+            const adapter = this.#getActiveAdapter();
+            if (adapter) {
+                value ? adapter.mute() : adapter.unMute();
+            }
+        }
+        catch (error) {
+            // If no active adapter, we just wait for the next play() call to apply the state
+        }
+        this.emit('muteChange', this.#isMuted);
+    }
     // ==========================================
     // ADAPTER MANAGEMENT
     // ==========================================
@@ -1007,6 +1038,8 @@ class TinyMediaPlayer extends EventEmitter {
             adapter.setVolume(this.#volume);
         }
         await adapter.play(this.#playlist[this.#currentIndex]);
+        if (this.#isMuted)
+            await adapter.mute();
         this.#isPlaying = true;
         this.emit('play', this.#currentIndex);
     }

package/docs/v1/libs/TinyMediaPlayer.md

@@ -20,10 +20,15 @@ To support different media platforms, `TinyMediaPlayer` relies on **Adapters**.
 | Method | Description | Parameters | Returns |
 | :--- | :--- | :--- | :--- |
 | `canHandle` | Determines if the adapter can play the provided content. | `content: MediaContent` | `boolean` |
+| `isReady` | Synchronously checks if the adapter is ready. | None | `boolean` |
+| `waitIsReady` | Asynchronously waits until the adapter is ready. | None | `Promise<void>` |
 | `play` | Starts or resumes playback of the provided content. | `content: MediaContent` | `Promise<void>` |
 | `pause` | Pauses the current playback. | None | `Promise<void>` |
 | `stop` | Stops the playback completely and resets the platform state. | None | `Promise<void>` |
 | `seek` | Seeks to a specific time in the media timeline. | `timeMs: number` | `Promise<void>` |
+| `isMuted` | Checks whether the player is currently muted. | None | `boolean \| null` |
+| `mute` | Mutes the current playback. | None | `Promise<void>` |
+| `unMute` | Unmutes the current playback. | None | `Promise<void>` |
 | `getCurrentTime` | Retrieves the current playback position. | None | `number` (ms) |
 | `getTotalDuration` | Gets the total duration of the content. | None | `number` (ms) |
 | `getRemainingTime` | Gets the remaining time until the content ends. | None | `number` (ms) |
@@ -31,7 +36,8 @@ To support different media platforms, `TinyMediaPlayer` relies on **Adapters**.
 | `getTimeData` | Retrieves a consolidated object containing all time-related metrics. | None | `ContentTimeData` |
 | `setVolume` | Sets the playback volume for the underlying API. | `volume: number` (0.0 to 1.0) | `void` |
 | `getVolume` | Gets the current playback volume. | None | `number` (0.0 to 1.0) |
-| `destroy` | Cleans up the instance, removes listeners, and marks it as destroyed. | None | `void` |
+| `getContentData` | Retrieves the metadata of the loaded content. | None | `Promise<ContentData>` |
+| `destroy` | Cleans up the instance and marks it as destroyed. | None | `void` |
 
 ---
 
@@ -59,9 +65,9 @@ const player = new TinyMediaPlayer({
 });
 
 YoutubeMediaAdapter.defaultContainer = YoutubeMediaAdapter.createIframeContainer({
-videoId: 'fzKvGbQ9SgY',
-hidden: true,
-autoplay: false,
+  videoId: 'fzKvGbQ9SgY',
+  hidden: true,
+  autoplay: false,
 });
 
 // Register the ready-made adapters
@@ -93,46 +99,30 @@ class MyCustomServiceAdapter extends BaseMediaAdapter {
     return content.url.startsWith('https://example.com/');
   }
 
-  /**
-   * Determines if this adapter can play the given content.
-   * @param {MediaContent} content - The media content to check.
-   * @returns {boolean} - True if the URL matches the service.
-   */
   canHandle(content) {
     return MyCustomServiceAdapter.canHandle(content);
   }
 
-  /**
-   * Starts playback for the provided content.
-   * @param {MediaContent} content - The content to play.
-   * @returns {Promise<void>}
-   */
   async play(content) {
     console.log(`Starting playback for: ${content.title}`);
-    // Logic to interface with the custom service API goes here
-  }
-
-  async pause() {
-    // Logic to pause custom service playback
-  }
-
-  async stop() {
-    // Logic to stop custom service playback
-  }
-
-  async seek(timeMs) {
-    // Logic to seek in custom service playback
-  }
-
-  getCurrentTime() {
-    // Logic to return current time from custom service
-    return 0; 
   }
 
-  setVolume(volume) {
-    // Logic to set volume on custom service
-    console.log(`Volume set to: ${volume}`);
-  }
+  async pause() {}
+  async stop() {}
+  async seek(timeMs) {}
+  getCurrentTime() { return 0; }
+  setVolume(volume) {}
+  getVolume() { return 1.0; }
+  async getContentData() { return {}; }
+  async waitIsReady() {}
+  isReady() { return true; }
+  isMuted() { return false; }
+  async mute() {}
+  async unMute() {}
+  getTotalDuration() { return 0; }
+  getRemainingTime() { return 0; }
+  getPlaybackPercentage() { return 0; }
+  getTimeData() { return {}; }
 }
 
 // Registering the custom adapter
@@ -214,6 +204,7 @@ When initializing `new TinyMediaPlayer(options)`, you can pass the following `Ti
 | `isRandom` | `boolean` | Enables or disables shuffle mode. |
 | `isPlaying` | `boolean` | Indicates if media is currently playing. |
 | `volume` | `number` | The current volume level (strictly between `0.0` and `1.0`). |
+| `isMuted` | `boolean` | Sets the mute state of the player. |
 
 #### 🎨 UX & Customization
 | Property | Type | Description |
@@ -274,13 +265,15 @@ When initializing `new TinyMediaPlayer(options)`, you can pass the following `Ti
 * **`next()`**: **(Async)** Advances to the next track (respects `loopMode` and `isRandom`).
 * **`prev()`**: **(Async)** Returns to the previous track (respects `loopMode` and `isRandom`).
 * **`seek(timeMs)`**: **(Async)** Jumps to a specific millisecond in the current track.
-* **`step(stepMs)`**: **(Async)** Moves the timeline forward (positive) or backward (negative) by a specified amount.
+* **`step(stepMs)`**: **(Async)** Moves the timeline forward (+) or backward (-) by `stepMs`.
 
 #### ⏳ Time Utilities
 * **`getCurrentTime()`**: Gets the current playback time in milliseconds.
 * **`getTotalDuration()`**: Gets the total duration of the current track in milliseconds.
 * **`getRemainingTime()`**: Gets the remaining time until the current track ends in milliseconds.
 * **`getPlaybackPercentage()`**: Gets the percentage of the current track that has been played (0-100).
+* **`getContentData()`**: Retrieves structured metadata for the current content.
+* **`waitIsReady()`**: **(Async)** Waits until the active adapter is fully initialized.
 
 #### ♻️ Lifecycle
 * **`destroy()`**: **(Async)** Safely stops playback, clears state, removes adapters, and detaches all listeners to prevent memory leaks.
@@ -313,6 +306,7 @@ When initializing `new TinyMediaPlayer(options)`, you can pass the following `Ti
 | `smoothStopVolumeChange` | `boolean` | Emitted when the smooth stop volume setting is toggled. |
 | `fadeVolumeSpeedChange` | `number` | Emitted when the volume fade speed is updated. |
 | `prevClickTimeoutDurationChange` | `number` | Emitted when the "repeat on prev" timeout duration is updated. |
+| `muteChange` | `boolean` | Emitted when the mute state is toggled. |
 
 ### 💀 Lifecycle Events
 | Event | Data Type | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.28.6",
+  "version": "1.28.7",
   "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
   "bin": {
     "tiny-essentials-fork": "./TinyFork.mjs"
@@ -160,6 +160,10 @@
       "require": "./dist/v1/libs/TinyMediaPlayer/docs/YouTubePlayer.cjs",
       "import": "./dist/v1/libs/TinyMediaPlayer/docs/YouTubePlayer.mjs"
     },
+    "./libs/TinyMediaPlayer/docs/SoundCloudWidget": {
+      "require": "./dist/v1/libs/TinyMediaPlayer/docs/SoundCloudWidget.cjs",
+      "import": "./dist/v1/libs/TinyMediaPlayer/docs/SoundCloudWidget.mjs"
+    },
     "./libs/TinyRadioFm": {
       "require": "./dist/v1/libs/TinyRadioFm.cjs",
       "import": "./dist/v1/libs/TinyRadioFm.mjs"