eyevinn-channel-engine 5.1.2 → 5.2.0

package/engine/{session.js → session.ts}

@@ -1,5 +1,6 @@
 const crypto = require('crypto');
 const debug = require('debug')('engine-session');
+const fetch = require('node-fetch');
 const HLSVod = require('@eyevinn/hls-vodtolive');
 const m3u8 = require('@eyevinn/m3u8');
 const HLSRepeatVod = require('@eyevinn/hls-repeat');
@@ -20,13 +21,22 @@ const {
 const ChaosMonkey = require('./chaos_monkey.js');
 
 const EVENT_LIST_LIMIT = 100;
+// Rejection marker used by `_getNextVod()` when, in `event` mode, the asset
+// manager signals that there are no more VODs to play (see issue #362).
+const END_OF_SCHEDULE = "END_OF_SCHEDULE";
 const DEFAULT_PLAYHEAD_DIFF_THRESHOLD = 1000;
 const DEFAULT_MAX_TICK_INTERVAL = 10000;
 const DEFAULT_DIFF_COMPENSATION_RATE = 0.5;
+// Max time (ms) to wait for the configured ad-serving endpoint (#370) before
+// giving up and falling back to the slate-only break. Kept short so a slow or
+// unreachable endpoint never stalls a session tick.
+const AD_SERVER_TIMEOUT_MS = 2000;
 
 const timer = ms => new Promise(res => setTimeout(res, ms));
 
 class Session {
+  [key: string]: any;
+
   /**
    *
    * config: {
@@ -34,7 +44,7 @@ class Session {
    * }
    *
    */
-  constructor(assetManager, config, sessionStore) {
+  constructor(assetManager: any, config: any, sessionStore: any) {
     this._assetManager = assetManager;
     this._sessionId = crypto.randomBytes(20).toString('hex');
 
@@ -88,6 +98,22 @@ class Session {
     this.currentPlayheadRef = null;
     this.disableLegacyMasterManifestFormat = null;
     this.rollingPDT = null;
+    this.event = false;
+    // End-of-schedule detection (issue #362). Only meaningful when `event` mode is
+    // enabled. Set to true once the asset manager has signalled that there are no
+    // more VODs to play (see `_isEndOfScheduleSignal`). ENDLIST emission based on
+    // this state is out of scope here and handled by #363.
+    this.isEndOfSchedule = false;
+    // Ad-break / interstitial config surface (issue #367). Disabled by default;
+    // no interstitial tags are emitted from this yet (follow-up #368).
+    this.adBreak = { enabled: false };
+    // Custom pass-through parameters forwarded to the asset manager's
+    // getNextVod() (issue #378). Populated per-session by the master-manifest
+    // request handler (wired up in #379) after filtering against the
+    // customVodRequestParams allowlist (#377). Defaults to an empty object so
+    // that, until a setter populates it, existing IAssetManager implementations
+    // are unaffected.
+    this.customParams = {};
     if (config) {
       if (config.alwaysNewSegments) {
         this.alwaysNewSegments = config.alwaysNewSegments;
@@ -101,6 +127,9 @@ class Session {
       if (config.rollingPDT) {
         this.rollingPDT = config.rollingPDT;
       }
+      if (config.event) {
+        this.event = config.event;
+      }
       if (config.alwaysMapBandwidthByNearest) {
         this.alwaysMapBandwidthByNearest = config.alwaysMapBandwidthByNearest;
       }
@@ -137,7 +166,23 @@ class Session {
         this._audioTracks = config.audioTracks;
       }
       if (config.subtitleTracks) {
-        this._subtitleTracks = config.subtitleTracks;
+        // Normalize expected subtitle tracks before forwarding them to
+        // @eyevinn/hls-vodtolive as expectedSubtitleTracks. The dependency's
+        // matcher (see node_modules/@eyevinn/hls-vodtolive/index.js) compares a
+        // source SUBTITLES rendition against BOTH element.language and
+        // element.name and unconditionally calls element.name.toLowerCase().
+        // When a source manifest omits LANGUAGE it falls back to matching on the
+        // manifest NAME. If an operator configures a track with only a
+        // `language` (no `name`), the matcher throws on the missing name and no
+        // track is ever matched (issue #385, broken out from #325). Defaulting
+        // `name` to `language` keeps the contract well-formed so a NAME-only
+        // source whose NAME equals the configured language/name still resolves
+        // to real cues instead of dummy vtt. This is not a fuzzy match: it only
+        // fills in an omitted field with the operator's own value.
+        this._subtitleTracks = config.subtitleTracks.map((track) => ({
+          ...track,
+          name: track.name != null ? track.name : track.language,
+        }));
       }
       if (config.closedCaptions) {
         this._closedCaptions = config.closedCaptions;
@@ -154,6 +199,10 @@ class Session {
         this.slateDuration = config.slateDuration || 4000;
         debug(`Will use slate URI ${this.slateUri} (${this.slateRepetitions} ${this.slateDuration}ms)`);
       }
+      if (config.adBreak && config.adBreak.enabled) {
+        this.adBreak = config.adBreak;
+        debug(`Ad breaks enabled, ad server URI ${this.adBreak.adServerUri}`);
+      }
       if (config.cloudWatchMetrics) {
         this.cloudWatchLogging = true;
       }
@@ -193,6 +242,14 @@ class Session {
     return this._sessionId;
   }
 
+  // Store the custom pass-through parameters for this session (issue #378).
+  // Intended to be called by the master-manifest request handler (#379) with the
+  // already-allowlist-filtered params. Passing a falsy value clears them back to
+  // an empty object so nothing extra is forwarded to the asset manager.
+  setCustomParams(customParams) {
+    this.customParams = customParams || {};
+  }
+
   async startPlayheadAsync() {
     debug(`[${this._sessionId}]: Playhead consumer started:`);
     debug(`[${this._sessionId}]: diffThreshold=${this.playheadDiffThreshold}`);
@@ -272,7 +329,7 @@ class Session {
           }
           // Apply external diff compensation if available.
           if (this.diffCompensation && this.diffCompensation > 0) {
-            const DIFF_COMPENSATION = (reqTickInterval * this.diffCompensationRate).toFixed(2) * 1000;
+            const DIFF_COMPENSATION = ((reqTickInterval * this.diffCompensationRate).toFixed(2) as any) * 1000;
             debug(`[${this._sessionId}]: Adding ${DIFF_COMPENSATION}msec to tickInterval to compensate for schedule diff (current=${this.diffCompensation}msec)`);
             tickInterval += (DIFF_COMPENSATION / 1000);
             this.diffCompensation -= DIFF_COMPENSATION;
@@ -312,7 +369,7 @@ class Session {
         }
       } catch (err) {
         debug(`[${this._sessionId}]: Playhead consumer crashed (1)`);
-        console.error(`[${this._sessionId}]: ${err.message}`);
+        console.error(`[${this._sessionId}]: ${err instanceof Error ? err.message : err}`);
         cloudWatchLog(!this.cloudWatchLogging, 'engine-session',
           { event: 'error', on: 'playhead', channel: this._sessionId, err: err });
         debug(err);
@@ -347,7 +404,7 @@ class Session {
       playheadStateMap[PlayheadState.CRASHED] = 'crashed';
       playheadStateMap[PlayheadState.STOPPED] = 'stopped';
 
-      const status = {
+      const status: any = {
         sessionId: this._sessionId,
         playhead: {
           state: playheadStateMap[state],
@@ -356,6 +413,10 @@ class Session {
         },
         slateInserted: sessionState.slateCount,
       };
+      if (this.event) {
+        // Surface the end-of-schedule state only in event mode (issue #362).
+        status.endOfSchedule = this.isEndOfSchedule;
+      }
       return status;
     }
   }
@@ -413,7 +474,7 @@ class Session {
     let waitTimeMs = 2000;
     for (let i = segments[Object.keys(segments)[0]].length - 1; 0 < i; i--) {
       if (segments[Object.keys(segments)[0]][i].duration) {
-        waitTimeMs = parseInt(1000 * (segments[Object.keys(segments)[0]][i].duration / 3), 10);
+        waitTimeMs = parseInt((1000 * (segments[Object.keys(segments)[0]][i].duration / 3)) as any, 10);
         break;
       }
     }
@@ -425,7 +486,7 @@ class Session {
       for (let i = audioSegments[groupId][lang].length - 1; 0 < i; i--) {
         const segment = audioSegments[groupId][lang][i];
         if (segment.duration) {
-          waitTimeMsAudio = parseInt(1000 * (segment.duration / 3), 10);
+          waitTimeMsAudio = parseInt((1000 * (segment.duration / 3)) as any, 10);
           break;
         }
       }
@@ -724,7 +785,7 @@ class Session {
       }
       return null;
     }
-    let newSessionState = {};
+    let newSessionState: any = {};
     if (sessionState.state === SessionState.VOD_NEXT_INITIATING || sessionState.state === SessionState.VOD_RELOAD_INITIATING) {
       if (isLeader) {
         const isOldVod = this._isOldVod(playheadState.playheadRef, currentVod.getDuration());
@@ -756,7 +817,11 @@ class Session {
       let playheadAudio;
       let playheadSubtitle;
 
-      playheadPosVideoMs = (await this._getCurrentPlayheadPosition()) * 1000;
+      // Pass the locally-updated vodMediaSeqVideo (leader incremented above) so
+      // playhead position reflects this tick's video segment, not the stale
+      // value still in Redis. Without this, audio/subtitle stay 1 segment
+      // behind video for the entire VOD lifetime.
+      playheadPosVideoMs = (await this._getCurrentPlayheadPosition(sessionState.vodMediaSeqVideo)) * 1000;
 
       if (this.use_demuxed_audio) {
         const audioSeqLastIdx = currentVod.getLiveMediaSequencesCount("audio") - 1;
@@ -1300,6 +1365,8 @@ class Session {
                   newVod.addMetadata(k, vodResponse.timedMetadata[k]);
                 })
               }
+              const firstVodAdAsset = await this._resolveAdBreakAsset();
+              this._addInterstitialMetadata(newVod, vodResponse.unixTs, firstVodAdAsset);
               currentVod = newVod;
               if (vodResponse.desiredDuration) {
                 try {
@@ -1414,7 +1481,7 @@ class Session {
           }
         } else {
           // Handle edge case where Leader loaded next vod but Follower remained in state=VOD_PLAYING
-          if ((this.prevMediaSeqOffset.video !== null) & (sessionState.mediaSeq !== this.prevMediaSeqOffset.video)) {
+          if (((this.prevMediaSeqOffset.video !== null) as any) & ((sessionState.mediaSeq !== this.prevMediaSeqOffset.video) as any)) {
             debug(`[${this._sessionId}]: state=VOD_PLAYING, current[${sessionState.vodMediaSeqVideo}], prev[${this.prevVodMediaSeq.video}], total[${currentVod.getLiveMediaSequencesCount()}]`);
             debug(`[${this._sessionId}]: mediaSeq offsets -> current[${sessionState.vodMediaSeqVideo}], prev[${this.prevVodMediaSeq.video}]`);
             // Allow Follower to clear VodCache...
@@ -1489,6 +1556,8 @@ class Session {
                   newVod.addMetadata(k, vodResponse.timedMetadata[k]);
                 })
               }
+              const nextVodAdAsset = await this._resolveAdBreakAsset();
+              this._addInterstitialMetadata(newVod, vodResponse.unixTs, nextVodAdAsset);
               this.produceEvent({
                 type: 'NEXT_VOD_SELECTED',
                 data: {
@@ -1592,6 +1661,14 @@ class Session {
           cloudWatchLog(!this.cloudWatchLogging, 'engine-session',
             { event: 'error', on: 'nextvod', channel: this._sessionId, err: err, vod: vodResponse });
           await this._sessionState.remove("nextVod");
+          if (this.event && err === END_OF_SCHEDULE) {
+            // Event mode + end of schedule (issue #362): the session has already
+            // recorded its `ended` state in `_getNextVod()`. Do NOT fall through to
+            // slate insertion (that is the non-event retry behaviour). ENDLIST
+            // manifest handling is out of scope here and belongs to #363/#364.
+            debug(`[${this._sessionId}]: end of schedule reached, keeping current VOD (no slate in event mode)`);
+            break;
+          }
           currentVod = await this._insertSlate(currentVod);
           if (!currentVod) {
             debug("No slate to load");
@@ -1767,15 +1844,306 @@ class Session {
     }
   }
 
+  /**
+   * The "no more VODs" contract (issue #362).
+   *
+   * `AssetManager.getNextVod()` is normally expected to resolve with a `vodResponse`
+   * that either carries a playable `uri`, or is a `{ type: 'gap' }` marker. The
+   * end-of-schedule signal is therefore the natural absence of both: the asset
+   * manager resolving with a falsy value (`null`/`undefined`) or with an object
+   * that has neither a `uri` nor `type === 'gap'` (e.g. an empty `{}`).
+   *
+   * This is detection only — deciding what the session does with the signal is
+   * handled by the caller (and, later, ENDLIST emission by #363).
+   */
+  /**
+   * Append #EXT-X-ENDLIST to a served media playlist when, in event mode, the
+   * schedule has ended (issue #363). Returns the manifest unchanged otherwise, so
+   * the tag never appears while content is still playing or when event mode is off.
+   * Idempotent: never adds a second ENDLIST if one is already present.
+   */
+  _appendEndlistIfEnded(m3u8) {
+    if (!m3u8 || !this.event || !this.isEndOfSchedule) {
+      return m3u8;
+    }
+    if (/#EXT-X-ENDLIST/.test(m3u8)) {
+      return m3u8;
+    }
+    const separator = m3u8.endsWith("\n") ? "" : "\n";
+    return m3u8 + separator + "#EXT-X-ENDLIST\n";
+  }
+
+  // Attach the HLS-interstitial EXT-X-DATERANGE metadata for a configured ad
+  // break to a freshly-created content VOD (issue #368). Reuses the existing
+  // per-VOD `addMetadata`/`rangeMetadata` daterange pathway (the same one the
+  // slate VODs use for id/start-date/planned-duration), so the tag is rendered
+  // by @eyevinn/hls-vodtolive at the VOD's start segment. The `class` and
+  // `x-asset-uri`/`x-asset-list` keys are uppercased and rendered as standard
+  // DATERANGE attributes by the vod lib's daterange formatter.
+  //
+  // Strictly gated on `this.adBreak.enabled`: when ad breaks are disabled (the
+  // default) this is a no-op and the served manifest is byte-identical to the
+  // pre-#368 output.
+  //
+  // Asset-source precedence (#370): when the caller has resolved a real ad
+  // asset from the configured ad-serving endpoint (`_resolveAdBreakAsset()`),
+  // it is passed in as `resolvedAsset` and its `assetUri`/`assetList` becomes
+  // the interstitial `X-ASSET-URI`/`X-ASSET-LIST`. When no endpoint asset was
+  // resolved (endpoint unconfigured, or a timeout/HTTP-error/malformed response
+  // that made the resolver fall back), we degrade to the #367 config reference
+  // (slate.uri preferred, then adServerUri) so the break still renders.
+  _addInterstitialMetadata(vod, timestamp, resolvedAsset) {
+    if (!vod || !this.adBreak || !this.adBreak.enabled) {
+      return;
+    }
+    const fallbackUri =
+      (this.adBreak.slate && this.adBreak.slate.uri) || this.adBreak.adServerUri;
+    const assetList = resolvedAsset && resolvedAsset.assetList;
+    const assetUri = (resolvedAsset && resolvedAsset.assetUri) || fallbackUri;
+    if (!assetList && !assetUri) {
+      return;
+    }
+    const startDate = new Date(
+      typeof timestamp === "number" ? timestamp : Date.now()
+    ).toISOString();
+    let plannedDuration = 0;
+    if (this.adBreak.slate && this.adBreak.slate.duration) {
+      const reps = this.adBreak.slate.repetitions || 1;
+      plannedDuration = (reps * this.adBreak.slate.duration) / 1000;
+    }
+    vod.addMetadata("class", "com.apple.hls.interstitial");
+    vod.addMetadata("id", `adbreak-${this._sessionId}-${startDate}`);
+    vod.addMetadata("start-date", startDate);
+    if (plannedDuration > 0) {
+      vod.addMetadata("planned-duration", plannedDuration);
+    }
+    // A resolved asset-list (multiple ads) takes precedence over a single URI
+    // and maps to X-ASSET-LIST; otherwise a single X-ASSET-URI is emitted.
+    if (assetList) {
+      vod.addMetadata("x-asset-list", assetList);
+    } else {
+      vod.addMetadata("x-asset-uri", assetUri);
+    }
+  }
+
+  // Ad-serving endpoint client (issue #370).
+  //
+  // When an ad break is enabled and an `adBreak.adServerUri` is configured,
+  // query that endpoint and map its JSON response to the interstitial asset
+  // reference consumed by `_addInterstitialMetadata`.
+  //
+  // Response contract (kept deliberately generic — no ad-product specifics):
+  //   { "assetUri": "<uri>" }                     -> single X-ASSET-URI
+  //   { "assetList": "<uri>" }                    -> an X-ASSET-LIST endpoint
+  //   { "assets": ["<uri>", ...] }                -> first entry -> X-ASSET-URI
+  // Returns `{ assetUri }` or `{ assetList }` on success, or `null` when there
+  // is nothing to resolve or on ANY failure.
+  //
+  // Log-and-continue (per CLAUDE.md): a timeout, non-2xx HTTP status, network
+  // error, or malformed/empty JSON body all resolve to `null` (never throw), so
+  // the caller falls back to the slate-only break and the session tick is never
+  // interrupted. Returns `null` immediately (no fetch) when the feature is
+  // disabled or no `adServerUri` is configured.
+  async _resolveAdBreakAsset(fetchImpl?: any) {
+    if (!this.adBreak || !this.adBreak.enabled || !this.adBreak.adServerUri) {
+      return null;
+    }
+    const doFetch = fetchImpl || fetch;
+    const uri = this.adBreak.adServerUri;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), AD_SERVER_TIMEOUT_MS);
+    try {
+      const response = await doFetch(uri, {
+        signal: controller.signal,
+        headers: { accept: "application/json" }
+      });
+      if (!response || !response.ok) {
+        debug(
+          `[${this._sessionId}]: ad-server endpoint ${uri} returned ` +
+          `${response ? response.status : "no response"}, falling back to slate`
+        );
+        return null;
+      }
+      const body = await response.json();
+      if (!body || typeof body !== "object") {
+        debug(`[${this._sessionId}]: ad-server endpoint ${uri} returned a non-object body, falling back to slate`);
+        return null;
+      }
+      if (typeof body.assetList === "string" && body.assetList) {
+        return { assetList: body.assetList };
+      }
+      if (typeof body.assetUri === "string" && body.assetUri) {
+        return { assetUri: body.assetUri };
+      }
+      if (Array.isArray(body.assets) && typeof body.assets[0] === "string" && body.assets[0]) {
+        return { assetUri: body.assets[0] };
+      }
+      debug(`[${this._sessionId}]: ad-server endpoint ${uri} response had no usable asset, falling back to slate`);
+      return null;
+    } catch (err) {
+      // Covers AbortError (timeout), network errors, and JSON parse errors.
+      debug(`[${this._sessionId}]: ad-server endpoint ${uri} request failed (${err instanceof Error ? err.message : err}), falling back to slate`);
+      return null;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  // Ad-break slate coordination (issue #369).
+  //
+  // Builds the slate VOD that plays as the ad-break filler and brackets it with
+  // the #368 interstitial EXT-X-DATERANGE. The slate is driven by the #367
+  // `adBreak.slate` config (uri/repetitions/duration): a `HLSRepeatVod` repeats
+  // the slate asset `repetitions` times, so the slate segment run spans exactly
+  // `repetitions * duration / 1000` seconds — the very same value
+  // `_addInterstitialMetadata` computes for PLANNED-DURATION. Attaching that
+  // interstitial metadata to this slate VOD (at `unixTs`, its first segment)
+  // makes the DATERANGE START-DATE fall on the break boundary and its
+  // PLANNED-DURATION span exactly the slate run. Downstream (SSAI or the
+  // client-side interstitial) the slate is what gets replaced with real ads.
+  //
+  // Strictly gated on `this.adBreak.enabled` AND a configured `adBreak.slate`:
+  // when either is absent this returns null and every existing (non-ad-break)
+  // slate path — the error/gap filler slate via `_loadSlate`/`_truncateSlate` —
+  // is left completely untouched.
+  _buildAdBreakSlate(afterVod, unixTs, injectSlateLoaders) {
+    if (
+      !this.adBreak ||
+      !this.adBreak.enabled ||
+      !this.adBreak.slate ||
+      !this.adBreak.slate.uri
+    ) {
+      return Promise.resolve(null);
+    }
+    const slate = this.adBreak.slate;
+    const reps = slate.repetitions || 1;
+    const timestamp = typeof unixTs === "number" ? unixTs : Date.now();
+    // `injectSlateLoaders` lets callers (tests) feed the repeated slate asset
+    // from fixtures instead of the network; production passes nothing so the
+    // slate is fetched from `slate.uri` as usual. It may also carry a `fetch`
+    // stub used to resolve the ad-break asset (#370) without real network.
+    const { master, media, fetch: fetchImpl } = injectSlateLoaders || {};
+    // Resolve the real ad asset from the configured endpoint before rendering
+    // the slate so the interstitial DATERANGE can reference it; on any failure
+    // this yields null and the tag degrades to the slate reference.
+    return this._resolveAdBreakAsset(fetchImpl).then((resolvedAsset) => new Promise((resolve, reject) => {
+      try {
+        const slateVod = new HLSRepeatVod(slate.uri, reps);
+        let hlsVod;
+        slateVod
+          .load(master, media)
+          .then(() => {
+            const hlsOpts = {
+              sequenceAlwaysContainNewSegments: this.alwaysNewSegments,
+              forcedDemuxMode: this.use_demuxed_audio,
+              dummySubtitleEndpoint: this.dummySubtitleEndpoint,
+              subtitleSliceEndpoint: this.subtitleSliceEndpoint,
+              shouldContainSubtitles: this.use_vtt_subtitles,
+              expectedSubtitleTracks: this._subtitleTracks,
+              alwaysMapBandwidthByNearest: this.alwaysMapBandwidthByNearest,
+              skipSerializeMediaSequences: this.partialStoreHLSVod,
+              calculatePDT: this.rollingPDT
+            };
+            hlsVod = new HLSVod(slate.uri, null, timestamp, null, m3u8Header(this._instanceId), hlsOpts);
+            // Bracket exactly the slate: the interstitial DATERANGE lands on the
+            // slate's first segment (START-DATE = break boundary) and its
+            // PLANNED-DURATION equals the slate run length. The asset reference
+            // is the endpoint-resolved ad (or the slate fallback) from #370.
+            this._addInterstitialMetadata(hlsVod, timestamp, resolvedAsset);
+            const slateMediaManifestLoader = (bw) => {
+              let mediaManifestStream = new Readable();
+              // `HLSRepeatVod` prepends an EXT-X-DISCONTINUITY before the first
+              // repeated segment. That leading marker would occupy the VOD's
+              // first-segment slot and displace the interstitial DATERANGE
+              // (which the vod lib attaches only to the true first segment),
+              // breaking the "tag brackets exactly the slate" alignment. Drop
+              // that single leading discontinuity so the slate run begins
+              // cleanly at the break boundary and the DATERANGE lands on it.
+              const slateManifest = slateVod
+                .getMediaManifest(bw)
+                .replace(/(#EXT-X-MEDIA-SEQUENCE:\d+\r?\n)#EXT-X-DISCONTINUITY\r?\n/, "$1");
+              mediaManifestStream.push(slateManifest);
+              mediaManifestStream.push(null);
+              return mediaManifestStream;
+            };
+            if (this.use_demuxed_audio) {
+              const slateAudioManifestLoader = (audioGroupId, audioLanguage) => {
+                let mediaManifestStream = new Readable();
+                mediaManifestStream.push(slateVod.getAudioManifest(audioGroupId, audioLanguage));
+                mediaManifestStream.push(null);
+                return mediaManifestStream;
+              };
+              let subtitleManifestLoader;
+              if (this.use_vtt_subtitles && this._subtitleTracks) {
+                subtitleManifestLoader = (groupId, language) => {
+                  let mediaManifestStream = new Readable();
+                  mediaManifestStream.push(slateVod.getSubtitleManifest(groupId, language));
+                  mediaManifestStream.push(null);
+                  return mediaManifestStream;
+                };
+              }
+              if (afterVod) {
+                return hlsVod.loadAfter(afterVod, master || null, slateMediaManifestLoader, slateAudioManifestLoader, subtitleManifestLoader);
+              }
+              return hlsVod.load(master || null, slateMediaManifestLoader, slateAudioManifestLoader, subtitleManifestLoader);
+            }
+            if (afterVod) {
+              return hlsVod.loadAfter(afterVod, master || null, slateMediaManifestLoader);
+            }
+            return hlsVod.load(master || null, slateMediaManifestLoader);
+          })
+          .then(() => {
+            resolve(hlsVod);
+          })
+          .catch((err) => {
+            debug(err);
+            reject(err);
+          });
+      } catch (err) {
+        reject(err);
+      }
+    }));
+  }
+
+  _isEndOfScheduleSignal(nextVod) {
+    if (!nextVod) {
+      return true;
+    }
+    if (nextVod.uri) {
+      return false;
+    }
+    if (nextVod.type === 'gap') {
+      return false;
+    }
+    return true;
+  }
+
   _getNextVod() {
     return new Promise((resolve, reject) => {
+      // Post-end lock-down (issue #364): once the schedule has ended in event
+      // mode, never ask the asset manager for another VOD. The session keeps
+      // serving its final, ENDLIST-terminated playlist, so re-querying would be
+      // wasteful and could reset the ended state on a late/looping asset manager.
+      if (this.event && this.isEndOfSchedule) {
+        debug(`[${this._sessionId}]: schedule already ended (event mode), not requesting a new VOD`);
+        return reject(END_OF_SCHEDULE);
+      }
+
       let nextVodPromise;
 
-      nextVodPromise = this._assetManager.getNextVod({
+      // Forward per-session custom pass-through params (issue #378) when present.
+      // Only include the field if at least one param has been set, so existing
+      // IAssetManager implementations that don't expect it are unaffected.
+      const vodRequest: any = {
         sessionId: this._sessionId,
         category: this._category,
         playlistId: this._sessionId
-      });
+      };
+      if (this.customParams && Object.keys(this.customParams).length > 0) {
+        vodRequest.customParams = this.customParams;
+      }
+
+      nextVodPromise = this._assetManager.getNextVod(vodRequest);
 
       nextVodPromise.then(nextVod => {
         if (nextVod && nextVod.uri) {
@@ -1790,6 +2158,23 @@ class Session {
             title: 'GAP of ' + Math.floor(nextVod.desiredDuration) + ' sec',
           };
           resolve(nextVod);
+        } else if (this.event && this._isEndOfScheduleSignal(nextVod)) {
+          // Event mode: no new VOD was received from the asset manager, so the
+          // schedule has ended. Record an internal end-of-schedule state and log
+          // it, then reject with a distinguishable marker. No slate/retry here —
+          // that behaviour is deliberately reserved for non-event mode. ENDLIST
+          // manifest emission is out of scope for this issue (#363).
+          this.isEndOfSchedule = true;
+          debug(`[${this._sessionId}]: end of schedule detected (event mode), no new VOD received from asset manager`);
+          cloudWatchLog(!this.cloudWatchLogging, 'engine-session',
+            { event: 'endOfSchedule', channel: this._sessionId });
+          this.produceEvent({
+            type: 'END_OF_SCHEDULE',
+            data: {
+              sessionId: this._sessionId,
+            }
+          });
+          reject(END_OF_SCHEDULE);
         } else {
           console.error("Invalid VOD:", nextVod);
           reject("Invalid VOD from asset manager")
@@ -1799,7 +2184,7 @@ class Session {
     });
   }
 
-  _loadSlate(afterVod, reps, unixTs) {
+  _loadSlate(afterVod: any, reps?: any, unixTs?: any) {
     return new Promise((resolve, reject) => {
       try {
         const slateVod = new HLSRepeatVod(this.slateUri, reps || this.slateRepetitions);
@@ -1870,10 +2255,10 @@ class Session {
     });
   }
 
-  _truncateVod(vodResponse) {
+  _truncateVod(vodResponse: any): Promise<any> {
     return new Promise((resolve, reject) => {
       try {
-        const options = {};
+        const options: any = {};
         if (vodResponse.startOffset) {
           options.offset = vodResponse.startOffset / 1000;
         }
@@ -1915,7 +2300,7 @@ class Session {
     });
   }
 
-  _truncateSlate(afterVod, requestedDuration, vodUri, unixTs) {
+  _truncateSlate(afterVod: any, requestedDuration: any, vodUri: any, unixTs?: any): Promise<any> {
     return new Promise((resolve, reject) => {
       let nexVodUri = null;
       try {
@@ -2032,7 +2417,7 @@ class Session {
     });
   }
 
-  _getFirstDuration(manifest) {
+  _getFirstDuration(manifest: any): Promise<any> {
     return new Promise((resolve, reject) => {
       try {
         const parser = m3u8.createStream();
@@ -2068,12 +2453,21 @@ class Session {
     return 0;
   }
 
-  async _getCurrentPlayheadPosition() {
-    const sessionState = await this._sessionState.getValues(["vodMediaSeqVideo"]);
+  async _getCurrentPlayheadPosition(overrideVodMediaSeqVideo?: any) {
+    // Caller can pass the in-progress local vodMediaSeqVideo to avoid the Redis
+    // round-trip and the race where the leader has incremented its local value
+    // but hasn't written it to Redis yet (incrementAsync writes happen later via
+    // a parallel Promise.all). Falling back to Redis preserves the old behavior
+    // for callers like startPlayheadAsync that run after incrementAsync.
+    let vodMediaSeqVideo = overrideVodMediaSeqVideo;
+    if (vodMediaSeqVideo === undefined) {
+      const sessionState = await this._sessionState.getValues(["vodMediaSeqVideo"]);
+      vodMediaSeqVideo = sessionState.vodMediaSeqVideo;
+    }
     const currentVod = await this._sessionState.getCurrentVod();
     const playheadPositions = currentVod.getPlayheadPositions();
-    debug(`[${this._sessionId}]: Current playhead position (${sessionState.vodMediaSeqVideo}): ${roundToThreeDecimals(playheadPositions[sessionState.vodMediaSeqVideo])}`);
-    return playheadPositions[sessionState.vodMediaSeqVideo];
+    debug(`[${this._sessionId}]: Current playhead position (${vodMediaSeqVideo}): ${roundToThreeDecimals(playheadPositions[vodMediaSeqVideo])}`);
+    return playheadPositions[vodMediaSeqVideo];
   }
 
   async _getAudioPlayheadPosition(seqIdx) {
@@ -2096,7 +2490,7 @@ class Session {
     return playheadPositions[seqIdx];
   }
 
-  _getLastDuration(manifest) {
+  _getLastDuration(manifest: any): Promise<any> {
     return new Promise((resolve, reject) => {
       try {
         const parser = m3u8.createStream();
@@ -2345,6 +2739,11 @@ class Session {
         );
         this.prevVodMediaSeq[variantType] = playheadState[MSDKeys.vodMediaSeq];
         this.prevMediaSeqOffset[variantType] = playheadState[MSDKeys.mediaSeq];
+        // In event mode, once the schedule has ended (issue #363) terminate the
+        // served media playlist with #EXT-X-ENDLIST so players stop reloading.
+        // Applied uniformly to video, demuxed-audio and subtitle variants. The tag
+        // is never appended while content is still playing (isEndOfSchedule=false).
+        m3u8 = this._appendEndlistIfEnded(m3u8);
         return m3u8;
       } catch (err) {
         logerror(this._sessionId, err);