tiny-essentials 1.28.17 → 1.28.18

package/dist/v1/libs/media/TinyRadioFm.mjs

@@ -2,6 +2,7 @@ import { EventEmitter } from 'events';
 import { blobUrlToBase64, convertToBlobUrl, parseMediaMetadata, revokeContentUrls, valMediaContentMetadata, } from '../../basics/mediaContent.mjs';
 import { createCheckDestroyed } from '../utils/tools.mjs';
 import { isJsonObject } from '../../basics/objChecker.mjs';
+import TinyAdvancedRaffle from '../math/TinyAdvancedRaffle.mjs';
 const checkDestroy = createCheckDestroyed('TinyRadioFm');
 /**
  * @typedef {import('../../basics/mediaContent.mjs').PictureDataType} PictureDataType
@@ -71,12 +72,13 @@ const checkDestroy = createCheckDestroyed('TinyRadioFm');
  * @property {number} silenceDuration - Gap in ms between tracks.
  * @property {number} queryLimit - Safety lock for max items processed.
  * @property {boolean} voiceAfterMusic - Whether to play voice messages after music tracks.
+ * @property {number} voiceWeight - Weight used to calculate the probability of a voice block occurring.
  * @property {number} voiceMin - Minimum amount of voice messages to play if voiceAfterMusic is true.
  * @property {number} voiceMax - Maximum amount of voice messages to play.
  * @property {number} musicMaxConsecutive - Max times a music track can repeat consecutively (-1 = unlimited, 0 = strictly no repetition).
  * @property {number} musicMinConsecutive - Min times a music track must repeat consecutively (1 = no mandatory repetition).
  * @property {number} voiceMaxConsecutive - Max times a voice track can repeat consecutively (-1 = unlimited, 0 = strictly no repetition).
- * @property {number} voiceMinConsecutive - Min times a voice track must repeat consecutively (1 = no mandatory repetition).
+ * @property {number} voiceMinConsecutive - Min times a voice track can repeat consecutively (1 = no mandatory repetition).
  */
 //////////////////////////////////////////////////////////////////
 /**
@@ -302,6 +304,7 @@ class TinyRadioFm extends EventEmitter {
         voiceAfterMusic: true,
         voiceMin: 0,
         voiceMax: 1,
+        voiceWeight: 1,
         musicMaxConsecutive: 0,
         musicMinConsecutive: 0,
         voiceMaxConsecutive: 0,
@@ -363,6 +366,7 @@ class TinyRadioFm extends EventEmitter {
                 throw new TypeError(`${minKey} must be a non-negative number.`);
             }
         };
+        checkRange(config.voiceWeight, 'voiceWeight');
         checkRange(config.voiceMin, 'voiceMin');
         checkRange(config.voiceMax, 'voiceMax');
         checkRange(config.musicMinConsecutive, 'musicMinConsecutive');
@@ -838,11 +842,6 @@ class TinyRadioFm extends EventEmitter {
                 consecutiveCount: initialLastId === lastItem.id ? initialConsecutiveCount + 1 : 1,
             };
         }
-        /**
-         * Pool of available items for weighted selection.
-         * @type {Array<MediaContent & { weight: number }>}
-         */
-        const pool = list.map((item) => ({ ...item, weight: item.weight ?? 1 }));
         const random = this._prng(currentSeed);
         /**
          * The finalized deterministic sequence.
@@ -852,6 +851,27 @@ class TinyRadioFm extends EventEmitter {
         /** @type {string|null} */
         let lastId = initialLastId;
         let consecutiveCount = initialConsecutiveCount;
+        // Initializes TinyAdvancedRaffle specifically for this sequence generation
+        const raffle = new TinyAdvancedRaffle({
+            rng: random,
+            normalization: 'relative',
+        });
+        // We keep the pool as an array to respect the original structure and support possible
+        // duplicate IDs, if they occur (even though it is rare).
+        /** @type {MediaContent[]} */
+        const pool = [...list];
+        // Registers all items in the Raffle system
+        pool.forEach((item) => {
+            const itemWeight = item.weight ?? 1;
+            const existing = raffle.getItem(item.id);
+            if (!existing) {
+                raffle.addItem(item.id, { weight: itemWeight });
+            }
+            else {
+                // If the ID already exists, we add its weight to maintain the correct proportion
+                raffle.setBaseWeight(item.id, existing.baseWeight + itemWeight);
+            }
+        });
         while (pool.length > 0) {
             /** @type {MediaContent|null} */
             let selectedItem = null;
@@ -867,32 +887,28 @@ class TinyRadioFm extends EventEmitter {
                     selectedItem = sequence[sequence.length - 1];
                 }
             }
