tiny-essentials 1.28.16 → 1.28.18

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

@@ -4,6 +4,7 @@ var events = require('events');
 var mediaContent = require('../../basics/mediaContent.cjs');
 var tools = require('../utils/tools.cjs');
 var objChecker = require('../../basics/objChecker.cjs');
+var TinyAdvancedRaffle = require('../math/TinyAdvancedRaffle.cjs');
 
 const checkDestroy = tools.createCheckDestroyed('TinyRadioFm');
 
@@ -85,12 +86,13 @@ const checkDestroy = tools.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).
  */
 
 //////////////////////////////////////////////////////////////////
@@ -358,6 +360,7 @@ class TinyRadioFm extends events.EventEmitter {
     voiceAfterMusic: true,
     voiceMin: 0,
     voiceMax: 1,
+    voiceWeight: 1,
     musicMaxConsecutive: 0,
     musicMinConsecutive: 0,
     voiceMaxConsecutive: 0,
@@ -435,6 +438,7 @@ class TinyRadioFm extends events.EventEmitter {
       }
     };
 
+    checkRange(config.voiceWeight, 'voiceWeight');
     checkRange(config.voiceMin, 'voiceMin');
     checkRange(config.voiceMax, 'voiceMax');
     checkRange(config.musicMinConsecutive, 'musicMinConsecutive');
@@ -992,11 +996,6 @@ class TinyRadioFm extends events.EventEmitter {
       };
     }
 
-    /**
-     * 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);
 
     /**
@@ -1009,6 +1008,30 @@ class TinyRadioFm extends events.EventEmitter {
     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;
@@ -1026,35 +1049,32 @@ class TinyRadioFm extends events.EventEmitter {
         }
       }
 
-      // 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;
+          // 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;
+          }
         }
 
-        const totalWeight = validPool.reduce((sum, item) => sum + item.weight, 0);
+        const drawResult = raffle.drawOne();
 
-        if (totalWeight <= 0) {
-          selectedItem = validPool[0];
-          selectedIndex = pool.findIndex((p) => p.id === selectedItem?.id);
-        } 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;
-            }
+        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
@@ -1065,8 +1085,23 @@ class TinyRadioFm extends events.EventEmitter {
 
       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) {
@@ -1077,6 +1112,8 @@ class TinyRadioFm extends events.EventEmitter {
       }
     }
 
+    raffle.destroy(); // Ensures memory is cleared at the end of each cycle
+
     return { items: sequence, lastId, consecutiveCount };
   }
 
@@ -1146,19 +1183,25 @@ class TinyRadioFm extends events.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/dist/v1/libs/media/TinyRadioFm.d.mts

@@ -121,6 +121,10 @@ export type RadioConfig = {
      * - Whether to play voice messages after music tracks.
      */
     voiceAfterMusic: boolean;
+    /**
+     * - Weight used to calculate the probability of a voice block occurring.
+     */
+    voiceWeight: number;
     /**
      * - Minimum amount of voice messages to play if voiceAfterMusic is true.
      */
@@ -142,7 +146,7 @@ export type RadioConfig = {
      */
     voiceMaxConsecutive: number;
     /**
-     * - Min times a voice track must repeat consecutively (1 = no mandatory repetition).
+     * - Min times a voice track can repeat consecutively (1 = no mandatory repetition).
      */
     voiceMinConsecutive: number;
 };
