@bnhf/prismcast 1.3.4-2026.2.19

package/dist/utils/debugFilter.js

@@ -0,0 +1,157 @@
+/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * debugFilter.ts: Category-based debug log filtering for PrismCast.
+ */
+/* The debug filter provides category-based control over debug log output, inspired by the `debug` npm package. Categories use colon-separated namespaces
+ * (e.g., "tuning:hulu", "recovery:tab") and the PRISMCAST_DEBUG environment variable accepts comma-separated patterns with wildcard and exclusion support.
+ *
+ * Pattern syntax:
+ *   - "*" enables all categories.
+ *   - "category" enables an exact category or any sub-category (prefix match).
+ *   - "-category" excludes a category or its sub-categories, even when wildcard is active.
+ *
+ * Examples:
+ *   PRISMCAST_DEBUG=tuning:hulu          Only Hulu tuning messages.
+ *   PRISMCAST_DEBUG=recovery             All recovery sub-categories (recovery:tab, recovery:nav, etc.).
+ *   PRISMCAST_DEBUG=*,-streaming:ffmpeg,-streaming:segmenter  Everything except FFmpeg and segmenter messages.
+ */
+// Whether any debug output is configured at all. Fast-path check avoids category string work when debug is off.
+let anyEnabled = false;
+// Whether wildcard (*) was specified — all categories pass unless explicitly excluded.
+let wildcardEnabled = false;
+// Categories to include (exact or prefix match).
+const includeSet = new Set();
+// Categories to exclude (exact or prefix match). Takes priority over includes and wildcard.
+const excludeSet = new Set();
+/**
+ * Checks whether a category matches any pattern in the given set. A pattern matches if it equals the category exactly or if the category starts with the pattern
+ * followed by a colon (prefix match for sub-categories).
+ * @param category - The category to check.
+ * @param patterns - The set of patterns to match against.
+ * @returns True if the category matches any pattern.
+ */
+function matchesAny(category, patterns) {
+    if (patterns.has(category)) {
+        return true;
+    }
+    for (const pattern of patterns) {
+        if (category.startsWith(pattern + ":")) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Parses a comma-separated pattern string and configures the debug filter. Calling this function replaces any previous filter configuration.
+ * @param pattern - Comma-separated list of category patterns (e.g., "tuning:hulu,recovery,-streaming:ffmpeg").
+ */
+export function initDebugFilter(pattern) {
+    // Reset state.
+    includeSet.clear();
+    excludeSet.clear();
+    wildcardEnabled = false;
+    anyEnabled = false;
+    const parts = pattern.split(",").map((p) => p.trim()).filter((p) => p.length > 0);
+    if (parts.length === 0) {
+        return;
+    }
+    for (const part of parts) {
+        if (part === "*") {
+            wildcardEnabled = true;
+        }
+        else if (part.startsWith("-")) {
+            excludeSet.add(part.substring(1));
+        }
+        else {
+            includeSet.add(part);
+        }
+    }
+    anyEnabled = true;
+}
+/**
+ * Checks whether a specific debug category is enabled under the current filter configuration.
+ * @param category - The category to check (e.g., "tuning:hulu", "recovery:tab").
+ * @returns True if debug output should be produced for this category.
+ */
+export function isCategoryEnabled(category) {
+    if (!anyEnabled) {
+        return false;
+    }
+    // Excludes always win, even over wildcard.
+    if (matchesAny(category, excludeSet)) {
+        return false;
+    }
+    if (wildcardEnabled) {
+        return true;
+    }
+    return matchesAny(category, includeSet);
+}
+/**
+ * Fast-path check for whether any debug categories are configured. When this returns false, callers can skip category string construction entirely.
+ * @returns True if at least one debug category is enabled.
+ */
+export function isAnyDebugEnabled() {
+    return anyEnabled;
+}
+/**
+ * Reconstructs the current filter pattern string from internal state. Returns an empty string when no debug output is configured.
+ * @returns The current pattern string (e.g., "*,-streaming:ffmpeg" or "tuning:hulu,recovery").
+ */
+export function getCurrentPattern() {
+    if (!anyEnabled) {
+        return "";
+    }
+    const parts = [];
+    if (wildcardEnabled) {
+        parts.push("*");
+    }
+    // Exclude entries are prefixed with "-".
+    for (const entry of excludeSet) {
+        parts.push("-" + entry);
+    }
+    // Include entries are bare category names.
+    for (const entry of includeSet) {
+        parts.push(entry);
+    }
+    return parts.join(",");
+}
+/**
+ * Static registry of all known debug categories with descriptions. Sorted alphabetically by category. The /debug endpoint uses this to render hierarchical checkboxes.
+ * Parent groups (e.g., "streaming", "timing", "tuning") are derived by the UI from the colon-separated namespaces — only leaf categories are declared here.
+ */
+export const DEBUG_CATEGORIES = [
+    { category: "browser", description: "Browser lifecycle: launch, close, stale page cleanup, restart." },
+    { category: "browser:video", description: "Video context, fullscreen, volume locking, playback." },
+    { category: "config", description: "Provider groups, version checking." },
+    { category: "recovery", description: "General recovery: browser re-minimize, monitor abort." },
+    { category: "recovery:context", description: "Video context: frame detachment, re-search." },
+    { category: "recovery:nav", description: "Page navigation recovery: new tab detection, URL validation." },
+    { category: "recovery:segments", description: "Segment production: self-heal detection." },
+    { category: "recovery:tab", description: "Tab replacement: old tab cleanup, new tab creation, retries." },
+    { category: "retry", description: "Retry attempts, page-closed aborts." },
+    { category: "streaming:ffmpeg", description: "FFmpeg stderr output, pipe errors." },
+    { category: "streaming:hls", description: "HLS segment storage, page close errors." },
+    { category: "streaming:mpegts", description: "MPEG-TS remuxer errors, client connect/disconnect." },
+    { category: "streaming:segmenter", description: "fMP4 parsing: keyframes, init segments, duration clamping." },
+    { category: "streaming:setup", description: "Stream setup: redirect resolution, profile override, capture init." },
+    { category: "streaming:showinfo", description: "Channels DVR show name lookups, device mapping." },
+    { category: "timing:browser", description: "Browser launch: process spawn, extension init, display detection." },
+    { category: "timing:hls", description: "HLS playlist delivery time." },
+    { category: "timing:recovery", description: "Recovery totals: navigation recovery, tab replacement." },
+    { category: "timing:startup", description: "Stream startup: init segment, first playlist, capture ready." },
+    { category: "timing:tab", description: "Tab replacement: old tab cleanup, new page creation." },
+    { category: "timing:tune", description: "Tune waterfall: navigation, channel selection, video ready." },
+    { category: "tuning:hbo", description: "HBO Max: tab URL discovery, channel rail, navigation." },
+    { category: "tuning:hulu", description: "Hulu Live guide grid: binary search, cache, click retries." },
+    { category: "tuning:sling", description: "Sling TV guide grid: binary search, cache, click retries." },
+    { category: "tuning:yttv", description: "YouTube TV EPG grid navigation." }
+];
+/**
+ * Creates a lightweight elapsed-time closure using performance.now(). Call the returned function to get the elapsed milliseconds since creation.
+ * @returns A closure that returns elapsed milliseconds as a number.
+ */
+export function startTimer() {
+    const start = performance.now();
+    return () => Math.round(performance.now() - start);
+}
+//# sourceMappingURL=debugFilter.js.map

package/dist/utils/debugFilter.js.map

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

package/dist/utils/delay.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Creates a promise that resolves after the specified delay. This is a convenience wrapper around setTimeout that allows using async/await syntax for delays.
+ * @param ms - The delay duration in milliseconds.
+ * @returns A promise that resolves after the specified delay.
+ */
+export declare function delay(ms: number): Promise<void>;

package/dist/utils/delay.js

@@ -0,0 +1,15 @@
+/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * delay.ts: Async delay utility for PrismCast.
+ */
+/**
+ * Creates a promise that resolves after the specified delay. This is a convenience wrapper around setTimeout that allows using async/await syntax for delays.
+ * @param ms - The delay duration in milliseconds.
+ * @returns A promise that resolves after the specified delay.
+ */
+export async function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+//# sourceMappingURL=delay.js.map

package/dist/utils/delay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delay.js","sourceRoot":"","sources":["../../src/utils/delay.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,EAAU;IAEpC,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAEnC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/utils/errors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Formats an error for logging by extracting the message if available, falling back to string conversion for non-Error objects. Trailing punctuation is stripped
+ * to allow callers to add consistent punctuation in their log format strings.
+ * @param error - The error to format.
+ * @returns A string representation suitable for logging, without trailing punctuation.
+ */
+export declare function formatError(error: unknown): string;
+/**
+ * Checks whether an error indicates that the browser page or session has been closed or is otherwise unrecoverable. These errors should cause immediate abort of
+ * any retry loops rather than continuing to retry an operation that will never succeed. Common unrecoverable errors include closed targets, closed sessions, and
+ * detached frames (which occur when the page has been closed mid-operation).
+ * @param error - The error to check.
+ * @returns True if the error indicates a closed or unrecoverable state.
+ */
+export declare function isSessionClosedError(error: unknown): boolean;

package/dist/utils/errors.js

@@ -0,0 +1,40 @@
+/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * errors.ts: Error formatting and handling utilities for PrismCast.
+ */
+/* These utilities provide consistent error handling and formatting throughout the application. The formatError function extracts meaningful messages from various
+ * error types, while isSessionClosedError helps identify unrecoverable browser state errors that should abort retry loops.
+ */
+/**
+ * Formats an error for logging by extracting the message if available, falling back to string conversion for non-Error objects. Trailing punctuation is stripped
+ * to allow callers to add consistent punctuation in their log format strings.
+ * @param error - The error to format.
+ * @returns A string representation suitable for logging, without trailing punctuation.
+ */
+export function formatError(error) {
+    let message;
+    if (error instanceof Error) {
+        message = error.message;
+    }
+    else if (error && (typeof error.message === "string")) {
+        message = error.message;
+    }
+    else {
+        message = String(error);
+    }
+    // Strip trailing punctuation to prevent double punctuation when callers add their own.
+    return message.replace(/[.!?]+$/, "");
+}
+/**
+ * Checks whether an error indicates that the browser page or session has been closed or is otherwise unrecoverable. These errors should cause immediate abort of
+ * any retry loops rather than continuing to retry an operation that will never succeed. Common unrecoverable errors include closed targets, closed sessions, and
+ * detached frames (which occur when the page has been closed mid-operation).
+ * @param error - The error to check.
+ * @returns True if the error indicates a closed or unrecoverable state.
+ */
+export function isSessionClosedError(error) {
+    const message = formatError(error);
+    const unrecoverablePatterns = ["Target closed", "Session closed", "detached Frame"];
+    return unrecoverablePatterns.some((pattern) => message.includes(pattern));
+}
+//# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IAExC,IAAI,OAAe,CAAC;IAEpB,IAAG,KAAK,YAAY,KAAK,EAAE,CAAC;QAE1B,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC1B,CAAC;SAAM,IAAG,KAAK,IAAI,CAAC,OAAQ,KAA+B,CAAC,OAAO,KAAK,QAAQ,CAAC,EAAE,CAAC;QAElF,OAAO,GAAI,KAA6B,CAAC,OAAO,CAAC;IACnD,CAAC;SAAM,CAAC;QAEN,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAED,uFAAuF;IACvF,OAAO,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IAEjD,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAEnC,MAAM,qBAAqB,GAAG,CAAE,eAAe,EAAE,gBAAgB,EAAE,gBAAgB,CAAE,CAAC;IAEtF,OAAO,qBAAqB,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;AAC5E,CAAC"}

package/dist/utils/evaluate.d.ts

@@ -0,0 +1,51 @@
+import type { Frame, Page } from "puppeteer-core";
+/**
+ * Registers an AbortController for a stream. Called when a stream is created.
+ * @param streamIdStr - The stream ID string (e.g., "cnn-5jecl6").
+ * @param controller - The AbortController for this stream.
+ */
+export declare function registerAbortController(streamIdStr: string, controller: AbortController): void;
+/**
+ * Unregisters an AbortController for a stream. Called when a stream is terminated.
+ * @param streamIdStr - The stream ID string.
+ */
+export declare function unregisterAbortController(streamIdStr: string): void;
+/**
+ * Gets the AbortSignal for a stream, if one exists.
+ * @param streamIdStr - The stream ID string.
+ * @returns The AbortSignal if found, undefined otherwise.
+ */
+export declare function getAbortSignal(streamIdStr: string): AbortSignal | undefined;
+/**
+ * Gets the AbortController for a stream, if one exists.
+ * @param streamIdStr - The stream ID string.
+ * @returns The AbortController if found, undefined otherwise.
+ */
+export declare function getAbortController(streamIdStr: string): AbortController | undefined;
+/**
+ * Custom error class for timeout errors. This allows callers to distinguish timeout errors from other errors.
+ */
+export declare class EvaluateTimeoutError extends Error {
+    constructor(timeoutMs: number);
+}
+/**
+ * Custom error class for abort errors. This allows callers to distinguish abort errors from other errors.
+ */
+export declare class EvaluateAbortError extends Error {
+    constructor();
+}
+/**
+ * Executes a Puppeteer evaluate call with abort and timeout support. This wrapper provides immediate cancellation when a stream is terminated and a safety timeout to
+ * prevent hanging on unresponsive browsers.
+ *
+ * If running within a stream context (via AsyncLocalStorage), the abort signal for that stream is used. If no stream context is available, only the timeout is applied.
+ * @param context - The Page or Frame to evaluate in.
+ * @param pageFunction - The function to evaluate in the browser context.
+ * @param args - Arguments to pass to the function (optional).
+ * @param timeoutMs - Timeout in milliseconds (default: 15000).
+ * @returns The result of the evaluate call.
+ * @throws EvaluateAbortError if the stream was terminated.
+ * @throws EvaluateTimeoutError if the timeout was reached.
+ * @throws Any error from the underlying evaluate call.
+ */
+export declare function evaluateWithAbort<T, Args extends unknown[]>(context: Frame | Page, pageFunction: (...args: Args) => T, args?: Args, timeoutMs?: number): Promise<T>;

package/dist/utils/evaluate.js

@@ -0,0 +1,124 @@
+import { getStreamId } from "./streamContext.js";
+/* This module provides a wrapper around Puppeteer's page.evaluate() and frame.evaluate() that adds two critical safety mechanisms:
+ *
+ * 1. Abort signal: When a stream is terminated, its AbortController is triggered, immediately rejecting all pending evaluate calls for that stream. This prevents zombie
+ *    CDP calls from hanging for 180 seconds (Puppeteer's default protocolTimeout) when the browser becomes unresponsive.
+ *
+ * 2. Timeout: A configurable timeout (default 15 seconds) provides a safety net for evaluate calls that hang. This catches cases where the browser is unresponsive but
+ *    the stream hasn't been explicitly terminated yet.
+ *
+ * The wrapper automatically retrieves the abort signal from the stream registry using the stream context from AsyncLocalStorage. If no stream context is available
+ * (e.g., during browser initialization), it falls back to timeout-only behavior.
+ *
+ * IMPORTANT: When aborting or timing out, the underlying CDP call is still pending in Puppeteer - we just stop waiting for it locally. We attach a no-op .catch() to
+ * the evaluate promise to suppress unhandled rejection warnings when the CDP call eventually completes or times out.
+ */
+// Default timeout for evaluate calls in milliseconds.
+const DEFAULT_EVALUATE_TIMEOUT = 15000;
+// Map of stream ID strings to their AbortControllers. Uses string IDs (e.g., "cnn-5jecl6") since that's what the stream context provides via AsyncLocalStorage.
+const abortControllers = new Map();
+/**
+ * Registers an AbortController for a stream. Called when a stream is created.
+ * @param streamIdStr - The stream ID string (e.g., "cnn-5jecl6").
+ * @param controller - The AbortController for this stream.
+ */
+export function registerAbortController(streamIdStr, controller) {
+    abortControllers.set(streamIdStr, controller);
+}
+/**
+ * Unregisters an AbortController for a stream. Called when a stream is terminated.
+ * @param streamIdStr - The stream ID string.
+ */
+export function unregisterAbortController(streamIdStr) {
+    abortControllers.delete(streamIdStr);
+}
+/**
+ * Gets the AbortSignal for a stream, if one exists.
+ * @param streamIdStr - The stream ID string.
+ * @returns The AbortSignal if found, undefined otherwise.
+ */
+export function getAbortSignal(streamIdStr) {
+    return abortControllers.get(streamIdStr)?.signal;
+}
+/**
+ * Gets the AbortController for a stream, if one exists.
+ * @param streamIdStr - The stream ID string.
+ * @returns The AbortController if found, undefined otherwise.
+ */
+export function getAbortController(streamIdStr) {
+    return abortControllers.get(streamIdStr);
+}
+/**
+ * Custom error class for timeout errors. This allows callers to distinguish timeout errors from other errors.
+ */
+export class EvaluateTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super("Evaluate timed out after " + String(timeoutMs) + "ms.");
+        this.name = "EvaluateTimeoutError";
+    }
+}
+/**
+ * Custom error class for abort errors. This allows callers to distinguish abort errors from other errors.
+ */
+export class EvaluateAbortError extends Error {
+    constructor() {
+        super("Evaluate aborted due to stream termination.");
+        this.name = "EvaluateAbortError";
+    }
+}
+/**
+ * Executes a Puppeteer evaluate call with abort and timeout support. This wrapper provides immediate cancellation when a stream is terminated and a safety timeout to
+ * prevent hanging on unresponsive browsers.
+ *
+ * If running within a stream context (via AsyncLocalStorage), the abort signal for that stream is used. If no stream context is available, only the timeout is applied.
+ * @param context - The Page or Frame to evaluate in.
+ * @param pageFunction - The function to evaluate in the browser context.
+ * @param args - Arguments to pass to the function (optional).
+ * @param timeoutMs - Timeout in milliseconds (default: 15000).
+ * @returns The result of the evaluate call.
+ * @throws EvaluateAbortError if the stream was terminated.
+ * @throws EvaluateTimeoutError if the timeout was reached.
+ * @throws Any error from the underlying evaluate call.
+ */
+export async function evaluateWithAbort(context, pageFunction, args, timeoutMs) {
+    const timeout = timeoutMs ?? DEFAULT_EVALUATE_TIMEOUT;
+    // Get stream context to find the abort signal.
+    const streamIdStr = getStreamId();
+    const signal = streamIdStr !== undefined ? getAbortSignal(streamIdStr) : undefined;
+    // Check if already aborted before starting.
+    if (signal?.aborted) {
+        throw new EvaluateAbortError();
+    }
+    // Start the evaluate call. We use 'as unknown as' to bypass TypeScript's strict function signature checking since Puppeteer's evaluate accepts various function
+    // signatures that are difficult to type precisely.
+    const evaluatePromise = args ?
+        context.evaluate(pageFunction, ...args) :
+        context.evaluate(pageFunction);
+    // Attach a no-op catch to suppress unhandled rejection warnings. When we abort or timeout, the underlying CDP call is still pending and will eventually resolve or
+    // reject. Without this, we'd get unhandled rejection warnings when the CDP call completes after we've moved on.
+    evaluatePromise.catch(() => { });
+    // Create the timeout promise.
+    const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => {
+            reject(new EvaluateTimeoutError(timeout));
+        }, timeout);
+    });
+    // If we have an abort signal, create an abort promise.
+    if (signal) {
+        const abortPromise = new Promise((_, reject) => {
+            // Check if already aborted (race condition protection).
+            if (signal.aborted) {
+                reject(new EvaluateAbortError());
+                return;
+            }
+            signal.addEventListener("abort", () => {
+                reject(new EvaluateAbortError());
+            }, { once: true });
+        });
+        // Race all three: evaluate, timeout, and abort.
+        return Promise.race([evaluatePromise, timeoutPromise, abortPromise]);
+    }
+    // No abort signal available, just race evaluate against timeout.
+    return Promise.race([evaluatePromise, timeoutPromise]);
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/utils/evaluate.js.map

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

