prismcast 1.5.2 → 1.7.0

package/dist/native/index.js

@@ -0,0 +1,342 @@
+/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * index.ts: Coordinator for native HLS streaming — manifest interception, DRM probe, and proxy lifecycle.
+ */
+import { LOG, formatError, startTimer } from "../utils/index.js";
+import { clearProbeCache, probeManifest } from "./probe.js";
+import { installManifestInterceptor, removeManifestInterceptor } from "./intercept.js";
+import { createNativeProxy } from "./proxy.js";
+import { fetchDecryptionKey } from "./decrypt.js";
+/* This module orchestrates the native streaming decision. After the browser navigates to a channel and video playback begins, we check whether the provider's HLS
+ * stream can be consumed directly in Node (bypassing screen capture). The decision flow is:
+ *
+ * 1. Await the manifest interception promise (CDP listener was installed before navigation)
+ * 2. If no manifest was intercepted: return null (fall back to capture)
+ * 3. Probe the manifest for encryption type
+ * 4. If DRM: log the reason, return null
+ * 5. If clear or AES-128: create and return the native proxy
+ *
+ * Token refresh: When the intercepted URL contains expiration tokens, we schedule a timer to refresh the manifest before the tokens expire. The refresh first
+ * attempts a direct Node.js fetch of the master manifest URL (no browser involvement), falling back to a browser page reload when the master URL itself has expired.
+ * The proxy continues serving cached segments during the refresh.
+ */
+// Time in milliseconds before token expiry to trigger a refresh. We refresh 5 minutes early to ensure the new manifest is ready before the old one expires.
+const TOKEN_REFRESH_MARGIN = 300000;
+// Minimum delay in milliseconds before a token refresh fires. Prevents a refresh loop when the token lifetime is shorter than TOKEN_REFRESH_MARGIN (e.g., Fox Sports
+// tokens expire in ~118 seconds). Without this floor, the refresh delay would be Math.max(0, 118000 - 300000) = 0ms, triggering an infinite loop of page reloads.
+const MIN_REFRESH_DELAY = 30000;
+// Minimum remaining token lifetime (in milliseconds) for a direct-fetched variant URL to be considered usable. If the variant URL's token expires sooner than this,
+// the direct fetch result is discarded and we fall back to a page reload to get a genuinely fresh token. This prevents handing the proxy a variant URL that expires
+// almost immediately. Set low (5s) because the proxy only needs the variant URL to survive one poll cycle (~3s). A higher threshold (e.g., 30s) would cause Fox.com
+// channels to reject perfectly usable variant URLs — Fox.com tokens have ~57s total lifetime, leaving ~27s at the 30s refresh point.
+const MIN_USABLE_TOKEN_LIFETIME = 5000;
+// Timeout for awaiting the manifest interception promise after playback init.
+const INTERCEPTION_AWAIT_TIMEOUT = 5000;
+/**
+ * Attempts to upgrade a stream from screen capture to native HLS streaming. Returns the native proxy on success, or null if the stream is not viable for native
+ * consumption (DRM, interception timeout, or probe failure). The proxy owns the CDP session from interception and manages its lifecycle.
+ *
+ * @param options - Options for the native streaming attempt.
+ * @returns The native stream result on success, or null to fall back to capture.
+ */
+export async function attemptNativeStreaming(options) {
+    const { channelName, interceptionPromise, mpegTsClient, onError, page, streamId, streamIdStr, url } = options;
+    const elapsed = startTimer();
+    LOG.debug("native:coordinator", "Attempting native streaming for %s.", channelName);
+    // Await the manifest interception with a short timeout. The CDP listener was installed before navigation, so by the time we get here the manifest should
+    // already be captured or close to it.
+    let interception;
+    try {
+        interception = await Promise.race([
+            interceptionPromise,
+            new Promise((resolve) => {
+                setTimeout(() => { resolve(null); }, INTERCEPTION_AWAIT_TIMEOUT);
+            })
+        ]);
+    }
+    catch (error) {
+        LOG.debug("native:coordinator", "Manifest interception error for %s: %s.", channelName, formatError(error));
+        return null;
+    }
+    if (!interception) {
+        LOG.debug("native:coordinator", "No manifest intercepted for %s in %sms. Falling back to capture.", channelName, elapsed());
+        return null;
+    }
+    LOG.debug("native:coordinator", "Manifest intercepted for %s in %sms.", channelName, elapsed());
+    // Probe the manifest for encryption type.
+    const probeResult = await probeManifest(interception.masterManifestUrl, channelName);
+    if (!probeResult) {
+        LOG.debug("native:coordinator", "Probe failed for %s. Falling back to capture.", channelName);
+        removeManifestInterceptor(interception.cdpSession);
+        return null;
+    }
+    if (probeResult.encryption === "drm") {
+        LOG.debug("native:coordinator", "Native streaming not viable for %s: DRM-protected stream.", channelName);
+        removeManifestInterceptor(interception.cdpSession);
+        return null;
+    }
+    // Separate audio renditions (e.g., Google DAI on BET/VH1) cannot be served to MPEG-TS clients because the independent video and audio MPEG-TS segments have
+    // incompatible PAT/PMT tables and variable packet sizes from ad splicing. HLS clients (Channels DVR) handle separate audio renditions natively via master playlist.
+    if (mpegTsClient && probeResult.audioVariantUrl) {
+        LOG.debug("native:coordinator", "Native streaming not viable for %s: separate audio rendition incompatible with MPEG-TS clients.", channelName);
+        removeManifestInterceptor(interception.cdpSession);
+        return null;
+    }
+    LOG.debug("native:coordinator", "Native streaming viable for %s (%s, variant: %s).", channelName, probeResult.encryption, probeResult.bestVariantUrl.slice(0, 80));
+    // For AES-128 streams, pre-fetch the decryption key before committing to native mode. This validates key accessibility while the capture pipeline is still intact,
+    // allowing a seamless fallback to capture if the key is inaccessible. Without this, the proxy would discover the problem on its first segment fetch — after the
+    // capture pipeline has already been torn down and no fallback is possible.
+    let prefetchedKey = null;
+    if ((probeResult.encryption === "aes128") && probeResult.keyUrl) {
+        prefetchedKey = await fetchDecryptionKey(probeResult.keyUrl);
+        if (!prefetchedKey) {
+            LOG.debug("native:coordinator", "Native streaming not viable for %s: decryption key inaccessible.", channelName);
+            removeManifestInterceptor(interception.cdpSession);
+            return null;
+        }
+        LOG.debug("native:coordinator", "AES-128 decryption key pre-fetched for %s.", channelName);
+    }
+    // Create the native proxy. The CDP session is passed so the proxy can clean it up on stop(), preventing session leaks when the stream terminates before a token
+    // refresh occurs. For AES-128 streams, the pre-fetched key is passed so the proxy does not need to fetch it again on the first segment. The preroll segment count
+    // determines the segment index offset (reserving index space for preroll). Streams with separate audio cannot use preroll because the preroll content is muxed
+    // video+audio and can't be split into separate renditions.
+    const hasSeparateAudio = probeResult.audioVariantUrl !== null;
+    const proxyPrerollSegmentCount = (!hasSeparateAudio && options.prerollSegmentCount) ? options.prerollSegmentCount : 0;
+    const proxy = createNativeProxy({
+        audioVariantUrl: probeResult.audioVariantUrl,
+        cdpSession: interception.cdpSession,
+        channelName,
+        encryption: probeResult.encryption,
+        keyUrl: probeResult.keyUrl,
+        onError,
+        prefetchedKey,
+        prerollCodec: options.prerollCodec,
+        prerollSegmentCount: proxyPrerollSegmentCount,
+        streamId,
+        streamIdStr,
+        variantUrl: probeResult.bestVariantUrl
+    });
+    // Schedule token refresh if the URL contains expiration tokens.
+    scheduleTokenRefresh({
+        channelName,
+        masterUrl: interception.masterManifestUrl,
+        page,
+        proxy,
+        streamIdStr,
+        url
+    });
+    LOG.debug("timing:native", "Native streaming setup completed for %s in %sms.", channelName, elapsed());
+    return { bandwidth: probeResult.bandwidth, codec: probeResult.codec, hasAudio: probeResult.audioVariantUrl !== null, proxy, resolution: probeResult.resolution };
+}
+/**
+ * Parses token expiration from an HLS manifest or variant URL. Common patterns include `exp=N`, `hdnea=...~exp=N~...`, path-style `/exp=N~`, and `hdnts=exp%3DN`.
+ * Returns the expiration timestamp in milliseconds, or null if no expiration is found.
+ *
+ * @param url - The URL to parse for token expiration.
+ * @returns The expiration timestamp in milliseconds, or null.
+ */
+function parseTokenExpiry(url) {
+    // Pattern 1: exp=N (plain query parameter).
+    const expMatch = /[?&]exp=(\d{10,13})/.exec(url);
+    if (expMatch) {
+        const value = Number(expMatch[1]);
+        // If the value is 10 digits, it's seconds; if 13, it's milliseconds.
+        return value < 1e12 ? value * 1000 : value;
+    }
+    // Pattern 2: hdnea=...~exp=N~... (Akamai token in query parameter).
+    const hdneaExpMatch = /~exp=(\d{10,13})~/.exec(url);
+    if (hdneaExpMatch) {
+        const value = Number(hdneaExpMatch[1]);
+        return value < 1e12 ? value * 1000 : value;
+    }
+    // Pattern 3: /exp=N~ (Akamai token in URL path, e.g., foxvideo-sports.akamaized.net/exp=N~acl=...).
+    const pathExpMatch = /\/exp=(\d{10,13})~/.exec(url);
+    if (pathExpMatch) {
+        const value = Number(pathExpMatch[1]);
+        return value < 1e12 ? value * 1000 : value;
+    }
+    // Pattern 4: URL-encoded exp%3D (hdnts parameter).
+    const encodedExpMatch = /exp%3D(\d{10,13})/.exec(url);
+    if (encodedExpMatch) {
+        const value = Number(encodedExpMatch[1]);
+        return value < 1e12 ? value * 1000 : value;
+    }
+    return null;
+}
+/**
+ * Schedules a token refresh timer if the manifest URL contains an expiration token. The refresh occurs TOKEN_REFRESH_MARGIN milliseconds before the token expires.
+ * On timer fire, the refresh first attempts a direct Node.js fetch of the master manifest URL, falling back to a browser page reload if the direct fetch fails.
+ *
+ * @param options - Token refresh options.
+ */
+function scheduleTokenRefresh(options) {
+    const { channelName, masterUrl, page, proxy, streamIdStr, url } = options;
+    const expiry = parseTokenExpiry(masterUrl);
+    if (!expiry) {
+        LOG.debug("native:token", "No token expiry found in manifest URL for %s.", channelName);
+        return;
+    }
+    const timeUntilExpiry = expiry - Date.now();
+    const refreshIn = Math.max(MIN_REFRESH_DELAY, timeUntilExpiry - TOKEN_REFRESH_MARGIN);
+    LOG.debug("native:token", "Token expires in %ss for %s. Refresh scheduled in %ss.", Math.round(timeUntilExpiry / 1000), channelName, Math.round(refreshIn / 1000));
+    // Store the timer handle on the proxy so it can be cancelled if the proxy is stopped before the timer fires. Pass the master URL so the refresh can attempt a
+    // direct fetch before falling back to a page reload.
+    const timer = setTimeout(() => {
+        void refreshNativeManifest({ channelName, masterUrl, page, proxy, streamIdStr, url });
+    }, refreshIn);
+    proxy.setTokenRefreshTimer(timer);
+}
+/**
+ * Refreshes a native stream's manifest to obtain fresh auth tokens. Two strategies are tried in order:
+ *
+ * 1. **Direct fetch** (if masterUrl is provided): Re-fetches the master manifest URL from Node.js without involving the browser. This avoids the visible page reload
+ *    that disrupts the browser tab. The CDN returns the manifest with current token values as long as the URL's own auth token hasn't expired. When the master URL
+ *    expires, the direct fetch returns 403 and we fall through to strategy 2.
+ *
+ * 2. **Page reload**: Navigates the browser page back to the channel URL, triggering fresh authentication via cookies. A CDP interceptor captures the new master
+ *    manifest URL with fresh tokens. This is the only path that generates genuinely new tokens and is required when the master URL itself has expired.
+ *
+ * L2 recovery (failure-triggered) from the monitor omits masterUrl, going straight to page reload since the stream is already failing and needs a full refresh.
+ *
+ * @param options - Refresh options. masterUrl is optional — when provided, direct fetch is attempted first.
+ * @returns True if the refresh succeeded (proxy updated with new manifest), false otherwise.
+ */
+export async function refreshNativeManifest(options) {
+    const { channelName, masterUrl, page, proxy, streamIdStr, url } = options;
+    const streamLog = LOG.withStreamId(streamIdStr);
+    if (proxy.isStopped()) {
+        return false;
+    }
+    const refreshElapsed = startTimer();
+    streamLog.debug("native:token", "Starting manifest refresh for %s.", channelName);
+    // Strategy 1: Direct fetch. Re-fetch the master manifest URL from Node.js to get fresh variant URLs without reloading the browser page. This works as long as the
+    // master URL's own CDN auth token hasn't expired. When it does expire, probeManifest returns null (403) and we fall through to the page reload strategy.
+    if (masterUrl) {
+        const directResult = await tryDirectManifestRefresh(masterUrl, channelName, streamLog);
+        if (directResult) {
+            // Check if the proxy was stopped during the async probe (e.g., stream terminated while probing).
+            if (proxy.isStopped()) {
+                return false;
+            }
+            // Direct fetch succeeded. Update the proxy with the fresh variant URL(s).
+            proxy.updateVariantUrl(directResult.bestVariantUrl);
+            if (directResult.audioVariantUrl) {
+                proxy.updateAudioVariantUrl(directResult.audioVariantUrl);
+            }
+            streamLog.debug("native:token", "Manifest refresh completed for %s via direct fetch in %sms.", channelName, refreshElapsed());
+            // Schedule the next refresh with the same master URL. It may still be valid for subsequent direct fetches. Once it expires, the direct fetch will fail and
+            // the page reload fallback will generate a new master URL.
+            scheduleTokenRefresh({
+                channelName,
+                masterUrl,
+                page,
+                proxy,
+                streamIdStr,
+                url
+            });
+            return true;
+        }
+        // Direct fetch failed. Fall through to page reload.
+        streamLog.debug("native:token", "Direct manifest fetch failed for %s. Falling back to page reload.", channelName);
+    }
+    // Strategy 2: Page reload. Navigate the browser page to trigger fresh authentication and intercept a new master manifest via CDP.
+    if (page.isClosed()) {
+        streamLog.debug("native:token", "Manifest refresh failed for %s: page is closed.", channelName);
+        return false;
+    }
+    try {
+        // Install a fresh interceptor on the page. For token refresh, the page navigates directly to the channel URL (no guide grid), so the first manifest captured is
+        // the correct one. We call finalize() after navigation to resolve immediately with whatever was captured.
+        const handle = await installManifestInterceptor(page, 20000);
+        if (!handle) {
+            streamLog.debug("native:token", "Manifest refresh failed for %s: could not install interceptor.", channelName);
+            return false;
+        }
+        // Navigate the page back to the channel URL to trigger fresh authentication. The interceptor captures .m3u8 requests generated by this navigation. Note: this
+        // uses a bare page.goto without the provider's site profile (no waitForNetworkIdle, scroll options, etc.). This is acceptable because native streaming only
+        // activates for providers whose video players load the HLS manifest during basic page load. Providers requiring profile-aware navigation for manifest delivery
+        // would have failed the initial interception and would not be in native mode.
+        await page.goto(url, { timeout: 30000, waitUntil: "domcontentloaded" });
+        // Check if the proxy was stopped while we were navigating (e.g., stream terminated during the page load).
+        if (proxy.isStopped()) {
+            return false;
+        }
+        // Signal finalize and await the interception result. Token refresh always navigates directly (no guide grid), so the first manifest is correct.
+        handle.finalize(true);
+        const newInterception = await handle.promise;
+        if (!newInterception) {
+            streamLog.debug("native:token", "Manifest refresh failed for %s: no manifest intercepted after reload.", channelName);
+            return false;
+        }
+        // Check if the proxy was stopped while we were waiting for the interception. Clean up the new session since the proxy will not take ownership of it.
+        if (proxy.isStopped()) {
+            removeManifestInterceptor(newInterception.cdpSession);
+            return false;
+        }
+        // Probe the new manifest to get the updated variant URL. We probe before handing the new CDP session to the proxy so that a probe failure does not leave the
+        // proxy holding a reference to a session we are about to clean up.
+        const probeResult = await probeManifest(newInterception.masterManifestUrl, channelName);
+        if (!probeResult) {
+            streamLog.debug("native:token", "Manifest refresh failed for %s: probe failed on new manifest.", channelName);
+            removeManifestInterceptor(newInterception.cdpSession);
+            return false;
+        }
+        // Check if the proxy was stopped during the probe. Clean up the new session since the proxy will not take ownership of it.
+        if (proxy.isStopped()) {
+            removeManifestInterceptor(newInterception.cdpSession);
+            return false;
+        }
+        // Probe succeeded. Hand the new CDP session to the proxy. updateCdpSession cleans up the old session internally before replacing it.
+        proxy.updateCdpSession(newInterception.cdpSession);
+        // Update the proxy with the new variant URL(s).
+        proxy.updateVariantUrl(probeResult.bestVariantUrl);
+        if (probeResult.audioVariantUrl) {
+            proxy.updateAudioVariantUrl(probeResult.audioVariantUrl);
+        }
+        streamLog.debug("native:token", "Manifest refresh completed for %s via page reload in %sms.", channelName, refreshElapsed());
+        // Schedule the next proactive token refresh with the NEW master URL from the fresh interception. Subsequent direct fetches will use this URL until it expires.
+        scheduleTokenRefresh({
+            channelName,
+            masterUrl: newInterception.masterManifestUrl,
+            page,
+            proxy,
+            streamIdStr,
+            url
+        });
+        return true;
+    }
+    catch (error) {
+        streamLog.debug("native:token", "Manifest refresh failed for %s: %s.", channelName, formatError(error));
+        // Clear the probe cache so a subsequent attempt re-probes.
+        clearProbeCache(channelName);
+        return false;
+    }
+}
+/**
+ * Attempts to refresh the manifest by directly fetching the master manifest URL from Node.js. Returns the probe result if the fetch succeeds and the variant URL
+ * has sufficient token lifetime remaining, or null if the direct fetch should be abandoned in favor of a page reload.
+ *
+ * @param masterUrl - The master manifest URL to re-fetch.
+ * @param channelName - The channel name for logging and cache keys.
+ * @param streamLog - The stream-scoped logger.
+ * @returns The probe result with a fresh variant URL, or null on failure.
+ */
+async function tryDirectManifestRefresh(masterUrl, channelName, streamLog) {
+    const probeResult = await probeManifest(masterUrl, channelName);
+    if (!probeResult || (probeResult.encryption === "drm")) {
+        return null;
+    }
+    // Verify the variant URL's token hasn't already expired or is about to expire. Parse the expiry from the variant URL (not the master URL) since that's what the
+    // proxy will actually poll. If the token expires within MIN_USABLE_TOKEN_LIFETIME, the direct fetch result is stale — the page reload path will generate a
+    // genuinely fresh token.
+    const variantExpiry = parseTokenExpiry(probeResult.bestVariantUrl);
+    if (variantExpiry) {
+        const remaining = variantExpiry - Date.now();
+        if (remaining < MIN_USABLE_TOKEN_LIFETIME) {
+            streamLog.debug("native:token", "Direct fetch returned near-expired variant for %s (%ss remaining). Discarding.", channelName, Math.round(remaining / 1000));
+            return null;
+        }
+    }
+    return probeResult;
+}
+//# sourceMappingURL=index.js.map

