prismcast 1.0.1 → 1.0.3

package/dist/app.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Initializes and starts the HTTP server. Before accepting connections, we validate configuration, clean up stale Chrome processes, and warm up the browser
+ * instance.
+ * @param useConsoleLogging - Whether to log to console instead of file. Defaults to false (file logging).
+ */
+export declare function startServer(useConsoleLogging?: boolean): Promise<void>;

package/dist/app.js

@@ -0,0 +1,292 @@
+/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * app.ts: Express application builder for PrismCast.
+ */
+import { CONFIG, displayConfiguration, initializeConfiguration, validateConfiguration } from "./config/index.js";
+import { LOG, createMorganStream, formatError, isFFmpegAvailable, setConsoleLogging } from "./utils/index.js";
+import { closeBrowser, ensureDataDirectory, getCurrentBrowser, killStaleChromium, prepareExtension, startStalePageCleanup, stopStalePageCleanup } from "./browser/index.js";
+import { initializeFileLogger, shutdownFileLogger } from "./utils/fileLogger.js";
+import { startShowInfoPolling, stopShowInfoPolling } from "./streaming/showInfo.js";
+import { cleanupIdleStreams } from "./streaming/hls.js";
+import consoleStamp from "console-stamp";
+import express from "express";
+import { getAllStreams } from "./streaming/registry.js";
+import { initializeUserChannels } from "./config/userChannels.js";
+import morgan from "morgan";
+import { setupRoutes } from "./routes/index.js";
+import { terminateStream } from "./streaming/lifecycle.js";
+import { validateProfiles } from "./config/profiles.js";
+/*
+ * LOGGING MODE
+ *
+ * The logging mode is set at startup based on the --console CLI flag. When console logging is enabled, timestamps are added via console-stamp and output goes to
+ * stdout/stderr. When file logging is used (the default), output goes to ~/.prismcast/prismcast.log.
+ */
+// Track whether console logging is enabled, set during startServer().
+let usingConsoleLogging = false;
+/*
+ * APPLICATION STATE
+ *
+ * The HTTP server instance is stored globally so it can be closed during graceful shutdown.
+ */
+let server = null;
+// Interval for idle stream cleanup.
+let idleCleanupInterval = null;
+/**
+ * Starts the idle cleanup interval. Runs every 10 seconds to check for idle streams and terminate them.
+ */
+function startIdleCleanup() {
+    if (idleCleanupInterval) {
+        return;
+    }
+    // Check for idle streams every 10 seconds.
+    idleCleanupInterval = setInterval(() => {
+        cleanupIdleStreams();
+    }, 10000);
+}
+/**
+ * Stops the idle cleanup interval.
+ */
+function stopIdleCleanup() {
+    if (idleCleanupInterval) {
+        clearInterval(idleCleanupInterval);
+        idleCleanupInterval = null;
+    }
+}
+/*
+ * GRACEFUL SHUTDOWN
+ *
+ * When the process receives a termination signal, we close all active streams and the browser before exiting. This ensures resources are released cleanly.
+ */
+/**
+ * Sets up signal handlers for graceful shutdown. When SIGINT or SIGTERM is received, we close all streams, the browser, and the HTTP server before exiting.
+ */
+function setupGracefulShutdown() {
+    let shutdownInProgress = false;
+    async function shutdown(signal) {
+        // Prevent multiple shutdown attempts if multiple signals are received.
+        if (shutdownInProgress) {
+            return;
+        }
+        shutdownInProgress = true;
+        LOG.info("Received %s, starting graceful shutdown.", signal);
+        // Stop cleanup and polling intervals.
+        stopStalePageCleanup();
+        stopIdleCleanup();
+        stopShowInfoPolling();
+        // Terminate all streams. terminateStream() handles all cleanup including page closure and registry removal.
+        const streams = getAllStreams();
+        for (const stream of streams) {
+            terminateStream(stream.id, stream.info.storeKey, "server shutdown");
+        }
+        // Close the browser.
+        await closeBrowser();
+        // Close the HTTP server.
+        try {
+            if (server) {
+                server.close(() => {
+                    LOG.info("HTTP server closed successfully.");
+                });
+            }
+        }
+        catch (error) {
+            LOG.error("Error closing server during shutdown: %s.", formatError(error));
+        }
+        // Shut down file logger if in use.
+        if (!usingConsoleLogging) {
+            shutdownFileLogger();
+        }
+        process.exit(0);
+    }
+    process.on("SIGINT", () => {
+        void shutdown("SIGINT");
+    });
+    process.on("SIGTERM", () => {
+        void shutdown("SIGTERM");
+    });
+}
+/*
+ * APPLICATION BUILDER
+ *
+ * The buildApp function creates and configures the Express application with all middleware and routes. This is separated from the server startup to allow for
+ * testing and flexibility in deployment.
+ */
+/**
+ * Creates and configures the Express application with all middleware and routes.
+ * @returns The configured Express application.
+ */
+async function buildApp() {
+    try {
+        await prepareExtension();
+    }
+    catch (error) {
+        LOG.error("Cannot build app without extension: %s.", formatError(error));
+        throw error;
+    }
+    const app = express();
+    // Trust proxy headers (X-Forwarded-Proto, X-Forwarded-Host) so that req.protocol and req.hostname reflect what the client actually used when accessing through
+    // a reverse proxy. This ensures playlist URLs match the client's connection.
+    app.set("trust proxy", true);
+    // Add body parsing middleware for form submissions (configuration page).
+    app.use(express.urlencoded({ extended: true }));
+    app.use(express.json());
+    // Configure Morgan for HTTP request logging based on httpLogLevel configuration. Morgan output goes through morganStream which handles timestamp formatting
+    // consistently for both console and file logging modes.
+    if (CONFIG.logging.httpLogLevel !== "none") {
+        const morganFormat = ":method :url from :remote-addr responded :status in :response-time ms.";
+        const morganStream = createMorganStream();
+        // Patterns for browser-initiated asset requests that return 404. These are noise from browsers automatically requesting files that don't exist.
+        const browserAssetPatterns = ["/apple-touch-icon", "/favicon", "/robots.txt", "/site.webmanifest"];
+        if (CONFIG.logging.httpLogLevel === "errors") {
+            // Log requests with 4xx or 5xx status codes, but skip 404s for common browser asset requests.
+            app.use(morgan(morganFormat, {
+                skip: (req, res) => {
+                    // Log all non-error responses.
+                    if (res.statusCode < 400) {
+                        return true;
+                    }
+                    // Skip 404s for browser asset requests (favicon, apple-touch-icon, etc.).
+                    if (res.statusCode === 404) {
+                        const url = req.originalUrl || req.url;
+                        if (browserAssetPatterns.some((pattern) => url.startsWith(pattern))) {
+                            return true;
+                        }
+                    }
+                    // Skip 503s with Retry-After header. These indicate expected temporary unavailability (e.g., stream starting up) rather than a real error.
+                    if ((res.statusCode === 503) && res.getHeader("Retry-After")) {
+                        return true;
+                    }
+                    return false;
+                },
+                stream: morganStream
+            }));
+        }
+        else if (CONFIG.logging.httpLogLevel === "filtered") {
+            // Log important requests while skipping high-frequency polling endpoints. We always log errors, slow requests, and critical endpoints.
+            const skipPatterns = ["/logs", "/health", "/favicon", "/logo.png", "/logo.svg"];
+            app.use(morgan(morganFormat, {
+                skip: (req, res) => {
+                    // Always log errors.
+                    if (res.statusCode >= 400) {
+                        return false;
+                    }
+                    // Always log slow requests (over 1 second).
+                    const responseTime = parseFloat(res.getHeader("X-Response-Time") || "0");
+                    if (responseTime > 1000) {
+                        return false;
+                    }
+                    // Always log streaming and management endpoints.
+                    const url = req.originalUrl || req.url;
+                    const importantPatterns = ["/stream", "/streams", "/config", "/playlist", "/debug"];
+                    if (importantPatterns.some((pattern) => url.startsWith(pattern))) {
+                        return false;
+                    }
+                    // Skip high-frequency endpoints when successful.
+                    if (skipPatterns.some((pattern) => url.startsWith(pattern))) {
+                        return true;
+                    }
+                    // Skip successful requests to the root landing page.
+                    if ((url === "/") && (res.statusCode < 400)) {
+                        return true;
+                    }
+                    // Log everything else.
+                    return false;
+                },
+                stream: morganStream
+            }));
+        }
+        else {
+            // Log all requests.
+            app.use(morgan(morganFormat, { stream: morganStream }));
+        }
+    }
+    // Set up all HTTP endpoints.
+    setupRoutes(app);
+    // Global error handler. Express error handlers require 4 parameters even if unused.
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    app.use((err, _req, res, _next) => {
+        LOG.error("Unhandled error in request: %s.", formatError(err));
+        if (!res.headersSent) {
+            res.status(500).send("Internal server error");
+        }
+    });
+    return app;
+}
+/*
+ * SERVER STARTUP
+ *
+ * The startServer function initializes and starts the HTTP server. It validates configuration, cleans up stale processes, warms up the browser, and starts the
+ * Express application.
+ */
+/**
+ * Initializes and starts the HTTP server. Before accepting connections, we validate configuration, clean up stale Chrome processes, and warm up the browser
+ * instance.
+ * @param useConsoleLogging - Whether to log to console instead of file. Defaults to false (file logging).
+ */
+export async function startServer(useConsoleLogging = false) {
+    // Set logging mode early before any log calls.
+    usingConsoleLogging = useConsoleLogging;
+    setConsoleLogging(useConsoleLogging);
+    // Apply console-stamp for timestamps only when using console logging.
+    if (useConsoleLogging) {
+        consoleStamp(console, { format: ":date(yyyy/mm/dd HH:MM:ss.l)" });
+    }
+    // Initialize configuration from file and environment variables, then validate.
+    try {
+        await initializeConfiguration();
+        validateConfiguration();
+        validateProfiles();
+    }
+    catch (error) {
+        LOG.error(formatError(error));
+        process.exit(1);
+    }
+    displayConfiguration();
+    setupGracefulShutdown();
+    // Check FFmpeg availability if using FFmpeg capture mode.
+    if (CONFIG.streaming.captureMode === "ffmpeg") {
+        const ffmpegAvailable = await isFFmpegAvailable();
+        if (!ffmpegAvailable) {
+            LOG.error("FFmpeg is not available. FFmpeg capture mode requires FFmpeg to be installed and in the system PATH.");
+            LOG.error("Either install FFmpeg or change the capture mode to 'native' in the configuration.");
+            process.exit(1);
+        }
+        LOG.info("FFmpeg is available for FFmpeg capture mode.");
+    }
+    // Ensure the data directory exists before any operations that depend on it.
+    await ensureDataDirectory();
+    // Initialize file logger if not using console logging.
+    if (!useConsoleLogging) {
+        await initializeFileLogger(CONFIG.logging.maxSize);
+    }
+    // Load user channels from ~/.prismcast/channels.json if it exists.
+    await initializeUserChannels();
+    killStaleChromium();
+    // Warm up browser.
+    try {
+        await getCurrentBrowser();
+        LOG.info("Chrome ready.");
+    }
+    catch (error) {
+        LOG.error("Failed to initialize browser during startup: %s.", formatError(error));
+        throw error;
+    }
+    // Start stale page cleanup.
+    startStalePageCleanup();
+    // Start idle cleanup.
+    startIdleCleanup();
+    // Start show info polling for Channels DVR integration.
+    startShowInfoPolling();
+    // Build and start Express application.
+    try {
+        const app = await buildApp();
+        server = app.listen(CONFIG.server.port, CONFIG.server.host, () => {
+            LOG.info("PrismCast is now listening on %s:%s.", CONFIG.server.host, CONFIG.server.port);
+        });
+    }
+    catch (error) {
+        LOG.error("Failed to build application: %s.", formatError(error));
+        throw error;
+    }
+}
+//# sourceMappingURL=app.js.map

