@xiboplayer/schedule 0.1.3 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiboplayer/schedule",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "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.1.3"
+    "@xiboplayer/utils": "0.2.0"
   },
   "devDependencies": {
     "vitest": "^2.0.0"

package/src/index.js

@@ -18,3 +18,9 @@ export { InterruptScheduler } from './interrupts.js';
  * @module @xiboplayer/schedule/overlays
  */
 export { OverlayScheduler } from './overlays.js';
+
+/**
+ * Offline timeline calculator — duration parser + timeline simulator
+ * @module @xiboplayer/schedule/timeline
+ */
+export { calculateTimeline, parseLayoutDuration } from './timeline.js';

package/src/schedule.js

@@ -2,8 +2,11 @@
  * Schedule manager - determines which layouts to show
  */
 
+import { createLogger } from '@xiboplayer/utils';
 import { evaluateCriteria } from './criteria.js';
 
+const log = createLogger('Schedule');
+
 export class ScheduleManager {
   constructor(options = {}) {
     this.schedule = null;
@@ -131,11 +134,86 @@ export class ScheduleManager {
    * - Interrupts are interleaved with normal layouts
    */
   getCurrentLayouts() {
+    return this._getLayoutsAt(new Date());
+  }
+
+  /**
+   * Get layouts active at a specific time.
+   * Skips rate limiting and interrupt processing (those depend on real-time state).
+   * Used by timeline calculator to predict future playback.
+   * @param {Date} time - The time to evaluate
+   * @returns {string[]} Layout files active at that time
+   */
+  getLayoutsAtTime(time) {
+    return this._getLayoutsAt(time, { skipRateLimiting: true, skipInterrupts: true, quiet: true });
+  }
+
+  /**
+   * Get ALL time-active layouts with metadata, without priority or rate-limit filtering.
+   * Used by calculateTimeline() to simulate real playback with rate limiting and
+   * priority fallback (e.g., when high-priority layouts hit maxPlaysPerHour, lower
+   * priority layouts fill the gap).
+   *
+   * @param {Date} time - The time to evaluate
+   * @returns {Array<{file: string, priority: number, maxPlaysPerHour: number}>}
+   */
+  getAllLayoutsAtTime(time) {
+    if (!this.schedule) return [];
+
+    const now = time;
+    const results = [];
+
+    // Standalone layouts
+    if (this.schedule.layouts) {
+      for (const layout of this.schedule.layouts) {
+        if (!this.isRecurringScheduleActive(layout, now)) continue;
+        if (!this.isTimeActive(layout, now)) continue;
+        if (layout.criteria && layout.criteria.length > 0) {
+          if (!evaluateCriteria(layout.criteria, { now, displayProperties: this.displayProperties })) continue;
+        }
+        if (layout.isGeoAware && layout.geoLocation) {
+          if (!this.isWithinGeoFence(layout.geoLocation)) continue;
+        }
+        results.push({
+          file: layout.file,
+          priority: layout.priority || 0,
+          maxPlaysPerHour: layout.maxPlaysPerHour || 0,
+        });
+      }
+    }
+
+    // Campaign layouts
+    if (this.schedule.campaigns) {
+      for (const campaign of this.schedule.campaigns) {
+        if (!this.isRecurringScheduleActive(campaign, now)) continue;
+        if (!this.isTimeActive(campaign, now)) continue;
+        for (const layout of campaign.layouts) {
+          results.push({
+            file: layout.file,
+            priority: campaign.priority || 0,
+            maxPlaysPerHour: layout.maxPlaysPerHour || 0,
+          });
+        }
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Internal: evaluate schedule at a given time.
+   * @param {Date} now - Time to evaluate
+   * @param {Object} [options] - Options
+   * @param {boolean} [options.skipRateLimiting] - Skip maxPlaysPerHour checks
+   * @param {boolean} [options.skipInterrupts] - Skip interrupt/shareOfVoice processing
+   */
+  _getLayoutsAt(now, options = {}) {
     if (!this.schedule) {
       return [];
     }
 
-    const now = new Date();
+    const { skipRateLimiting = false, skipInterrupts = false, quiet = false } = options;
+    const _log = quiet ? () => {} : (...args) => log.info(...args);
     const activeItems = []; // Mix of campaign objects and standalone layouts
 
     // Track the highest priority of any time-active layout BEFORE rate-limit
@@ -181,7 +259,7 @@ export class ScheduleManager {
         // Check criteria conditions (date/time, display properties)
         if (layout.criteria && layout.criteria.length > 0) {
           if (!evaluateCriteria(layout.criteria, { now, displayProperties: this.displayProperties })) {
-            console.log('[Schedule] Layout', layout.id, 'filtered by criteria');
+            _log('[Schedule] Layout', layout.id, 'filtered by criteria');
             continue;
           }
         }
@@ -189,7 +267,7 @@ export class ScheduleManager {
         // Check geo-fencing
         if (layout.isGeoAware && layout.geoLocation) {
           if (!this.isWithinGeoFence(layout.geoLocation)) {
-            console.log('[Schedule] Layout', layout.id, 'filtered by geofence');
+            _log('[Schedule] Layout', layout.id, 'filtered by geofence');
             continue;
           }
         }
@@ -197,9 +275,9 @@ export class ScheduleManager {
         // Track priority before rate-limit filtering
         this._maxActivePriority = Math.max(this._maxActivePriority, layout.priority || 0);
 
-        // Check max plays per hour - but track that we filtered it
-        if (!this.canPlayLayout(layout.id, layout.maxPlaysPerHour)) {
-          console.log('[Schedule] Layout', layout.id, 'filtered by maxPlaysPerHour (limit:', layout.maxPlaysPerHour, ')');
+        // Check max plays per hour (skip for future time queries)
+        if (!skipRateLimiting && !this.canPlayLayout(layout.id, layout.maxPlaysPerHour)) {
+          _log('[Schedule] Layout', layout.id, 'filtered by maxPlaysPerHour (limit:', layout.maxPlaysPerHour, ')');
           // Continue to check other layouts, but don't add this one
           continue;
         }
@@ -220,17 +298,17 @@ export class ScheduleManager {
 
     // Find maximum priority across all items (campaigns and layouts)
     let maxPriority = Math.max(...activeItems.map(item => item.priority));
-    console.log('[Schedule] Max priority:', maxPriority, 'from', activeItems.length, 'active items');
+    _log('[Schedule] Max priority:', maxPriority, 'from', activeItems.length, 'active items');
 
     // Collect all layouts from items with max priority
     let allLayouts = [];
     for (const item of activeItems) {
       if (item.priority === maxPriority) {
-        console.log('[Schedule] Including priority', item.priority, 'layouts:', item.layouts.map(l => l.file));
+        _log('[Schedule] Including priority', item.priority, 'layouts:', item.layouts.map(l => l.file));
         // Add all layouts from this campaign or standalone layout
         allLayouts.push(...item.layouts);
       } else {
-        console.log('[Schedule] Skipping priority', item.priority, '< max', maxPriority);
+        _log('[Schedule] Skipping priority', item.priority, '< max', maxPriority);
       }
     }
 
@@ -245,23 +323,23 @@ export class ScheduleManager {
       });
     }
 
-    // Process interrupts if interrupt scheduler is available
-    if (this.interruptScheduler) {
+    // Process interrupts if interrupt scheduler is available (skip for future time queries)
+    if (!skipInterrupts && this.interruptScheduler) {
       const { normalLayouts, interruptLayouts } = this.interruptScheduler.separateLayouts(allLayouts);
 
       if (interruptLayouts.length > 0) {
-        console.log('[Schedule] Found', interruptLayouts.length, 'interrupt layouts with shareOfVoice');
+        _log('[Schedule] Found', interruptLayouts.length, 'interrupt layouts with shareOfVoice');
         const processedLayouts = this.interruptScheduler.processInterrupts(normalLayouts, interruptLayouts);
         // Extract file IDs from processed layouts
         const result = processedLayouts.map(l => l.file);
-        console.log('[Schedule] Final layouts (with interrupts):', result);
+        _log('[Schedule] Final layouts (with interrupts):', result);
         return result;
       }
     }
 
     // No interrupts, return layout files
     const result = allLayouts.map(l => l.file);
-    console.log('[Schedule] Final layouts:', result);
+    _log('[Schedule] Final layouts:', result);
     return result;
   }
 
@@ -307,7 +385,7 @@ export class ScheduleManager {
 
     // Check 1: Total plays in last hour must be under limit
     if (playsInLastHour.length >= maxPlaysPerHour) {
-      console.log(`[Schedule] Layout ${layoutId} has reached max plays per hour (${playsInLastHour.length}/${maxPlaysPerHour})`);
+      log.info(`Layout ${layoutId} has reached max plays per hour (${playsInLastHour.length}/${maxPlaysPerHour})`);
       return false;
     }
 
@@ -320,7 +398,7 @@ export class ScheduleManager {
 
       if (elapsed < minGapMs) {
         const remainingMin = ((minGapMs - elapsed) / 60000).toFixed(1);
-        console.log(`[Schedule] Layout ${layoutId} spacing: next play in ${remainingMin} min (${playsInLastHour.length}/${maxPlaysPerHour} plays, ${Math.round(minGapMs/60000)} min gap)`);
+        log.info(`Layout ${layoutId} spacing: next play in ${remainingMin} min (${playsInLastHour.length}/${maxPlaysPerHour} plays, ${Math.round(minGapMs/60000)} min gap)`);
         return false;
       }
     }
@@ -345,7 +423,7 @@ export class ScheduleManager {
     const cleaned = history.filter(timestamp => timestamp > oneHourAgo);
     this.playHistory.set(layoutId, cleaned);
 
-    console.log(`[Schedule] Recorded play for layout ${layoutId} (${cleaned.length} plays in last hour)`);
+    log.info(`Recorded play for layout ${layoutId} (${cleaned.length} plays in last hour)`);
   }
 
   /**
@@ -421,7 +499,7 @@ export class ScheduleManager {
    */
   clearPlayHistory() {
     this.playHistory.clear();
-    console.log('[Schedule] Play history cleared');
+    log.info('Play history cleared');
   }
 
   /**
@@ -431,7 +509,7 @@ export class ScheduleManager {
    */
   setLocation(latitude, longitude) {
     this.playerLocation = { latitude, longitude };
-    console.log(`[Schedule] Location set: ${latitude}, ${longitude}`);
+    log.info(`Location set: ${latitude}, ${longitude}`);
   }
 
   /**
@@ -456,7 +534,7 @@ export class ScheduleManager {
   isWithinGeoFence(geoLocation, defaultRadius = 500) {
     if (!this.playerLocation) {
       // No location available — be permissive, show the content
-      console.log('[Schedule] No player location, skipping geofence check');
+      log.debug('No player location, skipping geofence check');
       return true;
     }
 
@@ -465,7 +543,7 @@ export class ScheduleManager {
     // Parse "lat,lng" format
     const parts = geoLocation.split(',').map(s => parseFloat(s.trim()));
     if (parts.length < 2 || isNaN(parts[0]) || isNaN(parts[1])) {
-      console.log('[Schedule] Invalid geoLocation format:', geoLocation);
+      log.warn('Invalid geoLocation format:', geoLocation);
       return true; // Invalid format, be permissive
     }
 
@@ -479,7 +557,7 @@ export class ScheduleManager {
     );
 
     const within = distance <= radius;
-    console.log(`[Schedule] Geofence: ${distance.toFixed(0)}m from (${fenceLat},${fenceLng}), radius ${radius}m → ${within ? 'WITHIN' : 'OUTSIDE'}`);
+    log.info(`Geofence: ${distance.toFixed(0)}m from (${fenceLat},${fenceLng}), radius ${radius}m → ${within ? 'WITHIN' : 'OUTSIDE'}`);
     return within;
   }
 

package/src/timeline.js

@@ -0,0 +1,245 @@
+/**
+ * Offline Schedule Timeline Calculator
+ *
+ * Calculates deterministic playback timelines by parsing layout XLF durations
+ * and simulating round-robin scheduling. Enables the player to answer
+ * "what's the playback plan for the next N hours?" while offline.
+ */
+
+/**
+ * Parse layout duration from XLF XML string.
+ * Lightweight parser — uses DOMParser, no rendering.
+ *
+ * Duration resolution order:
+ *  1. Explicit <layout duration="60"> attribute
+ *  2. Sum of widget <media duration="X"> per region (max across regions)
+ *  3. Fallback: 60s
+ *
+ * @param {string} xlfXml - Raw XLF XML string
+ * @returns {number} Duration in seconds
+ */
+export function parseLayoutDuration(xlfXml) {
+  const doc = new DOMParser().parseFromString(xlfXml, 'text/xml');
+  const layoutEl = doc.querySelector('layout');
+  if (!layoutEl) return 60;
+
+  // 1. Explicit layout duration attribute
+  const explicit = parseInt(layoutEl.getAttribute('duration') || '0', 10);
+  if (explicit > 0) return explicit;
+
+  // 2. Calculate from widget durations (max region wins — regions play in parallel)
+  let maxDuration = 0;
+  for (const regionEl of layoutEl.querySelectorAll('region')) {
+    let regionDuration = 0;
+    for (const mediaEl of regionEl.querySelectorAll('media')) {
+      const dur = parseInt(mediaEl.getAttribute('duration') || '0', 10);
+      const useDuration = parseInt(mediaEl.getAttribute('useDuration') || '1', 10);
+      if (dur > 0 && useDuration !== 0) {
+        regionDuration += dur;
+      } else {
+        // Video with useDuration=0 means "play to end" — estimate 60s,
+        // corrected later via recordLayoutDuration() when video metadata loads
+        regionDuration += 60;
+      }
+    }
+    maxDuration = Math.max(maxDuration, regionDuration);
+  }
+
+  return maxDuration > 0 ? maxDuration : 60;
+}
+
+/**
+ * Compare two arrays of layout files for equality.
+ * @param {string[]} a
+ * @param {string[]} b
+ * @returns {boolean}
+ */
+function arraysEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * Check if a layout can play at a given time based on simulated play history.
+ * Replicates ScheduleManager.canPlayLayout() logic for timeline prediction.
+ *
+ * Even-distribution rules:
+ *   1. Total plays in sliding 1-hour window < maxPlaysPerHour
+ *   2. Time since last play >= (60 / maxPlaysPerHour) minutes
+ *
+ * @param {number[]} history - Simulated play timestamps (ms) for this layout
+ * @param {number} maxPlaysPerHour - Max plays per hour (0 = unlimited)
+ * @param {number} timeMs - Current simulated time in ms
+ * @returns {boolean}
+ */
+function canSimulatedPlay(history, maxPlaysPerHour, timeMs) {
+  if (!maxPlaysPerHour || maxPlaysPerHour === 0) return true;
+
+  const oneHourAgo = timeMs - 3600000;
+  const playsInLastHour = history.filter(t => t > oneHourAgo);
+
+  // Check 1: under hourly limit
+  if (playsInLastHour.length >= maxPlaysPerHour) return false;
+
+  // Check 2: minimum gap for even distribution
+  if (playsInLastHour.length > 0) {
+    const minGapMs = 3600000 / maxPlaysPerHour;
+    const lastPlay = Math.max(...playsInLastHour);
+    if (timeMs - lastPlay < minGapMs) return false;
+  }
+
+  return true;
+}
+
+/**
+ * Seed simulated play history from real play history.
+ * Maps layoutId-based history to layoutFile-based history.
+ * @param {Map<string, number[]>} realHistory - schedule.playHistory (layoutId → [timestamps])
+ * @returns {Map<string, number[]>} layoutFile → [timestamps]
+ */
+function seedPlayHistory(realHistory) {
+  const simulated = new Map();
+  if (!realHistory) return simulated;
+
+  for (const [layoutId, timestamps] of realHistory) {
+    const file = `${layoutId}.xlf`;
+    simulated.set(file, [...timestamps]);
+  }
+  return simulated;
+}
+
+/**
+ * From a list of layout metadata, apply simulated rate limiting and priority
+ * filtering to determine which layouts can actually play at the given time.
+ * Mirrors the real player logic: filter rate-limited layouts first, then
+ * pick highest remaining priority.
+ *
+ * @param {Array<{file: string, priority: number, maxPlaysPerHour: number}>} allLayouts
+ * @param {Map<string, number[]>} simPlays - Simulated play history
+ * @param {number} timeMs - Current simulated time in ms
+ * @returns {string[]} Layout files that can play, highest priority first
+ */
+function getPlayableLayouts(allLayouts, simPlays, timeMs) {
+  // Step 1: Filter out rate-limited layouts
+  const eligible = allLayouts.filter(l => {
+    if (!l.maxPlaysPerHour || l.maxPlaysPerHour === 0) return true;
+    const history = simPlays.get(l.file) || [];
+    return canSimulatedPlay(history, l.maxPlaysPerHour, timeMs);
+  });
+
+  if (eligible.length === 0) return [];
+
+  // Step 2: Pick highest priority from remaining layouts
+  const maxPriority = Math.max(...eligible.map(l => l.priority));
+  return eligible
+    .filter(l => l.priority === maxPriority)
+    .map(l => l.file);
+}
+
+/**
+ * Calculate a deterministic playback timeline by simulating round-robin scheduling
+ * with rate limiting (maxPlaysPerHour) and priority fallback. Produces a real
+ * schedule prediction that matches actual player behavior.
+ *
+ * When high-priority layouts hit their maxPlaysPerHour limit, the simulation
+ * falls back to lower-priority scheduled layouts before using the CMS default.
+ *
+ * @param {Object} schedule - ScheduleManager instance (needs getAllLayoutsAtTime(), schedule.default, playHistory)
+ * @param {Map<string, number>} durations - Map of layoutFile → duration in seconds
+ * @param {Object} [options]
+ * @param {Date}   [options.from]    - Start time (default: now)
+ * @param {number} [options.hours]   - Hours to simulate (default: 2)
+ * @param {number} [options.defaultDuration] - Fallback duration in seconds (default: 60)
+ * @returns {Array<{layoutFile: string, startTime: Date, endTime: Date, duration: number, isDefault: boolean}>}
+ */
+export function calculateTimeline(schedule, durations, options = {}) {
+  const from = options.from || new Date();
+  const hours = options.hours || 2;
+  const to = new Date(from.getTime() + hours * 3600000);
+  const defaultDuration = options.defaultDuration || 60;
+  const timeline = [];
+  let currentTime = new Date(from);
+
+  // Use getAllLayoutsAtTime if available (new API), fall back to getLayoutsAtTime (old API)
+  const hasFullApi = typeof schedule.getAllLayoutsAtTime === 'function';
+
+  // Seed simulated play history from real plays
+  const simPlays = seedPlayHistory(schedule.playHistory);
+
+  const maxEntries = 500;
+
+  while (currentTime < to && timeline.length < maxEntries) {
+    const timeMs = currentTime.getTime();
+    let playable;
+
+    if (hasFullApi) {
+      // Full simulation: get ALL active layouts, apply rate limiting + priority
+      const allLayouts = schedule.getAllLayoutsAtTime(currentTime);
+      playable = allLayouts.length > 0
+        ? getPlayableLayouts(allLayouts, simPlays, timeMs)
+        : [];
+    } else {
+      // Legacy fallback: no rate limiting simulation
+      playable = schedule.getLayoutsAtTime(currentTime);
+    }
+
+    if (playable.length === 0) {
+      // No playable layouts — use CMS default or skip ahead
+      const defaultFile = schedule.schedule?.default;
+      if (defaultFile) {
+        const dur = durations.get(defaultFile) || defaultDuration;
+        timeline.push({
+          layoutFile: defaultFile,
+          startTime: new Date(currentTime),
+          endTime: new Date(timeMs + dur * 1000),
+          duration: dur,
+          isDefault: true,
+        });
+        currentTime = new Date(timeMs + dur * 1000);
+      } else {
+        currentTime = new Date(timeMs + 60000);
+      }
+      continue;
+    }
+
+    // Round-robin through playable layouts
+    for (let i = 0; i < playable.length && currentTime < to && timeline.length < maxEntries; i++) {
+      const file = playable[i];
+      const dur = durations.get(file) || defaultDuration;
+      const endMs = currentTime.getTime() + dur * 1000;
+
+      timeline.push({
+        layoutFile: file,
+        startTime: new Date(currentTime),
+        endTime: new Date(endMs),
+        duration: dur,
+        isDefault: false,
+      });
+
+      // Record simulated play
+      if (hasFullApi) {
+        if (!simPlays.has(file)) simPlays.set(file, []);
+        simPlays.get(file).push(currentTime.getTime());
+      }
+
+      currentTime = new Date(endMs);
+
+      // Re-evaluate: if playable set changed, re-enter outer loop
+      if (hasFullApi) {
+        const nextAll = schedule.getAllLayoutsAtTime(currentTime);
+        const nextPlayable = nextAll.length > 0
+          ? getPlayableLayouts(nextAll, simPlays, currentTime.getTime())
+          : [];
+        if (!arraysEqual(playable, nextPlayable)) break;
+      } else {
+        const next = schedule.getLayoutsAtTime(currentTime);
+        if (!arraysEqual(playable, next)) break;
+      }
+    }
+  }
+
+  return timeline;
+}