prismcast 1.5.2 → 1.6.0

package/dist/streaming/preroll.js

@@ -0,0 +1,373 @@
+import { LOG, resolveFFmpegPath } from "../utils/index.js";
+import { createMP4BoxParser, offsetMoofTimestamps, parseMoovTrackInfo } from "./mp4Parser.js";
+import { CONFIG } from "../config/index.js";
+import { buildPlaylist } from "./playlistBuilder.js";
+import { getEffectiveViewport } from "../config/presets.js";
+import { spawn } from "node:child_process";
+/* When a client requests an HLS playlist for a channel that is still starting up, PrismCast returns a startup playlist immediately to prevent HTTP timeouts. Channels
+ * DVR requires at least one segment in the playlist — an empty playlist is rejected with "Playlist had no segments." This module generates PREROLL_TOTAL_DURATION
+ * seconds of black+silence fMP4 at server startup, splits it into individual segments with naturally monotonic PTS, and serves them via global routes so the startup
+ * playlist can reference valid media content.
+ *
+ * The preroll playlist is served progressively — segments are revealed over time based on elapsed wall-clock time, simulating a live stream. The client polls for
+ * updates, sees new segments appear, and keeps playing without stalling for the full duration of the tune. When real content arrives, the fMP4 segmenter's composite
+ * playlist takes over, including preroll entries in its sliding window during the transition. As real segments accumulate, preroll entries fall off the window and the
+ * playlist becomes purely live content.
+ */
+// Total duration of preroll content in seconds. FFmpeg generates this much continuous black+silence fMP4, which is then split into individual segments at keyframe
+// boundaries. The configured duration provides ample coverage for the slowest providers with the progressive playlist delivering content in real time for the full
+// tune duration.
+const PREROLL_TOTAL_DURATION = 30;
+// Number of segments to reveal immediately on the first preroll playlist request. The HLS spec (RFC 8216 Section 6.3.3) says a client should start playback 3 target
+// durations from the end of a live playlist, so 4 segments gives the client 3 playable segments plus one buffer.
+const PREROLL_INITIAL_WINDOW = 4;
+// Cached preroll buffers. Generated once at startup, reused for all streams.
+let prerollInitSegment = null;
+// Individual preroll media segment buffers. Each entry is one moof+mdat pair with naturally monotonic PTS from the continuous FFmpeg output. Unlike the previous
+// implementation that served the same buffer N times (causing PTS restarts), each segment has distinct timestamps.
+const prerollMediaSegments = [];
+// Per-segment durations in seconds. Derived from trun sample durations and moov timescales during splitPrerollBuffers(). Used for EXTINF values in the playlist.
+const prerollSegmentDurations = [];
+// Public Accessors.
+/**
+ * Returns true when the preroll init segment and at least one media segment have been generated and are ready to serve.
+ */
+export function isPrerollReady() {
+    return (prerollInitSegment !== null) && (prerollMediaSegments.length > 0);
+}
+/**
+ * Returns the number of preroll segments available. Used by the segmenter to determine the preroll-to-real segment index boundary.
+ * @returns The count of preroll media segments.
+ */
+export function getPrerollSegmentCount() {
+    return prerollMediaSegments.length;
+}
+/**
+ * Returns the duration of a specific preroll segment in seconds. Used by the segmenter's generatePlaylist() for EXTINF values when preroll entries are in the sliding
+ * window.
+ * @param index - The zero-based segment index.
+ * @returns The segment duration in seconds.
+ */
+export function getPrerollSegmentDuration(index) {
+    return prerollSegmentDurations[index] ?? 2;
+}
+/**
+ * Returns the total duration of all preroll segments in seconds. Used by the fmp4Segmenter to compute PTS offsets that make Chrome's real content timestamps continue
+ * from where the preroll ended, eliminating the PTS discontinuity at the preroll-to-live boundary.
+ * @returns The sum of all preroll segment durations in seconds.
+ */
+export function getPrerollTotalDurationSec() {
+    let total = 0;
+    for (const duration of prerollSegmentDurations) {
+        total += duration;
+    }
+    return total;
+}
+/**
+ * Returns the maximum duration across all preroll segments, rounded up to the nearest integer. Used for TARGETDURATION computation in the composite playlist.
+ * @returns The ceiling of the maximum preroll segment duration.
+ */
+export function getPrerollMaxDuration() {
+    if (prerollSegmentDurations.length === 0) {
+        return 2;
+    }
+    let max = 0;
+    for (const duration of prerollSegmentDurations) {
+        if (duration > max) {
+            max = duration;
+        }
+    }
+    return Math.ceil(max);
+}
+// Preroll Generation.
+/**
+ * Generates the preroll fMP4 at startup. Spawns FFmpeg to create PREROLL_TOTAL_DURATION seconds of black frame + silence as fragmented MP4, then splits
+ * the output into an init segment (ftyp + moov) and individual media segments (moof + mdat pairs) using the MP4 box parser. Each segment has naturally monotonic PTS
+ * because it comes from a continuous FFmpeg encode. If FFmpeg is unavailable or fails, the preroll is left uninitialized and the system degrades gracefully — the
+ * blocking stream setup path is used instead.
+ */
+export async function generatePreroll() {
+    const ffmpegPath = await resolveFFmpegPath();
+    if (!ffmpegPath) {
+        LOG.warn("FFmpeg is not available. Preroll generation skipped — startup playlists will have no segments.");
+        return;
+    }
+    // Use the effective viewport to match the resolution Chrome MediaRecorder will produce. This prevents a resolution mismatch at the preroll→live discontinuity
+    // boundary. Baseline profile and level 3.1 match Chrome's MediaRecorder output (confirmed via parseMoovCodecConfig telemetry). Slow preset and CRF 18 produce
+    // higher quality — acceptable for a short duration of simple content generated once at startup.
+    const viewport = getEffectiveViewport(CONFIG);
+    const size = String(viewport.width) + "x" + String(viewport.height);
+    const args = [
+        "-hide_banner", "-loglevel", "warning",
+        "-f", "lavfi", "-i", "color=black:size=" + size + ":rate=30:duration=" + String(PREROLL_TOTAL_DURATION),
+        "-f", "lavfi", "-i", "anullsrc=r=48000:cl=stereo",
+        "-t", String(PREROLL_TOTAL_DURATION),
+        "-c:v", "libx264", "-preset", "slow", "-tune", "stillimage", "-profile:v", "baseline", "-level", "3.1", "-pix_fmt", "yuv420p",
+        "-crf", "18",
+        "-g", "60",
+        "-c:a", "aac", "-b:a", "128000",
+        "-f", "mp4",
+        "-movflags", "frag_keyframe+empty_moov+default_base_moof+skip_sidx+skip_trailer",
+        "-flush_packets", "1",
+        "pipe:1"
+    ];
+    try {
+        const output = await spawnAndCollect(ffmpegPath, args);
+        splitPrerollBuffers(output);
+        const init = prerollInitSegment;
+        if (init && (prerollMediaSegments.length > 0)) {
+            const totalSize = prerollMediaSegments.reduce((sum, seg) => sum + seg.length, 0);
+            LOG.debug("streaming:preroll", "Preroll ready: %d segments, init=%d bytes, media=%d bytes total.", prerollMediaSegments.length, init.length, totalSize);
+        }
+        else {
+            LOG.warn("Preroll generation produced incomplete output — startup playlists will have no segments.");
+            return;
+        }
+    }
+    catch (error) {
+        LOG.warn("Preroll generation failed: %s.", error instanceof Error ? error.message : String(error));
+    }
+}
+// Internal Helpers.
+/**
+ * Spawns FFmpeg with the given arguments and collects all stdout output into a single Buffer. Used for one-shot operations like preroll generation where the entire
+ * output fits in memory.
+ * @param ffmpegBin - Path to the FFmpeg executable.
+ * @param args - FFmpeg command-line arguments.
+ * @returns Promise resolving to the complete stdout output as a Buffer.
+ */
+async function spawnAndCollect(ffmpegBin, args) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        const ffmpeg = spawn(ffmpegBin, args, { stdio: ["ignore", "pipe", "pipe"] });
+        ffmpeg.stdout.on("data", (chunk) => {
+            chunks.push(chunk);
+        });
+        ffmpeg.stderr.on("data", (data) => {
+            const message = data.toString().trim();
+            if (message.length > 0) {
+                LOG.debug("streaming:preroll", "FFmpeg: %s", message);
+            }
+        });
+        ffmpeg.on("error", (error) => {
+            reject(error);
+        });
+        ffmpeg.on("exit", (code) => {
+            if (code !== 0) {
+                reject(new Error("FFmpeg exited with code " + String(code) + "."));
+                return;
+            }
+            resolve(Buffer.concat(chunks));
+        });
+    });
+}
+/**
+ * Splits an fMP4 buffer into an init segment (ftyp + moov) and individual media segments (moof + mdat pairs) using the MP4 box parser. The init segment contains codec
+ * configuration needed by the HLS client to initialize its decoder. Each moof+mdat pair becomes a distinct segment buffer with naturally monotonic PTS timestamps.
+ *
+ * Duration extraction: the moov box is parsed with parseMoovTrackInfo() to get per-track timescales. Each moof is then parsed with offsetMoofTimestamps() (with an
+ * empty offset map for pure pass-through) to extract per-track trun durations. The maximum duration across tracks (converted to seconds via timescale) becomes the
+ * segment's EXTINF duration.
+ *
+ * @param data - The complete fMP4 output from FFmpeg.
+ */
+function splitPrerollBuffers(data) {
+    const initBoxes = [];
+    let moovBox = null;
+    // Accumulator for the current moof+mdat pair. A segment is finalized when the mdat following a moof arrives.
+    let pendingMoof = null;
+    const parser = createMP4BoxParser((box) => {
+        if ((box.type === "ftyp") || (box.type === "moov")) {
+            initBoxes.push(box.data);
+            if (box.type === "moov") {
+                moovBox = box.data;
+            }
+        }
+        else if (box.type === "moof") {
+            // Start a new segment. If there's an orphaned moof without a following mdat (shouldn't happen with well-formed fMP4), it gets overwritten.
+            pendingMoof = box.data;
+        }
+        else if (box.type === "mdat") {
+            // Finalize the current segment by combining the pending moof with this mdat.
+            if (pendingMoof) {
+                prerollMediaSegments.push(Buffer.concat([pendingMoof, box.data]));
+                pendingMoof = null;
+            }
+        }
+    });
+    parser.push(data);
+    parser.flush();
+    if (initBoxes.length > 0) {
+        prerollInitSegment = Buffer.concat(initBoxes);
+    }
+    // Extract per-segment durations from the moov timescales and moof trun sample durations. The moov provides the timescale for converting raw sample durations to
+    // seconds. Each moof's traf/trun boxes contain the accumulated sample durations for that fragment.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- moovBox is set inside the parser callback; TS can't track closure mutations.
+    if (moovBox && (prerollMediaSegments.length > 0)) {
+        const trackInfoMap = parseMoovTrackInfo(moovBox);
+        // Build a timescale lookup from trackId to timescale.
+        const timescales = new Map();
+        for (const [trackId, info] of trackInfoMap) {
+            timescales.set(trackId, info.timescale);
+        }
+        // Extract duration from each segment's moof box. The offsetMoofTimestamps function with an empty offset map acts as a pure reader — it returns per-track
+        // durations without modifying the buffer (it writes back the same tfdt values it read since the offset is 0). A fresh map is created per segment to prevent
+        // state accumulation across iterations.
+        for (const segment of prerollMediaSegments) {
+            // The segment buffer is moof+mdat concatenated. The moof is the first box — parse it to find its size.
+            if (segment.length < 8) {
+                prerollSegmentDurations.push(2);
+                continue;
+            }
+            const moofSize = segment.readUInt32BE(0);
+            const moofData = segment.subarray(0, moofSize);
+            // Extract per-track durations from the moof. Take the maximum across tracks and convert to seconds.
+            const trackResults = offsetMoofTimestamps(moofData, new Map());
+            let maxDurationSec = 0;
+            for (const [trackId, result] of trackResults) {
+                const timescale = timescales.get(trackId);
+                if (timescale && (result.duration > 0n)) {
+                    const seconds = Number(result.duration) / timescale;
+                    if (seconds > maxDurationSec) {
+                        maxDurationSec = seconds;
+                    }
+                }
+            }
+            // Fall back to 2 seconds if duration extraction failed (shouldn't happen with well-formed FFmpeg output).
+            prerollSegmentDurations.push(maxDurationSec > 0 ? maxDurationSec : 2);
+        }
+    }
+}
+// Preroll Compositor.
+// Maximum number of preroll entries allowed in a composite playlist window. When the composite playlist first appears, the client may be mid-stream in the progressive
+// preroll playlist at a low segment index. Limiting preroll entries forces MEDIA-SEQUENCE past the client's current position, causing it to seek forward to near the
+// live edge rather than playing through many seconds of remaining preroll before reaching real content.
+const MAX_PREROLL_IN_WINDOW = 3;
+/**
+ * Computes the sliding window start index for a composite playlist containing both preroll and real segments. The start index is determined by three constraints:
+ * (1) never negative, (2) the standard sliding window rule (current index minus window size), and (3) the preroll cap that limits how many preroll entries appear in
+ * the window. The third constraint is the key addition — it prevents clients from playing through many seconds of remaining preroll before reaching live content.
+ *
+ * @param options - Window computation parameters.
+ * @returns The start index for the composite playlist window.
+ */
+export function computePrerollWindow(options) {
+    const totalAvailable = options.prerollSegmentCount + options.realSegmentCount;
+    const windowSize = Math.min(totalAvailable, options.maxSegments);
+    return Math.max(0, options.currentSegmentIndex - windowSize, options.prerollSegmentCount - MAX_PREROLL_IN_WINDOW);
+}
+/**
+ * Builds an array of playlist segment entries for preroll segments within the given index range. Each entry has an absolute URL pointing to the global /preroll/ route
+ * and the duration extracted from the preroll segment cache. No per-segment metadata tags (DISCONTINUITY, PROGRAM-DATE-TIME, etc.) are set — preroll is synthetic
+ * placeholder content.
+ *
+ * @param options - Entry construction parameters.
+ * @returns Ordered array of preroll segment entries for the builder.
+ */
+export function buildPrerollEntries(options) {
+    const entries = [];
+    for (let i = options.startIndex; i < options.prerollSegmentCount; i++) {
+        entries.push({
+            duration: getPrerollSegmentDuration(i),
+            url: options.baseUrl + "/preroll/segment" + String(i) + options.extension
+        });
+    }
+    return entries;
+}
+/**
+ * Computes how many preroll segments should be visible based on elapsed wall-clock time since the preroll started. The initial window (PREROLL_INITIAL_WINDOW segments)
+ * is revealed immediately so the client has enough content to begin playback per the HLS 3-from-end rule. Additional segments are revealed one at a time as wall-clock
+ * time passes — each new segment appears when enough time has elapsed for the client to have consumed the prior content beyond the initial window.
+ *
+ * @param prerollStartTime - Wall-clock time when the preroll began.
+ * @returns The number of preroll segments to reveal.
+ */
+export function computeProgressiveReveal(prerollStartTime) {
+    const totalSegments = prerollMediaSegments.length;
+    const elapsedSec = (Date.now() - prerollStartTime.getTime()) / 1000;
+    let revealCount = Math.min(PREROLL_INITIAL_WINDOW, totalSegments);
+    // Compute the total duration of the initial window. Segments beyond this threshold are revealed progressively — each one becomes visible when elapsed time
+    // exceeds the cumulative duration of all segments before it, minus the initial window's duration (since those were available from the start).
+    let initialWindowDuration = 0;
+    for (let i = 0; i < Math.min(PREROLL_INITIAL_WINDOW, totalSegments); i++) {
+        initialWindowDuration += prerollSegmentDurations[i] ?? 2;
+    }
+    let cumulativeDuration = initialWindowDuration;
+    for (let i = PREROLL_INITIAL_WINDOW; i < totalSegments; i++) {
+        cumulativeDuration += prerollSegmentDurations[i] ?? 2;
+        if (elapsedSec < (cumulativeDuration - initialWindowDuration)) {
+            break;
+        }
+        revealCount = i + 1;
+    }
+    return revealCount;
+}
+// Playlist Generation.
+/**
+ * Generates a progressive HLS playlist referencing the global preroll segments. The playlist simulates a live stream by revealing segments based on elapsed wall-clock
+ * time since the preroll started. On each client poll, more segments become visible — the client sees new content appear and keeps playing without stalling.
+ *
+ * The playlist uses absolute URLs because preroll segments are served at global routes (/preroll/*) while the playlist itself is served under /hls/:name/. Without
+ * absolute URLs, the client would request /hls/:name/preroll/segment0.m4s which does not exist. The playlist omits #EXT-X-ENDLIST so it behaves as a live playlist —
+ * the client polls for updates and receives the real content playlist when ready.
+ *
+ * PROGRAM-DATE-TIME is intentionally omitted from the preroll playlist. Preroll is synthetic placeholder content — assigning it wall-clock timestamps would be
+ * misleading and would create a backward time jump at the preroll-to-live boundary (preroll PDT would overshoot real content PDT because the preroll covers 30
+ * seconds of content but real content typically arrives in ~15 seconds). PDT is emitted only on real segments once the segmenter produces them.
+ *
+ * @param baseUrl - The server's external URL (e.g., "http://192.168.1.100:5589").
+ * @param startingSequence - The MEDIA-SEQUENCE offset. Zero for fresh starts. For resume streams, this is set to the saved segment index so the preroll
+ *   playlist continues from the prior session's sequence range rather than restarting at 0.
+ * @param prerollStartTime - Wall-clock time when the preroll began. Used to compute elapsed time and determine how many segments to reveal.
+ * @returns The complete HLS playlist string, or an empty string if the preroll is not ready.
+ */
+export function generatePrerollPlaylist(baseUrl, startingSequence, prerollStartTime) {
+    if (!isPrerollReady()) {
+        return "";
+    }
+    const revealCount = computeProgressiveReveal(prerollStartTime);
+    const entries = buildPrerollEntries({ baseUrl, extension: ".m4s", prerollSegmentCount: revealCount, startIndex: 0 });
+    return buildPlaylist({
+        initialMapUri: baseUrl + "/preroll/init.mp4",
+        mediaSequence: startingSequence,
+        targetDuration: getPrerollMaxDuration(),
+        version: 7
+    }, entries);
+}
+// Route Setup.
+/**
+ * Registers the preroll segment routes on the Express application. These serve the cached preroll buffers with immutable cache headers since the content never
+ * changes after generation.
+ * @param app - The Express application.
+ */
+export function setupPrerollRoutes(app) {
+    app.get("/preroll/init.mp4", (_req, res) => {
+        if (!prerollInitSegment) {
+            res.status(404).send("Preroll not available.");
+            return;
+        }
+        res.setHeader("Cache-Control", "public, max-age=86400");
+        res.setHeader("Content-Type", "video/mp4");
+        res.send(prerollInitSegment);
+    });
+    // Parameterized route serves individual preroll segment buffers. Each segment contains a distinct moof+mdat pair with unique PTS values from the continuous FFmpeg
+    // output. The init.mp4 exact route above takes priority over this catch-all for init segment requests.
+    app.get("/preroll/:segment", (req, res) => {
+        // Extract the segment index from the filename (e.g., "segment5.m4s" → 5).
+        const segmentParam = req.params.segment;
+        const match = (typeof segmentParam === "string") ? /^segment(\d+)\.m4s$/.exec(segmentParam) : null;
+        if (!match) {
+            res.status(404).send("Preroll not available.");
+            return;
+        }
+        const index = parseInt(match[1], 10);
+        if ((index < 0) || (index >= prerollMediaSegments.length)) {
+            res.status(404).send("Preroll segment not found.");
+            return;
+        }
+        res.setHeader("Cache-Control", "public, max-age=86400");
+        res.setHeader("Content-Type", "video/mp4");
+        res.send(prerollMediaSegments[index]);
+    });
+}
+//# sourceMappingURL=preroll.js.map

