prismcast 1.2.0 → 1.3.0

package/dist/streaming/hls.js

@@ -1,4 +1,4 @@
-import { LOG, delay, formatError, runWithStreamContext } from "../utils/index.js";
+import { LOG, delay, formatError, runWithStreamContext, startTimer } from "../utils/index.js";
 import { StreamSetupError, createPageWithCapture, setupStream } from "./setup.js";
 import { createHLSState, getAllStreams, getStream, getStreamCount, registerStream, updateLastAccess } from "./registry.js";
 import { createInitialStreamStatus, emitStreamAdded } from "./statusEmitter.js";
@@ -12,27 +12,64 @@ import { createFMP4Segmenter } from "./fmp4Segmenter.js";
 import { createHash } from "node:crypto";
 import { registerClient } from "./clients.js";
 import { triggerShowNameUpdate } from "./showInfo.js";
-/* This module handles HLS (HTTP Live Streaming) output using fMP4 (fragmented MP4) segments. HLS mode uses MP4/AAC capture from puppeteer-stream, which is then
- * segmented natively without any external dependencies. The overall flow is:
+// 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, provider resolution, channel lookup, and login mode. Returns a
+ * discriminated union so callers can handle success and failure without coupling to Express response objects.
  *
- * 1. Client requests playlist at /hls/:name/stream.m3u8 (predefined channel) or /play?url=...&profile=... (ad-hoc URL)
- * 2. If no stream exists, we call initializeStream() which runs setupStream() and creates a native fMP4 segmenter
- * 3. The segmenter parses the MP4 stream and produces init.mp4 (codec config) + segment0.m4s, segment1.m4s, ...
- * 4. We store init segment and media segments in memory, return playlist to client
- * 5. Client fetches init.mp4 once, then media segments at /hls/:name/segmentN.m4s
- * 6. Idle timeout terminates streams with no recent segment requests
+ * This is extracted from ensureChannelStream() so it can be called by both HLS and MPEG-TS code paths without duplicating the validation logic.
  *
- * Shared streams: If multiple clients request the same channel (or the same ad-hoc URL with the same profile), they share one segmenter. 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.
+ * @param channelName - The channel key to validate.
+ * @returns Validation result with channel data on success, or error details on failure.
+ */
+export function validateChannel(channelName) {
+    if (isPredefinedChannelDisabled(channelName)) {
+        return { body: "Channel is disabled.", statusCode: 404, valid: false };
+    }
+    // Resolve provider selection. For multi-provider channels, this returns the user's selected provider key (e.g., "espn-disneyplus"). For single-provider channels
+    // or if no selection exists, it returns the canonical key unchanged.
+    const resolvedKey = resolveProviderKey(channelName);
+    // Get the resolved channel with inheritance applied. For provider variants, this merges the variant's properties with inherited properties from the canonical
+    // entry (name, stationId).
+    const channel = getResolvedChannel(resolvedKey);
+    // Fall back to getAllChannels if the resolved channel doesn't exist (e.g., for ad-hoc streams or non-grouped channels).
+    const effectiveChannel = channel ?? getAllChannels()[channelName];
+    // Log a warning if a provider selection resolved to a missing variant (e.g., variant was removed from channels after selection was saved).
+    if (!channel && (resolvedKey !== channelName)) {
+        LOG.warn("Provider '%s' not found for channel '%s'. Using default provider.", resolvedKey, channelName);
+    }
+    // Runtime check needed even though TypeScript thinks channel is always defined (Record indexing quirk).
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (!effectiveChannel) {
+        return { body: "Channel not found.", statusCode: 404, valid: false };
+    }
+    // Block new stream requests while login mode is active. This prevents the browser from being disrupted during authentication.
+    if (isLoginModeActive()) {
+        return { body: LOGIN_MODE_BODY, statusCode: 503, valid: false };
+    }
+    return { channel: effectiveChannel, resolvedKey, valid: true };
+}
+/**
+ * Sends a validation error response to the client. Handles both plain text bodies (via res.send) and object bodies (via res.json).
+ * @param validation - The failed validation result.
+ * @param res - Express response object.
  */
