streamer-node 1.0.31 → 1.0.37

package/dist/src/infrastructure/services/AdRotator.js

@@ -0,0 +1,223 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdRotationRegistry = exports.AdRotator = void 0;
+const fs = __importStar(require("fs"));
+/**
+ * Rotates a pool of N normalized still ads through two on-screen slots
+ * (left/right) while the stream stays live. Each slot advances independently on
+ * its own timer; the two slots never show the same ad at once; the pool is
+ * reshuffled each time it is fully consumed.
+ *
+ * Mechanism: the running ffmpeg reads two fixed PNG files (the slot files) via
+ * `-f image2 -loop 1`, re-reading them on every loop. To change a slot we simply
+ * overwrite its file (atomically, via temp + rename). The ffmpeg process never
+ * restarts.
+ */
+class AdRotator {
+    constructor(courtId, pool, slotLeftPath, slotRightPath, options, logger) {
+        this.courtId = courtId;
+        this.pool = pool;
+        this.slotLeftPath = slotLeftPath;
+        this.slotRightPath = slotRightPath;
+        this.options = options;
+        this.logger = logger;
+        this.queue = [];
+        this.cursor = 0;
+        this.left = { poolIndex: -1, timer: null };
+        this.right = { poolIndex: -1, timer: null };
+        this.stopped = false;
+    }
+    /**
+     * Seed the initial slot files. MUST run before ffmpeg starts so the slot
+     * inputs exist. Clears any stale slot files first, so an empty pool leaves no
+     * slot files behind (ffmpeg then adds no ad inputs).
+     */
+    prepare() {
+        this.removeSlotFiles();
+        if (this.pool.length === 0) {
+            return;
+        }
+        this.reshuffle();
+        this.cursor = 0;
+        this.left.poolIndex = this.next(-1);
+        this.writeSlot(this.slotLeftPath, this.pool[this.left.poolIndex]);
+        if (this.pool.length >= 2) {
+            this.right.poolIndex = this.next(this.left.poolIndex);
+            this.writeSlot(this.slotRightPath, this.pool[this.right.poolIndex]);
+        }
+    }
+    /**
+     * Begin rotation. Call after ffmpeg has started. With fewer than two ads there
+     * is nothing to rotate, so the seeded slot(s) simply stay put.
+     */
+    start() {
+        if (this.stopped || this.pool.length < 2) {
+            return;
+        }
+        this.logger.info("Starting ad rotation", {
+            courtId: this.courtId,
+            poolSize: this.pool.length,
+        });
+        // Left rotates after a full duration; right is offset by half its duration
+        // so the two slots never swap on the same tick.
+        this.scheduleSlot(this.left, this.slotLeftPath, this.right);
+        this.right.timer = setTimeout(() => {
+            if (this.stopped)
+                return;
+            this.right.poolIndex = this.next(this.left.poolIndex);
+            this.writeSlot(this.slotRightPath, this.pool[this.right.poolIndex]);
+            this.scheduleSlot(this.right, this.slotRightPath, this.left);
+        }, Math.floor(this.durationMs(this.right.poolIndex) / 2));
+    }
+    /** Stop all timers. Idempotent. Safe to call from teardown/retry/shutdown. */
+    stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        if (this.left.timer)
+            clearTimeout(this.left.timer);
+        if (this.right.timer)
+            clearTimeout(this.right.timer);
+        this.left.timer = null;
+        this.right.timer = null;
+        this.logger.info("Stopped ad rotation", { courtId: this.courtId });
+    }
+    scheduleSlot(slot, slotPath, otherSlot) {
+        if (this.stopped)
+            return;
+        slot.timer = setTimeout(() => {
+            if (this.stopped)
+                return;
+            slot.poolIndex = this.next(otherSlot.poolIndex);
+            this.writeSlot(slotPath, this.pool[slot.poolIndex]);
+            this.scheduleSlot(slot, slotPath, otherSlot);
+        }, this.durationMs(slot.poolIndex));
+    }
+    // Advance the cursor and return the next pool index, skipping the ad currently
+    // shown in the other slot (so both slots never show the same ad). Reshuffles
+    // when a full cycle has been consumed.
+    next(skipPoolIndex) {
+        const maxAttempts = this.queue.length + 1;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            if (this.cursor >= this.queue.length) {
+                this.reshuffle();
+                this.cursor = 0;
+            }
+            const idx = this.queue[this.cursor++];
+            // With a pool of <2 the skip cannot be honoured; allow the duplicate.
+            if (idx !== skipPoolIndex || this.pool.length < 2) {
+                return idx;
+            }
+        }
+        return (this.queue.find((i) => i !== skipPoolIndex) ?? this.queue[0]) ?? 0;
+    }
+    // Resolve the slot duration: payload value when valid, else the configured
+    // default, clamped to [min, max] to avoid file-swap thrash / runaway values.
+    durationMs(poolIndex) {
+        const raw = this.pool[poolIndex]?.durationSec;
+        let sec = typeof raw === "number" && isFinite(raw) && raw > 0
+            ? raw
+            : this.options.defaultDurationSec;
+        sec = Math.max(this.options.minDurationSec, Math.min(this.options.maxDurationSec, sec));
+        return sec * 1000;
+    }
+    // Atomically replace a slot file so ffmpeg never reads a half-written PNG.
+    writeSlot(slotPath, ad) {
+        try {
+            const tmp = `${slotPath}.tmp`;
+            fs.copyFileSync(ad.pngPath, tmp);
+            fs.renameSync(tmp, slotPath);
+        }
+        catch (error) {
+            this.logger.warn("Failed to write ad slot", {
+                courtId: this.courtId,
+                slotPath,
+                source: ad.pngPath,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    removeSlotFiles() {
+        for (const p of [this.slotLeftPath, this.slotRightPath]) {
+            try {
+                if (fs.existsSync(p))
+                    fs.unlinkSync(p);
+            }
+            catch {
+                // ignore — a stale slot file we can't remove will simply be overwritten
+            }
+        }
+    }
+    // Fisher–Yates shuffle of [0..pool.length-1].
+    reshuffle() {
+        const arr = Array.from({ length: this.pool.length }, (_, i) => i);
+        for (let i = arr.length - 1; i > 0; i--) {
+            const j = Math.floor(Math.random() * (i + 1));
+            [arr[i], arr[j]] = [arr[j], arr[i]];
+        }
+        this.queue = arr;
+    }
+}
+exports.AdRotator = AdRotator;
+/**
+ * Tracks the live AdRotator per court so its timers can be torn down when the
+ * stream stops, retries, fails, or the app shuts down. A leaked rotator would
+ * keep overwriting slot files for a dead stream.
+ */
+class AdRotationRegistry {
+    constructor() {
+        this.rotators = new Map();
+    }
+    set(courtId, rotator) {
+        this.stop(courtId);
+        this.rotators.set(courtId, rotator);
+    }
+    stop(courtId) {
+        const rotator = this.rotators.get(courtId);
+        if (rotator) {
+            rotator.stop();
+            this.rotators.delete(courtId);
+        }
+    }
+    stopAll() {
+        for (const rotator of this.rotators.values()) {
+            rotator.stop();
+        }
+        this.rotators.clear();
+    }
+}
+exports.AdRotationRegistry = AdRotationRegistry;
+//# sourceMappingURL=AdRotator.js.map

package/dist/src/infrastructure/services/AdRotator.js.map

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

package/dist/src/infrastructure/services/HighlightBufferManager.d.ts

@@ -0,0 +1,65 @@
+import { Logger } from "../../application/interfaces/Logger";
+/**
+ * Bookkeeping for one court's rolling highlight buffer: prunes aged segments
+ * and answers "which segment files cover this time window?".
+ *
+ * ── IN SIMPLE WORDS ──
+ * ffmpeg (the live process) writes short video chunks into a folder forever.
+ * This class is the janitor + index for that folder: every few seconds it
+ * deletes chunks older than the retention window (so the disk can't fill), and
+ * on demand it can list the chunks that overlap a requested time span (used
+ * later to cut a highlight clip). It runs NO process of its own — the recording
+ * is a second output of the live ffmpeg; this is pure filesystem bookkeeping.
+ *
+ * ── BUSINESS RULES ──
+ * - Retention: a chunk is kept only while newer than `retentionSec`. That value
+ *   is sized (Config) to exceed the full highlight window (pre + post + lag),
+ *   so pruning can never delete footage a pending extraction still needs.
+ * - A chunk's start time is read from its filename: the ffmpeg segment muxer
+ *   writes `seg-<runToken>-<epochSeconds>.ts` (`-strftime 1`, `%s`), so the
+ *   manifest is reconstructable from disk alone — no separate state to persist
+ *   or keep in sync, and it survives a restart.
+ *
+ * ── WHY IT'S BUILT THIS WAY (change at your peril) ──
+ * - The sweep is best-effort and NEVER throws: a cleanup failure must not crash
+ *   the app or disturb the live stream. Errors are logged and the next tick
+ *   retries.
+ * - Segment END time is start + `segmentSec`; retention/overlap compare against
+ *   END so a chunk is only dropped once its last frame is older than retention.
+ *
+ * ── DO NOT ──
+ * - Do NOT lower `retentionSec` below the extraction window, or a highlight
+ *   fired near the retention edge will have its oldest needed chunk already
+ *   deleted.
+ * - Do NOT assume `getSegmentsInWindow` returns a value — it returns null when
+ *   the buffer lacks the requested leading history (callers must handle it).
+ */
+export interface SegmentRecord {
+    path: string;
+    startMs: number;
+    endMs: number;
+}
+export declare class HighlightBufferManager {
+    private readonly courtId;
+    private readonly bufferDir;
+    private readonly segmentSec;
+    private readonly retentionSec;
+    private readonly logger;
+    private sweepTimer;
+    constructor(courtId: string, bufferDir: string, segmentSec: number, retentionSec: number, logger: Logger);
+    /** Begin the periodic retention sweep. Idempotent. */
+    start(): void;
+    /** Stop the sweep. Idempotent; safe from teardown/retry/shutdown. */
+    stop(): void;
+    /**
+     * Ordered segment records overlapping [startMs, endMs], or null when the
+     * buffer lacks the leading history to cover the window (e.g. the highlight
+     * fired before enough footage was recorded). "Covers the leading edge" means
+     * some segment starts at or before startMs.
+     */
+    getSegmentsInWindow(startMs: number, endMs: number): SegmentRecord[] | null;
+    private sweep;
+    private readSegments;
+    private parseSegmentFile;
+}
+//# sourceMappingURL=HighlightBufferManager.d.ts.map

package/dist/src/infrastructure/services/HighlightBufferManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HighlightBufferManager.d.ts","sourceRoot":"","sources":["../../../../src/infrastructure/services/HighlightBufferManager.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAYD,qBAAa,sBAAsB;IAI/B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAPzB,OAAO,CAAC,UAAU,CAA+B;gBAG9B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM;IAGjC,sDAAsD;IAC/C,KAAK,IAAI,IAAI;IAUpB,qEAAqE;IAC9D,IAAI,IAAI,IAAI;IAUnB;;;;;OAKG;IACI,mBAAmB,CACxB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,aAAa,EAAE,GAAG,IAAI;YAoDX,KAAK;IAsCnB,OAAO,CAAC,YAAY;IAmBpB,OAAO,CAAC,gBAAgB;CAWzB"}

package/dist/src/infrastructure/services/HighlightBufferManager.js

@@ -0,0 +1,203 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HighlightBufferManager = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// Cadence of the retention sweep. Frequent enough that on-disk data never
+// exceeds retention by more than a few seconds; cheap (one readdir + a handful
+// of unlinks over a ~tens-of-files directory).
+const SWEEP_INTERVAL_MS = 5000;
+// Pull the epoch-seconds start time out of `seg-<runToken>-<epoch>.ts`. The
+// trailing `-(digits).ts` is always the timestamp (runToken may itself contain
+// digits, but the epoch is the final hyphen-delimited numeric group).
+const SEGMENT_EPOCH_RE = /-(\d+)\.ts$/;
+class HighlightBufferManager {
+    constructor(courtId, bufferDir, segmentSec, retentionSec, logger) {
+        this.courtId = courtId;
+        this.bufferDir = bufferDir;
+        this.segmentSec = segmentSec;
+        this.retentionSec = retentionSec;
+        this.logger = logger;
+        this.sweepTimer = null;
+    }
+    /** Begin the periodic retention sweep. Idempotent. */
+    start() {
+        if (this.sweepTimer)
+            return;
+        this.logger.info("Highlight buffer manager started", {
+            courtId: this.courtId,
+            bufferDir: this.bufferDir,
+            retentionSec: this.retentionSec,
+        });
+        this.sweepTimer = setInterval(() => void this.sweep(), SWEEP_INTERVAL_MS);
+    }
+    /** Stop the sweep. Idempotent; safe from teardown/retry/shutdown. */
+    stop() {
+        if (this.sweepTimer) {
+            clearInterval(this.sweepTimer);
+            this.sweepTimer = null;
+            this.logger.info("Highlight buffer manager stopped", {
+                courtId: this.courtId,
+            });
+        }
+    }
+    /**
+     * Ordered segment records overlapping [startMs, endMs], or null when the
+     * buffer lacks the leading history to cover the window (e.g. the highlight
+     * fired before enough footage was recorded). "Covers the leading edge" means
+     * some segment starts at or before startMs.
+     */
+    getSegmentsInWindow(startMs, endMs) {
+        const all = this.readSegments();
+        if (all.length === 0)
+            return null;
+        const overlapping = all.filter((s) => s.endMs > startMs && s.startMs < endMs);
+        if (overlapping.length === 0)
+            return null;
+        // Leading edge must be present — we can never recover un-buffered past.
+        if (overlapping[0].startMs > startMs) {
+            this.logger.warn("Highlight window missing leading footage", {
+                courtId: this.courtId,
+                needFromMs: startMs,
+                haveFromMs: overlapping[0].startMs,
+            });
+            return null;
+        }
+        // Trailing edge must be present — otherwise the clip would be silently
+        // short (e.g. the post-roll segment hasn't flushed yet).
+        const last = overlapping[overlapping.length - 1];
+        if (last.endMs < endMs) {
+            this.logger.warn("Highlight window missing trailing footage", {
+                courtId: this.courtId,
+                needToMs: endMs,
+                haveToMs: last.endMs,
+            });
+            return null;
+        }
+        // Segments must be contiguous — a hole would shift all following content in
+        // the concatenated timeline, so the extracted window would capture the
+        // wrong moment. Tolerate sub-second rounding; flag any real gap.
+        const maxJoinGapMs = 1000;
+        for (let i = 1; i < overlapping.length; i++) {
+            if (overlapping[i].startMs - overlapping[i - 1].endMs > maxJoinGapMs) {
+                this.logger.warn("Highlight window has a segment gap; aborting", {
+                    courtId: this.courtId,
+                    gapAfterMs: overlapping[i - 1].endMs,
+                    nextStartMs: overlapping[i].startMs,
+                });
+                return null;
+            }
+        }
+        return overlapping;
+    }
+    // Best-effort deletion of segments whose last frame is older than retention.
+    // Async I/O so the 5s timer never blocks the event loop. Never throws
+    // (fire-and-forget from setInterval).
+    async sweep() {
+        try {
+            const cutoffMs = Date.now() - this.retentionSec * 1000;
+            let files;
+            try {
+                files = await fs.promises.readdir(this.bufferDir);
+            }
+            catch {
+                return; // dir not created yet / transient
+            }
+            let removed = 0;
+            for (const file of files) {
+                const seg = this.parseSegmentFile(file);
+                if (seg && seg.endMs < cutoffMs) {
+                    try {
+                        await fs.promises.unlink(seg.path);
+                        removed++;
+                    }
+                    catch {
+                        /* file may already be gone; ignore */
+                    }
+                }
+            }
+            if (removed > 0) {
+                this.logger.debug("Highlight buffer swept", {
+                    courtId: this.courtId,
+                    removed,
+                });
+            }
+        }
+        catch (error) {
+            this.logger.warn("Highlight buffer sweep failed (non-fatal)", {
+                courtId: this.courtId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    // Parse the buffer directory into sorted segment records from filenames.
+    // Returns [] when the directory doesn't exist yet or has no valid segments.
+    // Synchronous by design: called on-demand (window queries), not on a timer.
+    readSegments() {
+        let files;
+        try {
+            files = fs.readdirSync(this.bufferDir);
+        }
+        catch {
+            return []; // dir not created yet / transient
+        }
+        const records = [];
+        for (const file of files) {
+            const seg = this.parseSegmentFile(file);
+            if (seg)
+                records.push(seg);
+        }
+        records.sort((a, b) => a.startMs - b.startMs);
+        return records;
+    }
+    // Map a filename (`seg-<runToken>-<epoch>.ts`) to a record, or null if it
+    // isn't a recognizable segment. Shared by readSegments and sweep.
+    parseSegmentFile(file) {
+        const match = file.match(SEGMENT_EPOCH_RE);
+        if (!match)
+            return null;
+        const startMs = parseInt(match[1], 10) * 1000;
+        if (!Number.isFinite(startMs))
+            return null;
+        return {
+            path: path.join(this.bufferDir, file),
+            startMs,
+            endMs: startMs + this.segmentSec * 1000,
+        };
+    }
+}
+exports.HighlightBufferManager = HighlightBufferManager;
+//# sourceMappingURL=HighlightBufferManager.js.map

package/dist/src/infrastructure/services/HighlightBufferManager.js.map

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

package/dist/src/infrastructure/services/HighlightBufferRegistry.d.ts

@@ -0,0 +1,23 @@
+import { HighlightBufferManager } from "./HighlightBufferManager";
+/**
+ * Tracks the live HighlightBufferManager per court so its retention sweep is
+ * started on stream start and reliably stopped on stop / retry / shutdown —
+ * mirroring AdRotationRegistry. Without this, a leaked sweep timer would keep
+ * pruning a directory for a stream that no longer exists.
+ *
+ * ── DO NOT ──
+ * - Do NOT leak: every code path that ends a stream (stop use-case, retry,
+ *   killAll/shutdown) must call stop(courtId) or stopAll().
+ */
+export declare class HighlightBufferRegistry {
+    private readonly managers;
+    /** Register a court's manager, replacing (and stopping) any prior one. */
+    set(courtId: string, manager: HighlightBufferManager): void;
+    /** Look up a court's manager (e.g. for window queries during extraction). */
+    get(courtId: string): HighlightBufferManager | undefined;
+    /** Stop and deregister one court's manager. Idempotent. */
+    stop(courtId: string): void;
+    /** Stop and deregister all managers (shutdown / killAll). */
+    stopAll(): void;
+}
+//# sourceMappingURL=HighlightBufferRegistry.d.ts.map

package/dist/src/infrastructure/services/HighlightBufferRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HighlightBufferRegistry.d.ts","sourceRoot":"","sources":["../../../../src/infrastructure/services/HighlightBufferRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAElE;;;;;;;;;GASG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6C;IAEtE,0EAA0E;IAC1E,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,GAAG,IAAI;IAK3D,6EAA6E;IAC7E,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS;IAIxD,2DAA2D;IAC3D,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAQ3B,6DAA6D;IAC7D,OAAO,IAAI,IAAI;CAMhB"}

package/dist/src/infrastructure/services/HighlightBufferRegistry.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HighlightBufferRegistry = void 0;
+/**
+ * Tracks the live HighlightBufferManager per court so its retention sweep is
+ * started on stream start and reliably stopped on stop / retry / shutdown —
+ * mirroring AdRotationRegistry. Without this, a leaked sweep timer would keep
+ * pruning a directory for a stream that no longer exists.
+ *
+ * ── DO NOT ──
+ * - Do NOT leak: every code path that ends a stream (stop use-case, retry,
+ *   killAll/shutdown) must call stop(courtId) or stopAll().
+ */
+class HighlightBufferRegistry {
+    constructor() {
+        this.managers = new Map();
+    }
+    /** Register a court's manager, replacing (and stopping) any prior one. */
+    set(courtId, manager) {
+        this.stop(courtId);
+        this.managers.set(courtId, manager);
+    }
+    /** Look up a court's manager (e.g. for window queries during extraction). */
+    get(courtId) {
+        return this.managers.get(courtId);
+    }
+    /** Stop and deregister one court's manager. Idempotent. */
+    stop(courtId) {
+        const manager = this.managers.get(courtId);
+        if (manager) {
+            manager.stop();
+            this.managers.delete(courtId);
+        }
+    }
+    /** Stop and deregister all managers (shutdown / killAll). */
+    stopAll() {
+        for (const manager of this.managers.values()) {
+            manager.stop();
+        }
+        this.managers.clear();
+    }
+}
+exports.HighlightBufferRegistry = HighlightBufferRegistry;
+//# sourceMappingURL=HighlightBufferRegistry.js.map

package/dist/src/infrastructure/services/HighlightBufferRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HighlightBufferRegistry.js","sourceRoot":"","sources":["../../../../src/infrastructure/services/HighlightBufferRegistry.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;GASG;AACH,MAAa,uBAAuB;IAApC;QACmB,aAAQ,GAAG,IAAI,GAAG,EAAkC,CAAC;IA6BxE,CAAC;IA3BC,0EAA0E;IAC1E,GAAG,CAAC,OAAe,EAAE,OAA+B;QAClD,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACnB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;IAED,6EAA6E;IAC7E,GAAG,CAAC,OAAe;QACjB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IAED,2DAA2D;IAC3D,IAAI,CAAC,OAAe;QAClB,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC3C,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,IAAI,EAAE,CAAC;YACf,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAED,6DAA6D;IAC7D,OAAO;QACL,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;YAC7C,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;CACF;AA9BD,0DA8BC"}

package/dist/src/infrastructure/services/HighlightExtractorService.d.ts

@@ -0,0 +1,65 @@
+import { Logger } from "../../application/interfaces/Logger";
+import { SegmentRecord } from "./HighlightBufferManager";
+/**
+ * Cuts a highlight clip out of the rolling buffer's segment files.
+ *
+ * ── IN SIMPLE WORDS ──
+ * Given the buffered video chunks that overlap a time window, this stitches
+ * them together and trims to exactly the window, producing one clip file. It
+ * runs a one-shot ffmpeg, completely separate from the live stream.
+ *
+ * ── BUSINESS RULES ──
+ * - The clip spans [windowStart, windowEnd]; the trim offset is measured from
+ *   the FIRST overlapping segment's start (which sits at or before windowStart,
+ *   guaranteed by the buffer manifest's leading-edge check).
+ * - The extracted clip is RAW (no logos/crop). Ball-tracking reframe + logo
+ *   overlay (Phase 5) run on this clip afterwards; here we only get the window
+ *   right.
+ *
+ * ── WHY IT'S BUILT THIS WAY (change at your peril) ──
+ * - Output-side `-ss`/`-t` (after `-i`) + a real re-encode gives a
+ *   frame-accurate cut. Stream-copy would snap to the nearest keyframe (up to
+ *   `bufferSegmentSec` off) — unacceptable for a tight highlight window.
+ * - temp-file + atomic rename: a killed/failed ffmpeg never leaves a corrupt
+ *   clip at the final path. Fail-soft: any error returns null (logged), never
+ *   throws into the caller — a failed highlight must not disrupt anything.
+ *
+ * - Segments are HARDLINKED into a private dir before ffmpeg reads them. The
+ *   retention sweeper runs every 5s and this re-encode takes ~30s, so without
+ *   pinning the sweeper deletes segments ffmpeg hasn't reached yet — and
+ *   ffmpeg then TRUNCATES THE OUTPUT AND EXITS 0. That silent success turned a
+ *   30s window into a 9.12s clip while every log line reported normal.
+ *
+ * ── DO NOT ──
+ * - Do NOT assume success — callers must handle a null return.
+ * - Do NOT put the buffer dir and the output dir on different filesystems.
+ *   Hardlinks cannot cross a filesystem boundary, so pinning silently degrades
+ *   to the racy behaviour above (it is logged, but the reels get short again).
+ * - Do NOT treat a zero exit from ffmpeg as "the clip is complete" — compare
+ *   the probed duration against the requested window, which is what the
+ *   shortfall warning below does.
+ */
+export declare class HighlightExtractorService {
+    private readonly outputDir;
+    private readonly logger;
+    private readonly extractTimeoutMs;
+    constructor(outputDir: string, logger: Logger);
+    /**
+     * Concat the overlapping segments and trim to [windowStartMs, windowEndMs].
+     * Returns the written clip path, or null on any failure.
+     */
+    extractWindow(segments: SegmentRecord[], windowStartMs: number, windowEndMs: number, courtId: string): Promise<string | null>;
+    /**
+     * Hardlink each segment into `pinDir` so the retention sweeper cannot delete
+     * the data out from under ffmpeg. Returns the pinned paths, in order.
+     *
+     * A segment that is ALREADY gone is skipped rather than passed through: the
+     * concat demuxer aborts the whole remaining list on a missing file, so
+     * skipping one costs a small jump while passing it through costs everything
+     * after it.
+     */
+    private pinSegments;
+    /** Actual duration of `file` in seconds, or null if it can't be probed. */
+    private probeDurationSec;
+}
+//# sourceMappingURL=HighlightExtractorService.d.ts.map

package/dist/src/infrastructure/services/HighlightExtractorService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HighlightExtractorService.d.ts","sourceRoot":"","sources":["../../../../src/infrastructure/services/HighlightExtractorService.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAKzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,yBAAyB;IAMlC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJzB,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAW;gBAGzB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM;IAGjC;;;OAGG;IACU,aAAa,CACxB,QAAQ,EAAE,aAAa,EAAE,EACzB,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA8GzB;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW;IA8CnB,2EAA2E;IAC3E,OAAO,CAAC,gBAAgB;CAkBzB"}