package/dist/utils/ffmpeg.d.ts

@@ -0,0 +1,65 @@
+import type { Readable, Writable } from "node:stream";
+import type { ChildProcess } from "node:child_process";
+/**
+ * Resolves the FFmpeg executable path. Checks Channels DVR (macOS, Windows, Linux), then the bundled ffmpeg-for-homebridge, then system PATH. The resolved path is
+ * cached for subsequent calls.
+ * @returns Promise resolving to the FFmpeg path if found, or undefined if not available.
+ */
+export declare function resolveFFmpegPath(): Promise<string | undefined>;
+/**
+ * Result from spawning an FFmpeg process.
+ */
+export interface FFmpegProcess {
+    kill: () => void;
+    process: ChildProcess;
+    stdin: Writable;
+    stdout: Readable;
+}
+/**
+ * Spawns an FFmpeg process configured to transcode WebM (H264+Opus) to fMP4 (H264+AAC). The process reads from stdin and writes to stdout, allowing it to be
+ * integrated into a Node.js stream pipeline. Video is passed through unchanged; audio is transcoded from Opus to AAC for HLS compatibility.
+ *
+ * FFmpeg arguments:
+ * - `-hide_banner -loglevel warning`: Reduce noise, only show warnings/errors
+ * - `-probesize 16384`: Limit input probing to 16KB (Chrome's WebM header fits well under this) to minimize startup delay
+ * - `-i pipe:0`: Read input from stdin
+ * - `-c:v copy`: Copy video stream without re-encoding (H264 passthrough)
+ * - `-c:a aac -b:a <bitrate>`: Transcode audio to AAC at specified bitrate
+ * - `-f mp4`: Output MP4 container format
+ * - `-movflags frag_keyframe+empty_moov+default_base_moof`: Streaming-friendly fMP4 flags
+ * - `-flush_packets 1`: Flush output immediately after each packet to minimize latency
+ * - `pipe:1`: Write output to stdout
+ * @param audioBitrate - Audio bitrate in bits per second (e.g., 256000 for 256 kbps).
+ * @param onError - Callback invoked when FFmpeg exits unexpectedly or encounters an error.
+ * @param streamId - Stream identifier for logging.
+ * @param comment - Optional comment metadata (channel name or domain) to embed in the output.
+ * @returns FFmpeg process wrapper with stdin, stdout, and kill function.
+ */
+export declare function spawnFFmpeg(audioBitrate: number, onError: (error: Error) => void, streamId?: string, comment?: string): FFmpegProcess;
+/**
+ * Spawns an FFmpeg process configured to remux fMP4 input to MPEG-TS output with codec copy. The process reads a continuous fMP4 stream (init segment followed by
+ * media segments) from stdin and writes MPEG-TS to stdout. No transcoding occurs — both video (H264) and audio (AAC) are copied unchanged — so CPU usage is minimal.
+ *
+ * FFmpeg arguments:
+ * - `-hide_banner -loglevel warning`: Reduce noise, only show warnings/errors
+ * - `-probesize 16384`: Limit input probing to 16KB (fMP4 init segment is ~1.3KB) to minimize startup delay
+ * - `-f mp4 -i pipe:0`: Read fragmented MP4 from stdin
+ * - `-c copy`: Copy both video and audio codecs without transcoding
+ * - `-f mpegts`: Output MPEG-TS container format
+ * - `-mpegts_pmt_start_pid 0x0020`: Use ATSC-conventional PMT PID range instead of FFmpeg's default (0x1000). Minimum allowed value is 0x0020 (32).
+ * - `-mpegts_start_pid 0x0031`: Use ATSC-conventional elementary stream PIDs instead of FFmpeg's defaults (0x100+)
+ * - `-mpegts_service_type digital_tv`: Label the service as digital TV in the PMT service descriptor
+ * - `-pat_period 0.1`: Repeat PAT/PMT tables every 100ms, matching ATSC broadcast frequency
+ * - `-pcr_period 40`: Insert PCR timestamps every 40ms, matching ATSC broadcast convention
+ * - `-flush_packets 1`: Flush output immediately after each packet to minimize latency
+ * - `pipe:1`: Write output to stdout
+ * @param onError - Callback invoked when FFmpeg exits unexpectedly or encounters an error.
+ * @param streamId - Optional stream identifier for logging.
+ * @returns FFmpeg process wrapper with stdin, stdout, and kill function.
+ */
+export declare function spawnMpegTsRemuxer(onError: (error: Error) => void, streamId?: string): FFmpegProcess;
+/**
+ * Checks if FFmpeg is available on the system. This resolves the FFmpeg path and caches it for use by spawnFFmpeg().
+ * @returns Promise resolving to true if FFmpeg is available, false otherwise.
+ */
+export declare function isFFmpegAvailable(): Promise<boolean>;