package/dist/native/index.js.map

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

package/dist/native/intercept.d.ts

@@ -0,0 +1,35 @@
+import type { CDPSession, Page } from "puppeteer-core";
+import type { Nullable } from "../types/index.js";
+/**
+ * Result of manifest interception containing the CDP session for reuse during token refresh and the master manifest URL.
+ */
+export interface ManifestInterceptionResult {
+    cdpSession: CDPSession;
+    masterManifestUrl: string;
+}
+/**
+ * Handle returned by installManifestInterceptor. Provides the interception promise and a finalize function to signal that channel selection is complete.
+ */
+export interface ManifestInterceptorHandle {
+    finalize: (directTune: boolean) => void;
+    promise: Promise<Nullable<ManifestInterceptionResult>>;
+}
+/**
+ * Installs a CDP Network.responseReceived listener on the given page to capture master HLS manifest URLs. The listener tracks both the first and latest master
+ * manifest URLs as they arrive. The returned handle provides a promise that resolves when finalize() is called — the caller invokes finalize() after channel
+ * selection is complete, passing directTune to control which manifest is selected.
+ *
+ * For direct-navigation sites (directTune=true), the first master manifest is the correct one — it was loaded for the navigated URL. Background prefetches for
+ * other channels are ignored. For guide-based sites (directTune=false), the latest manifest is selected — it corresponds to the channel the user clicked.
+ *
+ * @param page - The Puppeteer page to monitor.
+ * @param timeout - Maximum time in milliseconds to wait for a manifest (default: 15 seconds). Acts as a safety net if finalize() is never called.
+ * @returns The interceptor handle, or null if the CDP session could not be created.
+ */
+export declare function installManifestInterceptor(page: Page, timeout?: number): Promise<Nullable<ManifestInterceptorHandle>>;
+/**
+ * Removes the Network domain listener and detaches the CDP session. Safe to call multiple times or on an already-detached session.
+ *
+ * @param cdpSession - The CDP session to clean up.
+ */
+export declare function removeManifestInterceptor(cdpSession: CDPSession): void;

