@bnhf/prismcast 1.3.4-2026.2.19

package/dist/streaming/setup.js

@@ -0,0 +1,670 @@
+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";
+import { invalidateDirectUrl, resolveDirectUrl } from "../browser/channelSelection.js";
+import { CONFIG } from "../config/index.js";
+import { getEffectiveViewport } from "../config/presets.js";
+import { getProviderDisplayName } from "../config/providers.js";
+import { monitorPlaybackHealth } from "./monitor.js";
+import { pipeline } from "node:stream/promises";
+import { resizeAndMinimizeWindow } from "../browser/cdp.js";
+/* This module contains the common stream setup logic for HLS streaming. The core logic is split into two functions:
+ *
+ * 1. createPageWithCapture(): Creates a browser page, starts media capture, navigates to the URL, and sets up video playback. This is the reusable core that both
+ *    initial stream setup and tab replacement recovery use.
+ *
+ * 2. setupStream(): Orchestrates stream creation by calling createPageWithCapture(), then registering the stream and starting the health monitor. This is the
+ *    entry point for new stream requests.
+ *
+ * The separation allows tab replacement recovery (in monitor.ts) to reuse the capture setup logic without duplicating code. When a browser tab becomes unresponsive,
+ * the recovery handler can close the old tab, call createPageWithCapture() to create a fresh one, and continue with the same stream ID.
+ *
+ * createPageWithCapture() handles:
+ * - Browser page creation with CSP bypass
+ * - Media stream initialization (native fMP4 or WebM+FFmpeg)
+ * - Navigation with retry
+ * - Video element detection and playback setup
+ *
+ * setupStream() additionally handles:
+ * - Request validation (URL format, concurrent stream limit)
+ * - Stream registration
+ * - Health monitor startup
+ * - Cleanup function creation
+ */
+// Native fMP4 capture uses MP4/AAC for direct HLS segmentation without transcoding.
+const NATIVE_FMP4_MIME_TYPE = "video/mp4;codecs=avc1,mp4a.40.2";
+// WebM+FFmpeg capture uses WebM/H264+Opus, which requires FFmpeg to transcode audio to AAC. This mode is more stable for long recordings because Chrome's native fMP4
+// MediaRecorder can become unstable after 20-30 minutes.
+const WEBM_FFMPEG_MIME_TYPE = "video/webm;codecs=h264,opus";
+// Capture initialization queue. Chrome's tabCapture extension can only initialize one capture at a time — concurrent getStream() calls fail with "Cannot capture a
+// 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();
+// 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.
+ */
+export class StreamSetupError extends Error {
+    statusCode;
+    userMessage;
+    constructor(message, statusCode, userMessage) {
+        super(message);
+        this.name = "StreamSetupError";
+        this.statusCode = statusCode;
+        this.userMessage = userMessage;
+    }
+}
+// Request ID Generation.
+/**
+ * Generates a short alphanumeric request ID for log correlation. The ID is 6 characters to keep log messages readable while providing enough uniqueness for
+ * practical debugging. With 36 possible characters (a-z, 0-9), there are 2.1 billion possible IDs, making collisions unlikely during any debugging session.
+ * @returns A 6-character alphanumeric string.
+ */
+function generateRequestId() {
+    const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+    let result = "";
+    for (let i = 0; i < 6; i++) {
+        result += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    return result;
+}
+/**
+ * Generates a concise stream identifier for logging purposes. The identifier combines the channel name or hostname with a unique request ID, making it easy to
+ * trace related log messages. We prefer the channel name when available because it's more meaningful than a hostname.
+ * @param channelName - The channel name if streaming a named channel.
+ * @param url - The URL being streamed.
+ * @returns A concise stream identifier.
+ */
+export function generateStreamId(channelName, url) {
+    const requestId = generateRequestId();
+    // If we have a channel name, use it as the prefix. Channel names are short and meaningful (e.g., "nbc", "espn").
+    if (channelName) {
+        return [channelName, "-", requestId].join("");
+    }
+    // For direct URL requests, use the concise domain as the prefix.
+    if (url) {
+        return [extractDomain(url), "-", requestId].join("");
+    }
+    // Fallback when neither channel name nor URL is available. This shouldn't happen in normal operation but provides a valid ID for edge cases.
+    return ["unknown-", requestId].join("");
+}
+// URL Validation.
+/**
+ * Validates a URL before attempting to navigate to it. This function checks for supported protocols, prevents local file access, and ensures the URL is properly
+ * formatted. Validating URLs before navigation prevents security issues and provides clear error messages.
+ * @param url - The URL to validate.
+ * @returns Validation result with optional reason for failure.
+ */
+export function validateStreamUrl(url) {
+    // A URL is required. This catches both undefined and empty string.
+    if (!url) {
+        return { reason: "URL is required.", valid: false };
+    }
+    try {
+        const parsed = new URL(url);
+        // We support HTTP, HTTPS, and chrome: protocols. HTTP and HTTPS are standard web protocols, while chrome: URLs are used for internal pages like
+        // chrome://gpu for diagnostics. Other protocols (javascript:, data:, blob:) are not supported.
+        const allowedProtocols = ["chrome:", "http:", "https:"];
+        if (!allowedProtocols.includes(parsed.protocol)) {
+            return { reason: ["Unsupported protocol: ", parsed.protocol].join(""), valid: false };
+        }
+        // Local file access is explicitly blocked for security reasons. While the URL constructor wouldn't typically parse a file: URL through the protocol check
+        // above, we check explicitly for defense in depth.
+        if (parsed.protocol === "file:") {
+            return { reason: "Local file access is not permitted.", valid: false };
+        }
+        return { valid: true };
+    }
+    catch (_error) {
+        // The URL constructor throws for invalid URLs. We catch this and return a clear error message.
+        return { reason: "Invalid URL format.", valid: false };
+    }
+}
+// Page and Capture Creation.
+/**
+ * Creates a browser page with media capture and navigates to the URL. This is the reusable core function used by both initial stream setup and tab replacement
+ * recovery. It handles:
+ * - Creating a new browser page with CSP bypass
+ * - Initializing media capture (native fMP4 or WebM+FFmpeg)
+ * - Navigating to the URL with retry
+ * - Setting up video playback via navigateToPage() + initializePlayback()
+ *
+ * The caller is responsible for:
+ * - Creating the segmenter and piping captureStream to it
+ * - Registering/updating the stream in the registry
+ * - Starting/updating the health monitor
+ * - Handling cleanup on failure
+ *
+ * @param options - Options for page and capture creation.
+ * @returns The page, context, capture stream, and FFmpeg process (if any).
+ * @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();
+    const page = await browser.newPage();
+    registerManagedPage(page);
+    await page.setBypassCSP(true);
+    // Select MIME type based on capture mode. FFmpeg mode is more stable for long recordings because Chrome's native fMP4 MediaRecorder can become unstable.
+    const useFFmpeg = CONFIG.streaming.captureMode === "ffmpeg";
+    const captureMimeType = useFFmpeg ? WEBM_FFMPEG_MIME_TYPE : NATIVE_FMP4_MIME_TYPE;
+    // Track the output stream that will be sent to the segmenter and FFmpeg process if used. Also track the raw capture stream separately - it must be destroyed
+    // before closing the page to ensure chrome.tabCapture releases the capture.
+    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 = {
+            audio: true,
+            audioBitsPerSecond: CONFIG.streaming.audioBitsPerSecond,
+            mimeType: captureMimeType,
+            video: true,
+            videoBitsPerSecond: CONFIG.streaming.videoBitsPerSecond,
+            videoConstraints: {
+                mandatory: {
+                    maxFrameRate: 60,
+                    maxHeight: getEffectiveViewport(CONFIG).height,
+                    maxWidth: getEffectiveViewport(CONFIG).width,
+                    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. 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;
+        });
+        // Guard against a permanently hung predecessor. If the previous capture doesn't complete within the navigation timeout, release our queue position and let the
+        // caller's error handling deal with it. This prevents a single stuck getStream() from blocking all future captures indefinitely.
+        try {
+            await Promise.race([
+                previousCapture,
+                new Promise((_, reject) => {
+                    setTimeout(() => {
+                        reject(new Error("Capture queue wait timed out."));
+                    }, CONFIG.streaming.navigationTimeout);
+                })
+            ]);
+        }
+        catch (error) {
+            // Release our queue position so subsequent captures aren't blocked by our failure.
+            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 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."));
+            }, CONFIG.streaming.navigationTimeout);
+        });
+        const stream = await Promise.race([streamPromise, timeoutPromise]);
+        // Store the raw capture stream. This must be destroyed before closing the page.
+        rawCaptureStream = stream;
+        // For FFmpeg mode, spawn FFmpeg to transcode the WebM stream to fMP4. FFmpeg copies the H264 video and transcodes Opus audio to AAC.
+        if (useFFmpeg) {
+            const ffmpeg = spawnFFmpeg(CONFIG.streaming.audioBitsPerSecond, (error) => {
+                LOG.error("FFmpeg process error: %s.", formatError(error));
+                if (onFFmpegError) {
+                    onFFmpegError(error);
+                }
+            }, streamId, comment);
+            ffmpegProcess = ffmpeg;
+            // Handle pipe errors on stdout. Stdin errors are handled by pipeline() below.
+            ffmpeg.stdout.on("error", (error) => {
+                const errorMessage = formatError(error);
+                if (errorMessage.includes("EPIPE")) {
+                    LOG.debug("streaming:ffmpeg", "FFmpeg stdout pipe closed: %s.", errorMessage);
+                }
+                else {
+                    LOG.error("FFmpeg stdout pipe error: %s.", errorMessage);
+                    ffmpeg.kill();
+                    if (onFFmpegError) {
+                        onFFmpegError(error);
+                    }
+                }
+            });
+            // Pipe the WebM capture stream to FFmpeg's stdin using pipeline() for proper cleanup. When FFmpeg is killed during tab replacement, pipeline() automatically
+            // destroys the source stream, preventing "write after end" errors that would occur with .pipe().
+            pipeline(stream, ffmpeg.stdin).catch((error) => {
+                const errorMessage = formatError(error);
+                // EPIPE, "write after end", and "Premature close" errors are expected during cleanup when FFmpeg is killed or the capture stream is destroyed.
+                if (errorMessage.includes("EPIPE") || errorMessage.includes("write after end") || errorMessage.includes("Premature close")) {
+                    return;
+                }
+                // Unexpected pipeline errors require cleanup.
+                LOG.error("Capture pipeline error: %s.", errorMessage);
+                ffmpeg.kill();
+                if (onFFmpegError) {
+                    onFFmpegError(error instanceof Error ? error : new Error(String(error)));
+                }
+            });
+            // Use FFmpeg's stdout (fMP4 output) as the output stream for segmentation.
+            outputStream = ffmpeg.stdout;
+        }
+        else {
+            // Native fMP4 mode: Use the raw capture stream directly. In this mode, rawCaptureStream and outputStream are the same object.
+            outputStream = rawCaptureStream;
+        }
+    }
+    catch (error) {
+        // Clean up on capture initialization failure. Destroy the raw capture stream first to ensure chrome.tabCapture releases the capture.
+        if (rawCaptureStream && !rawCaptureStream.destroyed) {
+            rawCaptureStream.destroy();
+        }
+        unregisterManagedPage(page);
+        if (!page.isClosed()) {
+            page.close().catch(() => { });
+        }
+        const errorMessage = formatError(error);
+        // 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;
+    let usedDirectUrl = false;
+    try {
+        if (!profile.noVideo) {
+            // Check for a direct watch URL. If available, navigate directly to it and skip channel selection, avoiding guide page navigation entirely. On failure,
+            // the cache entry is invalidated in the catch block so the outer retry loop (in streaming/hls.ts) re-invokes with the guide URL.
+            const directUrl = await resolveDirectUrl(profile, page);
+            usedDirectUrl = !!directUrl;
+            const navigationUrl = directUrl ?? url;
+            // 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).
+            await retryOperation(async () => {
+                await navigateToPage(page, navigationUrl, profile);
+            }, CONFIG.streaming.maxNavigationRetries, CONFIG.streaming.navigationTimeout, "page navigation for " + navigationUrl, undefined, () => page.isClosed());
+            // Phase 2: Channel selection + video setup. When navigating to a cached direct URL, skip channel selection since the URL already targets the correct
+            // channel. 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. 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, usedDirectUrl),
+                new Promise((_, reject) => {
+                    setTimeout(() => {
+                        reject(new Error("Playback initialization timed out after " + String(PLAYBACK_INIT_TIMEOUT) + "ms."));
+                    }, PLAYBACK_INIT_TIMEOUT);
+                })
+            ]);
+            context = tuneResult.context;
+        }
+        else {
+            await page.goto(url);
+            context = page;
+        }
+    }
+    catch (error) {
+        // If a cached direct URL was used, invalidate it so the next attempt falls through to guide navigation.
+        if (usedDirectUrl) {
+            invalidateDirectUrl(profile);
+        }
+        // Clean up on navigation or playback initialization failure. Destroy the raw capture stream first to ensure chrome.tabCapture releases the capture.
+        if (!rawCaptureStream.destroyed) {
+            rawCaptureStream.destroy();
+        }
+        if (ffmpegProcess) {
+            ffmpegProcess.kill();
+        }
+        unregisterManagedPage(page);
+        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,
+        ffmpegProcess,
+        page,
+        rawCaptureStream
+    };
+}
+// URL Redirect Resolution.
+/**
+ * Resolves a URL's final destination by following HTTP redirects. This is used for profile detection when a channel's URL belongs to an indirection service (e.g.,
+ * FruitDeepLinks) whose domain has no profile mapping. By following redirects, we discover the actual streaming site's domain and can resolve the correct profile.
+ *
+ * Uses a HEAD request to avoid downloading response bodies. The 3-second timeout ensures stream startup isn't blocked by slow or unreachable indirection services.
+ *
+ * @param url - The URL to resolve.
+ * @returns The final URL after following all redirects, or null on any error.
+ */
+async function resolveRedirectUrl(url) {
+    try {
+        const response = await fetch(url, { method: "HEAD", signal: AbortSignal.timeout(3000) });
+        return response.url;
+    }
+    catch {
+        return null;
+    }
+}
+// Stream Setup.
+/**
+ * Sets up a stream: validates input, creates browser page, initializes capture, navigates to URL, and starts health monitoring.
+ *
+ * This function handles all common stream setup logic. The caller is responsible for:
+ * - Connecting the returned captureStream to the appropriate output (HTTP response, FFmpeg, etc.)
+ * - Registering the stream in the registry
+ * - Triggering cleanup when the stream ends
+ *
+ * @param options - Stream configuration options.
+ * @param onCircuitBreak - Callback invoked when the circuit breaker trips (stream unrecoverable).
+ * @returns Setup result with capture stream, cleanup function, and metadata.
+ * @throws StreamSetupError if setup fails with appropriate status code and message.
+ */
+export async function setupStream(options, onCircuitBreak) {
+    const { channel, channelName, channelSelector, clickSelector, clickToPlay, noVideo, onTabReplacementFactory, profileOverride, url } = options;
+    // Generate stream identifiers early so all log messages include them.
+    const streamId = generateStreamId(channelName, url);
+    const numericStreamId = getNextStreamId();
+    const startTime = new Date();
+    // Create and register the AbortController for this stream. This allows pending evaluate calls to be cancelled immediately when the stream is terminated.
+    const abortController = new AbortController();
+    registerAbortController(streamId, abortController);
+    // Resolve the profile for this stream. If the original URL's domain has no mapping (profileName === "default"), try following HTTP redirects to discover the
+    // actual destination domain. This supports indirection services like FruitDeepLinks that use redirect URLs to route to the actual streaming site.
+    let profileResult = channel ? getProfileForChannel(channel) : getProfileForUrl(url);
+    if (profileResult.profileName === "default") {
+        const urlToResolve = channel?.url ?? url;
+        if (urlToResolve) {
+            const resolvedUrl = await resolveRedirectUrl(urlToResolve);
+            if (resolvedUrl && (resolvedUrl !== urlToResolve)) {
+                const redirectResult = getProfileForUrl(resolvedUrl);
+                if (redirectResult.profileName !== "default") {
+                    profileResult = redirectResult;
+                    LOG.debug("streaming:setup", "Resolved redirect for profile detection: %s → %s (%s).", urlToResolve, resolvedUrl, redirectResult.profileName);
+                }
+            }
+        }
+    }
+    let profile = profileResult.profile;
+    let profileName = profileResult.profileName;
+    // Wrap the setup in stream context for log correlation.
+    return runWithStreamContext({ channelName: channel?.name, streamId, url }, async () => {
+        // Apply profile override if specified.
+        if (profileOverride) {
+            const validProfiles = getProfiles().map((p) => p.name);
+            if (validProfiles.includes(profileOverride)) {
+                profile = resolveProfile(profileOverride);
+                profileName = profileOverride;
+                LOG.debug("streaming:setup", "Profile overridden to '%s' via query parameter.", profileOverride);
+            }
+            else {
+                LOG.warn("Unknown profile override '%s', using resolved profile.", profileOverride);
+            }
+        }
+        // Apply noVideo override if specified.
+        if (noVideo) {
+            profile = { ...profile, noVideo: true };
+        }
+        // Merge the ad-hoc channel selector into the profile if provided. This must happen after the profile override block above, which replaces the profile object
+        // wholesale and would discard an earlier merge. For predefined channels, getProfileForChannel already handles the merge from channel.channelSelector.
+        if (channelSelector) {
+            profile = { ...profile, channelSelector };
+        }
+        // Merge the ad-hoc clickToPlay and clickSelector options into the profile. clickSelector implies clickToPlay. For ad-hoc streams, these enable clicking an
+        // element to start playback - either the video element (clickToPlay alone) or a play button overlay (clickToPlay + clickSelector).
+        if (clickToPlay || clickSelector) {
+            profile = { ...profile, clickToPlay: true, ...(clickSelector ? { clickSelector } : {}) };
+        }
+        // Compute the metadata comment for FFmpeg. Prefer the friendly channel name, fall back to the channel key, or extract the domain from the URL.
+        const metadataComment = channel?.name ?? channelName ?? extractDomain(url);
+        // Compute the friendly provider display name once for use in both the monitor and the setup result.
+        const providerName = getProviderDisplayName(url);
+        // Create the tab replacement handler if a factory was provided. This is done after profile resolution so the handler has access to the final profile.
+        const onTabReplacement = onTabReplacementFactory ? onTabReplacementFactory(numericStreamId, streamId, profile, metadataComment) : undefined;
+        // Validate URL.
+        const validation = validateStreamUrl(url);
+        if (!validation.valid) {
+            LOG.error("Invalid URL requested: %s - %s.", url, validation.reason ?? "Unknown error");
+            throw new StreamSetupError(["Invalid URL: ", validation.reason ?? "Unknown error"].join(""), 400, validation.reason ?? "Invalid URL.");
+        }
+        // Check concurrent stream limit.
+        if (getStreamCount() >= CONFIG.streaming.maxConcurrentStreams) {
+            LOG.warn("Concurrent stream limit reached (%s/%s). Rejecting request.", getStreamCount(), CONFIG.streaming.maxConcurrentStreams);
+            throw new StreamSetupError("Concurrent stream limit reached.", 503, ["Maximum concurrent streams (", String(CONFIG.streaming.maxConcurrentStreams), ") reached. Try again later."].join(""));
+        }
+        // Create page and start capture using the shared function. This handles browser page creation, capture initialization, FFmpeg spawning, and navigation with retry.
+        let captureResult;
+        try {
+            captureResult = await createPageWithCapture({
+                comment: metadataComment,
+                onFFmpegError: onCircuitBreak,
+                profile,
+                streamId,
+                url
+            });
+        }
+        catch (error) {
+            // createPageWithCapture handles its own cleanup on failure (closes page, kills FFmpeg).
+            const errorMessage = formatError(error);
+            const isBenign = errorMessage.toLowerCase().includes("abort") || errorMessage.toLowerCase().includes("session closed");
+            if (!isBenign) {
+                LOG.error("Stream setup failed for %s: %s.", url, errorMessage);
+            }
+            // Capture infrastructure errors should return 503 to signal Channels DVR to back off. These include Chrome capture state issues, queue timeouts, and stream
+            // initialization failures. Using 503 with Retry-After prevents retry storms when there's a systemic issue.
+            const captureErrorPatterns = ["Cannot capture", "timed out", "Capture queue"];
+            const isCaptureError = captureErrorPatterns.some((pattern) => errorMessage.includes(pattern));
+            throw new StreamSetupError("Stream error.", isCaptureError ? 503 : 500, "Failed to start stream.");
+        }
+        const { captureStream, context, ffmpegProcess, page, rawCaptureStream } = captureResult;
+        // Monitor stream info for status updates.
+        const monitorStreamInfo = {
+            channelName: channel?.name ?? null,
+            numericStreamId,
+            providerName,
+            startTime
+        };
+        // Start the health monitor for this stream.
+        const stopMonitor = monitorPlaybackHealth(page, context, profile, url, streamId, monitorStreamInfo, onCircuitBreak, onTabReplacement);
+        // Cleanup function. Releases all resources associated with the stream. Idempotent - safe to call multiple times.
+        let cleanupCompleted = false;
+        const cleanup = async () => {
+            if (cleanupCompleted) {
+                return;
+            }
+            cleanupCompleted = true;
+            // Stop the health monitor first.
+            stopMonitor();
+            // Destroy the raw capture stream BEFORE closing the page. This triggers puppeteer-stream's close handler while the browser is still connected, ensuring
+            // STOP_RECORDING is called and chrome.tabCapture releases the capture. Without this, subsequent getStream() calls may hang with "active stream" errors.
+            if (!rawCaptureStream.destroyed) {
+                rawCaptureStream.destroy();
+            }
+            // Kill the FFmpeg process if using WebM+FFmpeg mode.
+            if (ffmpegProcess) {
+                ffmpegProcess.kill();
+            }
+            // Unregister from managed pages.
+            unregisterManagedPage(page);
+            // Close the browser page (fire-and-forget to avoid blocking on stuck pages).
+            if (!page.isClosed()) {
+                page.close().catch((error) => {
+                    LOG.debug("streaming:setup", "Page close error during cleanup: %s.", formatError(error));
+                });
+            }
+            // Re-minimize the browser window.
+            await minimizeBrowserWindow();
+        };
+        // Return the setup result.
+        return {
+            captureStream,
+            channelName: channel?.name ?? null,
+            cleanup,
+            ffmpegProcess,
+            numericStreamId,
+            page,
+            profile,
+            profileName,
+            providerName,
+            rawCaptureStream,
+            startTime,
+            stopMonitor,
+            streamId,
+            url
+        };
+    });
+}
+// 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.
+ *
+ * After a system reboot, Chrome's display stack or capture extension may not be ready when the service manager starts PrismCast. The probe retries up to
+ * PROBE_MAX_ATTEMPTS times with a delay between attempts, giving the system time to settle before giving up. This prevents a rapid restart storm where the service
+ * manager relaunches PrismCast repeatedly, each attempt orphaning a Chrome process and degrading the environment further.
+ *
+ * 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_MAX_ATTEMPTS = 3;
+    const PROBE_RETRY_DELAY = 5000;
+    const PROBE_TIMEOUT = 5000;
+    for (let attempt = 1; attempt <= PROBE_MAX_ATTEMPTS; attempt++) {
+        // eslint-disable-next-line no-await-in-loop -- Sequential retries are intentional; each probe must complete before deciding whether to retry.
+        const result = await attemptCaptureProbe(PROBE_TIMEOUT);
+        // Probe succeeded.
+        if (result === null) {
+            return;
+        }
+        // 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 (result.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);
+        }
+        // If we have retries remaining, log a warning and wait before the next attempt.
+        if (attempt < PROBE_MAX_ATTEMPTS) {
+            LOG.warn("Capture probe attempt %d of %d failed: %s. Retrying in %ds.", attempt, PROBE_MAX_ATTEMPTS, result, PROBE_RETRY_DELAY / 1000);
+            // eslint-disable-next-line no-await-in-loop -- Deliberate delay between sequential retry attempts.
+            await delay(PROBE_RETRY_DELAY);
+        }
+        else {
+            throw new Error("Capture system verification failed after " + String(PROBE_MAX_ATTEMPTS) + " attempts: " + result);
+        }
+    }
+}
+/**
+ * Executes a single capture probe attempt. Creates a temporary page, tries to start a capture stream, and tears everything down cleanly.
+ * @param timeout - Maximum time in milliseconds to wait for getStream() to respond.
+ * @returns Null on success, or an error message string on failure.
+ */
+async function attemptCaptureProbe(timeout) {
+    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."));
+                }, 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.");
+        return null;
+    }
+    catch (error) {
+        const errorMessage = formatError(error);
+        // Clean up the test page.
+        unregisterManagedPage(page);
+        if (!page.isClosed()) {
+            page.close().catch(() => { });
+        }
+        return errorMessage;
+    }
+}
+//# sourceMappingURL=setup.js.map