package/dist/streaming/preroll.js.map

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

package/dist/streaming/pretune.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Starts the pretune polling loop. Should be called on server startup after show info polling is initialized.
+ */
+export declare function startPretunePolling(): void;
+/**
+ * Stops the pretune polling loop and clears all pending timers. Should be called on server shutdown.
+ */
+export declare function stopPretunePolling(): void;

package/dist/streaming/pretune.js

@@ -0,0 +1,226 @@
+/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * pretune.ts: Predictive channel pretuning from Channels DVR schedule.
+ */
+import { LOG, delay, formatError } from "../utils/index.js";
+import { fetchFromDvr, getDeviceMappings, getDvrHost } from "./showInfo.js";
+import { getChannelStreamId, terminateStream } from "./lifecycle.js";
+import { initializeStream, validateChannel } from "./hls.js";
+import { emitCurrentSystemStatus } from "../browser/index.js";
+import { getStream } from "./registry.js";
+/* This module polls the Channels DVR schedule API to discover upcoming recordings and pretunes channels 30 seconds before they start. When the DVR requests the
+ * stream, it's already live with buffered segments — achieving near-instant tuning instead of 3-7 second cold starts.
+ *
+ * The polling loop runs every 60 seconds, checking for jobs starting within a 5-minute scheduling horizon. For each eligible job (PrismCast channel as the DVR's
+ * preferred source), a precise setTimeout is scheduled for 30 seconds before the recording start time. When the timer fires, the module validates the channel,
+ * checks for conflicts, and calls initializeStream() with the preTuned flag. A safety timeout tears down unclaimed streams 90 seconds after the scheduled start.
+ *
+ * Key design decisions:
+ * - Only pretune when a PrismCast guide number is the FIRST entry in the job's channels array (DVR's preferred source).
+ * - Skip channels that are already streaming — no duplicate streams for the same channel.
+ * - Pretune alongside existing streams freely; capacity enforcement is handled by initializeStream().
+ * - Retry up to 5 times within the pretune window on failure.
+ * - Safety timeout at start_time + 90s handles cancelled jobs or missed client connections.
+ */
+// Constants.
+// How often to poll for upcoming jobs (60 seconds).
+const POLL_INTERVAL_MS = 60000;
+// How far ahead to look for upcoming jobs (5 minutes).
+const SCHEDULING_HORIZON_MS = 300000;
+// How far before the recording start to begin pretuning (30 seconds).
+const PRETUNE_LEAD_MS = 30000;
+// Safety timeout for unclaimed pretuned streams (90 seconds past scheduled start).
+const SAFETY_TIMEOUT_MS = 90000;
+// Maximum retry attempts for failed pretune.
+const MAX_RETRIES = 5;
+// Delay between retry attempts (5 seconds).
+const RETRY_DELAY_MS = 5000;
+// State.
+// Interval handle for periodic job polling.
+let pollInterval = null;
+// Active pretune timers keyed by job ID. Used to avoid duplicate scheduling and to clear timers when jobs disappear.
+const activeTimers = new Map();
+// Safety timers keyed by stream ID. Used to tear down unclaimed pretuned streams after the scheduled start time.
+const safetyTimers = new Map();
+// Public API.
+/**
+ * Starts the pretune polling loop. Should be called on server startup after show info polling is initialized.
+ */
+export function startPretunePolling() {
+    if (pollInterval) {
+        return;
+    }
+    // Run the first poll after a short delay to allow the persisted DVR host to load.
+    setTimeout(() => {
+        void pollForUpcomingJobs();
+    }, 5000);
+    pollInterval = setInterval(() => {
+        void pollForUpcomingJobs();
+    }, POLL_INTERVAL_MS);
+}
+/**
+ * Stops the pretune polling loop and clears all pending timers. Should be called on server shutdown.
+ */
+export function stopPretunePolling() {
+    if (pollInterval) {
+        clearInterval(pollInterval);
+        pollInterval = null;
+    }
+    // Clear all pending pretune timers.
+    for (const timer of activeTimers.values()) {
+        clearTimeout(timer);
+    }
+    activeTimers.clear();
+    // Clear all safety timers.
+    for (const timer of safetyTimers.values()) {
+        clearTimeout(timer);
+    }
+    safetyTimers.clear();
+}
+// Internal Functions.
+/**
+ * Polls the Channels DVR API for upcoming scheduled recordings and schedules pretune timers for eligible jobs.
+ */
+async function pollForUpcomingJobs() {
+    const host = getDvrHost();
+    if (!host) {
+        return;
+    }
+    const jobs = await fetchFromDvr(host, "/api/v1/jobs");
+    if (jobs.length === 0) {
+        return;
+    }
+    const now = Date.now();
+    const horizon = now + SCHEDULING_HORIZON_MS;
+    // Track which job IDs we see this poll cycle so we can clear timers for removed jobs.
+    const seenJobIds = new Set();
+    // Get the device mappings once for resolving guide numbers. The cache ensures this is fast on repeated calls.
+    const mappings = await getDeviceMappings(host);
+    if (mappings.size === 0) {
+        return;
+    }
+    for (const job of jobs) {
+        // Skip cancelled or skipped jobs.
+        if (job.item.cancelled || job.skipped) {
+            continue;
+        }
+        const startMs = job.start_time * 1000;
+        // Skip jobs outside our scheduling horizon or already started.
+        if ((startMs > horizon) || (startMs <= now)) {
+            continue;
+        }
+        // Only consider jobs where the first (preferred) channel is a PrismCast channel.
+        if (job.channels.length === 0) {
+            continue;
+        }
+        const guideNumber = job.channels[0];
+        const channelId = resolveGuideNumber(mappings, guideNumber);
+        if (!channelId) {
+            continue;
+        }
+        seenJobIds.add(job.id);
+        // Skip if a timer is already scheduled for this job.
+        if (activeTimers.has(job.id)) {
+            continue;
+        }
+        // Calculate when to pretune. If the pretune time has already passed but the start time hasn't, pretune immediately.
+        const pretuneTime = startMs - PRETUNE_LEAD_MS;
+        const effectiveDelay = Math.max(0, pretuneTime - now);
+        LOG.debug("streaming:pretune", "Scheduling pretune for '%s' (%s) in %ds.", job.name, channelId, Math.round(effectiveDelay / 1000));
+        const timer = setTimeout(() => {
+            activeTimers.delete(job.id);
+            void pretuneChannel(channelId, job.name, startMs);
+        }, effectiveDelay);
+        activeTimers.set(job.id, timer);
+    }
+    // Clear timers for jobs that disappeared from the API (cancelled, rescheduled, or moved outside the horizon).
+    for (const [jobId, timer] of activeTimers) {
+        if (!seenJobIds.has(jobId)) {
+            clearTimeout(timer);
+            activeTimers.delete(jobId);
+            LOG.debug("streaming:pretune", "Cleared timer for removed job %s.", jobId);
+        }
+    }
+}
+/**
+ * Resolves a DVR guide number to a PrismCast channel ID by checking all device mappings.
+ * @param mappings - Map of DeviceID to (Map of GuideNumber to channel ID).
+ * @param guideNumber - The guide number to resolve (e.g., "7220").
+ * @returns The PrismCast channel ID if the guide number maps to a PrismCast channel, undefined otherwise.
+ */
+function resolveGuideNumber(mappings, guideNumber) {
+    for (const deviceMappings of mappings.values()) {
+        const channelId = deviceMappings.get(guideNumber);
+        if (channelId) {
+            return channelId;
+        }
+    }
+    return undefined;
+}
+/**
+ * Pretunes a channel ahead of a scheduled recording. Validates the channel, checks for conflicts, initializes the stream with the preTuned flag, and sets up a
+ * safety timeout for unclaimed streams. Retries on failure up to MAX_RETRIES times within the pretune window.
+ * @param channelId - The PrismCast channel key (e.g., "cnn").
+ * @param jobName - The program title for logging (e.g., "Anderson Cooper 360").
+ * @param startTimeMs - The recording start time in milliseconds.
+ */
+async function pretuneChannel(channelId, jobName, startTimeMs) {
+    // Check if the channel is already streaming.
+    const existingStreamId = getChannelStreamId(channelId);
+    if (existingStreamId !== undefined) {
+        return;
+    }
+    // Validate the channel.
+    const validation = validateChannel(channelId);
+    if (!validation.valid) {
+        LOG.debug("streaming:pretune", "Pretune validation failed for %s: %s.", channelId, typeof validation.body === "string" ? validation.body : "validation error");
+        return;
+    }
+    const displayName = validation.channel.name ?? channelId;
+    let attempts = 0;
+    while (attempts < MAX_RETRIES) {
+        attempts++;
+        try {
+            // eslint-disable-next-line no-await-in-loop
+            const streamId = await initializeStream({
+                channel: validation.channel,
+                channelName: channelId,
+                clientAddress: null,
+                preTuned: true,
+                url: validation.channel.url
+            });
+            if (streamId !== null) {
+                const leadSeconds = Math.round((startTimeMs - Date.now()) / 1000);
+                LOG.info("Pretuned %s for %s (starts in %ds).", displayName, jobName, leadSeconds);
+                // Set a safety timeout to tear down the stream if no real client connects within 90 seconds of the scheduled start.
+                const safetyDelay = Math.max(0, (startTimeMs + SAFETY_TIMEOUT_MS) - Date.now());
+                const safetyTimer = setTimeout(() => {
+                    safetyTimers.delete(streamId);
+                    const stream = getStream(streamId);
+                    if (stream?.preTuned) {
+                        LOG.info("No client connected for pretuned %s. Ending stream.", displayName);
+                        terminateStream(streamId, channelId, "pretune safety timeout");
+                        void emitCurrentSystemStatus();
+                    }
+                }, safetyDelay);
+                safetyTimers.set(streamId, safetyTimer);
+                return;
+            }
+        }
+        catch (error) {
+            LOG.warn("Pretune attempt %d/%d failed for %s: %s.", attempts, MAX_RETRIES, displayName, formatError(error));
+        }
+        // Stop retrying if we're past the scheduled start time.
+        if (Date.now() >= startTimeMs) {
+            LOG.debug("streaming:pretune", "Past start time for %s. Stopping pretune attempts.", channelId);
+            return;
+        }
+        // Brief delay before retry.
+        if (attempts < MAX_RETRIES) {
+            // eslint-disable-next-line no-await-in-loop
+            await delay(RETRY_DELAY_MS);
+        }
+    }
+    LOG.warn("All %d pretune attempts failed for %s.", MAX_RETRIES, displayName);
+}
+//# sourceMappingURL=pretune.js.map

package/dist/streaming/pretune.js.map

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