prismcast 1.10.2 → 1.11.0

package/dist/streaming/hls.js

@@ -1,23 +1,19 @@
-/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
- *
- * hls.ts: HLS streaming request handlers for PrismCast.
- */
-import { getEffectiveCaptureCodec, isCaptureHardwareAccelerated } from "./codec.js";
 import { LOG, formatError, runWithStreamContext, startTimer } from "../utils/index.js";
-import { StreamSetupError, createPageWithCapture, generateStreamId, setupStream } from "./setup.js";
-import { createHLSState, getAllStreams, getNextStreamId, getStream, getStreamCount, registerStream, updateLastAccess } from "./registry.js";
+import { StreamSetupError, createPageWithCapture, generateStreamId, reestablishChannelManifest, setupStream, validateStreamUrl } from "./setup.js";
+import { buildProbeCacheStamp, clearProbeCache } from "../native/probe.js";
+import { cancelPrerollTimer, createHLSState, getAllStreams, getNextStreamId, getStream, getStreamCount, registerStream, updateLastAccess } from "./registry.js";
 import { createInitialStreamStatus, emitStreamAdded } from "./statusEmitter.js";
 import { deleteResumeData, getResumeSegmentIndex, peekResumeData } from "./hlsResume.js";
 import { emitCurrentSystemStatus, isLoginModeActive, unregisterManagedPage } from "../browser/index.js";
 import { generatePrerollPlaylist, getPrerollCodec, getPrerollSegmentCount, isPrerollReady } from "./preroll.js";
 import { getAllChannels, getChannelLogo, isPredefinedChannelDisabled } from "../config/userChannels.js";
-import { getAudioPlaylist, getAudioSegment, getInitSegment, getPlaylist, getSegment, getVideoPlaylist, waitForPlaylist } from "./hlsSegments.js";
+import { getAudioPlaylist, getAudioSegment, getInitSegment, getNamedInitSegment, getPlaylist, getSegment, getVideoPlaylist, waitForPlaylist } from "./hlsSegments.js";
 import { getAuthDomainForChannel, getResolvedChannel, getServiceTagForChannel, isChannelAvailableByService, resolveServiceKey } from "../config/services.js";
 import { getChannelStreamId, isTerminationInitiated, setChannelStreamId, terminateStream } from "./lifecycle.js";
+import { getEffectiveCaptureCodec, isCaptureHardwareAccelerated } from "./codec.js";
 import { markChannelFailure, markChannelSuccess } from "../config/health.js";
 import { CONFIG } from "../config/index.js";
 import { attemptNativeStreaming } from "../native/index.js";
-import { clearProbeCache } from "../native/probe.js";
 import { createFMP4Segmenter } from "./fmp4Segmenter.js";
 import { createHash } from "node:crypto";
 import { getProviderBySlug } from "../browser/channelSelection.js";
@@ -41,14 +37,15 @@ import { triggerShowNameUpdate } from "./showInfo.js";
  *   the proxy takes over. Otherwise, createCaptureSegmenter() creates the fMP4 segmenter and pipes the capture stream. When the first real playlist arrives
  *   (from either the segmenter or native proxy), the preroll timer is cancelled and the client receives live content on the next poll.
  *
- * Shared streams: If multiple clients request the same channel (or the same ad-hoc URL with the same profile), they share one stream. The first client triggers
- * stream creation, and subsequent clients get the existing playlist and segments. Ad-hoc streams are identified by a synthetic key ("play-<hash>") derived from the
- * URL and profile, allowing them to use the same channelToStreamId deduplication mechanism as predefined channels.
+ * Shared streams: If multiple clients request the same channel (or the same ad-hoc URL with the same profile, selector, clickToPlay, and clickSelector), they share
+ * one stream. The first client triggers stream creation, and subsequent clients get the existing playlist and segments. Ad-hoc streams are identified by a
+ * synthetic key ("play-<hash>") derived from the URL, profile, selector, clickToPlay, and clickSelector, allowing them to use the same channelToStreamId
+ * deduplication mechanism as predefined channels.
  */
 // Delay before seeding the preroll playlist in milliseconds. If stream setup completes before this timer fires, the preroll is skipped and the client receives real
 // content directly. This ensures fast-tuning services (native HLS at 2-3s, most capture services at 4-7s) never see preroll, while slow services (Xfinity/Cox at
 // 13-15s) get preroll content after the delay to prevent HTTP timeouts.
