tiny-essentials 1.28.6 → 1.28.8

package/docs/v1/libs/TinyMediaPlayer.md

@@ -1,6 +1,6 @@
 # 🎧 TinyMediaPlayer Documentation
 
-`TinyMediaPlayer` is a robust, universal media player manager designed to orchestrate playback across multiple different media providers (such as YouTube, Spotify, etc.) using an **Adapter Pattern**.
+`TinyMediaPlayer` is a robust, universal media player manager designed to orchestrate playback across multiple different media providers (such as YouTube, Spotify, etc.) using an **Adapter Pattern**. It inherits debugging capabilities from `TinyDebugger`.
 
 ---
 
@@ -11,27 +11,31 @@ To support different media platforms, `TinyMediaPlayer` relies on **Adapters**.
 ### 🛠️ `BaseMediaAdapter` (Abstract Class)
 *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 |
 | :--- | :--- | :--- | :--- |
+| `static canHandle` | Determines if the adapter can play the provided content. | `content: MediaContent` | `boolean` |
 | `canHandle` | Determines if the adapter can play the provided content. | `content: MediaContent` | `boolean` |
+| `isReady` | Synchronously checks if the adapter is ready. | None | `boolean` |
+| `isPaused` | Checks whether the media adapter is paused. | None | `boolean` |
+| `isEnded` | Checks whether the media adapter is ended. | 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>` |
+| `stop` | Stops the playback completely and resets the internal platform state. | None | `Promise<void>` |
 | `seek` | Seeks to a specific time in the media timeline. | `timeMs: number` | `Promise<void>` |
-| `getCurrentTime` | Retrieves the current playback position. | None | `number` (ms) |
+| `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 time from the underlying API. | 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) |
-| `destroy` | Cleans up the instance, removes listeners, and marks it as destroyed. | None | `void` |
+| `getVolume` | Gets the playback volume from the underlying API. | None | `number` (0.0 to 1.0) |
+| `getContentData` | Retrieves the metadata of the currently loaded content. | None | `Promise<ContentData>` |
+| `destroy` | Cleans up the instance. | None | `void` |
 
 ---
 
@@ -59,9 +63,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
@@ -84,55 +88,37 @@ import { BaseMediaAdapter } from 'tiny-essentials/libs/TinyMediaPlayer/Base';
  * @extends BaseMediaAdapter
  */
 class MyCustomServiceAdapter extends BaseMediaAdapter {
-  /**
-   * 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.
-   */
   static canHandle(content) {
     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; }
+  isPaused() { return false; }
+  isEnded() { return false; }
+  isMuted() { return false; }
+  async mute() {}
+  async unMute() {}
+  getTotalDuration() { return 0; }
+  getRemainingTime() { return 0; }
+  getPlaybackPercentage() { return 0; }
+  getTimeData() { return {}; }
+  destroy() {}
 }
 
 // Registering the custom adapter
@@ -176,6 +162,9 @@ When initializing `new TinyMediaPlayer(options)`, you can pass the following `Ti
 * **`repeatCurrentOnPrev`** (`boolean`): If `true`, clicking 'previous' repeats the current track on the first click. (Default: `false`).
 * **`smoothPlayPauseVolume`** (`boolean`): If `true`, volume fades smoothly during play/pause transitions. (Default: `false`).
 * **`smoothStopVolume`** (`boolean`): If `true`, volume fades smoothly to zero when stopping. (Default: `false`).
+* **`debugMode`** (`boolean`): Whether to enable internal debug logging.
+* **`useLogColors`** (`boolean`): Whether to enable log color support.
+* **`logger`** (`Console`): A custom logger object.
 
 ---
 
@@ -214,6 +203,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` | Indicates if the player is currently muted. |
 
 #### 🎨 UX & Customization
 | Property | Type | Description |
@@ -270,20 +260,27 @@ When initializing `new TinyMediaPlayer(options)`, you can pass the following `Ti
 #### ⏯️ Playback Controls
 * **`play()`**: **(Async)** Starts playback of the current track.
 * **`pause()`**: **(Async)** Pauses the current track.
+* **`mute()`**: **(Async)** Mutes the playback.
+* **`unMute()`**: **(Async)** Unmutes the playback.
 * **`stop()`**: **(Async)** Stops the current track completely.
 * **`next()`**: **(Async)** Advances to the next track (respects `loopMode` and `isRandom`).
 * **`prev()`**: **(Async)** Returns to the previous track (respects `loopMode` and `isRandom`).
+* **`skipTo(index)`**: **(Async)** Jumps to a specific index in the playlist.
 * **`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).
+* **`isPaused` (Getter)**: Checks if the adapter is paused.
+* **`isEnded` (Getter)**: Checks if the adapter has ended.
+* **`getContentData()`**: **(Async)** 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.
+* **`destroy()`**: **(Async)** Safely stops playback, clears state, removes adapters, and detaches all listeners.
 
 ---
 
