Collection cycle — periodic CMS polling (RegisterDisplay, RequiredFiles, Schedule) with CRC32 optimization to skip redundant downloads
Layout scheduling — builds a playback queue from CMS schedule with support for campaigns, dayparting, priorities, and maxPlaysPerHour constraints
Layout state machine — controls which layout is playing, handles XMR interrupts (changeLayout, overlayLayout), layout overrides with auto-revert, and synchronized transitions in multi-display setups
Offline mode — falls back to IndexedDB-cached schedule and media when CMS is unreachable, with exponential backoff retry (30s -> 60s -> 120s -> normal interval)
Event bus — emits 50+ lifecycle events (collection-start, register-complete, layout-prepare-request, layout-current, offline-mode, timeline-updated, etc.)
XMR integration — WebSocket-based real-time messaging for remote commands (layout changes, purge, screenshots, geo-location, commands, triggers)
Multi-display sync — coordinates synchronized layout transitions and video playback across multiple displays via optional SyncManager
Layout blacklisting — automatic fallback when a layout fails to render 3+ times
Data connectors — real-time polling of external data sources (weather, feeds, APIs) for dynamic content widgets
Timeline calculation — predicts next 2 hours of layout playback with duration estimation and missing media detection

Architecture

+-----------------------------------------------------------------+
| PlayerCore (Pure Orchestration)                                 |
|                                                                 |
|  +-------------+--------------+--------------+                  |
|  | Collection  | Layout State | Offline      |                  |
|  | Cycle       | Machine      | Cache (IDB)  |                  |
|  +-------------+--------------+--------------+                  |
|                                                                 |
|  Events emitted (NO DOM manipulation):                          |
|  collection-start, schedule-received, download-request,         |
|  layout-prepare-request, layout-current, layout-expire-current, |
|  offline-mode, timeline-updated, sync-config, xmr-connected    |
+-----------------------------------------------------------------+
                             |
+-----------------------------------------------------------------+
| Dependencies (injected)                                         |
+-----------------------------------------------------------------+
| @xiboplayer/xmds     -> XMDS client (RegisterDisplay, etc.)    |
| @xiboplayer/schedule  -> Schedule queue builder, layout eval    |
| @xiboplayer/cache     -> Blob storage (media files, XLFs)      |
| @xiboplayer/renderer  -> Layout rendering (platform-specific)  |
| @xiboplayer/utils     -> Logger, EventEmitter, config          |
| @xiboplayer/sync      -> Multi-display SyncManager (optional)  |
+-----------------------------------------------------------------+
                             |
+-----------------------------------------------------------------+
| Platform Layer (PWA / Electron / Chromium / Mobile)             |
| - Renders layouts via renderer                                  |
| - Handles UI updates, status display, progress indicators       |
| - Manages storage, downloads via cache pkg                      |
| - Listens to core events and updates the DOM                    |
+-----------------------------------------------------------------+

Key principle: PlayerCore emits events; it does not manipulate the UI. The platform layer listens to these events and implements the actual rendering, DOM updates, and platform-specific behaviors.

Installation

npm install @xiboplayer/core

Usage

Basic setup

import { PlayerCore } from '@xiboplayer/core';

const core = new PlayerCore({
  config: displayConfig,
  xmds: xmdsClient,
  cache: cacheClient,
  schedule: scheduleManager,
  renderer: rendererInstance,
  xmrWrapper: XmrClass,
  statsCollector: statsClient,
  displaySettings: dsManager,
});

core.on('collection-start', () => console.log('Polling CMS...'));
core.on('schedule-received', (schedule) => console.log('Schedule updated'));
core.on('download-request', ({ files, layoutOrder }) => {
  downloadQueue(files, layoutOrder);
});

core.on('layout-prepare-request', (layoutId) => {
  renderer.renderLayout(layoutId);
});

core.on('offline-mode', (isOffline) => {
  updateStatusDisplay(isOffline ? 'Offline' : 'Online');
});

await core.collect();

Event handling

// Layout lifecycle
core.on('layout-prepare-request', (layoutId) => showLoadingBar());
core.on('layout-current', (layoutId) => hideLoadingBar());
core.on('layout-expire-current', () => fadeOutAndCleanup());

// Timeline/schedule preview
core.on('timeline-updated', (timeline) => {
  // timeline: [{ layoutFile, startTime, endTime, duration, missingMedia, isDefault }]
  updateTimelineOverlay(timeline);
});

// Offline
core.on('offline-mode', (isOffline) => {
  if (isOffline) showOfflineBanner('Using cached schedule');
  else hideOfflineBanner();
});

Layout overrides (XMR)

// Change to a specific layout, auto-revert after duration
core.changeLayout(layoutId, { duration: 30 });

// Overlay: push a layout on top of current content
core.overlayLayout(layoutId, { duration: 10 });

// Manual revert
await core.revertToSchedule();

Multi-display sync

import { SyncManager } from '@xiboplayer/sync';

const syncManager = new SyncManager({
  displayId: 'screen-1',
  syncConfig: regResult.syncConfig,
  onLayoutChange: async (layoutId) => {
    await renderer.prepareLayout(layoutId);
    syncManager.reportReady(layoutId);
  },
  onLayoutShow: (layoutId) => renderer.show(layoutId),
});

syncManager.start();
core.setSyncManager(syncManager);

Collection Cycle