-const PREROLL_DELAY_MS = 9_000;
+const PREROLL_DELAY_MS = 9000;
 /**
  * Builds the onError/onStop callbacks for createFMP4Segmenter. Both callbacks share the same termination chain (skip-if-already-terminating guard, log error,
  * terminate stream, emit current system status); the only differences between callsites are the log-message and termination-reason suffixes used to mark the
@@ -83,8 +80,8 @@ function buildSegmenterTerminationHandlers(streamId, channelName, options = {})
 // Login mode error body used by both validateChannel() and handlePlayStream() to ensure consistent response format.
 const LOGIN_MODE_BODY = { error: "Login in progress", message: "Please complete authentication before starting new streams." };
 /**
- * Validates a channel name for streaming. Performs all fast, synchronous checks: disabled status, service resolution, channel lookup, and login mode. Returns a
- * discriminated union so callers can handle success and failure without coupling to Express response objects.
+ * Validates a channel name for streaming. Performs all fast, synchronous checks: disabled status, service resolution, channel lookup, service-filter availability,
+ * and login mode. Returns a discriminated union so callers can handle success and failure without coupling to Express response objects.
  *
  * This is extracted from ensureChannelStream() so it can be called by both HLS and MPEG-TS code paths without duplicating the validation logic.
  *
@@ -107,7 +104,8 @@ export function validateChannel(channelName) {
     if (!channel && (resolvedKey !== channelName)) {
         LOG.warn("Service '%s' not found for channel '%s'. Using default service.", resolvedKey, channelName);
     }
-    // Runtime check needed even though TypeScript thinks channel is always defined (Record indexing quirk).
+    // effectiveChannel may be undefined: getResolvedChannel can return undefined and the getAllChannels() fallback is also possibly-undefined under
+    // noUncheckedIndexedAccess, so we guard before use.
     if (!effectiveChannel) {
         return { body: "Channel not found.", statusCode: 404, valid: false };
     }
@@ -139,6 +137,34 @@ export function sendValidationError(validation, res) {
         res.status(validation.statusCode).send(validation.body);
     }
 }
+// Capacity Reservation.
+/**
+ * Pure predicate for the concurrent-stream capacity decision. Returns true when a new stream may be admitted given the current active count and the configured
+ * limit. Extracted as a standalone function so the boundary arithmetic is pinned by a unit test without driving a browser. The count passed in must be the count
+ * BEFORE the new stream's pending entry is registered, so the new stream is naturally excluded from its own capacity check; admitting the final slot
+ * (active === maxConcurrent - 1) returns true.
+ * @param activeCount - Number of streams currently registered, excluding the stream being admitted.
+ * @param maxConcurrent - The configured concurrent-stream limit.
+ * @returns True if a slot is available for the new stream.
+ */
+export function hasStreamCapacity(activeCount, maxConcurrent) {
+    return activeCount < maxConcurrent;
+}
+/**
+ * Reserves a concurrent-stream slot at the registration site - the single source of truth for the capacity decision across both the preroll path
+ * (ensureChannelStream) and the blocking path (initializeStream). It evaluates capacity against the current registry count BEFORE the new stream's pending entry is
+ * registered, so the new stream is excluded from its own check. setupStream never re-checks capacity; this registration-site reservation is the sole authority for
+ * the decision, so at the boundary (one slot free) the registration-site gate admits the stream and no downstream check can double-count it against its own slot.
+ * When the limit is reached, a single idle stream is reclaimed to free a slot; reservation succeeds when either a slot was already free or one was reclaimed.
+ * @returns True if a slot was reserved (room existed or an idle stream was reclaimed), false if the limit is reached and no idle stream could be reclaimed.
+ */
+function reserveStreamSlot() {
+    if (hasStreamCapacity(getStreamCount(), CONFIG.streaming.maxConcurrentStreams)) {
+        return true;
+    }
+    // At capacity. Reclaim the longest-idle stream to make room; reservation succeeds only if one was actually freed.
+    return reclaimIdleStream();
+}
 // Public Endpoint Handlers.
 /**
  * Ensures a stream is running for a channel. If no stream exists, registers a pending stream with a preroll playlist (when available) and launches async setup. If a
@@ -174,15 +200,15 @@ export async function ensureChannelStream(channelName, req, res) {
     // stream setup runs asynchronously. When the preroll is not available (FFmpeg missing or failed), fall back to blocking initialization.
     const prerollCodec = getPrerollCodec();
     if (isPrerollReady(prerollCodec)) {
-        // Check capacity before registering the pending entry. The pending entry occupies a registry slot, so registering it at max capacity would cause setupStream's
-        // capacity check to reject - after we've already returned a preroll playlist to the client. By gating here, we can still send a proper 503 error response.
-        if (getStreamCount() >= CONFIG.streaming.maxConcurrentStreams) {
-            if (!reclaimIdleStream()) {
-                res.setHeader("Retry-After", "10");
-                res.setHeader("X-HDHomeRun-Error", "All Tuners In Use");
-                res.status(503).send("Maximum concurrent streams (" + String(CONFIG.streaming.maxConcurrentStreams) + ") reached. Try again later.");
-                return null;
-            }
+        // Reserve a capacity slot before registering the pending entry. The pending entry occupies a registry slot the instant it is registered, so the capacity
+        // decision must happen here - while the new stream is still excluded from the count - to avoid a later self-counting check rejecting it after the client has
+        // already received a preroll playlist. reserveStreamSlot is the single source of truth for this decision and reclaims an idle stream when at the limit. On
+        // failure we send a proper 503 here, before any registration or preroll response.
+        if (!reserveStreamSlot()) {
+            res.setHeader("Retry-After", "10");
+            res.setHeader("X-HDHomeRun-Error", "All Tuners In Use");
+            res.status(503).send("Maximum concurrent streams (" + String(CONFIG.streaming.maxConcurrentStreams) + ") reached. Try again later.");
+            return null;
         }
         const clientAddress = req.ip ?? req.socket.remoteAddress ?? null;
         const pending = registerPendingStream(channelName, validation.channel, clientAddress, req, prerollCodec);
@@ -258,8 +284,10 @@ export function handleHLSSegment(req, res) {
         sendSegment(initSegment, "init.mp4", res);
         return;
     }
-    // Handle media segments (.m4s and .ts). Check both video and audio segment stores.
-    const segment = getSegment(streamId, segmentName) ?? getAudioSegment(streamId, segmentName);
+    // Handle media segments (.m4s and .ts) and the named initialization segments a native fMP4 relay serves. Check the video and audio segment stores, then the
+    // relay's per-track init store - a name the relay minted for an upstream #EXT-X-MAP reference resolves here rather than through the literal branch above,
+    // which belongs to the capture path's single init slot.
+    const segment = getSegment(streamId, segmentName) ?? getAudioSegment(streamId, segmentName) ?? getNamedInitSegment(streamId, segmentName);
     if (!segment) {
         res.status(404).send("Segment not found.");
         return;
@@ -307,13 +335,13 @@ export function handleHLSVariantPlaylist(req, res) {
 }
 // Ad-Hoc Streaming.
 /**
- * Handles ad-hoc stream requests for arbitrary URLs. Generates a deterministic synthetic key from the URL and profile, starts a stream if none exists, and redirects
- * to the standard HLS playlist path. This enables streaming URLs that are not predefined as channels.
+ * Handles ad-hoc stream requests for arbitrary URLs. Generates a deterministic synthetic key from the URL, profile, selector, clickToPlay, and clickSelector, starts
+ * a stream if none exists, and redirects to the standard HLS playlist path. This enables streaming URLs that are not predefined as channels.
  *
- * The synthetic key includes the profile so that the same URL with different profiles produces separate streams. The "play-" prefix prevents collisions with
- * predefined channel names.
+ * The synthetic key includes the profile, selector, clickToPlay, and clickSelector so that the same URL with different options produces separate streams. The
+ * "play-" prefix prevents collisions with predefined channel names.
  *
- * Route: GET /play?url=<url>&profile=<name>
+ * Route: GET /play?url=<url>&profile=<name>&selector=<selector>&clickToPlay=<bool>&clickSelector=<selector>
  *
  * @param req - Express request object.
  * @param res - Express response object.
@@ -342,6 +370,18 @@ export async function handlePlayStream(req, res) {
         res.status(503).json(LOGIN_MODE_BODY);
         return;
     }
+    /* Reject a URL that cannot work before anything is reserved on its behalf. initializeStream takes a concurrent-stream slot and registers a pending entry
+     * before the deeper validation inside setupStream runs, so a URL destined to be refused would otherwise hold capacity a real stream could need, and would
+     * reach the redirect probe that issues an outbound request on its behalf first. The placement is deliberate in both directions: ahead of initializeStream so
+     * nothing is reserved, and behind the login-mode check so a URL submitted during login still answers 503 rather than 400. The same validator also runs inside
+     * setupStream, which is where channel-based streams meet it; one shared rule called from each entry point, not a second copy of the rule.
+     */
+    const validation = validateStreamUrl(url);
+    if (!validation.valid) {
+        LOG.error("Invalid URL requested: %s - %s.", url, validation.reason ?? "Unknown error");
+        res.status(400).send(validation.reason ?? "Invalid URL.");
+        return;
+    }
     // Capture client IP for Channels DVR API integration.
     const clientAddress = req.ip ?? req.socket.remoteAddress ?? null;
     // Start a new ad-hoc stream. initializeStream handles pending registration, capture setup, segmenter creation, and event emission.