-            // 2. Maximum repetition logic and random draw
+            // 2. Maximum repetition logic and drawing using the Raffle
             if (!selectedItem) {
-                let validPool = pool;
+                let excludedId = null;
                 if (lastId !== null && maxConsecutive !== -1 && consecutiveCount >= maxConsecutive) {
-                    validPool = pool.filter((item) => item.id !== lastId);
-                }
-                if (validPool.length === 0) {
-                    validPool = pool;
-                }
-                const totalWeight = validPool.reduce((sum, item) => sum + item.weight, 0);
-                if (totalWeight <= 0) {
-                    selectedItem = validPool[0];
-                    selectedIndex = pool.findIndex((p) => p.id === selectedItem?.id);
+                    // Checks if there are other different items in the pool before preventing the last one
+                    const hasOtherItems = pool.some((item) => item.id !== lastId);
+                    if (hasOtherItems) {
+                        raffle.excludeItem(lastId);
+                        excludedId = lastId;
+                    }
                 }
-                else {
-                    const r = random() * totalWeight;
-                    let sum = 0;
-                    for (let i = 0; i < validPool.length; i++) {
-                        sum += validPool[i].weight;
-                        if (r <= sum) {
-                            selectedItem = validPool[i];
-                            selectedIndex = pool.findIndex((p) => p.id === selectedItem?.id);
-                            break;
-                        }
+                const drawResult = raffle.drawOne();
+                if (drawResult) {
+                    selectedIndex = pool.findIndex((item) => item.id === drawResult.id);
+                    if (selectedIndex !== -1) {
+                        selectedItem = pool[selectedIndex];
                     }
                 }
+                // Removes the exclusion to avoid breaking future draws
+                if (excludedId) {
+                    raffle.includeItem(excludedId);
+                }
             }
             // Safety fallback
             if (!selectedItem) {
@@ -900,8 +916,25 @@ class TinyRadioFm extends EventEmitter {
                 selectedIndex = 0;
             }
             sequence.push(selectedItem);
+            // Updates the pool and the Raffle after the item has been drawn and used
             if (selectedIndex !== -1) {
                 pool.splice(selectedIndex, 1);
+                // If this item is no longer in the pool permanently, remove it from the Raffle
+                const stillInPool = pool.some((item) => item.id === selectedItem.id);
+                if (!stillInPool) {
+                    raffle.removeItem(selectedItem.id);
+                }
+                else {
+                    // If it still exists, we reduce the weight proportionally to continue the draw fairly
+                    const existing = raffle.getItem(selectedItem.id);
+                    if (existing) {
+                        const newWeight = Math.max(0, existing.baseWeight - (selectedItem.weight ?? 1));
+                        if (newWeight <= 0)
+                            raffle.removeItem(selectedItem.id);
+                        else
+                            raffle.setBaseWeight(selectedItem.id, newWeight);
+                    }
+                }
             }
             if (selectedItem.id === lastId) {
                 consecutiveCount++;
@@ -911,6 +944,7 @@ class TinyRadioFm extends EventEmitter {
                 consecutiveCount = 1;
             }
         }
+        raffle.destroy(); // Ensures memory is cleared at the end of each cycle
         return { items: sequence, lastId, consecutiveCount };
     }
     /**
@@ -956,17 +990,22 @@ class TinyRadioFm extends EventEmitter {
             });
             cycleDuration += music.duration + this.#config.silenceDuration;
             if (this.#config.voiceAfterMusic && voiceSeq.length > 0) {
-                const range = this.#config.voiceMax - this.#config.voiceMin + 1;
-                const voiceAmount = Math.floor(mixRandom() * range) + this.#config.voiceMin;
-                for (let v = 0; v < voiceAmount; v++) {
-                    const voice = voiceSeq[voiceCursor % voiceSeq.length];
-                    voiceCursor++;
-                    block.push({
-                        ...voice,
-                        cycleStart: cycleDuration,
-                        cycleEnd: cycleDuration + voice.duration,
-                    });
-                    cycleDuration += voice.duration + this.#config.silenceDuration;
+                // Calculate chance based on weight: P = W / (W + 1)
+                const voiceChance = this.#config.voiceWeight / (this.#config.voiceWeight + 1);
+                // Only proceed if the random roll is less than the calculated chance
+                if (mixRandom() < voiceChance) {
+                    const range = this.#config.voiceMax - this.#config.voiceMin + 1;
+                    const voiceAmount = Math.floor(mixRandom() * range) + this.#config.voiceMin;
+                    for (let v = 0; v < voiceAmount; v++) {
+                        const voice = voiceSeq[voiceCursor % voiceSeq.length];
+                        voiceCursor++;
+                        block.push({
+                            ...voice,
+                            cycleStart: cycleDuration,
+                            cycleEnd: cycleDuration + voice.duration,
+                        });
+                        cycleDuration += voice.duration + this.#config.silenceDuration;
+                    }
                 }
             }
         }

package/docs/v1/libs/media/TinyRadioFm.md

@@ -12,9 +12,9 @@
 * **🎵 Dual-Stream Logic:** Manages separate playlists for `music` and `voice`, with configurable interaction rules (e.g., playing voices after music).
 * **📅 Scheduled Mutations:** Schedule tasks to `add`, `remove`, or `move` items in the playlist at specific future timestamps.
 * **⚡ Custom Injections:** Inject "Custom Positions" into the timeline that interrupt the standard cycle.
-* **🧠 Smart Queuing:** Intelligent logic to prevent audio overlaps by automatically adjusting timestamps to the end of currently playing content.
+* **🧠 Smart Queuing:** Intelligent logic to prevent audio overlaps by automatically adjusting timestamps to the end of the currently playing content.
 * **💾 State Persistence:** Full export/import capabilities, including automatic conversion of Blob URLs to Base64 for easy storage.
-* **🧹 Memory Management:** Proactive cleanup of Blob URLs and event listeners to prevent memory leaks.
+* **🧹 Memory Management:** Proactive cleanup of Blob URLs and event listeners to prevent memory leaks, with configurable optimization for media and pictures.
 
 ---
 
@@ -31,6 +31,7 @@ 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. |
+| `voiceWeight` | `number` | `1` | Weight used to calculate the probability of a voice block occurring ($P = W / (W + 1)$). |
 | `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. |
@@ -50,11 +51,41 @@ Prepares a `MediaContent` object by extracting metadata from an audio source.
     * `metadata`: Optional manual overrides.
     * `parseFile`: Internal helper for file parsing.
     * `callbacks`: Object containing `onProgress` and `onError` handlers.
-    * `convertBase64toBlob`: If true, the image content will be converted directly into a high-performance Blob URL, use this method.
+    * `convertBase64toBlob`: If true, the image content will be converted directly into a high-performance Blob URL.
 * **Returns:** `Promise<MediaContent>`
 * **Throws:** `MediaLoadingError`
 
----
+#### `static get/set unknownArtist(value)`
+Gets or sets the identifier used when an artist cannot be determined.
+* **Value:** A `string` or a `function` that returns a `string`.
+* **Throws:** `TypeError` if the value is not a string or a function.
+
+### 📋 Properties (Getters & Setters)
+
+#### **System State & Lifecycle**
+* `destroyed`: Returns `true` if the instance has been destroyed.
+* `size`: Total count of all content items (music + voice).
+* `seed`: Gets/Sets the core randomness seed.
+* `anchorDate`: Gets the absolute timestamp used as the timeline anchor.
+* `cycleCacheSize`: Returns the number of items currently stored in the cycle cache.
+
+#### **Playlist Access (Returns Deep Clones)**
+* `musicList`: Returns a deep clone of the music playlist.
+* `voiceList`: Returns a deep clone of the voice playlist.
+* `allList`: Returns a deep clone of the combined music and voice playlists.
+* `customPositions`: Returns a deep clone of the custom position injections.
+* `scheduledTasks`: Returns a deep clone of the pending scheduled tasks.
+
+#### **Counters**
+* `musicSize`: Total number of items in the music playlist.
+* `voiceSize`: Total number of items in the voice playlist.
+* `customPosSize`: Number of active custom position injections.
+* `tasksSize`: Number of pending scheduled tasks.
+
+#### **Configuration & Optimization**
+* `config`: Gets/Sets the current `RadioConfig` object.
+* `optimizeMediaMemory`: Gets/Sets whether Blob URLs for media should be converted to Base64 during export.
+* `optimizePictureMemory`: Gets/Sets whether Blob URLs for pictures should be converted to Base64 during export.
 
 ### 📥 Content Management
 
@@ -67,12 +98,10 @@ Adds new content to the engine immediately.
 * **Emits:** `contentAdded`
 
 #### `remove(id)`
-Instantly removes content by its unique ID across all lists, custom positions, and pending tasks. It also revokes associated Blob URLs.
+Instantly removes content by its unique ID across all lists, custom positions, and pending tasks. It also revokes associated Blob URLs to free memory.
 * **Parameters:** `id` (string)
 * **Emits:** `contentRemoved`
 
----
-
 ### 📅 Task & Config Management
 
 #### `scheduleTask(timestamp, action, type, payload, smartQueue = true)`
@@ -90,8 +119,6 @@ Performs a partial or full update of the engine configuration.
 * **Parameters:** `config` (Partial or full `RadioConfig` object).
 * **Emits:** `configChanged`
 
----
-
 ### 🔍 Timeline & Querying
 
 #### `getCurrentEvent()`
@@ -106,7 +133,9 @@ Predicts upcoming events from a specific date forward using a virtual sandbox to
 * **Returns:** `RadioEvent[]`
 * **Throws:** `TypeError` or `RangeError` if limit is invalid.
 
----
+#### `searchCustomPositions()`
+Returns a shallow copy of all active custom positions currently injected into the timeline.
+* **Returns:** `CustomPosition[]`
 
 ### 💾 Persistence & Lifecycle
 
@@ -161,4 +190,4 @@ A structural block representing a single full iteration of the radio sequence.
 * `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.
+* `voiceConsecutiveCount`: Current consecutive count for voice.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.28.17",
+  "version": "1.28.18",
   "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"