+export function sendValidationError(validation, res) {
+    if (typeof validation.body === "object") {
+        res.status(validation.statusCode).json(validation.body);
+    }
+    else {
+        res.status(validation.statusCode).send(validation.body);
+    }
+}
 // Public Endpoint Handlers.
 /**
- * Ensures a stream is running for a channel. If no stream exists, starts one. If a stream startup is in progress (placeholder), waits for it to complete. Returns the
- * stream ID if successful, or null if an error occurred (with the error response already sent to the client).
+ * Ensures a stream is running for a channel. If no stream exists, starts one. If a stream startup is in progress (-1 sentinel), waits for it to complete. Returns
+ * the stream ID if successful, or null if an error occurred (with the error response already sent to the client).
  *
- * This is the shared entry point for both HLS and MPEG-TS handlers. It handles channel validation, login mode blocking, and concurrent startup deduplication. The
- * existing-stream check runs first so that ad-hoc streams (started via /play with synthetic keys) can be served without requiring a predefined channel definition.
+ * The existing-stream check runs first so that ad-hoc streams (registered under synthetic keys like "play-a1b2c3d4") can be served without failing the
+ * "Channel not found" check.
  *
  * For channels with multiple providers (e.g., ESPN via ESPN.com or Disney+), the user's provider selection is resolved before looking up the channel definition.
  * The stream is registered under the canonical key (channelName) for deduplication, but uses the resolved provider's URL and settings.
@@ -47,49 +84,24 @@ export async function ensureChannelStream(channelName, req, res) {
     // be served by the standard HLS playlist handler without failing the "Channel not found" check. A stream in channelToStreamId was already validated when it was
     // started, so no re-validation is needed.
     const streamId = getChannelStreamId(channelName);
-    // If a stream is already running (not a placeholder), return it directly.
+    // If a stream is already running (not a startup-in-progress sentinel), return it directly.
     if ((streamId !== undefined) && (streamId !== -1)) {
         return streamId;
     }
-    // If a placeholder (-1) exists, another request is already starting this stream. Poll until the real stream ID appears or we timeout.
+    // If a startup is in progress (-1 sentinel), another request is already starting this stream. Poll until the real stream ID appears or we timeout.
     if (streamId === -1) {
         return awaitStreamReady(channelName, res);
     }
     // No existing stream — validate the channel and start a new one. Channel validation is only needed for new streams because existing streams were already validated
     // at startup time.
-    if (isPredefinedChannelDisabled(channelName)) {
-        res.status(404).send("Channel is disabled.");
-        return null;
-    }
-    // Resolve provider selection. For multi-provider channels, this returns the user's selected provider key (e.g., "espn-disneyplus"). For single-provider channels
-    // or if no selection exists, it returns the canonical key unchanged.
-    const resolvedKey = resolveProviderKey(channelName);
-    // Get the resolved channel with inheritance applied. For provider variants, this merges the variant's properties with inherited properties from the canonical
-    // entry (name, stationId).
-    const channel = getResolvedChannel(resolvedKey);
-    // Fall back to getAllChannels if the resolved channel doesn't exist (e.g., for ad-hoc streams or non-grouped channels).
-    const effectiveChannel = channel ?? getAllChannels()[channelName];
-    // Log a warning if a provider selection resolved to a missing variant (e.g., variant was removed from channels after selection was saved).
-    if (!channel && (resolvedKey !== channelName)) {
-        LOG.warn("Provider '%s' not found for channel '%s'. Using default provider.", resolvedKey, channelName);
-    }
-    // Runtime check needed even though TypeScript thinks channel is always defined (Record indexing quirk).
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    if (!effectiveChannel) {
-        res.status(404).send("Channel not found.");
-        return null;
-    }
-    // Block new stream requests while login mode is active. This prevents the browser from being disrupted during authentication.
-    if (isLoginModeActive()) {
-        res.status(503).json({
-            error: "Login in progress",
-            message: "Please complete authentication before starting new streams."
-        });
+    const validation = validateChannel(channelName);
+    if (!validation.valid) {
+        sendValidationError(validation, res);
         return null;
     }
     // Start the stream using the resolved channel's URL. The stream is registered under channelName (canonical key) for deduplication, but uses the resolved
     // provider's definition.
-    const newStreamId = await startHLSStream(channelName, effectiveChannel.url, req, res, effectiveChannel);
+    const newStreamId = await startHLSStream(channelName, validation.channel.url, req, res, validation.channel);
     if (newStreamId === null) {
         // Error response already sent by startHLSStream.
         return null;
@@ -97,7 +109,7 @@ export async function ensureChannelStream(channelName, req, res) {
     return newStreamId;
 }
 /**
- * Handles HLS playlist requests. Ensures a stream is running for the requested channel, waits for the first playlist to be produced, then returns it.
+ * Handles HLS playlist requests. Ensures a stream is running for the channel (blocking until ready if a new stream must start), then returns the playlist.
  *
  * Route: GET /hls/:name/stream.m3u8
  *
@@ -110,40 +122,12 @@ export async function handleHLSPlaylist(req, res) {
         res.status(400).send("Channel name is required.");
         return;
     }
+    const clientAddress = req.ip ?? req.socket.remoteAddress ?? "unknown";
     const streamId = await ensureChannelStream(channelName, req, res);
     if (streamId === null) {
-        // Error response already sent by ensureChannelStream.
-        return;
-    }
-    // Capture client address for client tracking.
-    const clientAddress = req.ip ?? req.socket.remoteAddress ?? "unknown";
-    // If a playlist is already available, return it immediately.
-    const existingPlaylist = getPlaylist(streamId);
-    if (existingPlaylist) {
-        updateLastAccess(streamId);
-        registerClient(streamId, clientAddress, "hls");
-        res.setHeader("Cache-Control", "no-cache");
-        res.setHeader("Content-Type", "application/vnd.apple.mpegurl");
-        res.send(existingPlaylist);
-        return;
-    }
-    // Wait for the first playlist to be ready.
-    const playlistReady = await waitForPlaylist(streamId, CONFIG.streaming.navigationTimeout);
-    if (!playlistReady) {
-        res.setHeader("Retry-After", "5");
-        res.status(503).send("Stream is starting. Please retry.");
-        return;
-    }
-    const playlist = getPlaylist(streamId);
-    if (!playlist) {
-        res.status(500).send("Playlist not available.");
         return;
     }
-    updateLastAccess(streamId);
-    registerClient(streamId, clientAddress, "hls");
-    res.setHeader("Cache-Control", "no-cache");
-    res.setHeader("Content-Type", "application/vnd.apple.mpegurl");
-    res.send(playlist);
+    await sendPlaylistResponse(streamId, clientAddress, res);
 }
 /**
  * Handles HLS segment requests. Returns the requested segment from memory. Supports both the fMP4 initialization segment (init.mp4) and media segments (.m4s).
@@ -161,7 +145,7 @@ export function handleHLSSegment(req, res) {
         return;
     }
     const streamId = getChannelStreamId(channelName);
-    if (streamId === undefined) {
+    if ((streamId === undefined) || (streamId === -1)) {
         res.status(404).send("Stream not found.");
         return;
     }
@@ -173,9 +157,7 @@ export function handleHLSSegment(req, res) {
             return;
         }
         updateLastAccess(streamId);
-        res.setHeader("Cache-Control", "no-cache");
-        res.setHeader("Content-Type", "video/mp4");
-        res.send(initSegment);
+        sendSegment(initSegment, res);
         return;
     }
     // Handle media segments (.m4s).
@@ -185,9 +167,7 @@ export function handleHLSSegment(req, res) {
         return;
     }
     updateLastAccess(streamId);
-    res.setHeader("Cache-Control", "no-cache");
-    res.setHeader("Content-Type", "video/mp4");
-    res.send(segment);
+    sendSegment(segment, res);
 }
 // Ad-Hoc Streaming.
 /**
@@ -222,7 +202,7 @@ export async function handlePlayStream(req, res) {
         res.redirect(302, "/hls/" + channelName + "/stream.m3u8");
         return;
     }
-    // If a placeholder (-1) exists, another request is already starting this stream. Poll until the real stream ID appears or we timeout, then redirect.
+    // If a startup is in progress (-1 sentinel), another request is already starting this stream. Poll until the real stream ID appears or we timeout, then redirect.
     if (streamId === -1) {
         const resolvedId = await awaitStreamReady(channelName, res);
         if (resolvedId === null) {
@@ -234,15 +214,12 @@ export async function handlePlayStream(req, res) {
     }
     // Block new stream requests while login mode is active.
     if (isLoginModeActive()) {
-        res.status(503).json({
-            error: "Login in progress",
-            message: "Please complete authentication before starting new streams."
-        });
+        res.status(503).json(LOGIN_MODE_BODY);
         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 placeholder management, capture setup, segmenter creation, and event emission.
+    // Start a new ad-hoc stream. initializeStream handles capture setup, segmenter creation, and event emission.
     try {
         const newStreamId = await initializeStream({ channelName, channelSelector: selector, clickSelector, clickToPlay, clientAddress, profileOverride, url });
         if (newStreamId === null) {
@@ -264,28 +241,25 @@ export async function handlePlayStream(req, res) {
     }
     res.redirect(302, "/hls/" + channelName + "/stream.m3u8");
 }
-// Placeholder Polling.
+// Startup Polling.
 /**
- * Waits for a stream placeholder to resolve to a real stream ID. This is used when a second request arrives while the first is still starting the stream. The
- * placeholder (-1) in channelToStreamId signals that startup is in progress. We poll until the placeholder is replaced with a real stream ID, removed (startup
- * failed), or the timeout expires.
+ * Polls for a stream startup to complete. The -1 sentinel in channelToStreamId signals that startup is in progress. Returns the resolved stream ID on success, null
+ * if startup failed (sentinel removed), or undefined if the timeout expired while startup is still active.
  *
- * On failure, the appropriate error response is sent to the client and null is returned.
+ * This is the shared inner polling loop used by both awaitStreamReady() (which sends error responses) and awaitStreamReadySilent() (which does not).
  *
  * @param channelName - The channel name (or synthetic ad-hoc key) to poll.
- * @param res - Express response object for sending error responses on failure.
- * @returns The resolved stream ID on success, or null if startup failed or timed out (error response already sent).
+ * @returns The resolved stream ID, null if startup failed, or undefined if timed out.
  */