package/dist/native/intercept.js

@@ -0,0 +1,184 @@
+import { LOG, chromeFetch, startTimer } from "../utils/index.js";
+/* This module installs a Chrome DevTools Protocol (CDP) listener on the Network domain to capture HLS manifest URLs as the browser's video player fetches them. Unlike
+ * the per-call CDP sessions created by withCDPSession() in cdp.ts, we create a long-lived session here because the listener must remain active across multiple network
+ * requests until channel selection is complete.
+ *
+ * The listener filters for URLs ending in .m3u8 and fetches the manifest body directly via Node.js to inspect the content. Master manifests contain #EXT-X-STREAM-INF
+ * directives (variant playlist references), which distinguishes them from variant/media playlists. We use a direct fetch rather than CDP's Network.getResponseBody
+ * because Chrome's network cache can evict response bodies before we read them, causing spurious "No data found for resource" failures.
+ *
+ * For multi-channel sites, the video player may load manifests for channels other than the one requested. The interceptor tracks both the first and latest master
+ * manifest URLs to handle two distinct scenarios:
+ *
+ * - Direct-navigation sites (Fox Sports): The first manifest is the correct one — the player loaded it for the navigated URL. Background prefetches for other channels
+ *   may arrive later but should be ignored. finalize(directTune=true) selects the first manifest.
+ *
+ * - Guide-based sites (Fox.com, Hulu, Sling, YouTube TV): The player loads a default channel's manifest during page navigation, then the guide grid strategy clicks the
+ *   correct entry, triggering a new manifest fetch. finalize(directTune=false) selects the latest manifest.
+ */
+// Default timeout for manifest interception after installation.
+const INTERCEPTION_TIMEOUT = 15000;
+// Brief delay after finalize() is called to allow any in-flight manifest response to arrive. Applied only for guide-based tunes (directTune=false) where the
+// channel switch may trigger a manifest fetch that arrives milliseconds after the click handler returns. Direct tunes skip this delay and resolve immediately.
+const FINALIZE_SETTLE_DELAY = 1500;
+/**
+ * Installs a CDP Network.responseReceived listener on the given page to capture master HLS manifest URLs. The listener tracks both the first and latest master
+ * manifest URLs as they arrive. The returned handle provides a promise that resolves when finalize() is called — the caller invokes finalize() after channel
+ * selection is complete, passing directTune to control which manifest is selected.
+ *
+ * For direct-navigation sites (directTune=true), the first master manifest is the correct one — it was loaded for the navigated URL. Background prefetches for
+ * other channels are ignored. For guide-based sites (directTune=false), the latest manifest is selected — it corresponds to the channel the user clicked.
+ *
+ * @param page - The Puppeteer page to monitor.
+ * @param timeout - Maximum time in milliseconds to wait for a manifest (default: 15 seconds). Acts as a safety net if finalize() is never called.
+ * @returns The interceptor handle, or null if the CDP session could not be created.
+ */
+export async function installManifestInterceptor(page, timeout = INTERCEPTION_TIMEOUT) {
+    if (page.isClosed()) {
+        return null;
+    }
+    const elapsed = startTimer();
+    let cdpSession;
+    try {
+        cdpSession = await page.createCDPSession();
+    }
+    catch (error) {
+        LOG.debug("native:intercept", "Failed to create CDP session: %s.", String(error));
+        return null;
+    }
+    // Enable the Network domain to receive request and response events.
+    try {
+        await cdpSession.send("Network.enable");
+    }
+    catch (error) {
+        LOG.debug("native:intercept", "Failed to enable Network domain: %s.", String(error));
+        return null;
+    }
+    LOG.debug("native:intercept", "CDP manifest interceptor installed.");
+    // Track both the first and most recently observed master manifest URLs. For direct-navigation sites (directTune=true), the first manifest is the correct one — the
+    // player loaded it for the navigated URL. Background prefetches for other channels may arrive later and must not overwrite the selection. For guide-based sites
+    // (directTune=false), the last manifest is correct — the guide click triggers a new manifest fetch that replaces whatever the player initially loaded.
+    let firstManifestUrl = null;
+    let latestManifestUrl = null;
+    let resolved = false;
+    let manifestCount = 0;
+    // Finalize function, assigned inside the promise constructor and exposed on the returned handle.
+    let finalize = () => { };
+    const promise = new Promise((resolve) => {
+        // Timeout guard. If finalize() is never called (defensive), resolve with whatever we have after the timeout.
+        const timer = setTimeout(() => {
+            if (!resolved) {
+                resolved = true;
+                cdpSession.off("Network.responseReceived", wrappedHandler);
+                if (latestManifestUrl) {
+                    LOG.debug("native:intercept", "Manifest interception timed out after %sms. Resolving with latest URL (%s captured).", elapsed(), manifestCount);
+                    resolve({ cdpSession, masterManifestUrl: latestManifestUrl });
+                }
+                else {
+                    LOG.debug("native:intercept", "Manifest interception timed out after %sms. No master manifest captured.", elapsed());
+                    removeManifestInterceptor(cdpSession);
+                    resolve(null);
+                }
+            }
+        }, timeout);
+        // Listen for completed responses. We use Network.responseReceived to capture .m3u8 URLs, then fetch the manifest body directly from Node.js to verify it is
+        // a master manifest. This avoids CDP's Network.getResponseBody which is unreliable — Chrome's network cache can evict response bodies before we read them.
+        const onResponseReceived = async (params) => {
+            if (resolved) {
+                return;
+            }
+            const url = params.response.url;
+            // Filter for .m3u8 URLs. Strip query parameters before checking the extension.
+            const urlPath = url.split("?")[0];
+            if (!urlPath.endsWith(".m3u8")) {
+                return;
+            }
+            LOG.debug("native:intercept", "Observed .m3u8 response: %s.", url.slice(0, 120));
+            // Fetch the manifest body directly to inspect whether this is a master manifest. The URL contains embedded CDN auth tokens, so no cookies or special
+            // headers are needed beyond the Chrome User-Agent injected by chromeFetch().
+            try {
+                const response = await chromeFetch(url, { signal: AbortSignal.timeout(5000) });
+                if (!response.ok) {
+                    LOG.debug("native:intercept", "Manifest fetch returned HTTP %s for %s.", response.status, url.slice(0, 120));
+                    return;
+                }
+                const body = await response.text();
+                // Master manifests contain #EXT-X-STREAM-INF directives that reference variant playlists. Media/variant playlists contain #EXTINF or #EXT-X-TARGETDURATION
+                // but not #EXT-X-STREAM-INF.
+                if (body.includes("#EXT-X-STREAM-INF")) {
+                    manifestCount++;
+                    firstManifestUrl ??= url;
+                    latestManifestUrl = url;
+                    LOG.debug("native:intercept", "Master manifest captured (#%s) in %sms: %s.", manifestCount, elapsed(), url.slice(0, 120));
+                }
+                else {
+                    LOG.debug("native:intercept", "Skipping non-master .m3u8 (no #EXT-X-STREAM-INF).");
+                }
+            }
+            catch (error) {
+                LOG.debug("native:intercept", "Could not fetch .m3u8 body: %s.", String(error));
+            }
+        };
+        // Wrap the async handler to avoid no-misused-promises — EventEmitter.on() does not handle returned promises.
+        const wrappedHandler = (...args) => { void onResponseReceived(...args); };
+        cdpSession.on("Network.responseReceived", wrappedHandler);
+        // Assign the finalize function. Called by the stream setup code after channel selection is complete. The resolution strategy depends on two factors: whether a
+        // manifest has already been captured, and whether the tune is direct or guide-based.
+        //
+        // - Manifest captured + direct tune: resolve immediately (A&E, most TVE sites — manifest arrived during page load).
+        // - Manifest captured + guide tune: wait FINALIZE_SETTLE_DELAY (Fox guide, Hulu — a newer manifest from the channel switch may still arrive).
+        // - No manifest captured + either: wait FINALIZE_SETTLE_DELAY (Fox Sports — manifest fetch starts after video element appears, hasn't arrived yet).
+        finalize = (directTune) => {
+            if (resolved) {
+                return;
+            }
+            // Helper that resolves the promise with the current state. For direct tunes, the first manifest is the correct one (loaded for the navigated URL — background
+            // prefetches for other channels may have overwritten latestManifestUrl). For guide tunes, the last manifest is correct (from the channel switch click).
+            const resolveNow = () => {
+                if (resolved) {
+                    return;
+                }
+                resolved = true;
+                clearTimeout(timer);
+                cdpSession.off("Network.responseReceived", wrappedHandler);
+                const selectedUrl = directTune ? firstManifestUrl : latestManifestUrl;
+                if (selectedUrl) {
+                    LOG.debug("native:intercept", "Interception finalized in %sms with %s manifest(s). Using %s: %s.", elapsed(), manifestCount, directTune ? "first" : "latest", selectedUrl.slice(0, 120));
+                    resolve({ cdpSession, masterManifestUrl: selectedUrl });
+                }
+                else {
+                    LOG.debug("native:intercept", "Interception finalized in %sms but no master manifest was captured.", elapsed());
+                    removeManifestInterceptor(cdpSession);
+                    resolve(null);
+                }
+            };
+            if (directTune && firstManifestUrl) {
+                // Direct tune with manifest already captured: resolve immediately with zero delay. The first manifest arrived during page load and is the correct one.
+                resolveNow();
+            }
+            else {
+                // Either no manifest captured yet (some providers fetch the manifest after the video element appears) or a guide-based tune where the channel switch
+                // may produce a newer manifest. Wait briefly for in-flight responses.
+                setTimeout(resolveNow, FINALIZE_SETTLE_DELAY);
+            }
+        };
+    });
+    return { finalize, promise };
+}
+/**
+ * Removes the Network domain listener and detaches the CDP session. Safe to call multiple times or on an already-detached session.
+ *
+ * @param cdpSession - The CDP session to clean up.
+ */
+export function removeManifestInterceptor(cdpSession) {
+    try {
+        cdpSession.removeAllListeners("Network.responseReceived");
+        void cdpSession.send("Network.disable").catch(() => { });
+        void cdpSession.detach().catch(() => { });
+    }
+    catch (_error) {
+        // Ignore errors during cleanup — the session may already be detached.
+    }
+    LOG.debug("native:intercept", "CDP manifest interceptor removed.");
+}
+//# sourceMappingURL=intercept.js.map