@@ -313,6 +310,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 |
@@ -324,6 +322,6 @@ When initializing `new TinyMediaPlayer(options)`, you can pass the following `Ti
 ## ⚠️ Error Handling
 
 The class uses strict validation. The following errors may be thrown:
-* **`TypeError`**: Thrown when an argument is of the wrong type (e.g., invalid index type, non-boolean options, invalid adapter instance, or empty storage key).
-* **`RangeError`**: Thrown when a number is out of allowed bounds (e.g., negative time, volume outside `0.0`-`1.0`, negative durations, or index out of playlist bounds).
+* **`TypeError`**: Thrown when an argument is of the wrong type.
+* **`RangeError`**: Thrown when a number is out of allowed bounds.
 * **`Error`**: Thrown if no compatible adapter is found for the current content.

package/docs/v1/libs/TinyRadioFm.md

@@ -31,7 +31,9 @@ The behavior of the engine is controlled via the `RadioConfig` object.
 | `voiceAfterMusic` | `boolean` | `true` | If `true`, voice messages play after music tracks. |
 | `voiceMin` | `number` | `0` | Minimum number of voice messages to play in a cycle. |
 | `voiceMax` | `number` | `1` | Maximum number of voice messages to play in a cycle. |
+| `musicMinConsecutive`| `number` | `0` | Min times a music track must repeat consecutively. |
 | `musicMaxConsecutive`| `number` | `0` | Max consecutive music repeats (`-1` = unlimited, `0` = no repeats). |
+| `voiceMinConsecutive`| `number` | `0` | Min times a voice track must repeat consecutively. |
 | `voiceMaxConsecutive`| `number` | `0` | Max consecutive voice repeats (`-1` = unlimited, `0` = no repeats). |
 
 ---
@@ -60,7 +62,7 @@ Adds new content to the engine immediately.
 * **Parameters:**
     * `type`: `'music' | 'voice' | 'custom'`.
     * `data`: The `MediaContent` object (must include `id` and `duration`).
-    * `smartQueue`: If `true`, delays insertion until the current content ends (primarily for `custom`).
+    * `smartQueue`: If `true`, delays insertion until the end of the content playing at that timestamp (primarily for `custom`).
 * **Emits:** `contentAdded`
 
 #### `remove(id)`
@@ -108,7 +110,7 @@ Predicts upcoming events from a specific date forward using a virtual sandbox to
 ### 💾 Persistence & Lifecycle
 
 #### `async exportState()`
-Exports the entire radio state (playlists, tasks, seed, config) as a JSON string. Automatically converts all image Blob URLs to **Base64** for portability.
+Exports the entire radio state (playlists, tasks, seed, config) as a JSON string. Automatically converts all image Blob URLs to **Base64** for easy storage.
 * **Returns:** `Promise<string>`
 
 #### `importState(json)`
@@ -138,4 +140,24 @@ An instruction to change the radio state.
 * `timestamp`: Execution time.
 * `action`: `'add' | 'remove' | 'move'`.
 * `type`: `'music' | 'voice'`.
-* `payload`: Action-specific data.
+* `payload`: Action-specific data (`MediaContent`, `string`, or `ScheduledMovePayload`).
+
+### `CustomPosition` 📍
+Represents content injected at a specific absolute timestamp.
+* `content`: The `MediaContent` object.
+* `intendedTimestamp`: The target absolute timestamp.
+* `originalTimestamp`: The timestamp preserved for intelligent repositioning.
+
+### `ScheduledMovePayload` 🚚
+Data required to relocate an existing item within a playlist.
+* `id`: Content ID to move.
+* `newIndex`: The target index in the playlist.
+
+### `CycleBlock` 🔄
+A structural block representing a single full iteration of the radio sequence.
+* `items`: Items belonging to this cycle.
+* `duration`: Total duration of the cycle block in ms.
+* `lastMusicId`: ID of the last music played in this block.
+* `musicConsecutiveCount`: Current consecutive count for music.
+* `lastVoiceId`: ID of the last voice played in this block.
+* `voiceConsecutiveCount`: Current consecutive count for voice.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.28.6",
+  "version": "1.28.8",
   "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"
@@ -156,14 +156,26 @@
       "require": "./dist/v1/libs/TinyMediaPlayer/HtmlVideo.cjs",
       "import": "./dist/v1/libs/TinyMediaPlayer/HtmlVideo.mjs"
     },
+    "./libs/TinyMediaPlayer/Mock": {
+      "require": "./dist/v1/libs/TinyMediaPlayer/Mock.cjs",
+      "import": "./dist/v1/libs/TinyMediaPlayer/Mock.mjs"
+    },
     "./libs/TinyMediaPlayer/docs/YouTubePlayer": {
       "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"
     },
+    "./libs/TinyDebugger": {
+      "require": "./dist/v1/libs/TinyDebugger.cjs",
+      "import": "./dist/v1/libs/TinyDebugger.mjs"
+    },
     "./libs/UltraRandomMsgGen": {
       "require": "./dist/v1/libs/UltraRandomMsgGen.cjs",
       "import": "./dist/v1/libs/UltraRandomMsgGen.mjs"