package/dist/app.js.map

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

package/dist/browser/cdp.d.ts

@@ -0,0 +1,38 @@
+import type { CDPSession, Page } from "puppeteer-core";
+/**
+ * Executes a CDP (Chrome DevTools Protocol) operation with proper session lifecycle management. This helper handles the common pattern of:
+ * 1. Creating a CDP session attached to the page's target
+ * 2. Getting the browser window ID for the page
+ * 3. Calling the provided operation with the session and window ID
+ * 4. Gracefully handling errors when the page is closed during the operation
+ *
+ * The session is created fresh for each call rather than being reused because CDP sessions become invalid when the page navigates or closes. Creating a new
+ * session ensures we always have a valid connection.
+ * @param page - The Puppeteer page object to create a CDP session for.
+ * @param operation - An async function that receives the CDP session and window ID. The operation can use any CDP commands via session.send().
+ * @returns The result of the operation, or undefined if the page was closed or an error occurred.
+ */
+export declare function withCDPSession<T>(page: Page, operation: (session: CDPSession, windowId: number) => Promise<T>): Promise<T | undefined>;
+/**
+ * Resizes the browser window to match our target viewport dimensions and optionally minimizes it. This function solves the problem of ensuring the video content
+ * area exactly matches our configured viewport size.
+ *
+ * The complication is that browser windows have "chrome" - the title bar, toolbar, borders, and other UI elements that take up space. If we set the window size
+ * to 1280x720, the actual content area will be smaller (perhaps 1280x670 after accounting for the toolbar). To get a 1280x720 content area, we need to add the
+ * chrome dimensions to our window size.
+ *
+ * This function:
+ * 1. Measures the current chrome dimensions by comparing window.outerWidth/Height to window.innerWidth/Height
+ * 2. Sets the window size to viewport + chrome dimensions, giving us the exact viewport size we want
+ * 3. Optionally minimizes the window to reduce GPU usage while still allowing capture
+ * @param page - The Puppeteer page object.
+ * @param shouldMinimize - Whether to minimize the window after resizing. Set to true for stream pages (to reduce GPU usage) and false for debug pages (where
+ *   visibility is desired).
+ */
+export declare function resizeAndMinimizeWindow(page: Page, shouldMinimize: boolean): Promise<void>;
+/**
+ * Un-minimizes the browser window, restoring it to normal state. This is used when the user needs to interact with the browser, such as during the authentication
+ * login flow where the user must complete TV provider authentication in the visible browser window.
+ * @param page - The Puppeteer page object.
+ */
+export declare function unminimizeWindow(page: Page): Promise<void>;

