eyevinn-channel-engine 5.1.2 → 5.2.0

package/.github/workflows/nodejs.yml

@@ -9,7 +9,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [20.x, 22.x]
+        node-version: [22.x, 24.x]
 
     steps:
     - uses: actions/checkout@v4

package/.github/workflows/publish.yml

@@ -12,7 +12,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 24
           registry-url: https://registry.npmjs.org/
       - run: |
           npm ci

package/.github/workflows/rc.yml

@@ -12,7 +12,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 24
           registry-url: https://registry.npmjs.org/
       - run: |
           npm ci

package/CONTRIBUTING.md

@@ -17,6 +17,46 @@ We follow the [GitHub Flow](https://guides.github.com/introduction/flow/index.ht
 
 When submitting code changes your submissions are understood to be under the same MIT License that covers the project. Feel free to contact Eyevinn Technology if that's a concern.
 
+# TypeScript migration
+
+The `engine/` tree is being migrated from JavaScript to TypeScript **incrementally**, one
+module at a time, so that `master` keeps building and testing green throughout. The build
+(`npm run build`, which runs `tsc --project ./`) already compiles a mixed JS/TS tree because
+`allowJs` is enabled in `tsconfig.json`.
+
+## Target strictness level
+
+The end state is a fully-typed, strictly-checked tree:
+
+- `strict: true` (implies `noImplicitAny`, `strictNullChecks`, etc.)
+- `checkJs: true` for any remaining `.js` files
+
+These global flags are **intentionally not enabled yet**. Turning them on across the ~7,500
+LOC of currently-untyped JS would surface a large number of errors at once and break
+`master`'s build. Instead, opt in **per file** as each module is hardened:
+
+- Add `// @ts-check` at the top of a `.js` file to type-check just that file, or
+- Convert the file to `.ts` (preferred — see checklist below).
+
+The global `strict` / `checkJs` flags land **last**, in the final migration slice (**#376**),
+once every module has already been converted or individually `@ts-check`-clean.
+
+## Per-file conversion checklist
+
+Convert **one module per commit** to keep diffs reviewable and bisectable:
+
+1. Rename the file `.js` → `.ts` (use `git mv` to preserve history).
+2. Add explicit types for all exported functions, classes, and their public members.
+3. Keep the **public API and runtime behavior identical** — this is a type-only migration,
+   no behavior changes. Prefer `unknown` + narrowing over `any` where practical; leave a
+   `// TODO(ts):` note if a proper type is deferred.
+4. Run `npm run build && npm test` locally and confirm both are green (the jasmine suite must
+   report `0 failures`).
+5. Commit with a conventional-commit message, e.g. `refactor(engine): migrate util to TypeScript`.
+
+CI already gates every push on `npm run build` (tsc) followed by `npm test`, so a file that
+fails type-checking or breaks a test cannot land on `master`.
+
 # Code of Conduct
 
 ## Our Pledge

package/Dockerfile

@@ -1,4 +1,4 @@
-FROM node:18-alpine
+FROM node:24-alpine
 
 WORKDIR /app
 

package/README.md

@@ -40,28 +40,89 @@ Please see the [Documentation](https://vod2live.docs.eyevinn.technology) for int
 - Develop adapters to plugin with custom scheduling endpoints
 - High Availability with Redis Cache or Valkey as shared state store
 - Support for WebVTT subtitles
-- Support for DRM encrypted HLS VODs (in beta)
+- Support for Widevine DRM encrypted HLS+CMAF VODs (in beta); see `examples/drm.ts`
 - Improved performance with Redis connection pooling and pipelining
 - Enhanced stability in High Availability mode
 - Support for livemix with demuxed content (TS and CMAF)
+- Support for SGAI HLS-interstitial ad breaks with client-side ad replacement
 - And much more!
 
+### Ad breaks (HLS interstitials)
+
+A channel can be configured to open SGAI HLS-interstitial ad breaks. When
+enabled, the engine emits EXT-X-DATERANGE interstitial metadata on the
+manifest and resolves the ad asset from a configured ad-serving endpoint, with
+a slate fallback if that endpoint cannot be reached. Configure it through the
+`adBreak` option (engine-level default or per channel); see
+[docs/reference.md](docs/reference.md#ad-break-configuration-hls-interstitials)
+for the full field reference and `examples/adbreak.ts` for a runnable example.
+
+### Custom VOD request parameters
+
+The engine can be configured with an allowlist of query-parameter names that
+are permitted to be forwarded to the asset manager's `getNextVod()` request,
+through the `customVodRequestParams` option on `ChannelEngineOpts`. Only
+parameters named in the allowlist may be passed through; all others are
+ignored, and the default (option omitted) is an empty allowlist with no
+pass-through. See
+[docs/reference.md](docs/reference.md#custom-vod-request-parameters) for the
+field reference.
+
+Declare the allowlist when creating the engine and read the forwarded values
+from `vodRequest.customParams` in your asset manager's `getNextVod()`:
+
+```js
+const { ChannelEngine } = require('eyevinn-channel-engine');
+
+class MyAssetManager {
+  getNextVod(vodRequest) {
+    // Only allowlisted params are present; everything else is stripped.
+    // `customParams` is omitted entirely when no allowlisted param was sent.
+    const myparam = vodRequest.customParams && vodRequest.customParams.myparam;
+    return Promise.resolve({
+      id: '1',
+      title: 'Example',
+      uri: myparam
+        ? `https://vod.example.com/${myparam}/master.m3u8`
+        : 'https://vod.example.com/default/master.m3u8'
+    });
+  }
+}
+
+const engine = new ChannelEngine(new MyAssetManager(), {
+  channelManager: myChannelManager,
+  // Allowlist the query-parameter names to forward to getNextVod().
+  customVodRequestParams: ['myparam']
+});
+engine.start();
+engine.listen(8000);
+```
+
+A request such as:
+
+```
+GET /channels/1/master.m3u8?myparam=foo
+```
+
+forwards `{ myparam: 'foo' }` to `getNextVod()` via `vodRequest.customParams`.
+Any query parameter not in `customVodRequestParams` (e.g. `?other=bar`) is
+dropped before it reaches the asset manager.
+
 ## System Requirements
 
 Supported Node.js Versions
 
 | Version | Supported | 
 | ------- | --------- |
-| 14.x    | Yes       |
-| 16.x    | Yes       |
-| 18.x    | Yes       |
+| 22.x    | Yes       |
+| 24.x    | Yes       |
 
 ## Supported Source Formats
 
-| HLS Format | Muxed | Demuxed | Mix w. Live | Subtitles | Mix w. Live & Subtitles | DRM |
-| ---------- | ----- | ------- | ----------- | --------- | ----------------------- | --- |
-| HLS + TS   | Yes   | Yes     | Yes         | Yes       | No                      | No  |
-| HLS + CMAF | Yes   | Yes     | Yes         | Yes       | No                      | No  |
+| HLS Format | Muxed | Demuxed | Mix w. Live | Subtitles | Mix w. Live & Subtitles | DRM            |
+| ---------- | ----- | ------- | ----------- | --------- | ----------------------- | -------------- |
+| HLS + TS   | Yes   | Yes     | Yes         | Yes       | No                      | No             |
+| HLS + CMAF | Yes   | Yes     | Yes         | Yes       | No                      | Yes (Widevine) |
 
 NOTE: The engine does not support subtitles in the live-mix + demux setting. Furthermore, then using the live-mix + demux setting, it is most optimal to use HLS content which has the same segment durations on all variants.
 Using a mix of different segment durations may result in occasional playback/audio sync issues, but not always. Further development will be needed to resolve this and improve the robustness of the live-mix + demux experience.
@@ -198,6 +259,7 @@ In addition there other reference implemetations that can be used:
 - `examples/drm.ts` : example with DRM
 - `examples/autocreate.ts` : example to auto create channel on demand
 - `examples/truncate.ts` : example when trimming start and end of a VOD
+- `examples/adbreak.ts` : example with a channel configured for HLS-interstitial ad breaks
 
 ### Source linking hls-vodtolive library
 

package/dist/engine/chaos_monkey.d.ts

@@ -1 +1 @@
-export function loadVod(p: any): Promise<any>;
+export {};

package/dist/engine/chaos_monkey.js

@@ -1,4 +1,5 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
 const debug = require('debug')('chaos-monkey');
 const CHAOS_MONKEY_PROBABILITY = process.env.CHAOS_MONKEY_PROBABILITY || 0.5;
 const doChaos = () => process.env.CHAOS_MONKEY === "true" && Math.random() < CHAOS_MONKEY_PROBABILITY;

package/dist/engine/event_stream.d.ts

@@ -1,6 +1 @@
-export = EventStream;
-declare class EventStream {
-    constructor(session: any);
-    _session: any;
-    poll(): Promise<any>;
-}
+export {};

package/dist/engine/event_stream.js

@@ -1,5 +1,7 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
 class EventStream {
+    _session;
     constructor(session) {
         this._session = session;
     }

package/dist/engine/memcached_state_store.d.ts

@@ -1,13 +1 @@
-export = MemcachedStateStore;
-declare class MemcachedStateStore {
-    constructor(keyPrefix: any, opts: any);
-    keyPrefix: any;
-    client: any;
-    initAsync(id: any, initData: any): Promise<{}>;
-    resetAsync(id: any, initData: any): Promise<void>;
-    resetAllAsync(): Promise<void>;
-    getAsync(id: any, key: any): Promise<any>;
-    setAsync(id: any, key: any, value: any): Promise<any>;
-    setVolatileAsync(id: any, key: any, value: any): Promise<void>;
-    removeAsync(id: any, key: any): Promise<void>;
-}
+export {};

package/dist/engine/memcached_state_store.js

@@ -1,7 +1,11 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
 const MemcacheClient = require("memcache-client");
 const debug = require("debug")("memcached-state-store");
+// Type-only migration (#373): a faithful port of the original JS.
 class MemcachedStateStore {
+    keyPrefix;
+    client;
     constructor(keyPrefix, opts) {
         this.keyPrefix = keyPrefix;
         if (opts.version) {

package/dist/engine/memory_state_store.d.ts

@@ -1,13 +1 @@
-export = MemoryStateStore;
-declare class MemoryStateStore {
-    constructor(type: any, opts: any);
-    sharedStates: {};
-    globalSharedStates: {};
-    initAsync(id: any, initData: any): Promise<any>;
-    resetAsync(id: any, initData: any): Promise<void>;
-    resetAllAsync(): Promise<void>;
-    getAsync(id: any, key: any): Promise<any>;
-    setAsync(id: any, key: any, value: any): Promise<any>;
-    setVolatileAsync(id: any, key: any, value: any): Promise<any>;
-    removeAsync(id: any, key: any): Promise<void>;
-}
+export {};

package/dist/engine/memory_state_store.js

@@ -1,6 +1,11 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
 const debug = require("debug")("memory-state-store");
+// Type-only migration (#373): a faithful port of the original JS. Runtime
+// behavior and the exported constructor signature are unchanged.
 class MemoryStateStore {
+    sharedStates;
+    globalSharedStates;
     constructor(type, opts) {
         this.sharedStates = {};
         this.globalSharedStates = {};

package/dist/engine/playhead_state.d.ts

@@ -1,27 +1 @@
-export const PlayheadState: Readonly<{
-    RUNNING: 1;
-    STOPPED: 2;
-    CRASHED: 3;
-    IDLE: 4;
-}>;
-export class PlayheadStateStore extends SharedStateStore {
-    constructor(opts: any);
-    create(sessionId: any): Promise<SharedPlayheadState>;
-}
-import SharedStateStore = require("./shared_state_store.js");
-declare class SharedPlayheadState {
-    constructor(store: any, sessionId: any, opts: any);
-    sessionId: any;
-    store: any;
-    state: 4;
-    lastM3u8: any;
-    get(key: any): Promise<any>;
-    getState(): Promise<4>;
-    getLastM3u8(): Promise<any>;
-    getValues(keys: any): Promise<any>;
-    set(key: any, value: any, isLeader: any): Promise<any>;
-    setValues(keyValues: any, isLeader: any): Promise<any>;
-    setState(newState: any): Promise<4>;
-    setLastM3u8(m3u8: any): Promise<any>;
-}
 export {};

package/dist/engine/playhead_state.js

@@ -1,5 +1,10 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
 const SharedStateStore = require('./shared_state_store.js');
+// Type-only migration (#373): a faithful port of the original JS.
+// `SharedStateStore` is loaded via CommonJS `require` (erasable syntax) so the
+// still-`.js` consumers keep resolving it unchanged; the base type is `any` at
+// this interop boundary.
 const PlayheadState = Object.freeze({
     RUNNING: 1,
     STOPPED: 2,
@@ -7,6 +12,10 @@ const PlayheadState = Object.freeze({
     IDLE: 4
 });
 class SharedPlayheadState {
+    sessionId;
+    store;
+    state;
+    lastM3u8;
     constructor(store, sessionId, opts) {
         this.sessionId = sessionId;
         this.store = store;

package/dist/engine/preflight.d.ts

@@ -1 +1 @@
-export function handler(req: any, res: any): Promise<void>;
+export {};

package/dist/engine/preflight.js

@@ -1,4 +1,5 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
 const constants = {
     ALLOW_HEADERS: [
         'accept',

package/dist/engine/redis_state_store.d.ts

@@ -1,19 +1 @@
-export = RedisStateStore;
-declare class RedisStateStore {
-    constructor(keyPrefix: any, opts: any);
-    keyPrefix: any;
-    volatileKeyTTL: any;
-    pool: any[];
-    createRedisPool(size: any, redisUrl: any): any[];
-    getClientFromPool(maxWaitTime?: number): Promise<any>;
-    returnClientToPool(client: any): void;
-    initAsync(id: any, initData: any): Promise<{}>;
-    resetAsync(id: any, initData: any): Promise<void>;
-    resetAllAsync(): Promise<void>;
-    getValues(id: any, keys: any): Promise<{}>;
-    getAsync(id: any, key: any): Promise<any>;
-    setValues(id: any, data: any): Promise<{}>;
-    setAsync(id: any, key: any, value: any): Promise<any>;
-    setVolatileAsync(id: any, key: any, value: any): Promise<any>;
-    removeAsync(id: any, key: any): Promise<any>;
-}
+export {};

package/dist/engine/redis_state_store.js

@@ -1,7 +1,9 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
 const Redis = require("ioredis");
 const debug = require("debug")("redis-state-store");
 const { cloudWatchLog, timer } = require("./util.js");
+// Type-only migration (#373): a faithful port of the original JS.
 const DEFAULT_VOLATILE_KEY_TTL = 5; // Timeout so it should not expire within one normal increment iteration (in seconds)
 function isTrue(s) {
     const regex = /^\s*(true|1)\s*$/i;
@@ -10,6 +12,9 @@ function isTrue(s) {
 const REDIS_VERBOSE_LOG = process.env.REDIS_VERBOSE_LOG ? isTrue(process.env.REDIS_VERBOSE_LOG) : false;
 const REDIS_POOL_SIZE = process.env.REDIS_POOL_SIZE ? parseInt(process.env.REDIS_POOL_SIZE) : 15;
 class RedisStateStore {
+    keyPrefix;
+    volatileKeyTTL;
+    pool;
     constructor(keyPrefix, opts) {
         this.keyPrefix = keyPrefix;
         if (opts.version) {

package/dist/engine/server.d.ts

@@ -1,7 +1,18 @@
+export interface AdBreakOpts {
+    enabled: boolean;
+    adServerUri?: string;
+    slate?: SlateOpts;
+}
+export interface SlateOpts {
+    uri: string;
+    repetitions?: number;
+    duration?: number;
+}
 export interface ChannelEngineOpts {
     defaultSlateUri?: string;
     slateRepetitions?: number;
     slateDuration?: number;
+    adBreak?: AdBreakOpts;
     redisUrl?: string;
     memcachedUrl?: string;
     sharedStoreCacheTTL?: number;
@@ -35,11 +46,19 @@ export interface ChannelEngineOpts {
     sessionEventStream?: boolean;
     sessionHealthKey?: string;
     rollingPDT?: boolean;
+    event?: boolean;
+    customVodRequestParams?: string[];
+    streamSwitchTimeIntervalMs?: number;
+    streamSwitchOngoingEventIntervalMs?: number;
+    streamSwitchNearEndEventIntervalMs?: number;
 }
 export interface VodRequest {
     sessionId: string;
     category?: string;
     playlistId: string;
+    customParams?: {
+        [key: string]: string;
+    };
 }
 export interface VodResponseMetadata {
     id: string;
@@ -86,6 +105,8 @@ export interface Channel {
     audioTracks?: AudioTracks[];
     subtitleTracks?: SubtitleTracks[];
     closedCaptions?: ClosedCaptions[];
+    slate?: SlateOpts;
+    adBreak?: AdBreakOpts;
 }
 export interface ClosedCaptions {
     id: string;
@@ -138,6 +159,7 @@ export declare class ChannelEngine {
     private alwaysMapBandwidthByNearest;
     private defaultSlateUri?;
     private slateDuration?;
+    private adBreak?;
     private assetMgr;
     private streamSwitchManager?;
     private slateRepetitions?;
@@ -146,6 +168,8 @@ export declare class ChannelEngine {
     private serverStartTime;
     private instanceId;
     private streamSwitchTimeIntervalMs;
+    private streamSwitchOngoingEventIntervalMs;
+    private streamSwitchNearEndEventIntervalMs;
     private sessionStore;
     private sessionLiveStore;
     private streamerOpts;
@@ -156,7 +180,10 @@ export declare class ChannelEngine {
     private sessionResetKey;
     private sessionEventStream;
     private sessionHealthKey;
+    private customVodRequestParams;
+    private static normalizeAdBreak;
     constructor(assetMgr: IAssetManager, options?: ChannelEngineOpts);
+    computeStreamSwitchIntervalMs(baseIntervalMs: any): any;
     updateStreamSwitchAsync(): Promise<void>;
     updateChannelsAsync(channelMgr: any, options: any): Promise<void>;
     start(): void;