@bnhf/prismcast 1.3.4-2026.2.19

package/dist/streaming/statusEmitter.js

@@ -0,0 +1,139 @@
+import { EventEmitter } from "events";
+/* A singleton EventEmitter that broadcasts status updates to all subscribed SSE clients. The emitter maintains current state for all streams, allowing new clients
+ * to receive a snapshot of current status immediately upon connecting.
+ */
+const statusEmitter = new EventEmitter();
+// Increase the default listener limit to support many concurrent SSE connections.
+statusEmitter.setMaxListeners(100);
+/**
+ * Creates the initial StreamStatus object for a new stream. This provides a consistent starting state with all health metrics at their default values.
+ * @param options - The stream initialization options.
+ * @returns The initial stream status.
+ */
+export function createInitialStreamStatus(options) {
+    return {
+        bufferingDuration: null,
+        channel: options.channelName,
+        clientCount: 0,
+        clients: [],
+        currentTime: 0,
+        duration: 0,
+        escalationLevel: 0,
+        health: "healthy",
+        id: options.numericStreamId,
+        lastIssueTime: null,
+        lastIssueType: null,
+        lastRecoveryTime: null,
+        logoUrl: "",
+        memoryBytes: 0,
+        networkState: 0,
+        pageReloadsInWindow: 0,
+        providerName: options.providerName,
+        readyState: 0,
+        recoveryAttempts: 0,
+        showName: "",
+        startTime: options.startTime.toISOString(),
+        url: options.url
+    };
+}
+// Current status for all active streams, keyed by stream ID.
+const streamStatuses = new Map();
+// Cached system status, updated periodically and on significant events.
+let cachedSystemStatus = null;
+/**
+ * Emits a stream added event when a new stream starts.
+ * @param status - The initial status of the new stream.
+ */
+export function emitStreamAdded(status) {
+    streamStatuses.set(status.id, status);
+    statusEmitter.emit("streamAdded", status);
+}
+/**
+ * Emits a stream removed event when a stream ends.
+ * @param streamId - The ID of the stream that ended.
+ */
+export function emitStreamRemoved(streamId) {
+    streamStatuses.delete(streamId);
+    statusEmitter.emit("streamRemoved", { id: streamId });
+}
+/**
+ * Emits a stream health changed event with the current stream status. This function always stores and emits the status to ensure SSE clients and snapshots have
+ * current data. During healthy playback the monitor calls this every ~2 seconds anyway, so removing the previous selective filter has negligible bandwidth impact
+ * while eliminating staleness during recovery/buffering periods.
+ * @param status - The updated stream status.
+ */
+export function emitStreamHealthChanged(status) {
+    streamStatuses.set(status.id, status);
+    statusEmitter.emit("streamHealthChanged", status);
+}
+/**
+ * Emits a system status changed event when browser or system state changes.
+ * @param status - The updated system status.
+ */
+export function emitSystemStatusChanged(status) {
+    // Only emit if something meaningful changed.
+    if ((cachedSystemStatus?.browser.connected !== status.browser.connected) ||
+        (cachedSystemStatus.streams.active !== status.streams.active)) {
+        cachedSystemStatus = status;
+        statusEmitter.emit("systemStatusChanged", status);
+    }
+}
+/**
+ * Updates the cached system status without emitting an event. Used for periodic updates that should be included in snapshots but don't need to notify clients.
+ * @param status - The updated system status.
+ */
+export function updateSystemStatus(status) {
+    cachedSystemStatus = status;
+}
+/**
+ * Gets the current status snapshot for all streams and the system.
+ * @returns The current status snapshot.
+ */
+export function getStatusSnapshot() {
+    return {
+        streams: Array.from(streamStatuses.values()),
+        system: cachedSystemStatus ?? {
+            browser: { connected: false, pageCount: 0 },
+            memory: { heapUsed: 0, rss: 0 },
+            streams: { active: 0, limit: 10 },
+            uptime: 0
+        }
+    };
+}
+/**
+ * Gets the current status for a specific stream.
+ * @param streamId - The ID of the stream.
+ * @returns The stream status, or undefined if not found.
+ */
+export function getStreamStatus(streamId) {
+    return streamStatuses.get(streamId);
+}
+/**
+ * Removes a stream from the status tracking without emitting an event. Used during cleanup when the stream has already been removed.
+ * @param streamId - The ID of the stream to remove.
+ */
+export function removeStreamStatus(streamId) {
+    streamStatuses.delete(streamId);
+}
+/**
+ * Subscribes a callback to receive all status events. Returns an unsubscribe function.
+ * @param callback - Function to call when a status event is emitted.
+ * @returns A function to unsubscribe the callback.
+ */
+export function subscribeToStatus(callback) {
+    const streamAddedHandler = (data) => { callback("streamAdded", data); };
+    const streamRemovedHandler = (data) => { callback("streamRemoved", data); };
+    const streamHealthChangedHandler = (data) => { callback("streamHealthChanged", data); };
+    const systemStatusChangedHandler = (data) => { callback("systemStatusChanged", data); };
+    statusEmitter.on("streamAdded", streamAddedHandler);
+    statusEmitter.on("streamRemoved", streamRemovedHandler);
+    statusEmitter.on("streamHealthChanged", streamHealthChangedHandler);
+    statusEmitter.on("systemStatusChanged", systemStatusChangedHandler);
+    return () => {
+        statusEmitter.off("streamAdded", streamAddedHandler);
+        statusEmitter.off("streamRemoved", streamRemovedHandler);
+        statusEmitter.off("streamHealthChanged", streamHealthChangedHandler);
+        statusEmitter.off("systemStatusChanged", systemStatusChangedHandler);
+    };
+}
+//# sourceMappingURL=statusEmitter.js.map