@@ -285,12 +289,13 @@ export type TinyRadioFmImport = {
  * @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).
  */
 /**
  * An extension of MediaContent that includes temporal boundaries within a generated cycle.

package/dist/v1/libs/media/TinyRadioFm.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"TinyRadioFm.d.mts","sourceRoot":"","sources":["../../../../src/v1/libs/media/TinyRadioFm.mjs"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAcnC,YAAmE,eAAe,GAAxE,OAAO,+BAA+B,EAAE,eAAe,CAAiB;AAClF,YAAoE,gBAAgB,GAA1E,OAAO,+BAA+B,EAAE,gBAAgB,CAAkB;AACpF,YAAyF,oBAAoB,GAAnG,OAAO,+BAA+B,EAAE,oBAAoB,CAAC,eAAe,CAAC,CAAsB;AAC7G,YAAiF,YAAY,GAAnF,OAAO,+BAA+B,EAAE,YAAY,CAAC,eAAe,CAAC,CAAc;AAC7F,YAA4D,QAAQ,GAA1D,OAAO,+BAA+B,EAAE,QAAQ,CAAU;AACpE,YAA+D,WAAW,GAAhE,OAAO,+BAA+B,EAAE,WAAW,CAAa;AAC1E,YAAqE,iBAAiB,GAA5E,OAAO,+BAA+B,EAAE,iBAAiB,CAAmB;AACtF,YAAyE,qBAAqB,GAApF,OAAO,+BAA+B,EAAE,qBAAqB,CAAuB;AAC9F,YAAwE,oBAAoB,GAAlF,OAAO,+BAA+B,EAAE,oBAAoB,CAAsB;AAC5F,YAA6E,yBAAyB,GAA5F,OAAO,+BAA+B,EAAE,yBAAyB,CAA2B;AACtG,YAAuE,mBAAmB,GAAhF,OAAO,+BAA+B,EAAE,mBAAmB,CAAqB;AAO1F,YAAkB,cAAc,GAChC;;;;IAAyB,OAAO,EAArB,YAAY,CACvB;;;;IAAmB,iBAAiB,EAAzB,MAAM,CACjB;;;;IAAmB,iBAAiB,EAAzB,MAAM,CACnB;CAAA,CAAA;AAME,YAAkB,oBAAoB,GACtC;;;;IAAmB,EAAE,EAAV,MAAM,CACjB;;;;IAAmB,QAAQ,EAAhB,MAAM,CACnB;CAAA,CAAA;AAIE,YAAwD,oBAAoB,GAAlE,YAAY,GAAG,MAAM,GAAG,oBAAoB,CAAsB;AAK5E,YAAkB,aAAa,GAC/B;;;;IAAmB,SAAS,EAAjB,MAAM,CACjB;;;;IAAkC,MAAM,EAA7B,KAAK,GAAC,QAAQ,GAAC,MAAM,CAChC;;;;IAA4B,IAAI,EAArB,OAAO,GAAC,OAAO,CAC1B;;;;IAAiC,OAAO,EAA7B,oBAAoB,CACjC;CAAA,CAAA;AAME,YAAkB,UAAU,GAC5B;;;;IAAmB,EAAE,EAAV,MAAM,CACjB;;;;IAAmB,KAAK,EAAb,MAAM,CACjB;;;;IAAmB,MAAM,EAAd,MAAM,CACjB;;;;IAAmB,GAAG,EAAX,MAAM,CACjB;;;;IAAmB,QAAQ,EAAhB,MAAM,CACjB;;;;IAAmB,aAAa,EAArB,MAAM,CACjB;;;;IAAmB,WAAW,EAAnB,MAAM,CACjB;;;;IAAmB,WAAW,EAAnB,MAAM,CACjB;;;;IAAmB,aAAa,EAArB,MAAM,CACjB;;;;IAAmB,QAAQ,EAAhB,MAAM,CACjB;;;;IAAoB,QAAQ,EAAjB,OAAO,CACpB;CAAA,CAAA;AAIE,YAA+B,UAAU,GAA/B,UAAU,GAAC,QAAQ,CAAY;AAKzC,YAAkB,WAAW,GAC7B;;;;IAAuB,IAAI,EAAhB,UAAU,CACrB;;;;IAAuB,SAAS,EAArB,UAAU,CACrB;;;;IAAmB,eAAe,EAAvB,MAAM,CACjB;;;;IAAmB,UAAU,EAAlB,MAAM,CACjB;;;;IAAoB,eAAe,EAAxB,OAAO,CAClB;;;;IAAmB,QAAQ,EAAhB,MAAM,CACjB;;;;IAAmB,QAAQ,EAAhB,MAAM,CACjB;;;;IAAmB,mBAAmB,EAA3B,MAAM,CACjB;;;;IAAmB,mBAAmB,EAA3B,MAAM,CACjB;;;;IAAmB,mBAAmB,EAA3B,MAAM,CACjB;;;;IAAmB,mBAAmB,EAA3B,MAAM,CACnB;CAAA,CAAA;AAME,YAAoE,cAAc,GAAxE,YAAY,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;CAAE,CAAgB;AAKlF,YAAkB,UAAU,GAC5B;;;;IAA6B,KAAK,EAAvB,cAAc,EAAE,CAC3B;;;;IAAmB,QAAQ,EAAhB,MAAM,CACjB;;;;IAAwB,WAAW,EAAxB,MAAM,GAAC,IAAI,CACtB;;;;IAAmB,qBAAqB,EAA7B,MAAM,CACjB;;;;IAAwB,WAAW,EAAxB,MAAM,GAAC,IAAI,CACtB;;;;IAAmB,qBAAqB,EAA7B,MAAM,CACnB;CAAA,CAAA;AAIE,YAAkB,aAAa,GAC/B;;;;IAAuB,KAAK,EAAjB,UAAU,CACrB;;;;IAAmB,cAAc,EAAtB,MAAM,CACjB;;;;IAAmB,SAAS,EAAjB,MAAM,CACnB;CAAA,CAAA;AAME,YAAkB,iBAAiB,GACnC;;;;IAA2B,KAAK,EAArB,YAAY,EAAE,CACzB;;;;IAA2B,KAAK,EAArB,YAAY,EAAE,CACzB;;;;IAA6B,MAAM,EAAxB,cAAc,EAAE,CAC3B;;;;IAA4B,KAAK,EAAtB,aAAa,EAAE,CAC1B;;;;IAAmB,IAAI,EAAZ,MAAM,CACjB;;;;IAAmB,UAAU,EAAlB,MAAM,CACjB;;;;IAAwB,MAAM,EAAnB,WAAW,CACxB;CAAA,CAAA;AA5HD;;;;;;;;;;;;GAYG;AAIH;;;;;;GAMG;AAIH;;;;;GAKG;AAEH;;;GAGG;AAEH;;;;;;;GAOG;AAIH;;;;;;;;;;;;;;GAcG;AAEH;;;GAGG;AAEH;;;;;;;;;;;;;;GAcG;AAIH;;;GAGG;AAEH;;;;;;;;;GASG;AAEH;;;;;;GAMG;AAIH;;;;;;;;;;GAUG;AAIH;;;GAGG;AACH,cAAM,WAAY,SAAQ,YAAY;;IACpC;;;;;;;;;;;;;;OAcG;IACH,OAAa,YAAY,CACvB,MAAM,EAZG,MAAM,GAAG,gBAYZ,EACN,eAAe,AAZd,CACA,EADQ,OAAO,CAAC,gBAAgB,GAAG,oBAAoB,CAAC,GAAG;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAY3E,EACf,QAAQ,AAZP,CACA,EADQ,OAAO,CAAC,gBAAgB,GAAG,oBAAoB,CAAC,GAAG;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAYlF,EACR,SAAS,AAZR,CACA,EADQ,yBAYA,EACT,SAAS,AAZR,CAGA,EAFA;QAA6D,UAAU,AAAvE,CACA,EADQ,CAAC,QAAQ,EAAE,oBAAoB,KAAK,IAAI,CAChD;QAA2D,OAAO,AAAlE,CACA,EADQ,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAC9C;KASQ,EACT,mBAAmB,AAVlB,CACA,EADQ,OAUiB,GATf,OAAO,CAAC,YAAY,CAAC,CAoBjC;IAQD;;;OAGG;IACH,MAAM,KAAK,aAAa,IAFX,mBAAmB,CAI/B;IAED;;;;OAIG;IACH,MAAM,KAAK,aAAa,CAAC,KAAK,EAHnB,mBAGmB,EAI7B;IAKD,IAAI,SAAS,YAEZ;IAED;;;OAGG;IACH,IAAI,IAAI,IAFK,MAAM,CAKlB;IAED;;;OAGG;IACH,IAAI,SAAS,IAFA,MAAM,CAKlB;IAED;;;OAGG;IACH,IAAI,SAAS,IAFA,MAAM,CAKlB;IAED;;;OAGG;IACH,IAAI,aAAa,IAFJ,MAAM,CAKlB;IAED;;;OAGG;IACH,IAAI,SAAS,IAFA,MAAM,CAKlB;IAED;;;OAGG;IACH,IAAI,cAAc,IAFL,MAAM,CAKlB;IAID;;;OAGG;IACH,IAAI,SAAS,IAFA,YAAY,EAAE,CAK1B;IAID;;;OAGG;IACH,IAAI,SAAS,IAFA,YAAY,EAAE,CAK1B;IAID;;;OAGG;IACH,IAAI,eAAe,IAFN,cAAc,EAAE,CAK5B;IAID;;;OAGG;IACH,IAAI,cAAc,IAFL,aAAa,EAAE,CAK3B;IAED;;;OAGG;IACH,IAAI,OAAO,IAFE,YAAY,EAAE,CAK1B;IAID;;;OAGG;IACH,IAAI,IAAI,IAFK,MAAM,CAKlB;IACD;;;OAGG;IACH,IAAI,IAAI,CAAC,IAAI,EAFF,MAEE,EAMZ;IAID;;;OAGG;IACH,IAAI,UAAU,IAFD,MAAM,CAKlB;IAmBD;;;OAGG;IACH,IAAI,MAAM,IAFG,WAAW,CAKvB;IACD;;;;OAIG;IACH,IAAI,MAAM,CAAC,MAAM,EAHN,WAGM,EAQhB;IA+ED;;;;OAIG;IACH,IAAI,mBAAmB,IAFV,OAAO,CAKnB;IAED;;;;OAIG;IACH,IAAI,mBAAmB,CAAC,KAAK,EAHlB,OAGkB,EAI5B;IAKD;;;;OAIG;IACH,IAAI,qBAAqB,IAFZ,OAAO,CAKnB;IAED;;;;OAIG;IACH,IAAI,qBAAqB,CAAC,KAAK,EAHpB,OAGoB,EAI9B;IAED;;;;;OAKG;IACH,YAAY,WAAW,AAJpB,CACA,EADQ,iBAAiB,GAAC,IAIC,EAAE,IAAI,AAHjC,CACA,EADQ,MAG6B,EAcvC;IAID;;;OAGG;IACH,kBAAkB,CAAC,IAAI,EAFZ,YAEY,QA2BtB;IAED;;;OAGG;IACG,kBAAkB,CAAC,IAAI,EAFlB,YAEkB,iBAqB5B;IAED;;;;;;OAMG;IACH,GAAG,CAAC,IAAI,EALG,OAAO,GAAC,OAAO,GAAC,QAKnB,EAAE,IAAI,EAJH,YAAY,GAAG;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAIhC,EAAE,UAAU,AAHvB,CACA,EADQ,OAGsB,QA6BhC;IAED;;;;;;;;OAQG;IACH,YAAY,CAAC,SAAS,EAPX,MAOW,EAAE,MAAM,EANnB,KAAK,GAAC,QAAQ,GAAC,MAMI,EAAE,IAAI,EALzB,OAAO,GAAC,OAKiB,EAAE,OAAO,EAJlC,oBAIkC,EAAE,UAAU,AAHtD,CACA,EADQ,OAGqD,QAmE/D;IAED;;;;OAIG;IACH,MAAM,CAAC,EAAE,EAHE,MAGF,QAuCR;IAED;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAHL,OAAO,CAAC,WAAW,CAGd,QAcf;IAED;;;OAGG;IACH,eAAe,IAFF,UAAU,GAAC,IAAI,CAO3B;IAED;;;;;;;;OAQG;IACH,aAAa,CAAC,UAAU,EANb,MAMa,EAAE,KAAK,AAL5B,CACA,EADQ,MAKyB,GAJvB,UAAU,EAAE,CAmCxB;IAED;;;OAGG;IACH,qBAAqB,IAFR,cAAc,EAAE,CAM5B;IAED;;;;;OAKG;YACG,qBAAqB;IAW3B;;;;OAIG;YACH,YAAY;IAYZ;;;OAGG;IACG,WAAW,IAFJ,OAAO,CAAC,MAAM,CAAC,CAwC3B;IAED;;;;OAIG;IACH,WAAW,CAAC,IAAI,EAHL,MAAM,GAAC,iBAGF,QAkBf;IAED;;;;;OAKG;YACH,KAAK;IA0lBL;;;;OAIG;IACH,OAAO,CAAC,aAAa,AAFlB,CAAqC,EAA7B,OAEiB,QA4B3B;CACF;eAEc,WAAW"}
+{"version":3,"file":"TinyRadioFm.d.mts","sourceRoot":"","sources":["../../../../src/v1/libs/media/TinyRadioFm.mjs"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAenC,YAAmE,eAAe,GAAxE,OAAO,+BAA+B,EAAE,eAAe,CAAiB;AAClF,YAAoE,gBAAgB,GAA1E,OAAO,+BAA+B,EAAE,gBAAgB,CAAkB;AACpF,YAAyF,oBAAoB,GAAnG,OAAO,+BAA+B,EAAE,oBAAoB,CAAC,eAAe,CAAC,CAAsB;AAC7G,YAAiF,YAAY,GAAnF,OAAO,+BAA+B,EAAE,YAAY,CAAC,eAAe,CAAC,CAAc;AAC7F,YAA4D,QAAQ,GAA1D,OAAO,+BAA+B,EAAE,QAAQ,CAAU;AACpE,YAA+D,WAAW,GAAhE,OAAO,+BAA+B,EAAE,WAAW,CAAa;AAC1E,YAAqE,iBAAiB,GAA5E,OAAO,+BAA+B,EAAE,iBAAiB,CAAmB;AACtF,YAAyE,qBAAqB,GAApF,OAAO,+BAA+B,EAAE,qBAAqB,CAAuB;AAC9F,YAAwE,oBAAoB,GAAlF,OAAO,+BAA+B,EAAE,oBAAoB,CAAsB;AAC5F,YAA6E,yBAAyB,GAA5F,OAAO,+BAA+B,EAAE,yBAAyB,CAA2B;AACtG,YAAuE,mBAAmB,GAAhF,OAAO,+BAA+B,EAAE,mBAAmB,CAAqB;AAO1F,YAAkB,cAAc,GAChC;;;;IAAyB,OAAO,EAArB,YAAY,CACvB;;;;IAAmB,iBAAiB,EAAzB,MAAM,CACjB;;;;IAAmB,iBAAiB,EAAzB,MAAM,CACnB;CAAA,CAAA;AAME,YAAkB,oBAAoB,GACtC;;;;IAAmB,EAAE,EAAV,MAAM,CACjB;;;;IAAmB,QAAQ,EAAhB,MAAM,CACnB;CAAA,CAAA;AAIE,YAAwD,oBAAoB,GAAlE,YAAY,GAAG,MAAM,GAAG,oBAAoB,CAAsB;AAK5E,YAAkB,aAAa,GAC/B;;;;IAAmB,SAAS,EAAjB,MAAM,CACjB;;;;IAAkC,MAAM,EAA7B,KAAK,GAAC,QAAQ,GAAC,MAAM,CAChC;;;;IAA4B,IAAI,EAArB,OAAO,GAAC,OAAO,CAC1B;;;;IAAiC,OAAO,EAA7B,oBAAoB,CACjC;CAAA,CAAA;AAME,YAAkB,UAAU,GAC5B;;;;IAAmB,EAAE,EAAV,MAAM,CACjB;;;;IAAmB,KAAK,EAAb,MAAM,CACjB;;;;IAAmB,MAAM,EAAd,MAAM,CACjB;;;;IAAmB,GAAG,EAAX,MAAM,CACjB;;;;IAAmB,QAAQ,EAAhB,MAAM,CACjB;;;;IAAmB,aAAa,EAArB,MAAM,CACjB;;;;IAAmB,WAAW,EAAnB,MAAM,CACjB;;;;IAAmB,WAAW,EAAnB,MAAM,CACjB;;;;IAAmB,aAAa,EAArB,MAAM,CACjB;;;;IAAmB,QAAQ,EAAhB,MAAM,CACjB;;;;IAAoB,QAAQ,EAAjB,OAAO,CACpB;CAAA,CAAA;AAIE,YAA+B,UAAU,GAA/B,UAAU,GAAC,QAAQ,CAAY;AAKzC,YAAkB,WAAW,GAC7B;;;;IAAuB,IAAI,EAAhB,UAAU,CACrB;;;;IAAuB,SAAS,EAArB,UAAU,CACrB;;;;IAAmB,eAAe,EAAvB,MAAM,CACjB;;;;IAAmB,UAAU,EAAlB,MAAM,CACjB;;;;IAAoB,eAAe,EAAxB,OAAO,CAClB;;;;IAAmB,WAAW,EAAnB,MAAM,CACjB;;;;IAAmB,QAAQ,EAAhB,MAAM,CACjB;;;;IAAmB,QAAQ,EAAhB,MAAM,CACjB;;;;IAAmB,mBAAmB,EAA3B,MAAM,CACjB;;;;IAAmB,mBAAmB,EAA3B,MAAM,CACjB;;;;IAAmB,mBAAmB,EAA3B,MAAM,CACjB;;;;IAAmB,mBAAmB,EAA3B,MAAM,CACnB;CAAA,CAAA;AAME,YAAoE,cAAc,GAAxE,YAAY,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;CAAE,CAAgB;AAKlF,YAAkB,UAAU,GAC5B;;;;IAA6B,KAAK,EAAvB,cAAc,EAAE,CAC3B;;;;IAAmB,QAAQ,EAAhB,MAAM,CACjB;;;;IAAwB,WAAW,EAAxB,MAAM,GAAC,IAAI,CACtB;;;;IAAmB,qBAAqB,EAA7B,MAAM,CACjB;;;;IAAwB,WAAW,EAAxB,MAAM,GAAC,IAAI,CACtB;;;;IAAmB,qBAAqB,EAA7B,MAAM,CACnB;CAAA,CAAA;AAIE,YAAkB,aAAa,GAC/B;;;;IAAuB,KAAK,EAAjB,UAAU,CACrB;;;;IAAmB,cAAc,EAAtB,MAAM,CACjB;;;;IAAmB,SAAS,EAAjB,MAAM,CACnB;CAAA,CAAA;AAME,YAAkB,iBAAiB,GACnC;;;;IAA2B,KAAK,EAArB,YAAY,EAAE,CACzB;;;;IAA2B,KAAK,EAArB,YAAY,EAAE,CACzB;;;;IAA6B,MAAM,EAAxB,cAAc,EAAE,CAC3B;;;;IAA4B,KAAK,EAAtB,aAAa,EAAE,CAC1B;;;;IAAmB,IAAI,EAAZ,MAAM,CACjB;;;;IAAmB,UAAU,EAAlB,MAAM,CACjB;;;;IAAwB,MAAM,EAAnB,WAAW,CACxB;CAAA,CAAA;AA7HD;;;;;;;;;;;;GAYG;AAIH;;;;;;GAMG;AAIH;;;;;GAKG;AAEH;;;GAGG;AAEH;;;;;;;GAOG;AAIH;;;;;;;;;;;;;;GAcG;AAEH;;;GAGG;AAEH;;;;;;;;;;;;;;;GAeG;AAIH;;;GAGG;AAEH;;;;;;;;;GASG;AAEH;;;;;;GAMG;AAIH;;;;;;;;;;GAUG;AAIH;;;GAGG;AACH,cAAM,WAAY,SAAQ,YAAY;;IACpC;;;;;;;;;;;;;;OAcG;IACH,OAAa,YAAY,CACvB,MAAM,EAZG,MAAM,GAAG,gBAYZ,EACN,eAAe,AAZd,CACA,EADQ,OAAO,CAAC,gBAAgB,GAAG,oBAAoB,CAAC,GAAG;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAY3E,EACf,QAAQ,AAZP,CACA,EADQ,OAAO,CAAC,gBAAgB,GAAG,oBAAoB,CAAC,GAAG;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAYlF,EACR,SAAS,AAZR,CACA,EADQ,yBAYA,EACT,SAAS,AAZR,CAGA,EAFA;QAA6D,UAAU,AAAvE,CACA,EADQ,CAAC,QAAQ,EAAE,oBAAoB,KAAK,IAAI,CAChD;QAA2D,OAAO,AAAlE,CACA,EADQ,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAC9C;KASQ,EACT,mBAAmB,AAVlB,CACA,EADQ,OAUiB,GATf,OAAO,CAAC,YAAY,CAAC,CAoBjC;IAQD;;;OAGG;IACH,MAAM,KAAK,aAAa,IAFX,mBAAmB,CAI/B;IAED;;;;OAIG;IACH,MAAM,KAAK,aAAa,CAAC,KAAK,EAHnB,mBAGmB,EAI7B;IAKD,IAAI,SAAS,YAEZ;IAED;;;OAGG;IACH,IAAI,IAAI,IAFK,MAAM,CAKlB;IAED;;;OAGG;IACH,IAAI,SAAS,IAFA,MAAM,CAKlB;IAED;;;OAGG;IACH,IAAI,SAAS,IAFA,MAAM,CAKlB;IAED;;;OAGG;IACH,IAAI,aAAa,IAFJ,MAAM,CAKlB;IAED;;;OAGG;IACH,IAAI,SAAS,IAFA,MAAM,CAKlB;IAED;;;OAGG;IACH,IAAI,cAAc,IAFL,MAAM,CAKlB;IAID;;;OAGG;IACH,IAAI,SAAS,IAFA,YAAY,EAAE,CAK1B;IAID;;;OAGG;IACH,IAAI,SAAS,IAFA,YAAY,EAAE,CAK1B;IAID;;;OAGG;IACH,IAAI,eAAe,IAFN,cAAc,EAAE,CAK5B;IAID;;;OAGG;IACH,IAAI,cAAc,IAFL,aAAa,EAAE,CAK3B;IAED;;;OAGG;IACH,IAAI,OAAO,IAFE,YAAY,EAAE,CAK1B;IAID;;;OAGG;IACH,IAAI,IAAI,IAFK,MAAM,CAKlB;IACD;;;OAGG;IACH,IAAI,IAAI,CAAC,IAAI,EAFF,MAEE,EAMZ;IAID;;;OAGG;IACH,IAAI,UAAU,IAFD,MAAM,CAKlB;IAoBD;;;OAGG;IACH,IAAI,MAAM,IAFG,WAAW,CAKvB;IACD;;;;OAIG;IACH,IAAI,MAAM,CAAC,MAAM,EAHN,WAGM,EAQhB;IAgFD;;;;OAIG;IACH,IAAI,mBAAmB,IAFV,OAAO,CAKnB;IAED;;;;OAIG;IACH,IAAI,mBAAmB,CAAC,KAAK,EAHlB,OAGkB,EAI5B;IAKD;;;;OAIG;IACH,IAAI,qBAAqB,IAFZ,OAAO,CAKnB;IAED;;;;OAIG;IACH,IAAI,qBAAqB,CAAC,KAAK,EAHpB,OAGoB,EAI9B;IAED;;;;;OAKG;IACH,YAAY,WAAW,AAJpB,CACA,EADQ,iBAAiB,GAAC,IAIC,EAAE,IAAI,AAHjC,CACA,EADQ,MAG6B,EAcvC;IAID;;;OAGG;IACH,kBAAkB,CAAC,IAAI,EAFZ,YAEY,QA2BtB;IAED;;;OAGG;IACG,kBAAkB,CAAC,IAAI,EAFlB,YAEkB,iBAqB5B;IAED;;;;;;OAMG;IACH,GAAG,CAAC,IAAI,EALG,OAAO,GAAC,OAAO,GAAC,QAKnB,EAAE,IAAI,EAJH,YAAY,GAAG;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAIhC,EAAE,UAAU,AAHvB,CACA,EADQ,OAGsB,QA6BhC;IAED;;;;;;;;OAQG;IACH,YAAY,CAAC,SAAS,EAPX,MAOW,EAAE,MAAM,EANnB,KAAK,GAAC,QAAQ,GAAC,MAMI,EAAE,IAAI,EALzB,OAAO,GAAC,OAKiB,EAAE,OAAO,EAJlC,oBAIkC,EAAE,UAAU,AAHtD,CACA,EADQ,OAGqD,QAmE/D;IAED;;;;OAIG;IACH,MAAM,CAAC,EAAE,EAHE,MAGF,QAuCR;IAED;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAHL,OAAO,CAAC,WAAW,CAGd,QAcf;IAED;;;OAGG;IACH,eAAe,IAFF,UAAU,GAAC,IAAI,CAO3B;IAED;;;;;;;;OAQG;IACH,aAAa,CAAC,UAAU,EANb,MAMa,EAAE,KAAK,AAL5B,CACA,EADQ,MAKyB,GAJvB,UAAU,EAAE,CAmCxB;IAED;;;OAGG;IACH,qBAAqB,IAFR,cAAc,EAAE,CAM5B;IAED;;;;;OAKG;YACG,qBAAqB;IAW3B;;;;OAIG;YACH,YAAY;IAYZ;;;OAGG;IACG,WAAW,IAFJ,OAAO,CAAC,MAAM,CAAC,CAwC3B;IAED;;;;OAIG;IACH,WAAW,CAAC,IAAI,EAHL,MAAM,GAAC,iBAGF,QAkBf;IAED;;;;;OAKG;YACH,KAAK;IAioBL;;;;OAIG;IACH,OAAO,CAAC,aAAa,AAFlB,CAAqC,EAA7B,OAEiB,QA4B3B;CACF;eAEc,WAAW"}

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/Exports.md

@@ -60,6 +60,7 @@ Direct access to smaller utilities:
 * `basics/text`
 * `basics/promiseUtils`
 * `basics/browserDetector`
+* `basics/jsonFilter`
 
 Direct access to file utilities:
 
@@ -229,11 +230,11 @@ Each library can be imported separately:
 **ESM (modern projects)**
 
 ```js
-import { TinyTextarea } from "tiny-essentials/libs/text/TinyTextarea";
+import TinyTextarea from "tiny-essentials/libs/text/TinyTextarea";
 ```
 
 **CommonJS (Node.js)**
 
 ```js
-const { TinyTextarea } = require("tiny-essentials/libs/text/TinyTextarea");
+const { shuffleArray } = require("tiny-essentials/basics/array");
 ```

package/docs/v1/README.md

@@ -13,6 +13,7 @@ Here, you can navigate through different sections of the project. Below are the
 - 📦 **[Array](./basics/array.md)** — A tiny utility for shuffling arrays using the Fisher–Yates algorithm.
 - ⏰ **[Clock](./basics/clock.md)** — A versatile time utility module for calculating and formatting time durations.
 - 🧠 **[ObjFilter](./basics/objFilter.md)** — Type detection, extension, and analysis made easy with simple and extensible type validation.
+- 🔍 **[jsonFilter](./basics/jsonFilter.md)** — High-precision utilities for filtering objects, arrays, and complex data structures like Maps and Sets.
 * 🧮 **[objChecker](./basics/objChecker.md)** — Utilities for counting keys in objects or arrays and for safely detecting plain JSON-compatible objects.
 - 🔢 **[SimpleMath](./basics/simpleMath.md)** — A collection of simple math utilities for calculations like the Rule of Three and percentages.
 - ✍️ **[Text](./basics/text.md)** — A utility for transforming text into title case formats, with multiple options for capitalization.
@@ -178,4 +179,4 @@ If you're curious about how I integrate AI into my development workflow — incl
 
 ✨ **Visit the Tiny-Essentials documentation hub here:**
 
-👉 [https://github.com/Tiny-Essentials/.github/tree/main/docs](https://github.com/Tiny-Essentials/.github/tree/main/docs)
+👉 [https://github.com/Tiny-Essentials/Tiny-AI-Workflow](https://github.com/Tiny-Essentials/Tiny-AI-Workflow)