@@ -381,7 +421,7 @@ async function sendPlaylistResponse(streamId, clientAddress, res) {
     // The playlist may not be populated yet if the deferred preroll timer hasn't fired and the segmenter hasn't produced content. Wait for the playlistReady promise
     // which resolves when either source provides a playlist. The 30-second timeout covers pathological cases like setup hanging.
     if (!playlist) {
-        const ready = await waitForPlaylist(streamId, 30_000);
+        const ready = await waitForPlaylist(streamId, 30000);
         if (ready) {
             playlist = getPlaylist(streamId);
         }
@@ -431,18 +471,6 @@ function sendSegment(data, segmentName, res) {
     res.send(data);
 }
 // Stream Lifecycle.
-/**
- * Cleans up resources from a stream that was terminated during setup before the segmenter was stored in the registry. This handles the rare race condition where
- * another code path (e.g., circuit breaker) calls terminateStream() between registerStream() and the segmenter assignment.
- *
- * terminateStream() already cleaned up the page, monitor, channel mapping, and registry entry. We only need to stop the segmenter, which was created after
- * termination occurred and therefore wasn't cleaned up.
- * @param segmenter - The orphaned fMP4 segmenter instance to stop.
- */
-function cleanupOrphanedSetup(segmenter) {
-    LOG.debug("streaming:setup", "Stream was terminated during setup. Stopping orphaned segmenter.");
-    segmenter.stop();
-}
 // Maps vertical resolution heights to standard display labels. Used by formatNativeQuality() to convert "1920x1080" -> "1080p".
 const RESOLUTION_LABELS = { "1080": "1080p", "2160": "4K", "360": "360p", "480": "480p", "720": "720p" };
 /**
@@ -506,26 +534,18 @@ function createTabReplacementHandler(numericStreamId, streamId, channelName, url
         // Get the current init segment, segment index, and per-track timestamps from the old segmenter before stopping it. The init segment enables discontinuity
         // suppression when codec parameters are unchanged, the segment index allows the new segmenter to continue numbering, and the track timestamps ensure monotonic
         // baseMediaDecodeTime across capture restarts.
-        const currentInitSegment = stream.segmenter?.getInitSegment();
-        const currentInitVersion = stream.segmenter?.getInitVersion() ?? 0;
-        const currentSegmentIndex = stream.segmenter?.getSegmentIndex() ?? 0;
-        const currentSessionStats = stream.segmenter?.getSessionStats();
-        const currentTrackTimestamps = stream.segmenter?.getTrackTimestamps();
-        // Destroy the OLD capture stream first. This MUST happen before closing the page to ensure chrome.tabCapture releases the capture. Without this, the new
-        // getStream() call would hang with "Cannot capture a tab with an active stream" error.
-        if (stream.rawCaptureStream && !stream.rawCaptureStream.destroyed) {
-            LOG.debug("recovery:tab", "Destroying old capture stream for tab replacement.");
-            stream.rawCaptureStream.destroy();
-        }
-        // Stop the current segmenter if it exists.
-        if (stream.segmenter) {
-            LOG.debug("recovery:tab", "Stopping current segmenter for tab replacement.");
-            stream.segmenter.stop();
-        }
-        // Stop the FFmpeg process if it exists.
-        if (stream.ffmpegProcess) {
-            LOG.debug("recovery:tab", "Stopping FFmpeg process for tab replacement.");
-            stream.ffmpegProcess.kill();
+        const oldSegmenter = stream.captureSession?.segmenter;
+        const currentInitSegment = oldSegmenter?.getInitSegment();
+        const currentInitVersion = oldSegmenter?.getInitVersion() ?? 0;
+        const currentSegmentIndex = oldSegmenter?.getSegmentIndex() ?? 0;
+        const currentSessionStats = oldSegmenter?.getSessionStats();
+        const currentTrackTimestamps = oldSegmenter?.getTrackTimestamps();
+        // Dispose the OLD capture pipeline. The CaptureSession kills the FFmpeg child first (setting its shuttingDown flag before the capture stream's EOF can reach
+        // FFmpeg's stdin), then destroys the capture stream (which MUST happen before the old page is closed below, so chrome.tabCapture releases the capture and the
+        // new getStream() does not hang with "Cannot capture a tab with an active stream"), then stops the segmenter. The new pipeline is constructed fresh further down.
+        if (stream.captureSession) {
+            LOG.debug("recovery:tab", "Disposing old capture pipeline for tab replacement.");
+            stream.captureSession.dispose();
         }
         // Close the current page. The page may be null for pending entries whose async setup has not yet completed.
         const oldPage = stream.page;
@@ -544,6 +564,7 @@ function createTabReplacementHandler(numericStreamId, streamId, channelName, url
         try {
             captureResult = await createPageWithCapture({
                 comment: metadataComment,
+                numericStreamId,
                 onFFmpegError: (error) => {
                     LOG.error("FFmpeg error during tab replacement recovery: %s.", formatError(error));
                     onCircuitBreak();
@@ -559,6 +580,21 @@ function createTabReplacementHandler(numericStreamId, streamId, channelName, url
             return null;
         }
         LOG.debug("timing:tab", "New page with capture created. (+%sms)", tabElapsed());
+        // Re-check the stream before adopting the fresh resources. The awaited createPageWithCapture above yields the event loop, so the stream can terminate mid-await;
+        // the entry writes below would then attach the new page and capture session to an entry that termination already disposed, orphaning both. Tear the fresh resources
+        // down in the same order the old-pipeline teardown above uses - dispose the capture session first so chrome.tabCapture releases cleanly, then unregister the
+        // managed page, then close it - and abandon the replacement.
+        if (!getStream(numericStreamId)) {
+            captureResult.captureSession.dispose();
+            unregisterManagedPage(captureResult.page);
+            if (!captureResult.page.isClosed()) {
+                captureResult.page.close().catch((error) => {
+                    LOG.debug("recovery:tab", "Page close error during aborted tab replacement: %s.", formatError(error));
+                });
+            }
+            LOG.debug("recovery:tab", "Stream %s terminated during tab replacement - discarded the fresh page and capture session.", streamId);
+            return null;
+        }
         // Create a new segmenter for the new capture stream. Continue from the current segment index for playlist continuity, pass the per-track timestamp counters
         // for monotonic baseMediaDecodeTime, and mark the first segment with a discontinuity tag so clients know the stream parameters may have changed.
         const newSegmenter = createFMP4Segmenter({
@@ -571,13 +607,11 @@ function createTabReplacementHandler(numericStreamId, streamId, channelName, url
             startingSegmentIndex: currentSegmentIndex,
             streamId: numericStreamId
         });
-        // Pipe the new capture to the new segmenter.
-        newSegmenter.pipe(captureResult.captureStream);
-        // Update the registry entry with the new resources.
-        stream.ffmpegProcess = captureResult.ffmpegProcess;
+        // Wire the new segmenter into the new capture session (attachSegmenter pipes the session's capture output into it), then install the session and page on the
+        // registry entry.
+        captureResult.captureSession.attachSegmenter(newSegmenter);
+        stream.captureSession = captureResult.captureSession;
         stream.page = captureResult.page;
-        stream.rawCaptureStream = captureResult.rawCaptureStream;
-        stream.segmenter = newSegmenter;
         LOG.info("Tab replacement complete. New capture started with segment continuity.");
         LOG.debug("timing:tab", "Tab replacement complete. Total: %sms.", tabElapsed());
         return {
@@ -598,6 +632,13 @@ function createTabReplacementHandler(numericStreamId, streamId, channelName, url
  */
 export async function initializeStream(options) {
     const { channel, channelName, url } = options;
+    // Reserve a capacity slot before registering the pending entry. This is the same single-source-of-truth gate used by the preroll path, applied here so the
+    // blocking callers (pretune, MPEG-TS, ad-hoc play) gate capacity at the registration site - while the new stream is still excluded from the count - rather than
+    // relying on a downstream self-counting check that would double-count this stream against its own slot and spuriously reject the final slot. On failure we throw
+    // the same StreamSetupError(503) the callers already handle, so their error responses and HDHomeRun headers are unchanged.
+    if (!reserveStreamSlot()) {
+        throw new StreamSetupError("Concurrent stream limit reached.", 503, "Maximum concurrent streams (" + String(CONFIG.streaming.maxConcurrentStreams) + ") reached. Try again later.");
+    }
     // Allocate stream IDs. For predefined channels, use the channel name for the stream ID prefix. For ad-hoc streams, omit it so generateStreamId derives a prefix
     // from the URL (e.g., "foxsports-abc123"), which is more informative in logs.
     const numericStreamId = getNextStreamId();
@@ -636,7 +677,8 @@ function registerPendingStream(channelName, channel, clientAddress, req, codec)
     const baseUrl = protocol + "://" + (host ?? fallbackHost);
     // Create HLS state with a deferred preroll timer. The timer fires after PREROLL_DELAY_MS - if stream setup hasn't completed by then, preroll is seeded and the
     // playlist response is unblocked. For resume streams, the preroll's MEDIA-SEQUENCE is offset by the saved segment index so it continues from the prior session's
-    // sequence range. The timer is cancelled by completeStreamSetup() when the segmenter or native proxy is created, preventing races.
+    // sequence range. The timer is disarmed through cancelPrerollTimer() once real content arrives or preroll state is otherwise invalidated, so it cannot fire against
+    // state that has moved on.
     const hls = createHLSState();
     // Snapshot the resume segment index once at registration. Both the preroll timer callback and completeStreamSetup() use this single snapshot, eliminating the TTL
     // race that would occur if each read the resume map independently at different times.
@@ -673,9 +715,9 @@ function createPendingEntry(options) {
     const { channel, channelName, hls, numericStreamId, streamIdStr, url } = options;
     registerStream({
         captureCodec: null,
+        captureSession: null,
         channelName: channel?.name ?? null,
         clientAddress: options.clientAddress ?? null,
-        ffmpegProcess: null,
         hardwareAccelerated: false,
         hls,
         id: numericStreamId,
@@ -683,17 +725,18 @@ function createPendingEntry(options) {
             lastPlaylistRequest: Date.now(),
             storeKey: channelName
         },
+        monitor: null,
         mpegTsClientCount: 0,
         nativeBandwidth: 0,
+        nativeContainer: null,
         nativeProxy: null,
         nativeResolution: null,
         page: null,
         preTuned: options.preTuned ?? false,
+        probeIdentity: null,
         profile: null,
-        rawCaptureStream: null,
-        segmenter: null,
+        reestablishManifest: null,
         startTime: options.streamStartTime ?? new Date(),
-        stopMonitor: null,
         streamIdStr,
         streamingMode: "capture",
         url
@@ -730,8 +773,9 @@ function handleSetupFailure(numericStreamId, channelName, channel, error, logErr
     }
 }
 /**
- * Attempts to upgrade the stream from capture to native HLS. Finalizes the manifest interception, probes the manifest, creates a native proxy, stops the capture
- * pipeline, suppresses page audio, and updates the registry entry. Returns the codec and formatted quality string on success, or null if native is not viable.
+ * Attempts to upgrade the stream from capture to native HLS. Consumes the manifest interception already finalized by setupStream(), probes the manifest, creates a
+ * native proxy, stops the capture pipeline, suppresses page audio, and updates the registry entry. Returns the codec and formatted quality string on success, or
+ * null if native is not viable.
  * @param setup - The stream setup result from setupStream().
  * @param numericStreamId - The stream's numeric ID.
  * @param channelName - The channel key for logging and cache operations.
@@ -750,6 +794,12 @@ async function startNativeProxy(setup, numericStreamId, channelName, url, mpegTs
     // is read dynamically from the stream's HLS state at playlist generation time.
     const pendingForNative = getStream(numericStreamId);
     const nativePrerollSegmentCount = pendingForNative?.hls.prerollSegmentCount ?? 0;
+    // The re-establishment capability closes over the stream's own tune facts here, in the layer that owns them: a token-refresh reload re-acquires its
+    // manifest through the stream's real tune rather than a bare navigation. The page stays a parameter rather than a captured value because the callers
+    // own the page reference - the monitor hands its own current page to every recovery action it drives.
+    const reestablishManifest = (page) => {
+        return reestablishChannelManifest({ channelName: setup.channelName, page, profile: setup.profile, streamIdStr: setup.streamId, url });
+    };
     const nativeResult = await attemptNativeStreaming({
         channelName,
         interceptionPromise: setup.manifestInterception.promise,
@@ -763,9 +813,23 @@ async function startNativeProxy(setup, numericStreamId, channelName, url, mpegTs
             LOG.warn("Native proxy error for %s: %s. Falling back to capture.", channelName, error);
             clearProbeCache(channelName);
         },
+        onFeedApplied: (metadata) => {
+            // The registry write stays in the streaming layer, exactly as the error report above does: native reports upward and the layer that owns the entry is the
+            // layer that writes it. A refresh can land on a different rung of the service's ladder, so the status display reads the quality the stream is actually
+            // serving rather than the one it tuned to. An entry that is already gone means the stream is terminating, which is nothing to record.
+            const refreshed = getStream(numericStreamId);
+            if (!refreshed) {
+                return;
+            }
+            refreshed.captureCodec = metadata.codec;
+            refreshed.nativeBandwidth = metadata.bandwidth;
+            refreshed.nativeResolution = metadata.resolution;
+        },
         page: setup.page,
         prerollCodec: pendingForNative?.hls.prerollCodec ?? "h264",
         prerollSegmentCount: nativePrerollSegmentCount,
+        probeIdentity: setup.probeIdentity,
+        reestablishManifest,
         streamId: numericStreamId,
         streamIdStr: setup.streamId,
         url
@@ -778,18 +842,25 @@ async function startNativeProxy(setup, numericStreamId, channelName, url, mpegTs
         nativeResult.proxy.stop();
         return null;
     }
-    // Stop the capture pipeline - native streaming replaces it entirely.
-    if (!setup.rawCaptureStream.destroyed) {
-        setup.rawCaptureStream.destroy();
-    }
-    if (setup.ffmpegProcess) {
-        setup.ffmpegProcess.kill();
-    }
+    // Dispose the capture pipeline - native streaming replaces it entirely. No segmenter has been attached yet (native is attempted before createCaptureSegmenter), so
+    // disposal kills the FFmpeg child and destroys the capture stream.
+    setup.captureSession.dispose();
+    // Consume the persisted capture-mode resume data for this channel. Resume data seeds an fMP4 segmenter's starting sequence and init segment for capture continuity
+    // across restarts; createCaptureSegmenter consumes it on the capture path. On this native-upgrade path that segmenter is never created, so without this delete the
+    // resume entry would linger until TTL and could be mis-applied to a later capture-mode stream for the same channel. Native streaming carries its own MPEG-TS
+    // sequencing, so the capture resume state is obsolete the moment we commit to native.
+    deleteResumeData(channelName);
     // Update the registry entry to reflect native mode. For streams with separate audio, clear preroll state - preroll is muxed video+audio and can't be
     // split into separate renditions. For muxed-audio streams, preserve preroll state so the proxy can build composite playlists with preroll entries.
-    currentStream.ffmpegProcess = null;
+    //
+    // The separate-audio path disarms the preroll timer alongside nulling the fields. The timer's callback closed over its own base-URL and codec copies at
+    // registration, so nulling the fields silences only sendPlaylistResponse's per-poll regeneration, not the one-shot overwrite the callback would still perform when
+    // it fires. Disarming here completes the invalidation. One residual is inherent to preroll-for-hasAudio: if the native tune already exceeded PREROLL_DELAY_MS the
+    // timer has already fired, so the nulled fields freeze the already-written preroll playlist until the proxy's first real content arrives - bounded, not a stall.
+    currentStream.captureSession = null;
     currentStream.hls.hasAudio = nativeResult.hasAudio;
     if (nativeResult.hasAudio) {
+        cancelPrerollTimer(currentStream.hls);
         currentStream.hls.prerollBaseUrl = null;
         currentStream.hls.prerollCodec = null;
         currentStream.hls.prerollSegmentCount = 0;
@@ -797,15 +868,20 @@ async function startNativeProxy(setup, numericStreamId, channelName, url, mpegTs
     currentStream.captureCodec = nativeResult.codec;
     currentStream.hardwareAccelerated = false;
     currentStream.nativeBandwidth = nativeResult.bandwidth;
+    currentStream.nativeContainer = nativeResult.container;
     currentStream.nativeProxy = nativeResult.proxy;
     currentStream.nativeResolution = nativeResult.resolution;
-    currentStream.rawCaptureStream = null;
+    currentStream.reestablishManifest = reestablishManifest;
     currentStream.streamingMode = "native";
-    // Start the native proxy. Signal init segment readiness immediately - native MPEG-TS segments carry their own PAT/PMT codec configuration in every
-    // segment, so there is no separate init segment to wait for. Without this, MPEG-TS clients block on waitForInitSegment() and time out before the proxy's
-    // first poll cycle completes.
+    // Start the native proxy. Init readiness is conditional on the container. An MPEG-TS source carries its own PAT/PMT codec configuration in every segment and
+    // has no separate init to wait for, so readiness is signaled here and MPEG-TS clients are released immediately rather than blocking on waitForInitSegment()
+    // until it times out. An fMP4 source does have an init, and the store signals readiness when the video track's first one lands - video because the consumer
+    // waiting on this signal is the remux path, which resolves the video init. A null container reaches this only on a feed the DRM path abandoned, so it takes
+    // the immediate signal rather than deadlocking readiness on an init that will never arrive.
     nativeResult.proxy.start();
-    currentStream.hls.signalInitSegmentReady();
+    if (nativeResult.container !== "fmp4") {
+        currentStream.hls.signalInitSegmentReady();
+    }
     // Suppress audio on the browser page. The page stays alive for token refresh but the video element's audio is not part of the native stream - without
     // suppression, it plays audibly on the local machine.
     await suppressPageAudio(setup.page);
@@ -813,12 +889,13 @@ async function startNativeProxy(setup, numericStreamId, channelName, url, mpegTs
     return { codec: nativeResult.codec, quality: formatNativeQuality(nativeResult.bandwidth, nativeResult.codec, nativeResult.resolution) };
 }
 /**
- * Creates the fMP4 segmenter for capture mode streams. Reads resume data, creates the segmenter with preroll and resume configuration, pipes the capture stream,
- * and stores the segmenter in the registry. Resume data is consumed only after the segmenter is successfully stored, ensuring it survives if creation fails.
+ * Creates the fMP4 segmenter for capture mode streams. Reads resume data, creates the segmenter with preroll and resume configuration, and attaches it to the
+ * capture session (which pipes the session's capture output into it). Resume data is consumed only after the segmenter is successfully attached to a non-disposed
+ * session, ensuring it survives if the stream was terminated during setup.
  * @param setup - The stream setup result from setupStream().
  * @param numericStreamId - The stream's numeric ID.
  * @param channelName - The channel key for resume data and logging.
- * @returns True if the segmenter was created and stored, false if the stream was terminated during setup.
+ * @returns True if the segmenter was attached, false if the stream was terminated during setup (the session was already disposed).
  */
 function createCaptureSegmenter(setup, numericStreamId, channelName) {
     // Peek at resume data from a previous shutdown without consuming it. The data is consumed (deleted) only after the segmenter is successfully created and
@@ -852,25 +929,25 @@ function createCaptureSegmenter(setup, numericStreamId, channelName) {
         ...buildSegmenterTerminationHandlers(numericStreamId, channelName),
         streamId: numericStreamId
     });
-    // Pipe the capture stream to the segmenter.
-    segmenter.pipe(setup.captureStream);
-    // Store the segmenter reference in the registry.
-    const captureStream = getStream(numericStreamId);
-    if (captureStream) {
-        captureStream.segmenter = segmenter;
-        // Now that the segmenter is created, piped, and stored, consume the resume data so it's not used again on a subsequent stream start for the same channel.
-        if (resumeData) {
-            deleteResumeData(channelName);
-        }
-        return true;
+    // Attach the segmenter to the capture session. attachSegmenter pipes the session's capture output into the segmenter. If the stream was terminated mid-setup, the
+    // session is already disposed and attachSegmenter stops the orphan segmenter instead of wiring it - the single home for that rare-race cleanup.
+    setup.captureSession.attachSegmenter(segmenter);
+    if (setup.captureSession.disposed) {
+        // The stream was terminated during setup (rare race). attachSegmenter already stopped the orphan; leave the resume data intact so the next stream start for this
+        // channel can retry with it rather than losing it to an HLS sequence reset.
+        return false;
+    }
+    // The segmenter is created, piped, and owned by the session. Consume the resume data so it is not reused on a subsequent stream start for the same channel.
+    if (resumeData) {
+        deleteResumeData(channelName);
     }
-    // Stream was terminated during setup (rare race condition). Clean up the orphaned segmenter.
-    cleanupOrphanedSetup(segmenter);
-    return false;
+    return true;
 }
 /**
  * Completes the async portion of stream initialization. Creates the browser page, navigates to the URL, sets up capture, creates the segmenter, and fills in the
- * pending registry entry. On failure, cleans up the pending entry via terminateStream().
+ * pending registry entry. If the pending entry was terminated during setup (e.g., idle timeout) before this function reaches it, it releases the now-orphaned
+ * setup resources via setup.cleanup() and returns null. On a thrown error, it does not clean up the pending entry itself - callers reach handleSetupFailure(), which
+ * terminates the pending entry via terminateStream().
  *
  * This is the Phase 2 of the two-phase stream initialization. For the non-blocking HLS path, it runs as fire-and-forget via `void`. For the blocking path
  * (initializeStream), it is awaited directly.
@@ -881,11 +958,31 @@ function createCaptureSegmenter(setup, numericStreamId, channelName) {
  */
 async function completeStreamSetup(options) {
     const { channel, channelName, channelSelector, clickSelector, clickToPlay, mpegTsClient, numericStreamId, profileOverride, streamIdStr, url } = options;
-    // Circuit breaker callback - terminate the stream on unrecoverable errors.
+    /* Build the probe-cache identity once, here, and hand it onward as a value. This is the only frame that holds both halves of it on every entry path: the true
+     * per-stream key (channelName is the route key for a predefined tune, the binding hash for an ad-hoc /play, the channel id for a pretune) and the binding
+     * inputs the stamp is derived from. Nothing downstream may build one - setupStream's own channelName is deliberately undefined for ad-hoc streams, and a
+     * stamp assembled from a frame holding only part of the binding would silently describe a different stream than the one the tune reaches.
+     *
+     * The effective profile is the query override when one was supplied, otherwise the stored profile: an overridden tune reaches a different stream than the
+     * stored profile would, so the stamp honestly differs and an entry cached under the stored profile re-probes once under the override rather than answering
+     * for a page it never described.
+     */
+    const probeIdentity = {
+        key: channelName,
+        stamp: buildProbeCacheStamp(channel ? { channelSelector: channel.channelSelector, profile: profileOverride ?? channel.profile, url } :
+            { channelSelector, profile: profileOverride, url })
+    };
+    /* Circuit breaker callback - terminates this stream on unrecoverable errors, by the id the closure was built for. Resolving the id through the channel index
+     * at fire time could reach a different stream: a channel re-tuned while this callback was in flight is registered under the same name with a newer id, and the
+     * breaker's verdict belongs to the stream whose monitor reached it.
+     *
+     * The registry-presence guard is what makes a repeated or late invocation silent. terminateStream's own guard covers only a termination already underway - its
+     * tracking entry is removed when that termination completes - so a second call from an independent site (an FFmpeg error handler firing after the monitor
+     * already terminated the stream) would otherwise log a second termination summary and re-emit the stream-removed event for a stream long gone.
+     */
     const onCircuitBreak = () => {
-        const currentStreamId = getChannelStreamId(channelName);
-        if (currentStreamId !== undefined) {
-            terminateStream(currentStreamId, channelName, "too many errors");
+        if (getStream(numericStreamId)) {
+            terminateStream(numericStreamId, channelName, "too many errors");
             void emitCurrentSystemStatus();
         }
     };
@@ -893,10 +990,10 @@ async function completeStreamSetup(options) {
     const tabReplacementFactory = (_, streamId, profile, metadataComment) => {
         return createTabReplacementHandler(numericStreamId, streamId, channelName, url, profile, metadataComment, onCircuitBreak);
     };
-    // If at capacity, try to reclaim an idle stream before starting setup. This avoids rejecting new requests when idle streams can be freed.
-    if (getStreamCount() >= CONFIG.streaming.maxConcurrentStreams) {
-        reclaimIdleStream();
-    }
+    // Capacity was already reserved at the registration site (reserveStreamSlot in ensureChannelStream for the preroll path, and in initializeStream for the blocking
+    // path) before this stream's pending entry was registered, so the new stream is excluded from its own capacity check. We deliberately do NOT re-check or reclaim
+    // here: the pending entry is now counted, so a count-based check would double-count this stream against its own slot and could evict a healthy peer at the
+    // legitimate boundary. The registration-site reservation is the single source of truth for the capacity decision.
     // Pass the pre-allocated IDs to setupStream so it uses them instead of generating new ones. This ensures the abort controller, health monitor, and tab replacement
     // handler all reference the same stream identity as the pending registry entry. Pass channelName only for predefined channels - for ad-hoc streams, omitting it
     // causes generateStreamId to derive the stream ID string from the URL (e.g., "foxsports-abc123"), which is more informative in logs.
@@ -908,6 +1005,7 @@ async function completeStreamSetup(options) {
         clickToPlay: channel ? undefined : clickToPlay,
         numericStreamId,
         onTabReplacementFactory: tabReplacementFactory,
+        probeIdentity,
         profileOverride,
         streamId: streamIdStr,
         url
@@ -921,12 +1019,12 @@ async function completeStreamSetup(options) {
         });
         return null;
     }
-    stream.ffmpegProcess = setup.ffmpegProcess;
+    stream.captureSession = setup.captureSession;
+    stream.monitor = setup.monitor;
     stream.page = setup.page;
+    stream.probeIdentity = setup.probeIdentity;
     stream.profile = setup.profile;
-    stream.rawCaptureStream = setup.rawCaptureStream;
     stream.startTime = setup.startTime;
-    stream.stopMonitor = setup.stopMonitor;
     stream.url = setup.url;
     // Continue within stream context for consistent logging.
     return runWithStreamContext({ channelName: channel?.name, streamId: setup.streamId, url: setup.url }, async () => {
@@ -953,6 +1051,8 @@ async function completeStreamSetup(options) {
         }
         const effectiveCodec = getEffectiveCaptureCodec();
         const captureHwAccel = isCaptureHardwareAccelerated();
+        // Prefix the codec label with U+26A1, the high-voltage / lightning-bolt glyph, as a visual marker in the "Streaming..." log line that capture is
+        // hardware-accelerated. The glyph is written as an escape so the source stays ASCII; it renders as the lightning bolt in the log output.
         const ffmpegCodec = captureHwAccel ? ("\u26A1 " + effectiveCodec.toUpperCase()) : effectiveCodec.toUpperCase();
         const captureMode = (streamingMode === "native") ? ("native HLS" + nativeQuality) :
             (CONFIG.streaming.captureMode === "ffmpeg" ? "FFmpeg [" + ffmpegCodec + "]" : "Native fMP4");