tiny-essentials 1.28.5 → 1.28.7

package/dist/v1/libs/TinyMediaPlayer.cjs

@@ -18,6 +18,7 @@ const checkDestroy = utils.createCheckDestroyed('TinyMediaPlayer');
  * @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
  */
 
 /**
@@ -126,6 +127,9 @@ class TinyMediaPlayer extends events.EventEmitter {
   /** @type {boolean} */
   #isPlaying = false;
 
+  /** @type {boolean} */
+  #isMuted = false;
+
   /** @type {number} */
   #volume = 1.0;
 
@@ -682,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
   // ==========================================
@@ -1124,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);
   }
@@ -1358,6 +1396,43 @@ class TinyMediaPlayer extends events.EventEmitter {
     }
   }
 
+  /**
+   * 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
   // ==========================================

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

@@ -9,6 +9,7 @@ export type LoadingMediaProgress = import('../basics/mediaContent.mjs').LoadingM
 export type MediaLoadingErrorData = import('../basics/mediaContent.mjs').MediaLoadingErrorData;
 export type UnknownArtistGetter = import('../basics/mediaContent.mjs').UnknownArtistGetter;
 export type ContentTimeData = import('./TinyMediaPlayer/index.mjs').ContentTimeData;
+export type ContentData = import('./TinyMediaPlayer/index.mjs').ContentData;
 export type LoopModeType = 'NONE' | 'TRACK' | 'PLAYLIST';
 export type TinyMediaPlayerOptions = {
     /**
@@ -52,6 +53,7 @@ export type SearchResult = {
  * @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
  */
 /**
  * The loop configuration modes.
@@ -218,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[];
@@ -380,6 +391,17 @@ declare class TinyMediaPlayer extends EventEmitter {
      * @returns {number} A value between 0 and 100.
      */
     getPlaybackPercentage(): number;
+    /**
+     * 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>}
+     */
+    getContentData(): Promise<ContentData>;
+    /**
+     * Asynchronously waits until the content media adapter is fully initialized and ready.
+     * @returns {Promise<void>} A promise that resolves once the adapter is ready.
+     */
+    waitIsReady(): Promise<void>;
     /**
      * Safely destroys the TinyMediaPlayer instance.
      * This method stops active playback, clears the internal playlist,

package/dist/v1/libs/TinyMediaPlayer.mjs

@@ -14,6 +14,7 @@ const checkDestroy = createCheckDestroyed('TinyMediaPlayer');
  * @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
  */
 /**
  * The loop configuration modes.
@@ -97,6 +98,8 @@ class TinyMediaPlayer extends EventEmitter {
     #isRandom = false;
     /** @type {boolean} */
     #isPlaying = false;
+    /** @type {boolean} */
+    #isMuted = false;
     /** @type {number} */
     #volume = 1.0;
     /** @type {boolean} */
@@ -607,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
     // ==========================================
@@ -1006,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);
     }