-async function awaitStreamReady(channelName, res) {
+async function pollStreamReady(channelName) {
     const pollInterval = 200;
     const deadline = Date.now() + CONFIG.streaming.navigationTimeout;
     while (Date.now() < deadline) {
         // eslint-disable-next-line no-await-in-loop
         await delay(pollInterval);
         const streamId = getChannelStreamId(channelName);
-        // The startup failed and the placeholder was removed.
+        // The startup failed and the sentinel was removed.
         if (streamId === undefined) {
-            res.status(500).send("Stream startup failed.");
             return null;
         }
         // Real stream ID is now available.
@@ -293,10 +267,104 @@ async function awaitStreamReady(channelName, res) {
             return streamId;
         }
     }
-    // Timed out waiting for the placeholder to resolve.
-    res.setHeader("Retry-After", "5");
-    res.status(503).send("Stream is starting. Please retry.");
-    return null;
+    // Timed out waiting for the startup to complete.
+    return undefined;
+}
+/**
+ * Waits for a stream startup to complete. This is used when a second request arrives while the first is still starting the stream. The -1 sentinel in
+ * channelToStreamId signals that startup is in progress. We poll until the sentinel is replaced with a real stream ID, removed (startup failed), or the
+ * timeout expires.
+ *
+ * On failure, the appropriate error response is sent to the client and null is returned.
+ *
+ * @param channelName - The channel name (or synthetic ad-hoc key) to poll.
+ * @param res - Express response object for sending error responses on failure.
+ * @returns The resolved stream ID on success, or null if startup failed or timed out (error response already sent).
+ */
+async function awaitStreamReady(channelName, res) {
+    const result = await pollStreamReady(channelName);
+    // Startup failed (sentinel removed).
+    if (result === null) {
+        res.status(500).send("Stream startup failed.");
+        return null;
+    }
+    // Timed out.
+    if (result === undefined) {
+        res.setHeader("Retry-After", "5");
+        res.status(503).send("Stream is starting. Please retry.");
+        return null;
+    }
+    return result;
+}
+/**
+ * Waits for a stream startup to complete without sending any HTTP responses. Used by MPEG-TS when headers have already been flushed and error responses cannot be
+ * sent.
+ *
+ * @param channelName - The channel name (or synthetic ad-hoc key) to poll.
+ * @returns The resolved stream ID on success, or null if startup failed or timed out.
+ */
+export async function awaitStreamReadySilent(channelName) {
+    const result = await pollStreamReady(channelName);
+    // Both null (failed) and undefined (timed out) map to null for the silent variant.
+    if ((result === null) || (result === undefined)) {
+        return null;
+    }
+    return result;
+}
+// Response Helpers.
+/**
+ * Sends the playlist for a stream, waiting for the first playlist if needed. Handles client registration and access tracking. This is the shared pattern used by
+ * multiple code paths in handleHLSPlaylist() to avoid duplicating the get-wait-check-register-send sequence.
+ * @param streamId - The numeric stream ID.
+ * @param clientAddress - Client address for tracking.
+ * @param res - Express response object.
+ */
+async function sendPlaylistResponse(streamId, clientAddress, res) {
+    // Try to get an existing playlist first.
+    let playlist = getPlaylist(streamId);
+    // If no playlist yet, wait for the first one.
+    if (!playlist) {
+        const playlistReady = await waitForPlaylist(streamId, CONFIG.streaming.navigationTimeout);
+        if (!playlistReady) {
+            res.setHeader("Retry-After", "5");
+            res.status(503).send("Stream is starting. Please retry.");
+            return;
+        }
+        playlist = getPlaylist(streamId);
+        if (!playlist) {
+            res.status(500).send("Playlist not available.");
+            return;
+        }
+        // Log the time from stream start to first playlist delivery. This only fires for the initial playlist wait, not for subsequent playlist polls.
+        const stream = getStream(streamId);
+        if (stream) {
+            const elapsed = ((Date.now() - stream.startTime.getTime()) / 1000).toFixed(3);
+            LOG.debug("timing:hls", "Playlist delivered to client in %ss.", elapsed);
+        }
+    }
+    updateLastAccess(streamId);
+    registerClient(streamId, clientAddress, "hls");
+    sendPlaylist(playlist, res);
+}
+/**
+ * Sends a playlist string as an HLS response with appropriate headers.
+ * @param playlist - The M3U8 playlist content.
+ * @param res - Express response object.
+ */
+function sendPlaylist(playlist, res) {
+    res.setHeader("Cache-Control", "no-cache");
+    res.setHeader("Content-Type", "application/vnd.apple.mpegurl");
+    res.send(playlist);
+}
+/**
+ * Sends a segment buffer as a video/mp4 response with appropriate headers.
+ * @param data - The segment data.
+ * @param res - Express response object.
+ */
+function sendSegment(data, res) {
+    res.setHeader("Cache-Control", "no-cache");
+    res.setHeader("Content-Type", "video/mp4");
+    res.send(data);
 }
 // Stream Lifecycle.
 /**
@@ -308,7 +376,7 @@ async function awaitStreamReady(channelName, res) {
  * @param segmenter - The orphaned fMP4 segmenter instance to stop.
  */
 function cleanupOrphanedSetup(segmenter) {
-    LOG.warn("Stream was terminated during setup. Stopping orphaned segmenter.");
+    LOG.debug("streaming:setup", "Stream was terminated during setup. Stopping orphaned segmenter.");
     segmenter.stop();
 }
 /**
@@ -333,39 +401,46 @@ function cleanupOrphanedSetup(segmenter) {
  */
 function createTabReplacementHandler(numericStreamId, streamId, channelName, url, profile, metadataComment, onCircuitBreak) {
     return async () => {
+        const tabElapsed = startTimer();
         // Get the current stream entry.
         const stream = getStream(numericStreamId);
         if (!stream) {
-            LOG.warn("Tab replacement requested but stream %s no longer exists.", streamId);
+            LOG.debug("recovery:tab", "Tab replacement requested but stream %s no longer exists.", streamId);
             return null;
         }
-        // Get the current segment index from the old segmenter before stopping it. This allows the new segmenter to continue numbering from where we left off.
+        // 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 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("Destroying old capture stream for tab replacement.");
+            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("Stopping current segmenter for tab replacement.");
+            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("Stopping FFmpeg process for tab replacement.");
+            LOG.debug("recovery:tab", "Stopping FFmpeg process for tab replacement.");
             stream.ffmpegProcess.kill();
         }
         // Close the current page.
         const oldPage = stream.page;
         unregisterManagedPage(oldPage);
         if (!oldPage.isClosed()) {
-            LOG.debug("Closing unresponsive page for tab replacement.");
+            LOG.debug("recovery:tab", "Closing unresponsive page for tab replacement.");
             oldPage.close().catch((error) => {
-                LOG.warn("Page close error during tab replacement: %s.", formatError(error));
+                LOG.debug("recovery:tab", "Page close error during tab replacement: %s.", formatError(error));
             });
         }
+        LOG.debug("timing:tab", "Old tab cleanup complete. (+%sms)", tabElapsed());
         // Create a new page with capture.
         let captureResult;
         try {
@@ -381,12 +456,14 @@ function createTabReplacementHandler(numericStreamId, streamId, channelName, url
             });
         }
         catch (error) {
-            LOG.error("Failed to create new page during tab replacement: %s.", formatError(error));
+            LOG.warn("Failed to create new page during tab replacement: %s.", formatError(error));
             return null;
         }
-        // Create a new segmenter for the new capture stream. Continue from the current segment index for playlist continuity, and mark the first segment with a
-        // discontinuity tag so clients know the stream parameters may have changed.
+        LOG.debug("timing:tab", "New page with capture created. (+%sms)", tabElapsed());
+        // 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({
+            initialTrackTimestamps: currentTrackTimestamps,
             onError: (error) => {
                 if (isTerminationInitiated(numericStreamId)) {
                     return;
@@ -399,11 +476,13 @@ function createTabReplacementHandler(numericStreamId, streamId, channelName, url
                 if (isTerminationInitiated(numericStreamId)) {
                     return;
                 }
-                LOG.warn("Segmenter stopped unexpectedly after tab replacement for %s.", channelName);
+                LOG.error("Segmenter stopped unexpectedly after tab replacement for %s.", channelName);
                 terminateStream(numericStreamId, channelName, "stream ended unexpectedly after recovery");
                 void emitCurrentSystemStatus();
             },
             pendingDiscontinuity: true,
+            previousInitSegment: currentInitSegment,
+            startingInitVersion: currentInitVersion,
             startingSegmentIndex: currentSegmentIndex,
             streamId: numericStreamId
         });
@@ -415,6 +494,7 @@ function createTabReplacementHandler(numericStreamId, streamId, channelName, url
         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 {
             context: captureResult.context,
             page: captureResult.page
@@ -422,26 +502,27 @@ function createTabReplacementHandler(numericStreamId, streamId, channelName, url
     };
 }
 /**
- * Initializes a new HLS stream. This is the shared stream startup logic used by both channel-based and ad-hoc streams. It handles placeholder management, browser
- * capture setup, segmenter creation, stream registration, and event emission.
+ * Initializes a new HLS stream. This is the shared stream startup logic used by both channel-based and ad-hoc streams. It handles browser capture setup, segmenter
+ * creation, stream registration, and event emission.
  *
- * On success, the stream is fully registered and producing segments. On failure, the placeholder is cleaned up and the error is re-thrown for the caller to handle
- * HTTP error responses appropriately (channel-based streams need HDHomeRun headers, ad-hoc streams do not).
+ * A -1 sentinel is set in channelToStreamId during setup to prevent duplicate stream starts. On success, the sentinel is replaced with the real stream ID. On
+ * failure, the sentinel is removed and the error is re-thrown for the caller to handle HTTP error responses appropriately (channel-based streams need HDHomeRun
+ * headers, ad-hoc streams do not).
  *
  * @param options - Stream initialization options.
  * @returns The stream ID on success, or null if the stream was terminated during the narrow setup window (orphaned setup race condition).
  * @throws StreamSetupError if setup fails, or Error for unexpected failures.
  */
-async function initializeStream(options) {
+export async function initializeStream(options) {
     const { channel, channelName, channelSelector, clickSelector, clickToPlay, clientAddress, profileOverride, url } = options;
-    // Create a placeholder to prevent duplicate stream starts while we're setting up.
-    const placeholderStreamId = -1;
-    setChannelStreamId(channelName, placeholderStreamId);
+    // Set a -1 sentinel to prevent duplicate stream starts while we're setting up.
+    const startupSentinel = -1;
+    setChannelStreamId(channelName, startupSentinel);
     let setup;
     // Circuit breaker callback — terminate the stream on unrecoverable errors.
     const onCircuitBreak = () => {
         const streamId = getChannelStreamId(channelName);
-        if ((streamId !== undefined) && (streamId !== placeholderStreamId)) {
+        if ((streamId !== undefined) && (streamId !== startupSentinel)) {
             terminateStream(streamId, channelName, "too many errors");
             void emitCurrentSystemStatus();
         }
@@ -469,13 +550,13 @@ async function initializeStream(options) {
         }, onCircuitBreak);
     }
     catch (error) {
-        // Remove placeholder on failure and re-throw for the caller to handle error responses.
+        // Remove startup sentinel on failure and re-throw for the caller to handle error responses.
         deleteChannelStreamId(channelName);
         throw error;
     }
     // Update the channel mapping with the real stream ID.
     setChannelStreamId(channelName, setup.numericStreamId);
-    // Continue within stream context for consistent logging. The async is required by runWithStreamContext's signature.
+    // Continue within stream context for consistent logging.
     return runWithStreamContext({ channelName: channel?.name, streamId: setup.streamId, url: setup.url }, 
     // eslint-disable-next-line @typescript-eslint/require-await
     async () => {
@@ -517,7 +598,7 @@ async function initializeStream(options) {
                 if (isTerminationInitiated(setup.numericStreamId)) {
                     return;
                 }
-                LOG.warn("Segmenter stopped unexpectedly for %s.", channelName);
+                LOG.error("Segmenter stopped unexpectedly for %s.", channelName);
                 terminateStream(setup.numericStreamId, channelName, "stream ended unexpectedly");
                 void emitCurrentSystemStatus();
             },
@@ -537,7 +618,8 @@ async function initializeStream(options) {
         }
         const captureMode = CONFIG.streaming.captureMode === "ffmpeg" ? "FFmpeg" : "Native";
         const displayName = channel?.name ?? url;
-        LOG.info("Streaming %s (%s, %s).", displayName, setup.profileName, captureMode);
+        const tuneTime = ((Date.now() - setup.startTime.getTime()) / 1000).toFixed(1);
+        LOG.info("Streaming %s (%s, %s). Tuned in %ss.", displayName, setup.profileName, captureMode, tuneTime);
         // Emit stream added event.
         emitStreamAdded(createInitialStreamStatus({
             channelName: channel?.name ?? null,