package/dist/native/intercept.js.map

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

package/dist/native/probe.d.ts

@@ -0,0 +1,49 @@
+import type { Nullable } from "../types/index.js";
+/**
+ * Encryption classification result from probing an HLS manifest.
+ */
+export type EncryptionType = "aes128" | "clear" | "drm";
+/**
+ * Result of probing an HLS master manifest for encryption type and best variant.
+ */
+export interface ProbeResult {
+    audioVariantUrl: Nullable<string>;
+    bandwidth: number;
+    bestVariantUrl: string;
+    codec: Nullable<string>;
+    encryption: EncryptionType;
+    keyUrl: Nullable<string>;
+    resolution: Nullable<string>;
+}
+/**
+ * Returns the cached encryption type for a channel, or null if the channel has not been probed or the cache entry has expired. Used by the stream setup path to skip
+ * CDP interceptor installation for channels already known to use DRM.
+ *
+ * @param channelName - The channel name to look up.
+ * @returns The cached encryption type, or null if not probed or expired.
+ */
+export declare function getCachedEncryption(channelName: string): Nullable<EncryptionType>;
+/**
+ * Clears the probe cache for a specific channel. Called when a native stream fails, forcing a fresh probe on the next attempt.
+ *
+ * @param channelName - The channel name to clear from the cache.
+ */
+export declare function clearProbeCache(channelName: string): void;
+/**
+ * Probes an HLS master manifest to determine encryption type and select the best variant. The probe cache is checked for DRM channels only — if a previous probe
+ * classified the channel as DRM, we return the cached result immediately since the caller will bail out regardless of URLs. For viable channels (clear or aes128),
+ * we always run the full probe because the variant URL and key URL contain auth tokens that expire between browser sessions.
+ *
+ * @param masterUrl - The master manifest URL (contains auth tokens from the browser's original request).
+ * @param channelName - The channel name for cache lookup.
+ * @returns The probe result, or null if probing fails.
+ */
+export declare function probeManifest(masterUrl: string, channelName: string): Promise<Nullable<ProbeResult>>;
+/**
+ * Resolves a potentially relative URL against a base URL. Handles both absolute and relative URLs. Exported for reuse by the proxy module.
+ *
+ * @param url - The URL to resolve (may be relative or absolute).
+ * @param baseUrl - The base URL for resolving relative references.
+ * @returns The resolved absolute URL.
+ */
+export declare function resolveUrl(url: string, baseUrl: string): string;