@@ -1223,6 +1257,43 @@ class TinyMediaPlayer extends EventEmitter {
             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
     // ==========================================

package/docs/v1/libs/TinyMediaPlayer.md

@@ -9,17 +9,35 @@
 To support different media platforms, `TinyMediaPlayer` relies on **Adapters**. You must create a class that extends `BaseMediaAdapter` for every new service you wish to support.
 
 ### 🛠️ `BaseMediaAdapter` (Abstract Class)
-*This class cannot be instantiated directly. It serves as an interface.*
+*This class cannot be instantiated directly. It serves as an interface that all specific API wrappers must extend and implement.*
 
+#### Properties
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `destroyed` | `boolean` | Indicates if the adapter instance has been destroyed. |
+
+#### Methods
 | Method | Description | Parameters | Returns |
 | :--- | :--- | :--- | :--- |
-| `canHandle` | Checks if the adapter supports a specific content item. | `content: MediaContent` | `boolean` |
-| `play` | Starts or resumes playback. | `content: MediaContent` | `Promise<void>` |
+| `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 playback and resets the platform state. | None | `Promise<void>` |
-| `seek` | Jumps to a specific time. | `timeMs: number` | `Promise<void>` |
-| `getCurrentTime` | Gets the current playback position. | None | `number` (ms) |
-| `setVolume` | Sets the volume level. | `volume: number` (0.0 to 1.0) | `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) |
+| `getPlaybackPercentage` | Gets the percentage of the content that has been played. | None | `number` (0 to 100) |
+| `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) |
+| `getContentData` | Retrieves the metadata of the loaded content. | None | `Promise<ContentData>` |
+| `destroy` | Cleans up the instance and marks it as destroyed. | None | `void` |
 
 ---
 
@@ -31,7 +49,8 @@ You can integrate `TinyMediaPlayer` into your project using two methods: using t
 The library provides several optimized adapters for common media sources. You can import them and register them directly with your player instance.
 
 **Available Adapters:**
-* `YoutubeMediaAdapter` from `tiny-essentials/libs/TinyMediaPlayer/Youtube`
+* `YoutubeMediaAdapter` from `tiny-essentials/libs/TinyMediaPlayer/Youtube` (https://www.youtube.com/watch?v=XXXXXXXXXXX)
+* `SoundCloudMediaAdapter` from `tiny-essentials/libs/TinyMediaPlayer/SoundCloud` (https://api.soundcloud.com/tracks/XXXXXXXXX (From SoundCloud Embed))
 * `HtmlAudioAdapter` from `tiny-essentials/libs/TinyMediaPlayer/HtmlAudio`
 * `HtmlVideoAdapter` from `tiny-essentials/libs/TinyMediaPlayer/HtmlVideo`
 
@@ -46,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
@@ -76,41 +95,34 @@ class MyCustomServiceAdapter extends BaseMediaAdapter {
    * @param {MediaContent} content - The media content to check.
    * @returns {boolean} - True if the URL matches the service.
    */
-  canHandle(content) {
+  static canHandle(content) {
     return content.url.startsWith('https://example.com/');
   }
 
-  /**
-   * 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
+  canHandle(content) {
+    return MyCustomServiceAdapter.canHandle(content);
   }
 
-  getCurrentTime() {
-    // Logic to return current time from custom service
-    return 0; 
+  async play(content) {
+    console.log(`Starting playback for: ${content.title}`);
   }
 
-  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
@@ -192,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 |
@@ -252,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.
@@ -291,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.5",
+  "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"
@@ -108,6 +108,10 @@
       "require": "./dist/v1/basics/text.cjs",
       "import": "./dist/v1/basics/text.mjs"
     },
+    "./basics/promiseUtils": {
+      "require": "./dist/v1/basics/promiseUtils.cjs",
+      "import": "./dist/v1/basics/promiseUtils.mjs"
+    },
     "./fileManager": {
       "require": "./dist/v1/fileManager/index.cjs",
       "import": "./dist/v1/fileManager/index.mjs"
@@ -140,6 +144,10 @@
       "require": "./dist/v1/libs/TinyMediaPlayer/Youtube.cjs",
       "import": "./dist/v1/libs/TinyMediaPlayer/Youtube.mjs"
     },
+    "./libs/TinyMediaPlayer/SoundCloud": {
+      "require": "./dist/v1/libs/TinyMediaPlayer/SoundCloud.cjs",
+      "import": "./dist/v1/libs/TinyMediaPlayer/SoundCloud.mjs"
+    },
     "./libs/TinyMediaPlayer/HtmlAudio": {
       "require": "./dist/v1/libs/TinyMediaPlayer/HtmlAudio.cjs",
       "import": "./dist/v1/libs/TinyMediaPlayer/HtmlAudio.mjs"
@@ -152,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"
@@ -503,23 +515,16 @@
   },
   "keywords": [
     "tiny-essentials",
-    "timeout",
+    "utility-library",
     "storage",
     "text-editor",
     "color-converter",
     "clock",
     "time",
-    "text",
-    "text-range",
-    "input-editor",
-    "string-utils",
     "string-manipulation",
     "obj-type",
     "type-checker",
-    "simple-math",
-    "math-utils",
     "shuffle-array",
-    "array-utils",
     "json",
     "json-utils",
     "json-color",
@@ -536,7 +541,47 @@
     "toolkit",
     "frontend-utils",
     "backend-utils",
-    "nodejs-utils"
+    "nodejs-utils",
+    "array-utils",
+    "object-utils",
+    "string-utils",
+    "math-utils",
+    "dom-utils",
+    "html-utils",
+    "css-utils",
+    "modular-scripts",
+    "type-validation",
+    "text-manipulation",
+    "text-formatting",
+    "color-management",
+    "color-conversion",
+    "color-validation",
+    "drag-and-drop",
+    "scroll-management",
+    "clipboard-management",
+    "notifications",
+    "toast-notifications",
+    "loading-screen",
+    "cookie-consent",
+    "i18n",
+    "iframe-communication",
+    "window-communication",
+    "media-playback",
+    "audio-processing",
+    "gamepad-api",
+    "input-handling",
+    "file-upload",
+    "inventory-management",
+    "level-up-system",
+    "raffle-system",
+    "day-night-cycle",
+    "rate-limiting",
+    "promise-queue",
+    "file-management",
+    "terminal-ui",
+    "json-formatting",
+    "fuzzy-logic",
+    "text-range-editor"
   ],
   "author": "Yasmin Seidel (Jasmin Dreasond)",
   "license": "LGPL-3.0-only",