@xiboplayer/schedule 0.5.5 → 0.5.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiboplayer/schedule",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "Complete scheduling solution: campaigns, dayparting, interrupts, and overlays",
   "type": "module",
   "main": "./src/index.js",
@@ -11,7 +11,7 @@
     "./overlays": "./src/overlays.js"
   },
   "dependencies": {
-    "@xiboplayer/utils": "0.5.5"
+    "@xiboplayer/utils": "0.5.7"
   },
   "devDependencies": {
     "vitest": "^2.0.0"

package/src/index.js

@@ -25,4 +25,4 @@ export { OverlayScheduler } from './overlays.js';
  * Offline timeline calculator — duration parser + timeline simulator
  * @module @xiboplayer/schedule/timeline
  */
-export { calculateTimeline, parseLayoutDuration } from './timeline.js';
+export { calculateTimeline, parseLayoutDuration, buildScheduleQueue } from './timeline.js';

package/src/schedule.js

@@ -4,6 +4,7 @@
 
 import { createLogger } from '@xiboplayer/utils';
 import { evaluateCriteria } from './criteria.js';
+import { buildScheduleQueue } from './timeline.js';
 
 const log = createLogger('Schedule');
 
@@ -16,6 +17,11 @@ export class ScheduleManager {
     this.weatherData = {}; // Weather data from GetWeather XMDS call
     this.playerLocation = null; // { latitude, longitude } from Geolocation API
     this._layoutMetadata = new Map(); // layoutFile → { syncEvent, shareOfVoice, ... }
+
+    // Pre-calculated schedule queue (LCM-based deterministic timeline)
+    this._scheduleQueue = null;      // { queue: [{layoutId, duration}], periodSeconds }
+    this._queuePosition = 0;         // Current position in the queue
+    this._queueLayoutSet = null;     // Stringified active layout set (for invalidation)
   }
 
   /**
@@ -23,6 +29,7 @@ export class ScheduleManager {
    */
   setSchedule(schedule) {
     this.schedule = schedule;
+    this._invalidateQueue();
   }
 
   /**
@@ -606,42 +613,102 @@ export class ScheduleManager {
   }
 
   /**
-   * Get current layouts with the default layout interleaved between scheduled layouts.
+   * Get (or build) the deterministic schedule queue.
    *
-   * Xibo CMS expects the default layout (fallback) to play between each scheduled
-   * layout in the rotation. For example, with layouts [A, B, C] and default D,
-   * the result is [A, D, B, D, C, D].
+   * Uses LCM-based even distribution to pre-calculate a repeating cycle where
+   * each rate-limited layout plays at evenly spaced intervals and gaps are
+   * filled by unlimited layouts and the CMS default.
    *
-   * No interleaving when:
-   * - There is no default layout configured
-   * - There are no scheduled layouts (only default plays)
-   * - There is only one scheduled layout (no gaps to fill)
+   * The queue is cached and only rebuilt when:
+   * - The schedule changes (setSchedule)
+   * - The active layout set changes (time boundary crossed)
+   * - durations are updated
    *
-   * @returns {string[]} Layout files with default interleaved
+   * @param {Map<string, number>} durations - layoutFile → duration in seconds
+   * @param {Object} [options]
+   * @param {Set<string>} [options.dynamicLayouts] - Set of layout files with useDuration=0
+   * @returns {{ queue: Array<{layoutId: string, duration: number}>, periodSeconds: number }}
    */
-  getInterleavedLayouts() {
-    const layouts = this.getCurrentLayouts();
-    const defaultLayout = this.schedule?.default;
+  getScheduleQueue(durations, options = {}) {
+    const allLayouts = this.getAllLayoutsAtTime(new Date());
+    const layoutSetKey = allLayouts.map(l => `${l.file}:${l.priority}:${l.maxPlaysPerHour}`).sort().join('|');
 
-    // No interleaving needed: no default, no layouts, or single layout
-    if (!defaultLayout || layouts.length <= 1) {
-      return layouts;
+    // Return cached queue if the active layout set hasn't changed
+    if (this._scheduleQueue && this._queueLayoutSet === layoutSetKey) {
+      return this._scheduleQueue;
     }
 
-    // If the only layout is the default itself, return as-is
-    if (layouts.length === 1 && layouts[0] === defaultLayout) {
-      return layouts;
-    }
+    const result = buildScheduleQueue(allLayouts, durations, {
+      defaultLayout: this.schedule?.default || null,
+      defaultDuration: 60,
+      dynamicLayouts: options.dynamicLayouts || new Set(),
+    });
+
+    this._scheduleQueue = result;
+    this._queueLayoutSet = layoutSetKey;
+    // Reset position when queue is rebuilt
+    this._queuePosition = 0;
 
-    // Interleave: A, D, B, D, C, D
-    const interleaved = [];
-    for (const layout of layouts) {
-      interleaved.push(layout);
-      interleaved.push(defaultLayout);
+    if (result.queue.length > 0) {
+      log.info(`[Schedule] Built queue: ${result.queue.length} entries, period ${result.periodSeconds}s`);
+      log.info(`[Schedule] Queue: ${result.queue.map(e => `${e.layoutId}(${e.duration}s)`).join(' → ')}`);
     }
 
-    log.info('[Schedule] Interleaved', layouts.length, 'layouts with default', defaultLayout);
-    return interleaved;
+    return result;
+  }
+
+  /**
+   * Pop the next entry from the schedule queue.
+   * Wraps around at the end (the LCM period guarantees the pattern repeats).
+   *
+   * @param {Map<string, number>} durations - layoutFile → duration in seconds
+   * @param {Object} [options]
+   * @param {Set<string>} [options.dynamicLayouts] - Dynamic layout set
+   * @returns {{ layoutId: string, duration: number } | null}
+   */
+  popNextFromQueue(durations, options = {}) {
+    const { queue } = this.getScheduleQueue(durations, options);
+    if (queue.length === 0) return null;
+
+    const entry = queue[this._queuePosition % queue.length];
+    this._queuePosition = (this._queuePosition + 1) % queue.length;
+    return entry;
+  }
+
+  /**
+   * Peek at the next entry in the schedule queue without advancing.
+   *
+   * @param {Map<string, number>} durations - layoutFile → duration in seconds
+   * @param {Object} [options]
+   * @returns {{ layoutId: string, duration: number } | null}
+   */
+  peekNextInQueue(durations, options = {}) {
+    const { queue } = this.getScheduleQueue(durations, options);
+    if (queue.length === 0) return null;
+    return queue[this._queuePosition % queue.length];
+  }
+
+  /**
+   * Peek at the entry after the current one (two positions ahead).
+   * Used for preloading.
+   *
+   * @param {Map<string, number>} durations
+   * @param {Object} [options]
+   * @returns {{ layoutId: string, duration: number } | null}
+   */
+  peekAfterNext(durations, options = {}) {
+    const { queue } = this.getScheduleQueue(durations, options);
+    if (queue.length <= 1) return null;
+    return queue[(this._queuePosition + 1) % queue.length];
+  }
+
+  /**
+   * Invalidate the cached queue (called on schedule change, time boundaries, etc.)
+   */
+  _invalidateQueue() {
+    this._scheduleQueue = null;
+    this._queueLayoutSet = null;
+    this._queuePosition = 0;
   }
 
   /**

package/src/schedule.test.js

@@ -196,107 +196,150 @@ describe('ScheduleManager - Campaigns', () => {
   });
 });
 
-describe('ScheduleManager - Default Layout Interleaving', () => {
+describe('ScheduleManager - Schedule Queue (LCM-based)', () => {
   let manager;
+  const durations = new Map();
 
   beforeEach(() => {
     manager = new ScheduleManager();
+    durations.clear();
+    durations.set('100', 60);
+    durations.set('200', 60);
+    durations.set('300', 60);
+    durations.set('999', 60);
   });
 
-  it('should interleave default layout between multiple scheduled layouts', () => {
+  it('should build a queue with unlimited layouts and default', () => {
     manager.setSchedule({
       default: '999',
       layouts: [
         { file: '100', priority: 10, fromdt: dateStr(-1), todt: dateStr(1) },
         { file: '200', priority: 10, fromdt: dateStr(-1), todt: dateStr(1) },
-        { file: '300', priority: 10, fromdt: dateStr(-1), todt: dateStr(1) }
       ],
       campaigns: []
     });
 
-    const layouts = manager.getInterleavedLayouts();
+    const { queue } = manager.getScheduleQueue(durations);
 
-    expect(layouts).toEqual(['100', '999', '200', '999', '300', '999']);
+    // Should include all layouts
+    expect(queue.length).toBeGreaterThan(0);
+    const layoutIds = queue.map(e => e.layoutId);
+    expect(layoutIds).toContain('100');
+    expect(layoutIds).toContain('200');
   });
 
-  it('should not interleave when only default layout is active', () => {
+  it('should return only default when no layouts are scheduled', () => {
     manager.setSchedule({
       default: '999',
       layouts: [],
       campaigns: []
     });
 
-    const layouts = manager.getInterleavedLayouts();
+    const { queue } = manager.getScheduleQueue(durations);
 
-    expect(layouts).toEqual(['999']);
+    expect(queue).toHaveLength(1);
+    expect(queue[0].layoutId).toBe('999');
   });
 
-  it('should not interleave when only one scheduled layout', () => {
+  it('should return empty queue when no schedule set', () => {
+    const { queue } = manager.getScheduleQueue(durations);
+
+    expect(queue).toEqual([]);
+  });
+
+  it('should place rate-limited layouts at even intervals', () => {
+    durations.set('472', 219);
     manager.setSchedule({
       default: '999',
       layouts: [
-        { file: '100', priority: 10, fromdt: dateStr(-1), todt: dateStr(1) }
+        { file: '472', priority: 10, maxPlaysPerHour: 3, fromdt: dateStr(-1), todt: dateStr(1) },
       ],
       campaigns: []
     });
 
-    const layouts = manager.getInterleavedLayouts();
+    const { queue, periodSeconds } = manager.getScheduleQueue(durations);
 
-    expect(layouts).toEqual(['100']);
+    // With maxPlaysPerHour=3, interval=1200s, LCM=1200s
+    expect(periodSeconds).toBe(1200);
+    // Should have exactly 1 play of 472 in a 1200s period
+    const plays472 = queue.filter(e => e.layoutId === '472');
+    expect(plays472).toHaveLength(1);
+    // Gaps filled by default
+    const defaultPlays = queue.filter(e => e.layoutId === '999');
+    expect(defaultPlays.length).toBeGreaterThan(0);
   });
 
-  it('should preserve layout order when interleaving', () => {
+  it('should pop entries in order and wrap around', () => {
     manager.setSchedule({
       default: '999',
-      layouts: [],
-      campaigns: [
-        {
-          id: '1',
-          priority: 10,
-          fromdt: dateStr(-1),
-          todt: dateStr(1),
-          layouts: [
-            { file: '205' },
-            { file: '203' },
-            { file: '204' }
-          ]
-        }
-      ]
+      layouts: [
+        { file: '100', priority: 10, fromdt: dateStr(-1), todt: dateStr(1) },
+        { file: '200', priority: 10, fromdt: dateStr(-1), todt: dateStr(1) },
+      ],
+      campaigns: []
     });
 
-    const layouts = manager.getInterleavedLayouts();
-
-    // Order must be preserved: 205, default, 203, default, 204, default
-    expect(layouts).toEqual(['205', '999', '203', '999', '204', '999']);
-  });
+    const { queue } = manager.getScheduleQueue(durations);
+    const firstPop = manager.popNextFromQueue(durations);
+    const secondPop = manager.popNextFromQueue(durations);
 
-  it('should return empty array when no schedule is set', () => {
-    const layouts = manager.getInterleavedLayouts();
+    expect(firstPop.layoutId).toBe(queue[0].layoutId);
+    expect(secondPop.layoutId).toBe(queue[1].layoutId);
 
-    expect(layouts).toEqual([]);
+    // Pop through entire queue to test wrap-around
+    for (let i = 2; i < queue.length; i++) {
+      manager.popNextFromQueue(durations);
+    }
+    const wrapped = manager.popNextFromQueue(durations);
+    expect(wrapped.layoutId).toBe(queue[0].layoutId);
   });
 
-  it('should not interleave when no default layout is configured', () => {
+  it('should invalidate queue on schedule change', () => {
     manager.setSchedule({
+      default: '999',
       layouts: [
         { file: '100', priority: 10, fromdt: dateStr(-1), todt: dateStr(1) },
-        { file: '200', priority: 10, fromdt: dateStr(-1), todt: dateStr(1) }
       ],
       campaigns: []
     });
 
-    const layouts = manager.getInterleavedLayouts();
+    manager.popNextFromQueue(durations); // advance position
 
-    // No default, so no interleaving — just the scheduled layouts
-    expect(layouts).toEqual(['100', '200']);
+    // Change schedule — should reset
+    manager.setSchedule({
+      default: '999',
+      layouts: [
+        { file: '200', priority: 10, fromdt: dateStr(-1), todt: dateStr(1) },
+      ],
+      campaigns: []
+    });
+
+    const { queue } = manager.getScheduleQueue(durations);
+    expect(queue.map(e => e.layoutId)).toContain('200');
+    expect(queue.map(e => e.layoutId)).not.toContain('100');
   });
 
-  it('should interleave with campaign and standalone layouts at same priority', () => {
+  it('should cache queue and return same result for unchanged schedule', () => {
     manager.setSchedule({
       default: '999',
       layouts: [
-        { file: '100', priority: 10, fromdt: dateStr(-1), todt: dateStr(1) }
+        { file: '100', priority: 10, fromdt: dateStr(-1), todt: dateStr(1) },
       ],
+      campaigns: []
+    });
+
+    const result1 = manager.getScheduleQueue(durations);
+    const result2 = manager.getScheduleQueue(durations);
+
+    expect(result1).toBe(result2); // Same reference (cached)
+  });
+
+  it('should include campaign layouts in queue', () => {
+    durations.set('205', 60);
+    durations.set('203', 60);
+    manager.setSchedule({
+      default: '999',
+      layouts: [],
       campaigns: [
         {
           id: '1',
@@ -304,21 +347,17 @@ describe('ScheduleManager - Default Layout Interleaving', () => {
           fromdt: dateStr(-1),
           todt: dateStr(1),
           layouts: [
-            { file: '200' },
-            { file: '201' }
+            { file: '205' },
+            { file: '203' },
           ]
         }
       ]
     });
 
-    const layouts = manager.getInterleavedLayouts();
-
-    // 3 scheduled layouts + 3 default insertions = 6
-    expect(layouts).toHaveLength(6);
-    // Every odd-indexed element should be the default
-    expect(layouts[1]).toBe('999');
-    expect(layouts[3]).toBe('999');
-    expect(layouts[5]).toBe('999');
+    const { queue } = manager.getScheduleQueue(durations);
+    const layoutIds = queue.map(e => e.layoutId);
+    expect(layoutIds).toContain('205');
+    expect(layoutIds).toContain('203');
   });
 });
 

package/src/timeline.js

@@ -16,19 +16,20 @@
  *  3. Fallback: 60s
  *
  * @param {string} xlfXml - Raw XLF XML string
- * @returns {number} Duration in seconds
+ * @returns {{ duration: number, isDynamic: boolean }} Duration in seconds and whether any widget has useDuration=0
  */
 export function parseLayoutDuration(xlfXml) {
   const doc = new DOMParser().parseFromString(xlfXml, 'text/xml');
   const layoutEl = doc.querySelector('layout');
-  if (!layoutEl) return 60;
+  if (!layoutEl) return { duration: 60, isDynamic: false };
 
   // 1. Explicit layout duration attribute
   const explicit = parseInt(layoutEl.getAttribute('duration') || '0', 10);
-  if (explicit > 0) return explicit;
+  if (explicit > 0) return { duration: explicit, isDynamic: false };
 
   // 2. Calculate from widget durations (max region wins — regions play in parallel)
   let maxDuration = 0;
+  let isDynamic = false;
   for (const regionEl of layoutEl.querySelectorAll('region')) {
     let regionDuration = 0;
     for (const mediaEl of regionEl.querySelectorAll('media')) {
@@ -40,12 +41,14 @@ export function parseLayoutDuration(xlfXml) {
         // Video with useDuration=0 means "play to end" — estimate 60s,
         // corrected later via recordLayoutDuration() when video metadata loads
         regionDuration += 60;
+        isDynamic = true;
       }
     }
     maxDuration = Math.max(maxDuration, regionDuration);
   }
 
-  return maxDuration > 0 ? maxDuration : 60;
+  const duration = maxDuration > 0 ? maxDuration : 60;
+  return { duration, isDynamic };
 }
 
 /**
@@ -267,3 +270,136 @@ export function calculateTimeline(schedule, durations, options = {}) {
 
   return timeline;
 }
+
+// ── LCM-based deterministic schedule queue ──────────────────────────────
+
+/**
+ * Greatest common divisor (Euclidean algorithm).
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+function gcd(a, b) {
+  a = Math.abs(Math.round(a));
+  b = Math.abs(Math.round(b));
+  while (b) { [a, b] = [b, a % b]; }
+  return a;
+}
+
+/**
+ * Least common multiple of two integers.
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+function lcm(a, b) {
+  if (a === 0 || b === 0) return 0;
+  return Math.abs(Math.round(a) * Math.round(b)) / gcd(a, b);
+}
+
+/**
+ * LCM of an array of integers.
+ * @param {number[]} values
+ * @returns {number}
+ */
+function lcmArray(values) {
+  return values.reduce((acc, v) => lcm(acc, v), 1);
+}
+
+/**
+ * Build a deterministic playback queue by simulating one LCM period.
+ *
+ * Uses getPlayableLayouts() (the same priority-fallback + rate-limit logic
+ * that calculateTimeline uses) to simulate playback for one repeating cycle.
+ * This ensures the queue matches the timeline overlay exactly: high-priority
+ * rate-limited layouts get their slots, then lower-priority layouts fill gaps.
+ *
+ * @param {Array<{file: string, priority: number, maxPlaysPerHour: number}>} allLayouts
+ *   All time-active layouts from schedule.getAllLayoutsAtTime()
+ * @param {Map<string, number>} durations
+ *   Map of layoutFile → duration in seconds
+ * @param {Object} [options]
+ * @param {string}  [options.defaultLayout] - Default layout file (CMS fallback)
+ * @param {number}  [options.defaultDuration] - Fallback duration (default: 60)
+ * @param {Set<string>} [options.dynamicLayouts] - Set of layout files that are dynamic (video, useDuration=0)
+ * @returns {{ queue: Array<{layoutId: string, duration: number}>, periodSeconds: number }}
+ */
+export function buildScheduleQueue(allLayouts, durations, options = {}) {
+  const {
+    defaultLayout = null,
+    defaultDuration = 60,
+  } = options;
+
+  if (allLayouts.length === 0 && !defaultLayout) {
+    return { queue: [], periodSeconds: 0 };
+  }
+
+  // Step 1: Identify rate-limited layouts to calculate LCM period
+  const rateLimited = allLayouts.filter(l => l.maxPlaysPerHour > 0);
+
+  let periodSeconds;
+  if (rateLimited.length > 0) {
+    const intervals = rateLimited.map(l => Math.round(3600 / l.maxPlaysPerHour));
+    periodSeconds = lcmArray(intervals);
+    // Cap at 2 hours to prevent absurd periods
+    if (periodSeconds > 7200) periodSeconds = 7200;
+  } else {
+    // No rate-limited layouts — single round-robin cycle
+    const totalDuration = allLayouts.reduce((sum, l) => sum + (durations.get(l.file) || defaultDuration), 0)
+      + (defaultLayout && !allLayouts.some(l => l.file === defaultLayout)
+        ? (durations.get(defaultLayout) || defaultDuration)
+        : 0);
+    periodSeconds = totalDuration || defaultDuration;
+  }
+
+  // Step 2: Simulate playback for one period using getPlayableLayouts()
+  const queue = [];
+  const simPlays = new Map(); // file → [timestampMs] for rate-limit tracking
+  let cursorMs = 0;
+  const periodMs = periodSeconds * 1000;
+  const maxEntries = 500; // safety cap
+
+  while (cursorMs < periodMs && queue.length < maxEntries) {
+    // Get playable layouts at current simulated time (priority fallback + rate limits)
+    const playable = getPlayableLayouts(allLayouts, simPlays, cursorMs);
+
+    if (playable.length === 0) {
+      // All layouts exhausted — use default
+      if (defaultLayout) {
+        const dur = durations.get(defaultLayout) || defaultDuration;
+        queue.push({ layoutId: defaultLayout, duration: dur });
+        cursorMs += dur * 1000;
+      } else {
+        // No default — skip ahead 60s to avoid infinite loop
+        cursorMs += 60000;
+      }
+      continue;
+    }
+
+    // Play all playable layouts in round-robin order (one each), then re-evaluate
+    for (let i = 0; i < playable.length && cursorMs < periodMs && queue.length < maxEntries; i++) {
+      const file = playable[i];
+      const dur = durations.get(file) || defaultDuration;
+
+      queue.push({ layoutId: file, duration: dur });
+
+      // Record simulated play for rate-limit tracking
+      if (!simPlays.has(file)) simPlays.set(file, []);
+      simPlays.get(file).push(cursorMs);
+
+      cursorMs += dur * 1000;
+
+      // Re-evaluate after each play: if the playable set changed, break to outer loop
+      const nextPlayable = getPlayableLayouts(allLayouts, simPlays, cursorMs);
+      if (!arraysEqual(playable, nextPlayable)) break;
+    }
+  }
+
+  // Handle edge case: no layouts and only default
+  if (queue.length === 0 && defaultLayout) {
+    const defDur = durations.get(defaultLayout) || defaultDuration;
+    queue.push({ layoutId: defaultLayout, duration: defDur });
+  }
+
+  return { queue, periodSeconds };
+}