The collection cycle runs every 300 seconds (configurable via CMS settings):

1. REGISTERDISPLAY
   +- Authenticates display (hardware key)
   +- Returns: settings, syncConfig, commands, checkRf/checkSchedule CRC32
   +- Saves to IndexedDB for offline use

2. CRC32 SKIP OPTIMIZATION
   +- If checkRf unchanged -> skip RequiredFiles
   +- If checkSchedule unchanged -> skip Schedule

3. REQUIREDFILES (if checkRf changed)
   +- Gets media, layouts, resources, dependencies, widgets
   +- Checks for purge items (deleted media to remove)
   +- Resets blacklist (CMS may have fixed layouts)

4. SCHEDULE (if checkSchedule changed)
   +- Gets CMS schedule (layouts, campaigns, dayparting, criteria)
   +- Evaluates criteria (location, time, device, weather, custom)
   +- Builds playback queue with priorities, maxPlaysPerHour, durations

5. LAYOUT QUEUE EVALUATION
   +- Calculates queue from schedule + durations + constraints
   +- If current layout still valid -> keep playing
   +- If expired -> emit layout-expire-current
   +- If no current layout -> emit layout-prepare-request

6. DOWNLOAD MANAGEMENT
   +- Check download window (CMS can restrict to off-peak hours)
   +- Emit download-request with files + layout priority order

7. SUBMIT STATS & LOGS
   +- Proof-of-play, diagnostic logs, fault reports
   +- Multi-display: followers delegate to lead via SyncManager

8. FINALIZE
   +- Calculate timeline (next 2 hours)
   +- Emit timeline-updated, collection-complete
   +- Schedule next cycle

OFFLINE FALLBACK:
   If XMDS fails AND cached schedule exists:
   +- Use cached schedule + cached media
   +- Retry with backoff: 30s -> 60s -> 120s -> normal

Events

Event	Payload	Description
`collection-start`	--	Collection cycle beginning
`collection-complete`	--	Collection cycle finished
`collection-error`	`(error)`	CMS communication failed
`register-complete`	`(regResult)`	RegisterDisplay succeeded
`files-received`	`(files)`	RequiredFiles call succeeded
`schedule-received`	`(schedule)`	Schedule call succeeded
`download-request`	`(layoutOrder, files)`	Download needed files in layout priority order
`layout-prepare-request`	`(layoutId)`	Next layout ready for rendering
`layout-current`	`(layoutId)`	Layout is now playing
`layout-pending`	`(layoutId, requiredMediaIds)`	Layout waiting for media downloads
`layout-expire-current`	--	Current layout duration ended
`layout-already-playing`	`(layoutId)`	Schedule changed but current layout still valid
`no-layouts-scheduled`	--	No layouts match current time
`layout-blacklisted`	`({ layoutId, reason, failures })`	Layout failed 3+ times, skipped
`offline-mode`	`(isOffline)`	Entered/exited offline mode
`xmr-connected`	`(xmrUrl)`	XMR WebSocket connected
`sync-config`	`(syncConfig)`	Display is in a sync group
`timeline-updated`	`(timeline)`	Schedule preview for next 2 hours
`screenshot-request`	--	XMR requested screenshot
`revert-to-schedule`	--	Layout override ended
`overlay-layout-request`	`(layoutId)`	Overlay layout requested
`execute-native-command`	`({ code, commandString })`	Non-HTTP command for platform
`scheduled-command`	`(command)`	Scheduled command ready
`submit-stats-request`	--	Submit proof-of-play stats
`submit-logs-request`	--	Submit player logs
`submit-faults-request`	--	Submit faults (~60s cycle)

API Reference

Constructor

new PlayerCore({
  config,              // Display configuration (cmsUrl, hardwareKey, displayName, etc.)
  xmds,                // XMDS client instance
  cache,               // Cache/storage client
  schedule,            // Schedule manager
  renderer,            // Layout renderer
  xmrWrapper,          // XMR WebSocket wrapper class
  statsCollector?,     // Optional proof-of-play tracker
  displaySettings?,    // Optional display settings manager
})

Methods

Method	Returns	Description
`collect()`	`Promise<void>`	Start collection cycle
`collectNow()`	`Promise<void>`	Force immediate collection (clears CRC32 cache)
`collectOffline()`	`void`	Use cached schedule
`getNextLayout()`	`object \| null`	Get next layout from queue, skip blacklisted
`advanceToNextLayout()`	`void`	Pop next layout, emit layout-prepare-request
`advanceToPreviousLayout()`	`void`	Go back in schedule
`setCurrentLayout(layoutId)`	`void`	Mark layout as currently playing
`getCurrentLayoutId()`	`number \| null`	Get currently playing layout ID
`changeLayout(layoutId, opts)`	`Promise<void>`	XMR: change layout with optional duration
`overlayLayout(layoutId, opts)`	`Promise<void>`	XMR: push overlay layout
`revertToSchedule()`	`Promise<void>`	Exit layout override
`reportLayoutFailure(id, reason)`	`void`	Report render failure; blacklist after 3
`reportLayoutSuccess(id)`	`void`	Clear failure counter
`setSyncManager(syncManager)`	`void`	Attach SyncManager for multi-display
`isSyncLead()`	`boolean`	Check if this display is sync lead
`purgeAll()`	`Promise<void>`	Delete all cache and re-download
`cleanup()`	`void`	Stop all timers, close XMR, remove listeners