prismcast 1.2.1 → 1.3.0

package/dist/streaming/mpegts.js

@@ -1,30 +1,36 @@
-/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
- *
- * mpegts.ts: MPEG-TS streaming handler for PrismCast.
- */
 import { LOG, formatError, spawnMpegTsRemuxer } from "../utils/index.js";
+import { awaitStreamReadySilent, initializeStream, sendValidationError, validateChannel } from "./hls.js";
 import { getStream, updateLastAccess } from "./registry.js";
 import { registerClient, unregisterClient } from "./clients.js";
 import { CONFIG } from "../config/index.js";
-import { ensureChannelStream } from "./hls.js";
+import { StreamSetupError } from "./setup.js";
+import { getChannelStreamId } from "./lifecycle.js";
 import { waitForInitSegment } from "./hlsSegments.js";
 /* This module provides a continuous MPEG-TS byte stream from the same capture pipeline used for HLS. It is designed for HDHomeRun-compatible clients (such as Plex)
  * that expect raw MPEG-TS when tuning a channel. The existing capture → segmenter → HLS segments flow is unchanged. Each MPEG-TS client gets its own FFmpeg remuxer
  * that converts stored fMP4 segments to MPEG-TS with codec copy (no transcoding).
  *
  * Data flow per client:
- * 1. ensureChannelStream() starts or reuses an HLS capture
- * 2. Wait for the init segment (ftyp+moov codec configuration)
- * 3. Spawn FFmpeg: -f mp4 -i pipe:0 -c copy -f mpegts pipe:1
- * 4. Write init segment + existing media segments to FFmpeg stdin
- * 5. Subscribe to segment events for new segments in real time
- * 6. Pipe FFmpeg stdout to the HTTP response as video/mp2t
- * 7. On client disconnect or stream termination, kill FFmpeg and clean up
+ * 1. Validate channel and check for existing stream
+ * 2. If new stream needed, flush HTTP 200 headers immediately (so the client sees "connection accepted")
+ * 3. initializeStream() starts the capture, or awaitStreamReadySilent() waits for an in-progress startup
+ * 4. Wait for the init segment (ftyp+moov codec configuration)
+ * 5. Spawn FFmpeg: -f mp4 -i pipe:0 -c copy -f mpegts pipe:1
+ * 6. Write init segment + existing media segments to FFmpeg stdin
+ * 7. Subscribe to segment events for new segments in real time
+ * 8. Pipe FFmpeg stdout to the HTTP response as video/mp2t
+ * 9. On client disconnect or stream termination, kill FFmpeg and clean up
+ *
+ * The header flush in step 2 prevents client timeouts. Without it, the client receives zero bytes until the entire stream setup completes (4-10+ seconds), which may
+ * exceed the client's connection timeout.
  */
 // Public Endpoint Handler.
 /**
- * Handles MPEG-TS stream requests. Ensures a capture is running for the requested channel, waits for the init segment, spawns a per-client FFmpeg remuxer to convert
- * fMP4 to MPEG-TS, and streams the output to the HTTP response.
+ * Handles MPEG-TS stream requests. Validates the channel, flushes HTTP headers early for new streams, then ensures a capture is running, waits for the init segment,
+ * spawns a per-client FFmpeg remuxer, and streams the output.
+ *
+ * For new streams, headers are flushed before stream setup begins so the client sees an immediate 200 response. This prevents timeout failures during the 4-10+
+ * second startup sequence. The trade-off is that error responses cannot be sent after the flush — failures are logged server-side and the connection is closed.
  *
  * Route: GET /stream/:name
  *
@@ -37,23 +43,108 @@ export async function handleMpegTsStream(req, res) {
         res.status(400).send("Channel name is required.");
         return;
     }
-    // Ensure a stream is running for this channel. This validates the channel, starts a stream if needed, and handles concurrent startup deduplication.
-    const streamId = await ensureChannelStream(channelName, req, res);
-    if (streamId === null) {
-        // Error response already sent by ensureChannelStream.
+    // Check for an existing stream first. If one exists, we can skip validation and header flushing.
+    const existingStreamId = getChannelStreamId(channelName);
+    // Fast path: a real stream already exists. No early flush needed — the stream data will flow quickly.
+    if ((existingStreamId !== undefined) && (existingStreamId !== -1)) {
+        await serveMpegTsStream(existingStreamId, channelName, req, res);
         return;
     }
+    // If no existing stream or startup in progress, validate the channel before flushing headers. This ensures we can still return proper error responses for invalid
+    // channels, disabled channels, and login mode. Store the validated channel for use during stream initialization below.
+    let validatedChannel;
+    if (existingStreamId === undefined) {
+        const validation = validateChannel(channelName);
+        if (!validation.valid) {
+            sendValidationError(validation, res);
+            return;
+        }
+        validatedChannel = validation.channel;
+    }
+    // Flush HTTP 200 headers immediately. The client sees "connection accepted, data coming" and waits patiently. After this point, we cannot send error status codes —
+    // failures will close the connection with no data.
+    res.setHeader("Cache-Control", "no-cache");
+    res.setHeader("Connection", "close");
+    res.setHeader("Content-Type", "video/mp2t");
+    res.flushHeaders();
+    // Acquire the stream. If a startup is in progress (another request started it), poll silently. Otherwise, start a new stream via initializeStream().
+    let streamId;
+    if (existingStreamId === -1) {
+        // Another request is already starting this stream. Wait silently (no error responses possible after flush).
+        streamId = await awaitStreamReadySilent(channelName);
+        if (streamId === null) {
+            LOG.warn("MPEG-TS stream startup failed for %s (startup did not complete).", channelName);
+            res.end();
+            return;
+        }
+    }
+    else {
+        // Start a new stream directly. validatedChannel is guaranteed set: this branch runs only when existingStreamId === undefined, which requires successful
+        // validation above. Since headers are already flushed, errors are logged and the connection is closed.
+        if (!validatedChannel) {
+            res.end();
+            return;
+        }
+        try {
+            streamId = await initializeStream({
+                channel: validatedChannel,
+                channelName,
+                clientAddress: req.ip ?? req.socket.remoteAddress ?? null,
+                profileOverride: req.query.profile,
+                url: validatedChannel.url
+            });
+        }
+        catch (error) {
+            if (error instanceof StreamSetupError) {
+                LOG.warn("MPEG-TS stream startup failed for %s: %s.", channelName, error.userMessage);
+            }
+            else {
+                LOG.warn("MPEG-TS stream startup failed for %s: %s.", channelName, formatError(error));
+            }
+            res.end();
+            return;
+        }
+        if (streamId === null) {
+            LOG.warn("MPEG-TS stream startup failed for %s (terminated during setup).", channelName);
+            res.end();
+            return;
+        }
+    }
+    await serveMpegTsStream(streamId, channelName, req, res);
+}
+// Internal Helpers.
+/**
+ * Serves the MPEG-TS stream once a stream ID is available. Waits for the init segment, spawns the FFmpeg remuxer, and pipes the output to the response. This is the
+ * shared implementation used by both the fast path (existing stream) and the flush path (new stream).
+ *
+ * @param streamId - The numeric stream ID.
+ * @param channelName - The channel name for logging.
+ * @param req - Express request object.
+ * @param res - Express response object.
+ */
+async function serveMpegTsStream(streamId, channelName, req, res) {
     // Wait for the init segment to be available. The init segment contains codec configuration (ftyp+moov boxes) that FFmpeg needs before it can process media segments.
     const initReady = await waitForInitSegment(streamId, CONFIG.streaming.navigationTimeout);
     if (!initReady) {
-        res.setHeader("Retry-After", "5");
-        res.status(503).send("Stream is starting. Please retry.");
+        if (!res.headersSent) {
+            res.setHeader("Retry-After", "5");
+            res.status(503).send("Stream is starting. Please retry.");
+        }
+        else {
+            LOG.warn("MPEG-TS init segment timeout for %s.", channelName);
+            res.end();
+        }
         return;
     }
     // Get the stream from the registry and verify it's still alive with a valid init segment.
     const stream = getStream(streamId);
-    if (!stream || !stream.hls.initSegment) {
-        res.status(500).send("Stream no longer available.");
+    if (!stream?.hls.initSegment) {
+        if (!res.headersSent) {
+            res.status(500).send("Stream no longer available.");
+        }
+        else {
+            res.end();
+        }
         return;
     }
     // Capture client address for client tracking. Captured before any async operations so it remains consistent in the cleanup closure, even if the request object
@@ -74,7 +165,7 @@ export async function handleMpegTsStream(req, res) {
     // Spawn an FFmpeg process to remux fMP4 to MPEG-TS. The process reads concatenated fMP4 (init segment + media segments) from stdin and outputs a continuous
     // MPEG-TS stream on stdout. Video (H264) and audio (AAC) are copied without transcoding.
     const remuxer = spawnMpegTsRemuxer((error) => {
-        streamLog.debug("MPEG-TS remuxer error: %s.", formatError(error));
+        streamLog.debug("streaming:mpegts", "MPEG-TS remuxer error: %s.", formatError(error));
         cleanup();
         if (!res.writableEnded) {
             res.end();
@@ -121,7 +212,7 @@ export async function handleMpegTsStream(req, res) {
         stream.hls.segmentEmitter.off("segment", onSegment);
         stream.hls.segmentEmitter.off("terminated", onTerminated);
         remuxer.kill();
-        streamLog.debug("MPEG-TS client disconnected.");
+        streamLog.debug("streaming:mpegts", "MPEG-TS client disconnected.");
     };
     // Clean up when the client disconnects. Registered immediately after cleanup is assigned to minimize the window where a disconnect could be missed.
     req.on("close", () => {
@@ -130,10 +221,12 @@ export async function handleMpegTsStream(req, res) {
     // Subscribe to segment events BEFORE writing existing segments to avoid missing any segments added during the catchup phase.
     stream.hls.segmentEmitter.on("segment", onSegment);
     stream.hls.segmentEmitter.on("terminated", onTerminated);
-    // Set response headers for MPEG-TS streaming.
-    res.setHeader("Cache-Control", "no-cache");
-    res.setHeader("Connection", "close");
-    res.setHeader("Content-Type", "video/mp2t");
+    // Set response headers if they haven't been flushed yet (fast path for existing streams).
+    if (!res.headersSent) {
+        res.setHeader("Cache-Control", "no-cache");
+        res.setHeader("Connection", "close");
+        res.setHeader("Content-Type", "video/mp2t");
+    }
     // Pipe FFmpeg stdout to the HTTP response. When FFmpeg exits (either from stdin ending or being killed), stdout closes and the response ends automatically.
     remuxer.stdout.pipe(res);
     // Write the init segment first — FFmpeg needs the ftyp and moov boxes before it can process any media segments.
@@ -148,6 +241,6 @@ export async function handleMpegTsStream(req, res) {
         sentSegments.add(filename);
         remuxer.stdin.write(data);
     }
-    streamLog.debug("MPEG-TS client connected.");
+    streamLog.debug("streaming:mpegts", "MPEG-TS client connected.");
 }
 //# sourceMappingURL=mpegts.js.map

package/dist/streaming/mpegts.js.map

@@ -1 +1 @@
-{"version":3,"file":"mpegts.js","sourceRoot":"","sources":["../../src/streaming/mpegts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mpegts.js","sourceRoot":"","sources":["../../src/streaming/mpegts.ts"],"names":[],"mappings":"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"}

package/dist/streaming/registry.d.ts

@@ -116,4 +116,4 @@ export declare function getTotalSegmentMemory(): number;
  * @param entry - The stream registry entry to query.
  * @returns Segment size in bytes, or null if no segmenter exists.
  */
-export declare function getLastSegmentSize(entry: StreamRegistryEntry): number | null;
+export declare function getLastSegmentSize(entry: StreamRegistryEntry): Nullable<number>;

package/dist/streaming/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/streaming/registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/streaming/registry.ts"],"names":[],"mappings":"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"}

package/dist/streaming/setup.d.ts

@@ -7,7 +7,7 @@ import type { Readable } from "node:stream";
  * Factory function type for creating tab replacement handlers. Called by setupStream after generating stream IDs and resolving the profile, allowing the caller to
  * create a handler with access to all necessary context.
  */
-export type TabReplacementHandlerFactory = (numericStreamId: number, streamId: string, profile: ResolvedSiteProfile, metadataComment: string | undefined) => () => Promise<TabReplacementResult | null>;
+export type TabReplacementHandlerFactory = (numericStreamId: number, streamId: string, profile: ResolvedSiteProfile, metadataComment: string | undefined) => () => Promise<Nullable<TabReplacementResult>>;
 /**
  * Options for setting up a stream.
  */
@@ -58,6 +58,7 @@ export interface CreatePageWithCaptureOptions {
     profile: ResolvedSiteProfile;
     streamId: string;
     url: string;
+    _pageClosedRetries?: number;
 }
 /**
  * Result from creating a page with capture. Contains everything needed to create a segmenter and continue with stream setup.
@@ -117,3 +118,14 @@ export declare function createPageWithCapture(options: CreatePageWithCaptureOpti
  * @throws StreamSetupError if setup fails with appropriate status code and message.
  */
 export declare function setupStream(options: StreamSetupOptions, onCircuitBreak: () => void): Promise<StreamSetupResult>;
+/**
+ * Verifies that Chrome's capture system is functional before the server starts accepting requests. This detects stale tabCapture state left over from a previous
+ * Chrome process — common during quick service restarts where the old process hasn't fully exited before the new one launches. Without this probe, the first stream
+ * request would trigger the runtime stale capture handler, which exits the process because the puppeteer-stream mutex is permanently leaked.
+ *
+ * The probe creates a temporary page, attempts a short capture, and tears down both cleanly. A 500ms delay after destroying the capture stream allows
+ * puppeteer-stream's fire-and-forget STOP_RECORDING chain to complete before closing the page, preventing the stale capture cascade on the first real request.
+ *
+ * If stale capture state is detected, the process exits immediately — Chrome restart cannot fix the leaked mutex, only a fresh process can.
+ */
+export declare function verifyCaptureSystem(): Promise<void>;

package/dist/streaming/setup.js

@@ -1,5 +1,5 @@
-import { LOG, delay, extractDomain, formatError, registerAbortController, retryOperation, runWithStreamContext, spawnFFmpeg } from "../utils/index.js";
-import { closeBrowser, getCurrentBrowser, getStream, minimizeBrowserWindow, registerManagedPage, unregisterManagedPage } from "../browser/index.js";
+import { LOG, delay, extractDomain, formatError, registerAbortController, retryOperation, runWithStreamContext, spawnFFmpeg, startTimer } from "../utils/index.js";
+import { getCurrentBrowser, getStream, minimizeBrowserWindow, registerManagedPage, unregisterManagedPage } from "../browser/index.js";
 import { getNextStreamId, getStreamCount } from "./registry.js";
 import { getProfileForChannel, getProfileForUrl, getProfiles, resolveProfile } from "../config/profiles.js";
 import { initializePlayback, navigateToPage } from "../browser/video.js";
@@ -41,10 +41,9 @@ const WEBM_FFMPEG_MIME_TYPE = "video/webm;codecs=h264,opus";
 // tab with an active stream." We serialize capture initialization using a promise chain so requests execute sequentially. Once a capture is established, it runs
 // concurrently with other captures without issue.
 let captureQueue = Promise.resolve();
-// Stale capture recovery. Chrome's tabCapture can retain stale state after a crash, causing "Cannot capture a tab with an active stream" errors on fresh launches.
-// When detected, we restart Chrome entirely to clear the state. Limited to 3 attempts per server lifetime to prevent infinite loops.
-const MAX_STALE_CAPTURE_RECOVERY_ATTEMPTS = 3;
-let staleCaptureRecoveryAttempts = 0;
+// Maximum number of times createPageWithCapture() will retry when it detects that the page was closed while waiting in the capture queue (e.g., due to a browser
+// crash). An explicit guard prevents unbounded recursion.
+const MAX_PAGE_CLOSED_RETRIES = 3;
 /**
  * Error thrown when stream setup fails. Includes HTTP status code and user-friendly message for the response.
  */
@@ -144,6 +143,7 @@ export function validateStreamUrl(url) {
  * @throws Error if page creation, capture initialization, or navigation fails.
  */
 export async function createPageWithCapture(options) {
+    const captureElapsed = startTimer();
     const { comment, onFFmpegError, profile, streamId, url } = options;
     // Create browser page.
     const browser = await getCurrentBrowser();
@@ -158,6 +158,16 @@ export async function createPageWithCapture(options) {
     let outputStream;
     let rawCaptureStream = null;
     let ffmpegProcess = null;
+    // Capture queue release function, hoisted here so both the try and catch blocks can access it. Initialized in the try block when the queue entry is created.
+    // The once-guard prevents double-releasing from multiple code paths (success handler, catch block, timeout).
+    let captureQueueReleased = false;
+    let releaseCaptureQueue = () => { };
+    const releaseCaptureOnce = () => {
+        if (!captureQueueReleased) {
+            captureQueueReleased = true;
+            releaseCaptureQueue();
+        }
+    };
     // Initialize media stream capture.
     try {
         const streamOptions = {
@@ -171,17 +181,15 @@ export async function createPageWithCapture(options) {
                     maxFrameRate: 60,
                     maxHeight: getEffectiveViewport(CONFIG).height,
                     maxWidth: getEffectiveViewport(CONFIG).width,
-                    minFrameRate: CONFIG.streaming.frameRate,
+                    minFrameRate: Math.max(30, Math.min(60, CONFIG.streaming.frameRate)),
                     minHeight: getEffectiveViewport(CONFIG).height,
                     minWidth: getEffectiveViewport(CONFIG).width
                 }
             }
         };
         // Serialize capture initialization. Wait for any previous capture to finish before calling getStream(), because Chrome's tabCapture extension rejects
-        // concurrent initialization attempts. The lock is released when getStream() resolves or rejects (not when our timeout fires), because Chrome's extension state
-        // is what matters. If our timeout fires while getStream() is still in-flight, the catch block closes the page, which causes the pending getStream() to reject,
-        // which releases the lock and allows the next queued capture to proceed.
-        let releaseCaptureQueue = () => { };
+        // concurrent initialization attempts. On success, the lock is released immediately so the next caller can proceed. On failure, the lock is held until the
+        // catch block decides what to do — the catch block releases the lock after handling the error.
         const previousCapture = captureQueue;
         captureQueue = new Promise((resolve) => {
             releaseCaptureQueue = resolve;
@@ -200,12 +208,24 @@ export async function createPageWithCapture(options) {
         }
         catch (error) {
             // Release our queue position so subsequent captures aren't blocked by our failure.
-            releaseCaptureQueue();
+            releaseCaptureOnce();
             throw error;
         }
+        // After the queue wait, verify our page is still connected. If Chrome crashed while we were waiting, our page is dead and we need to start over with a
+        // fresh page on the new browser. Release our queue position first so subsequent callers aren't blocked.
+        if (page.isClosed()) {
+            releaseCaptureOnce();
+            unregisterManagedPage(page);
+            const retryCount = options._pageClosedRetries ?? 0;
+            if (retryCount >= MAX_PAGE_CLOSED_RETRIES) {
+                throw new Error("Browser crashed too many times during capture initialization.");
+            }
+            return await createPageWithCapture({ ...options, _pageClosedRetries: retryCount + 1 });
+        }
         const streamPromise = getStream(page, streamOptions);
-        // Release the queue when getStream() completes, regardless of success or failure. This is independent of our application timeout below.
-        void streamPromise.then(() => releaseCaptureQueue(), () => releaseCaptureQueue());
+        // Release the queue on success only. On failure, the catch block handles the release. The rejection handler is a no-op to suppress unhandled rejection
+        // warnings; the actual error handling happens in the catch block below.
+        void streamPromise.then(() => { releaseCaptureOnce(); }, () => { });
         const timeoutPromise = new Promise((_, reject) => {
             setTimeout(() => {
                 reject(new Error("Stream initialization timed out."));
@@ -227,7 +247,7 @@ export async function createPageWithCapture(options) {
             ffmpeg.stdout.on("error", (error) => {
                 const errorMessage = formatError(error);
                 if (errorMessage.includes("EPIPE")) {
-                    LOG.debug("FFmpeg stdout pipe closed: %s.", errorMessage);
+                    LOG.debug("streaming:ffmpeg", "FFmpeg stdout pipe closed: %s.", errorMessage);
                 }
                 else {
                     LOG.error("FFmpeg stdout pipe error: %s.", errorMessage);
@@ -249,7 +269,7 @@ export async function createPageWithCapture(options) {
                 LOG.error("Capture pipeline error: %s.", errorMessage);
                 ffmpeg.kill();
                 if (onFFmpegError) {
-                    onFFmpegError(error);
+                    onFFmpegError(error instanceof Error ? error : new Error(String(error)));
                 }
             });
             // Use FFmpeg's stdout (fMP4 output) as the output stream for segmentation.
@@ -269,27 +289,25 @@ export async function createPageWithCapture(options) {
         if (!page.isClosed()) {
             page.close().catch(() => { });
         }
-        // Check for stale capture state error. This occurs after a crash when Chrome's tabCapture retains state from the previous process. Restarting Chrome clears
-        // the stale state. We limit recovery attempts to prevent infinite loops if the issue persists.
         const errorMessage = formatError(error);
-        if (errorMessage.includes("Cannot capture a tab with an active stream") && (staleCaptureRecoveryAttempts < MAX_STALE_CAPTURE_RECOVERY_ATTEMPTS)) {
-            staleCaptureRecoveryAttempts++;
-            LOG.warn("Stale capture state detected (attempt %d/%d). Restarting Chrome to clear state.", staleCaptureRecoveryAttempts, MAX_STALE_CAPTURE_RECOVERY_ATTEMPTS);
-            // Kill Chrome entirely to clear all tabCapture state.
-            await closeBrowser();
-            // Wait for Chrome to fully exit before relaunching.
-            await delay(1500);
-            // Relaunch Chrome. getCurrentBrowser() creates a fresh instance since closeBrowser() cleared the reference.
-            await getCurrentBrowser();
-            // Retry the capture with a fresh browser.
-            return createPageWithCapture(options);
+        // Stale capture state is unrecoverable. The "Cannot capture a tab with an active stream" error occurs inside puppeteer-stream's second lock section, which
+        // has no try/finally. The internal mutex is permanently leaked — all subsequent getStream() calls will hang on it. Chrome restart cannot fix module-level
+        // state, so the only recourse is a full process restart. Release the capture queue so other callers aren't left hanging, then exit.
+        if (errorMessage.includes("Cannot capture a tab with an active stream")) {
+            LOG.error("Stale capture state detected. puppeteer-stream's internal capture mutex is now permanently locked. The capture system is unrecoverable. " +
+                "Exiting so the service manager can restart with a clean module state.");
+            releaseCaptureOnce();
+            setTimeout(() => process.exit(1), 100);
+            throw error;
         }
+        // For non-stale errors, release the capture queue so subsequent callers can proceed.
+        releaseCaptureOnce();
         throw error;
     }
     // Navigate and set up playback. For noVideo profiles, just navigate without video setup.
     let context;
     try {
-        if (profile.noVideo === false) {
+        if (!profile.noVideo) {
             // Phase 1: Navigate to the page with retry. The 10-second navigationTimeout is appropriate for page loads, and retryOperation correctly reloads the page on
             // genuine navigation failures. Navigation is wrapped in retryOperation separately from channel selection so the timeout does not race with the internal click
             // retry loops in channel selection strategies (guideGrid can take 15-20 seconds for binary search + click retries).
@@ -297,9 +315,10 @@ export async function createPageWithCapture(options) {
                 await navigateToPage(page, url, profile);
             }, CONFIG.streaming.maxNavigationRetries, CONFIG.streaming.navigationTimeout, "page navigation for " + url, undefined, () => page.isClosed());
             // Phase 2: Channel selection + video setup. Runs after navigation succeeds with no outer timeout racing against internal click retries. Each sub-step
-            // (selectChannel, waitForVideoReady, etc.) has its own internal timeout via videoTimeout and click retry constants. A 30-second safety-net timeout prevents
-            // pathological hangs if multiple internal timeouts chain sequentially.
-            const PLAYBACK_INIT_TIMEOUT = 30000;
+            // (selectChannel, waitForVideoReady, etc.) has its own internal timeout via videoTimeout and click retry constants. For guideGrid strategies, a channel
+            // selection failure triggers an overlay dismiss and retry, which doubles the channel selection time budget. The 45-second safety-net timeout accommodates
+            // this retry while still preventing pathological hangs if multiple internal timeouts chain sequentially.
+            const PLAYBACK_INIT_TIMEOUT = 45000;
             const tuneResult = await Promise.race([
                 initializePlayback(page, profile),
                 new Promise((_, reject) => {
@@ -327,10 +346,14 @@ export async function createPageWithCapture(options) {
         if (!page.isClosed()) {
             page.close().catch(() => { });
         }
+        // Re-minimize the browser window. Navigation may have un-minimized it (new tab activation on macOS), and without this the window stays visible after the
+        // failed attempt. Fire-and-forget since we're about to throw.
+        minimizeBrowserWindow().catch(() => { });
         throw error;
     }
     // Resize and minimize window.
     await resizeAndMinimizeWindow(page, !profile.noVideo);
+    LOG.debug("timing:startup", "Page with capture ready. Total: %sms.", captureElapsed());
     return {
         captureStream: outputStream,
         context,
@@ -392,7 +415,7 @@ export async function setupStream(options, onCircuitBreak) {
                 const redirectResult = getProfileForUrl(resolvedUrl);
                 if (redirectResult.profileName !== "default") {
                     profileResult = redirectResult;
-                    LOG.info("Resolved redirect for profile detection: %s → %s (%s).", urlToResolve, resolvedUrl, redirectResult.profileName);
+                    LOG.debug("streaming:setup", "Resolved redirect for profile detection: %s → %s (%s).", urlToResolve, resolvedUrl, redirectResult.profileName);
                 }
             }
         }
@@ -407,7 +430,7 @@ export async function setupStream(options, onCircuitBreak) {
             if (validProfiles.includes(profileOverride)) {
                 profile = resolveProfile(profileOverride);
                 profileName = profileOverride;
-                LOG.info("Profile overridden to '%s' via query parameter.", profileOverride);
+                LOG.debug("streaming:setup", "Profile overridden to '%s' via query parameter.", profileOverride);
             }
             else {
                 LOG.warn("Unknown profile override '%s', using resolved profile.", profileOverride);
@@ -501,7 +524,7 @@ export async function setupStream(options, onCircuitBreak) {
             // Close the browser page (fire-and-forget to avoid blocking on stuck pages).
             if (!page.isClosed()) {
                 page.close().catch((error) => {
-                    LOG.warn("Page close error during cleanup: %s.", formatError(error));
+                    LOG.debug("streaming:setup", "Page close error during cleanup: %s.", formatError(error));
                 });
             }
             // Re-minimize the browser window.
@@ -526,4 +549,81 @@ export async function setupStream(options, onCircuitBreak) {
         };
     });
 }
+// Startup Capture Verification.
+/**
+ * Verifies that Chrome's capture system is functional before the server starts accepting requests. This detects stale tabCapture state left over from a previous
+ * Chrome process — common during quick service restarts where the old process hasn't fully exited before the new one launches. Without this probe, the first stream
+ * request would trigger the runtime stale capture handler, which exits the process because the puppeteer-stream mutex is permanently leaked.
+ *
+ * The probe creates a temporary page, attempts a short capture, and tears down both cleanly. A 500ms delay after destroying the capture stream allows
+ * puppeteer-stream's fire-and-forget STOP_RECORDING chain to complete before closing the page, preventing the stale capture cascade on the first real request.
+ *
+ * If stale capture state is detected, the process exits immediately — Chrome restart cannot fix the leaked mutex, only a fresh process can.
+ */
+export async function verifyCaptureSystem() {
+    const PROBE_TIMEOUT = 5000;
+    const browser = await getCurrentBrowser();
+    const page = await browser.newPage();
+    registerManagedPage(page);
+    try {
+        // Use the same capture MIME type and viewport constraints as the runtime. The stale state error occurs at the tabCapture API level before encoding matters,
+        // but matching the runtime configuration ensures the probe exercises the exact same getStream() parameters.
+        const useFFmpeg = CONFIG.streaming.captureMode === "ffmpeg";
+        const captureMimeType = useFFmpeg ? WEBM_FFMPEG_MIME_TYPE : NATIVE_FMP4_MIME_TYPE;
+        const streamOptions = {
+            audio: true,
+            mimeType: captureMimeType,
+            video: true,
+            videoConstraints: {
+                mandatory: {
+                    maxFrameRate: 30,
+                    maxHeight: getEffectiveViewport(CONFIG).height,
+                    maxWidth: getEffectiveViewport(CONFIG).width,
+                    minFrameRate: 30,
+                    minHeight: getEffectiveViewport(CONFIG).height,
+                    minWidth: getEffectiveViewport(CONFIG).width
+                }
+            }
+        };
+        const stream = await Promise.race([
+            getStream(page, streamOptions),
+            new Promise((_, reject) => {
+                setTimeout(() => {
+                    reject(new Error("Capture probe timed out."));
+                }, PROBE_TIMEOUT);
+            })
+        ]);
+        // Capture succeeded — the system is functional. Destroy the stream before closing the page to ensure chrome.tabCapture releases the capture cleanly.
+        const readable = stream;
+        readable.destroy();
+        // Wait for puppeteer-stream's capture cleanup chain to complete. readable.destroy() triggers STOP_RECORDING via the close handler, but the call is
+        // fire-and-forget. The async chain (STOP_RECORDING → recorder.stop() → onstop → track.stop()) must finish before closing the page, or Chrome's tabCapture
+        // state may linger and cause "Cannot capture a tab with an active stream" errors on the first real stream request.
+        await delay(500);
+        unregisterManagedPage(page);
+        if (!page.isClosed()) {
+            await page.close();
+        }
+        LOG.info("Capture system verified successfully.");
+    }
+    catch (error) {
+        const errorMessage = formatError(error);
+        // Clean up the test page.
+        unregisterManagedPage(page);
+        if (!page.isClosed()) {
+            page.close().catch(() => { });
+        }
+        // Stale capture state is unrecoverable. The error occurs inside puppeteer-stream's second lock section, which has no try/finally — the internal mutex is
+        // permanently leaked. All subsequent getStream() calls will hang on it. Chrome restart cannot fix module-level state, so exit and let the service manager
+        // restart with a clean process.
+        if (errorMessage.includes("Cannot capture a tab with an active stream")) {
+            LOG.error("Startup probe detected stale capture state. puppeteer-stream's internal capture mutex is now permanently locked. Exiting so the service " +
+                "manager can restart with a clean module state.");
+            process.exit(1);
+        }
+        // Non-stale error. Fail immediately — retrying without restarting Chrome won't change anything, and a non-stale getStream() failure at startup indicates a
+        // fundamental problem (extension not loaded, Chrome misconfigured, etc.).
+        throw new Error("Capture system verification failed: " + errorMessage);
+    }
+}
 //# sourceMappingURL=setup.js.map