package/dist/streaming/statusEmitter.js.map

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

package/dist/types/index.d.ts

@@ -0,0 +1,403 @@
+import type { Frame, Page } from "puppeteer-core";
+import type { RecoveryMetrics } from "../streaming/monitor.js";
+/**
+ * A utility type that represents a value that can be null.
+ * @typeParam T - The type that can be nullable.
+ */
+export type Nullable<T> = T | null;
+/**
+ * Browser-related configuration controlling Chrome launch behavior. Viewport dimensions are derived from the quality preset via getViewport() and are not stored in
+ * this configuration object.
+ */
+export interface BrowserConfig {
+    executablePath: Nullable<string>;
+    initTimeout: number;
+}
+/**
+ * Filesystem paths for Chrome profile data and extension files.
+ */
+export interface PathsConfig {
+    chromeProfileName: string;
+    extensionDirName: string;
+}
+/**
+ * Playback monitoring and recovery timing configuration. These values control how quickly the system detects playback problems and how aggressively it attempts
+ * recovery. The defaults balance responsiveness against false positives from temporary buffering.
+ */
+export interface PlaybackConfig {
+    bufferingGracePeriod: number;
+    channelSelectorDelay: number;
+    channelSwitchDelay: number;
+    clickToPlayDelay: number;
+    iframeInitDelay: number;
+    maxPageReloads: number;
+    monitorInterval: number;
+    pageReloadWindow: number;
+    sourceReloadDelay: number;
+    stallCountThreshold: number;
+    stallThreshold: number;
+    sustainedPlaybackRequired: number;
+}
+/**
+ * Recovery behavior configuration controlling retry logic, backoff timing, and circuit breaker thresholds. These settings determine how the system handles
+ * failures and prevents runaway resource consumption from broken streams.
+ */
+export interface RecoveryConfig {
+    backoffJitter: number;
+    circuitBreakerThreshold: number;
+    circuitBreakerWindow: number;
+    maxBackoffDelay: number;
+    stalePageCleanupInterval: number;
+    stalePageGracePeriod: number;
+}
+/**
+ * HLS streaming configuration controlling segment generation and lifecycle.
+ */
+export interface HLSConfig {
+    idleTimeout: number;
+    maxSegments: number;
+    segmentDuration: number;
+}
+/**
+ * Channels configuration controlling which predefined channels are enabled.
+ */
+export interface ChannelsConfig {
+    disabledPredefined: string[];
+    enabledProviders: string[];
+}
+/**
+ * HDHomeRun emulation configuration. When enabled, PrismCast runs a separate HTTP server that emulates the HDHomeRun API, allowing Plex to discover and use
+ * PrismCast as a virtual tuner for live TV and DVR recording. The emulated device appears in Plex's tuner setup and serves PrismCast's HLS streams directly.
+ */
+export interface HdhrConfig {
+    deviceId: string;
+    enabled: boolean;
+    friendlyName: string;
+    port: number;
+}
+/**
+ * Logging configuration controlling file-based logging behavior.
+ */
+export interface LoggingConfig {
+    httpLogLevel: "all" | "errors" | "filtered" | "none";
+    maxSize: number;
+}
+/**
+ * HTTP server configuration controlling network binding.
+ */
+export interface ServerConfig {
+    host: string;
+    port: number;
+}
+/**
+ * Capture mode for media recording. Determines how video/audio is captured from the browser and processed for HLS output.
+ * - "ffmpeg": Captures WebM (H264+Opus) and uses FFmpeg to transcode audio to AAC. More stable for long recordings.
+ * - "native": Captures fMP4 (H264+AAC) directly from Chrome. No dependencies but may be unstable with long recordings.
+ */
+export type CaptureMode = "ffmpeg" | "native";
+/**
+ * Media streaming configuration controlling video capture quality, timeouts, and concurrency limits.
+ */
+export interface StreamingConfig {
+    audioBitsPerSecond: number;
+    captureMode: CaptureMode;
+    frameRate: number;
+    maxConcurrentStreams: number;
+    maxNavigationRetries: number;
+    navigationTimeout: number;
+    qualityPreset: string;
+    videoBitsPerSecond: number;
+    videoTimeout: number;
+}
+/**
+ * Root configuration object containing all application settings organized by functional area.
+ */
+export interface Config {
+    browser: BrowserConfig;
+    channels: ChannelsConfig;
+    hdhr: HdhrConfig;
+    hls: HLSConfig;
+    logging: LoggingConfig;
+    paths: PathsConfig;
+    playback: PlaybackConfig;
+    recovery: RecoveryConfig;
+    server: ServerConfig;
+    streaming: StreamingConfig;
+}
+/**
+ * UI category for profile grouping in dropdowns and reference documentation. Profiles are grouped by their fullscreen mechanism and special characteristics.
+ * - "api": Profiles using the JavaScript fullscreen API (including embedded iframe and click-to-play variants).
+ * - "keyboard": Profiles using keyboard shortcuts (typically the 'f' key) for fullscreen.
+ * - "multiChannel": Multi-channel profiles requiring a channel selector for tile or thumbnail-based channel selection.
+ * - "special": Special-purpose profiles like static page capture.
+ */
+export type ProfileCategory = "api" | "keyboard" | "multiChannel" | "special";
+/**
+ * Site profile definition with optional flags. All flags are optional because profiles can inherit from other profiles, and only the flags that differ from the
+ * parent need to be specified. The DEFAULT_SITE_PROFILE provides baseline values for any flags not set through inheritance.
+ */
+export interface SiteProfile {
+    category?: ProfileCategory;
+    channelSelection?: ChannelSelectionConfig;
+    channelSelector?: Nullable<string>;
+    clickSelector?: Nullable<string>;
+    clickToPlay?: boolean;
+    description?: string;
+    extends?: string;
+    summary?: string;
+    fullscreenKey?: Nullable<string>;
+    fullscreenSelector?: Nullable<string>;
+    lockVolumeProperties?: boolean;
+    needsIframeHandling?: boolean;
+    noVideo?: boolean;
+    selectReadyVideo?: boolean;
+    useRequestFullscreen?: boolean;
+    waitForNetworkIdle?: boolean;
+}
+/**
+ * Fully-resolved site profile with all flags having concrete values. After resolving inheritance chains and applying defaults, every flag has a definite boolean
+ * or string value. This interface is used by stream handling code that needs to check profile flags without worrying about undefined values.
+ */
+export interface ResolvedSiteProfile {
+    channelSelection: ChannelSelectionConfig;
+    channelSelector: Nullable<string>;
+    clickSelector: Nullable<string>;
+    clickToPlay: boolean;
+    fullscreenKey: Nullable<string>;
+    fullscreenSelector: Nullable<string>;
+    lockVolumeProperties: boolean;
+    maxContinuousPlayback: Nullable<number>;
+    needsIframeHandling: boolean;
+    noVideo: boolean;
+    selectReadyVideo: boolean;
+    useRequestFullscreen: boolean;
+    waitForNetworkIdle: boolean;
+}
+/**
+ * Result of resolving a site profile. Includes both the resolved profile configuration and the name of the profile that was matched. The name indicates whether the
+ * profile came from a channel hint, domain-based autodetection, or the default fallback.
+ */
+export interface ProfileResolutionResult {
+    profile: ResolvedSiteProfile;
+    profileName: string;
+}
+/**
+ * Channel definition mapping a short name to a streaming URL with optional configuration overrides.
+ */
+export interface Channel {
+    channelNumber?: number;
+    channelSelector?: string;
+    name?: string;
+    profile?: string;
+    provider?: string;
+    stationId?: string;
+    url: string;
+}
+/**
+ * Enriched channel entry returned by getChannelListing(). Wraps a Channel definition with source classification and enabled status metadata, providing the
+ * single source of truth for merged channel data across the codebase.
+ */
+export interface ChannelListingEntry {
+    availableByProvider: boolean;
+    channel: Channel;
+    enabled: boolean;
+    key: string;
+    source: "override" | "predefined" | "user";
+}
+/**
+ * Map of channel short names to channel definitions. Channel names must be URL-safe strings (lowercase letters, numbers, hyphens) since they appear in stream
+ * request URLs.
+ */
+export type ChannelMap = Record<string, Channel>;
+/**
+ * Represents a group of provider variants for the same content. Used by the UI to display provider selection dropdowns for multi-provider channels.
+ */
+export interface ProviderGroup {
+    canonicalKey: string;
+    variants: {
+        key: string;
+        label: string;
+    }[];
+}
+/**
+ * Information about an active streaming session. Created when a stream request is received and deleted when the stream ends.
+ */
+export interface StreamInfo {
+    channelName: Nullable<string>;
+    id: number;
+    page: Page;
+    startTime: Date;
+    stopMonitor: Nullable<() => RecoveryMetrics>;
+    url: string;
+}
+/**
+ * Snapshot of a video element's playback state. Collected by the playback health monitor to detect stalls, errors, and other problems.
+ */
+export interface VideoState {
+    currentTime: number;
+    ended: boolean;
+    error: boolean;
+    muted: boolean;
+    networkState: number;
+    paused: boolean;
+    readyState: number;
+    time: number;
+    volume: number;
+}
+/**
+ * Strategy for selecting a video element when multiple are present. "selectFirstVideo" takes the first video in DOM order; "selectReadyVideo" finds the video
+ * with readyState >= 3, which typically identifies the actively playing main content rather than preloaded ads.
+ */
+export type VideoSelectorType = "selectFirstVideo" | "selectReadyVideo";
+/**
+ * Result of URL validation indicating whether the URL is safe to navigate to.
+ */
+export interface UrlValidationResult {
+    reason?: string;
+    valid: boolean;
+}
+/**
+ * Alias for UrlValidationResult maintained for backward compatibility with existing code.
+ */
+export type UrlValidation = UrlValidationResult;
+/**
+ * Health check response structure returned by the /health endpoint.
+ */
+export interface HealthStatus {
+    browser: {
+        connected: boolean;
+        pageCount: number;
+    };
+    captureMode: string;
+    chrome: Nullable<string>;
+    clients: {
+        byType: {
+            count: number;
+            type: string;
+        }[];
+        total: number;
+    };
+    ffmpegAvailable: boolean;
+    memory: {
+        heapTotal: number;
+        heapUsed: number;
+        rss: number;
+        segmentBuffers: number;
+    };
+    message?: string;
+    status: "degraded" | "healthy" | "unhealthy";
+    streams: {
+        active: number;
+        limit: number;
+    };
+    timestamp: string;
+    uptime: number;
+    version: string;
+}
+/**
+ * Information about a single active stream as returned by the /streams endpoint.
+ */
+export interface StreamListItem {
+    channel: Nullable<string>;
+    duration: number;
+    id: number;
+    startTime: string;
+    url: string;
+}
+/**
+ * Response structure for the /streams endpoint.
+ */
+export interface StreamListResponse {
+    count: number;
+    limit: number;
+    streams: StreamListItem[];
+}
+/**
+ * Available channel selection strategies. Each strategy implements a different approach to finding and selecting channels in a multi-channel player UI.
+ *
+ * - "foxGrid": Find channel by station code in a non-virtualized guide grid, click the channel logo button via DOM .click(). Used by Fox.com.
+ * - "guideGrid": Find channel by exact-matching image alt text, click nearest clickable ancestor. Optionally clicks a tab to reveal the list first. Used by Hulu
+ *   Live TV.
+ * - "hboGrid": Discover the HBO tab page URL from the homepage menu bar, scrape the live channel tile rail for a matching channel name, and navigate to the watch
+ *   URL. Caches the tab URL across tunes with stale-cache fallback. Used by HBO Max.
+ * - "none": No channel selection needed (single-channel sites). This is the default.
+ * - "slingGrid": Find channel by data-testid in a virtualized A-Z guide grid, scroll via binary search on .guide-cell scrollTop, click the on-now program
+ *   cell. Used by Sling TV.
+ * - "thumbnailRow": Find channel by matching image URL slug, click adjacent element on the same row. Used by USA Network.
+ * - "tileClick": Find channel tile by matching image URL slug, click tile, then click play button on modal. Used by Disney+ live channels.
+ * - "youtubeGrid": Find channel by aria-label in a non-virtualized EPG grid, extract the watch URL, and navigate directly. Used by YouTube TV.
+ */
+export type ChannelSelectionStrategy = "foxGrid" | "guideGrid" | "hboGrid" | "none" | "slingGrid" | "thumbnailRow" | "tileClick" | "youtubeGrid";
+/**
+ * Configuration for channel selection behavior within a site profile.
+ */
+export interface ChannelSelectionConfig {
+    listSelector?: string;
+    playSelector?: string;
+    strategy: ChannelSelectionStrategy;
+}
+export interface ChannelSelectionProfile extends ResolvedSiteProfile {
+    channelSelector: string;
+}
+export declare function isChannelSelectionProfile(profile: ResolvedSiteProfile): profile is ChannelSelectionProfile;
+/**
+ * Result of attempting to select a channel from a multi-channel player UI.
+ */
+export interface ChannelSelectorResult {
+    reason?: string;
+    success: boolean;
+}
+/**
+ * The strategy function signature. All strategies take the Puppeteer page and a narrowed profile with guaranteed non-null channelSelector.
+ */
+export type ChannelStrategyHandler = (page: Page, profile: ChannelSelectionProfile) => Promise<ChannelSelectorResult>;
+/**
+ * The complete contract for a channel selection strategy. Each provider file exports a single object implementing this interface. The coordinator accesses all
+ * provider behavior through these hooks — no strategy-specific imports or hardcoded strategy name checks outside the registry.
+ */
+export interface ChannelStrategyEntry {
+    /**
+     * Resets all module-level caches (row positions, discovered URLs, watch URLs). Called on browser restart when cached state may be stale.
+     */
+    clearCache?: () => void;
+    /**
+     * Selects the target channel in the provider's guide UI. Receives a Puppeteer page and a profile with a guaranteed non-null channelSelector. Must handle its
+     * own retry logic (e.g., overlay dismiss) and return a result indicating success or failure with a diagnostic reason.
+     */
+    execute: ChannelStrategyHandler;
+    /**
+     * Removes a cached watch URL after it failed to produce a working stream. Called by the coordinator when a cached direct navigation fails.
+     */
+    invalidateDirectUrl?: (channelSelector: string) => void;
+    /**
+     * Returns a watch URL for direct navigation, bypassing guide page loading. Implementations may perform async work such as fetching current asset IDs from
+     * provider APIs. The page parameter allows setting up response interception or accessing browser context when needed (e.g., cold cache setup).
+     */
+    resolveDirectUrl?: (channelSelector: string, page: Page) => Promise<Nullable<string>>;
+    /**
+     * Set to true when the channelSelector is an image URL slug that must be polled for load completion before strategy dispatch. The coordinator waits for an img
+     * element whose src contains the slug to reach loaded state.
+     */
+    usesImageSlug?: boolean;
+}
+/**
+ * Coordinates for a click target, used when clicking channel selector elements.
+ */
+export interface ClickTarget {
+    x: number;
+    y: number;
+}
+/**
+ * Result of tuning to a channel, containing the video context needed for monitoring.
+ */
+export interface TuneResult {
+    context: Frame | Page;
+}
+/**
+ * Browser chrome dimensions (toolbars, borders) calculated by comparing window.outerHeight/Width to window.innerHeight/Width. Used to set window size such that
+ * the viewport (content area) matches our target dimensions.
+ */
+export interface UiSize {
+    height: number;
+    width: number;
+}