package/dist/browser/cdp.js

@@ -0,0 +1,158 @@
+import { LOG, evaluateWithAbort, formatError } from "../utils/index.js";
+import { CONFIG } from "../config/index.js";
+import { getBrowserChrome } from "./display.js";
+import { getEffectiveViewport } from "../config/presets.js";
+/*
+ * CDP SESSION HELPERS
+ *
+ * The Chrome DevTools Protocol (CDP) provides low-level access to Chrome's internal state and capabilities. While Puppeteer abstracts most common operations, some
+ * features require direct CDP access:
+ *
+ * - Window management: Setting window size, position, and state (minimized, maximized, fullscreen). Puppeteer's viewport API controls the content area, but we
+ *   need CDP to control the entire window including browser chrome.
+ *
+ * - Browser-level operations: Operations that affect the browser rather than a specific page, like getting the window ID for a page's target.
+ *
+ * CDP sessions are created per-page and must be managed carefully:
+ * - Sessions can fail if the page or target is closed while we're using it
+ * - The "No target with given id" error is common and expected when pages close during operations
+ * - We wrap CDP operations in try/catch to handle these transient errors gracefully
+ *
+ * The withCDPSession helper encapsulates the common pattern of creating a session, getting the window ID, performing an operation, and handling errors.
+ */
+/**
+ * Executes a CDP (Chrome DevTools Protocol) operation with proper session lifecycle management. This helper handles the common pattern of:
+ * 1. Creating a CDP session attached to the page's target
+ * 2. Getting the browser window ID for the page
+ * 3. Calling the provided operation with the session and window ID
+ * 4. Gracefully handling errors when the page is closed during the operation
+ *
+ * The session is created fresh for each call rather than being reused because CDP sessions become invalid when the page navigates or closes. Creating a new
+ * session ensures we always have a valid connection.
+ * @param page - The Puppeteer page object to create a CDP session for.
+ * @param operation - An async function that receives the CDP session and window ID. The operation can use any CDP commands via session.send().
+ * @returns The result of the operation, or undefined if the page was closed or an error occurred.
+ */
+export async function withCDPSession(page, operation) {
+    // Early exit if the page is already closed. This prevents errors when trying to create a session for a closed page.
+    if (page.isClosed()) {
+        return undefined;
+    }
+    try {
+        // Create a CDP session attached to the page's target. The session provides access to all CDP domains (Browser, Page, Network, etc.) for this specific
+        // target. Each page has its own target in Chrome's DevTools architecture.
+        const session = await page.createCDPSession();
+        // Get the browser window ID for this page. Chrome organizes pages into windows, and we need the window ID to perform window-level operations like resizing
+        // or minimizing. The Browser.getWindowForTarget command returns the window ID for the current target.
+        const windowResult = await session.send("Browser.getWindowForTarget");
+        const windowId = windowResult.windowId;
+        // If we couldn't get a window ID, the target may be in an invalid state. Return undefined to indicate the operation couldn't be performed.
+        if (!windowId) {
+            return undefined;
+        }
+        // Execute the caller's operation with the session and window ID.
+        return await operation(session, windowId);
+    }
+    catch (error) {
+        const message = formatError(error);
+        // "No target with given id" is a common error that occurs when the page closes during our operation. This is expected during stream termination and
+        // shouldn't be logged as a warning since it's not actionable. We also check if the page is closed, as errors during page closure are expected.
+        if ((message.indexOf("No target with given id") === -1) && !page.isClosed()) {
+            LOG.warn("CDP operation failed: %s.", message);
+        }
+        return undefined;
+    }
+}
+/**
+ * Resizes the browser window to match our target viewport dimensions and optionally minimizes it. This function solves the problem of ensuring the video content
+ * area exactly matches our configured viewport size.
+ *
+ * The complication is that browser windows have "chrome" - the title bar, toolbar, borders, and other UI elements that take up space. If we set the window size
+ * to 1280x720, the actual content area will be smaller (perhaps 1280x670 after accounting for the toolbar). To get a 1280x720 content area, we need to add the
+ * chrome dimensions to our window size.
+ *
+ * This function:
+ * 1. Measures the current chrome dimensions by comparing window.outerWidth/Height to window.innerWidth/Height
+ * 2. Sets the window size to viewport + chrome dimensions, giving us the exact viewport size we want
+ * 3. Optionally minimizes the window to reduce GPU usage while still allowing capture
+ * @param page - The Puppeteer page object.
+ * @param shouldMinimize - Whether to minimize the window after resizing. Set to true for stream pages (to reduce GPU usage) and false for debug pages (where
+ *   visibility is desired).
+ */
+export async function resizeAndMinimizeWindow(page, shouldMinimize) {
+    // Early exit if the page is already closed.
+    if (page.isClosed()) {
+        return;
+    }
+    // Get browser chrome dimensions. Prefer cached values from display detection, which were measured when the browser was in a known good state. Fall back to
+    // measuring via page.evaluate() if cached values aren't available (e.g., during early initialization or after cache clear).
+    let uiSize = getBrowserChrome();
+    if (!uiSize) {
+        try {
+            uiSize = await evaluateWithAbort(page, () => {
+                return {
+                    // Height of chrome = total window height - content height. This includes the title bar, toolbar, and any other vertical UI elements.
+                    height: window.outerHeight - window.innerHeight,
+                    // Width of chrome = total window width - content width. This typically includes window borders and any side panels.
+                    width: window.outerWidth - window.innerWidth
+                };
+            });
+        }
+        catch (_error) {
+            // If measuring fails (page closed, navigation in progress, etc.), silently return. The resize is not critical and will be attempted again on the next
+            // stream if needed.
+            return;
+        }
+    }
+    // Use CDP to set the window bounds. We add the chrome dimensions to our target viewport to get the correct total window size. CDP requires separate calls for
+    // dimensions and window state - they cannot be combined in a single call.
+    await withCDPSession(page, async (session, windowId) => {
+        // First, ensure the window is in "normal" state. If the browser launched with a window size larger than the display, Chrome may have automatically maximized
+        // the window. Setting bounds on a maximized window is ignored, so we must restore it to normal state first.
+        await session.send("Browser.setWindowBounds", {
+            bounds: { windowState: "normal" },
+            windowId
+        });
+        // Set the window size to viewport + chrome. After this, the content area will be exactly our target viewport dimensions.
+        const viewport = getEffectiveViewport(CONFIG);
+        await session.send("Browser.setWindowBounds", {
+            bounds: {
+                // Total window height = desired viewport height + chrome height (title bar, toolbar, etc.)
+                height: viewport.height + uiSize.height,
+                // Total window width = desired viewport width + chrome width (borders, etc.)
+                width: viewport.width + uiSize.width
+            },
+            windowId
+        });
+        // Optionally minimize the window to reduce GPU usage. This must be a separate CDP call because window state cannot be combined with dimensions. Minimizing
+        // doesn't stop video capture - the puppeteer-stream extension captures from the compositor rather than the visible display.
+        if (shouldMinimize) {
+            // Brief delay to allow Chrome's window manager to finish processing the resize before minimizing. Without this delay, the minimize can be ignored when the
+            // window is being significantly resized (e.g., during preset degradation from 1080p to 720p).
+            await new Promise((resolve) => setTimeout(resolve, 100));
+            await session.send("Browser.setWindowBounds", {
+                bounds: { windowState: "minimized" },
+                windowId
+            });
+        }
+    });
+}
+/**
+ * Un-minimizes the browser window, restoring it to normal state. This is used when the user needs to interact with the browser, such as during the authentication
+ * login flow where the user must complete TV provider authentication in the visible browser window.
+ * @param page - The Puppeteer page object.
+ */
+export async function unminimizeWindow(page) {
+    // Early exit if the page is already closed.
+    if (page.isClosed()) {
+        return;
+    }
+    await withCDPSession(page, async (session, windowId) => {
+        // Restore the window to normal (visible) state.
+        await session.send("Browser.setWindowBounds", {
+            bounds: { windowState: "normal" },
+            windowId
+        });
+    });
+}
+//# sourceMappingURL=cdp.js.map

package/dist/browser/cdp.js.map

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

package/dist/browser/channelSelection.d.ts

@@ -0,0 +1,16 @@
+import type { ChannelSelectorResult, ResolvedSiteProfile } from "../types/index.js";
+import type { Page } from "puppeteer-core";
+/**
+ * Selects a channel from a multi-channel player UI using the strategy specified in the profile. This is the main entry point for channel selection, called by
+ * tuneToChannel() after page navigation.
+ *
+ * The function handles:
+ * - Strategy dispatch based on profile.channelSelection.strategy
+ * - No-op for single-channel sites (strategy "none" or no channelSelector)
+ * - Logging of selection attempts and results
+ * - Timing delays before and after selection
+ * @param page - The Puppeteer page object.
+ * @param profile - The resolved site profile containing channelSelection config and channelSelector slug.
+ * @returns Result object with success status and optional failure reason.
+ */
+export declare function selectChannel(page: Page, profile: ResolvedSiteProfile): Promise<ChannelSelectorResult>;