package/dist/types/index.js

@@ -0,0 +1,6 @@
+// Type guard that proves channelSelector is a non-empty string. Matches the original !channelSelector truthiness check, which rejects both null and empty string.
+// Used by the coordinator before dispatching to strategy functions.
+export function isChannelSelectionProfile(profile) {
+    return (profile.channelSelector !== null) && (profile.channelSelector.length > 0);
+}
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAwzBA,kKAAkK;AAClK,oEAAoE;AACpE,MAAM,UAAU,yBAAyB,CAAC,OAA4B;IAEpE,OAAO,CAAC,OAAO,CAAC,eAAe,KAAK,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACpF,CAAC"}

package/dist/utils/debugFilter.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 declare function initDebugFilter(pattern: string): void;
+/**
+ * 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 declare function isCategoryEnabled(category: string): boolean;
+/**
+ * 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 declare function isAnyDebugEnabled(): boolean;
+/**
+ * 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 declare function getCurrentPattern(): string;
+/**
+ * Metadata for a known debug category. Used by the /debug UI to display available categories with descriptions.
+ */
+export interface DebugCategory {
+    readonly category: string;
+    readonly description: string;
+}
+/**
+ * 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 declare const DEBUG_CATEGORIES: readonly DebugCategory[];
+/**
+ * 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 declare function startTimer(): () => number;