@xenon-device-management/xenon 1.22.0 → 1.22.2

package/lib/src/services/recording/annotation-render.js

@@ -56,6 +56,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AnnotationRenderService = exports.ANNOTATION_FONT_PATH = void 0;
 exports.escapeFilterValue = escapeFilterValue;
+exports.containBoxPx = containBoxPx;
 const typedi_1 = require("typedi");
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
@@ -64,6 +65,7 @@ const recording_store_1 = require("./recording-store");
 const ffmpegPath_1 = require("../../helpers/ffmpegPath");
 const probeDuration_1 = require("./probeDuration");
 const annotationImage_1 = require("./annotationImage");
+const recordingTiming_1 = require("./recordingTiming");
 const logger_1 = __importDefault(require("../../logger"));
 const renderLog = logger_1.default.scope('AnnotationRender');
 // All ffmpeg spawns go through the bundled binary (resolveFfmpegPath) — a bare
@@ -93,6 +95,17 @@ function escapeFilterValue(value) {
     const forOptions = value.replace(/[\\':]/g, '\\$&');
     return forOptions.replace(/[\\'[\],;]/g, '\\$&');
 }
+/**
+ * Where the composite's `scale=W:H:force_original_aspect_ratio=decrease,
+ * pad=W:H:(ow-iw)/2:(oh-ih)/2` puts a srcW x srcH picture inside a W x H cell.
+ * Measured against the bundled ffmpeg: sizes round to nearest, offsets
+ * truncate (no rounding to even).
+ */
+function containBoxPx(cellW, cellH, srcW, srcH) {
+    const w = Math.min(cellW, Math.round((cellH * srcW) / srcH));
+    const h = Math.min(cellH, Math.round((cellW * srcH) / srcW));
+    return { x: Math.trunc((cellW - w) / 2), y: Math.trunc((cellH - h) / 2), w, h };
+}
 /**
  * Burns annotation metadata into an mp4 (ffmpeg drawbox / drawellipse / lines).
  * Used by the dashboard download paths so "Download video" includes what the
@@ -123,7 +136,10 @@ let AnnotationRenderService = class AnnotationRenderService {
             if (!rec.file_path || !fs.existsSync(rec.file_path)) {
                 throw new Error(`Source video missing for ${recordingId}`);
             }
-            const annotations = ((_a = rec.annotations) !== null && _a !== void 0 ? _a : []);
+            // Timecodes count from the dashboard's t=0; this video may have started
+            // before it (multi-device groups) or after it (added devices). Only the
+            // per-device video needs this: the composite starts at t=0.
+            const annotations = (0, recordingTiming_1.shiftAnnotations)(((_a = rec.annotations) !== null && _a !== void 0 ? _a : []), (0, recordingTiming_1.markShiftMs)((0, recordingTiming_1.readRecordingTiming)(rec.file_path)));
             if (annotations.length === 0) {
                 return { filePath: rec.file_path, annotated: false };
             }
@@ -132,46 +148,98 @@ let AnnotationRenderService = class AnnotationRenderService {
             // Invalidate when source or annotation set changes (annotations land after
             // the mp4 is finalized, so source mtime alone is not enough).
             const stamp = this.cacheStamp(rec.file_path, annotations);
-            let needsRender = true;
+            if (!this.isFresh(outPath, stampPath, stamp)) {
+                yield this.renderCached(outPath, stampPath, stamp, () => this.renderToFile(rec.file_path, outPath, annotations));
+            }
+            return { filePath: outPath, annotated: true };
+        });
+    }
+    /**
+     * The group's composite with every device's marks burned into its own cell.
+     * Raw when the composite has no layout record (recorded before marks could
+     * be placed in it) or no cell has marks.
+     */
+    resolveCompositePath(groupId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            // Lazy: keeps the orchestrator and pipeline graphs out of this module's load.
+            const { compositeOutputPath, compositeLayoutPath } = yield Promise.resolve().then(() => __importStar(require('./RecordingOrchestrator')));
+            const { cellOrigin } = yield Promise.resolve().then(() => __importStar(require('../VideoPipelineService')));
+            const compositePath = compositeOutputPath(groupId);
+            if (!fs.existsSync(compositePath))
+                throw new Error(`Composite missing for ${groupId}`);
+            const raw = { filePath: compositePath, annotated: false };
+            let layout;
             try {
-                if (fs.existsSync(outPath) &&
-                    fs.existsSync(stampPath) &&
-                    fs.readFileSync(stampPath, 'utf8') === stamp) {
-                    needsRender = false;
-                }
+                layout = JSON.parse(fs.readFileSync(compositeLayoutPath(groupId), 'utf8'));
             }
-            catch (_b) {
-                needsRender = true;
+            catch (_c) {
+                return raw;
             }
-            if (needsRender) {
-                yield this.renderCached(outPath, stampPath, stamp, rec.file_path, annotations);
+            const recordings = (yield this.store.listGroup(groupId));
+            const byId = new Map(recordings.map((r) => [r.id, r]));
+            const cells = [];
+            for (const cell of (_a = layout.cells) !== null && _a !== void 0 ? _a : []) {
+                const rec = byId.get(cell.recordingId);
+                const annotations = ((_b = rec === null || rec === void 0 ? void 0 : rec.annotations) !== null && _b !== void 0 ? _b : []);
+                if (!rec || annotations.length === 0)
+                    continue;
+                // The per-device video and the composite read the same source, so its
+                // frame size is the size the composite scaled into this cell.
+                const size = rec.file_path && fs.existsSync(rec.file_path)
+                    ? yield this.probeFrameSize(rec.file_path)
+                    : undefined;
+                const inner = size
+                    ? containBoxPx(layout.cellW, layout.cellH, size.w, size.h)
+                    : { x: 0, y: 0, w: layout.cellW, h: layout.cellH };
+                const origin = cellOrigin(cell.index, layout.cols, layout.cellW, layout.cellH);
+                cells.push({
+                    box: { x: origin.x + inner.x, y: origin.y + inner.y, w: inner.w, h: inner.h },
+                    annotations,
+                    imageFor: (a) => this.imageFor(rec.file_path, a),
+                });
+            }
+            if (cells.length === 0)
+                return raw;
+            const outPath = path.join(path.dirname(compositePath), 'composite.annotated.mp4');
+            const stampPath = `${outPath}.stamp`;
+            const stamp = this.compositeStamp(compositePath, cells);
+            if (!this.isFresh(outPath, stampPath, stamp)) {
+                yield this.renderCached(outPath, stampPath, stamp, () => __awaiter(this, void 0, void 0, function* () {
+                    const durationSec = yield this.probeDurationSec(compositePath);
+                    yield this.renderPlan(compositePath, outPath, (withText) => this.buildCompositeGraph(withText
+                        ? cells
+                        : cells.map((c) => (Object.assign(Object.assign({}, c), { annotations: this.withoutUndrawableText(c.annotations, c.imageFor) }))), durationSec));
+                }));
             }
             return { filePath: outPath, annotated: true };
         });
     }
+    isFresh(outPath, stampPath, stamp) {
+        try {
+            return (fs.existsSync(outPath) &&
+                fs.existsSync(stampPath) &&
+                fs.readFileSync(stampPath, 'utf8') === stamp);
+        }
+        catch (_a) {
+            return false;
+        }
+    }
     /**
      * Render `outPath` at most once across concurrent callers (keyed by outPath).
      * Prevents two `ffmpeg -y` processes from writing the same annotated mp4 while
      * a download streams it — see {@link renderInFlight}.
      */
-    renderCached(outPath, stampPath, stamp, sourcePath, annotations) {
+    renderCached(outPath, stampPath, stamp, render) {
         const existing = this.renderInFlight.get(outPath);
         if (existing)
             return existing;
         const task = (() => __awaiter(this, void 0, void 0, function* () {
             // A render that finished between the caller's cache check and now may have
             // already produced a valid file — re-check before spending another pass.
-            try {
-                if (fs.existsSync(outPath) &&
-                    fs.existsSync(stampPath) &&
-                    fs.readFileSync(stampPath, 'utf8') === stamp) {
-                    return;
-                }
-            }
-            catch (_a) {
-                /* fall through to render */
-            }
-            yield this.renderToFile(sourcePath, outPath, annotations);
+            if (this.isFresh(outPath, stampPath, stamp))
+                return;
+            yield render();
             fs.writeFileSync(stampPath, stamp, 'utf8');
         }))().finally(() => this.renderInFlight.delete(outPath));
         this.renderInFlight.set(outPath, task);
@@ -193,7 +261,14 @@ let AnnotationRenderService = class AnnotationRenderService {
         });
     }
     /** Pure helper — exported for unit tests. */
-    buildFilterParts(annotations, videoDurationSec) {
+    buildFilterParts(annotations, videoDurationSec, 
+    /** Draw inside this pixel box (a composite cell's picture); default: the whole frame. */
+    box) {
+        // Frame-relative expressions by default; absolute pixels inside a box.
+        const X = (v) => (box ? `${Math.round(box.x + v * box.w)}` : `iw*${this.f(v)}`);
+        const Y = (v) => (box ? `${Math.round(box.y + v * box.h)}` : `ih*${this.f(v)}`);
+        const W = (v) => (box ? `${Math.round(v * box.w)}` : `iw*${this.f(v)}`);
+        const H = (v) => (box ? `${Math.round(v * box.h)}` : `ih*${this.f(v)}`);
         const parts = [];
         for (const a of annotations) {
             let g = {};
@@ -218,8 +293,8 @@ let AnnotationRenderService = class AnnotationRenderService {
                 const top = Math.max(0, cy - ry);
                 const bw = Math.min(1, rx * 2);
                 const bh = Math.min(1, ry * 2);
-                parts.push(`drawbox=x=iw*${this.f(left)}:y=ih*${this.f(top)}:w=iw*${this.f(bw)}:h=ih*${this.f(bh)}:color=${color}@0.35:t=fill:${enable}`);
-                parts.push(`drawbox=x=iw*${this.f(left)}:y=ih*${this.f(top)}:w=iw*${this.f(bw)}:h=ih*${this.f(bh)}:color=${color}:t=6:${enable}`);
+                parts.push(`drawbox=x=${X(left)}:y=${Y(top)}:w=${W(bw)}:h=${H(bh)}:color=${color}@0.35:t=fill:${enable}`);
+                parts.push(`drawbox=x=${X(left)}:y=${Y(top)}:w=${W(bw)}:h=${H(bh)}:color=${color}:t=6:${enable}`);
                 continue;
             }
             if (a.shape === 'ARROW') {
@@ -232,9 +307,9 @@ let AnnotationRenderService = class AnnotationRenderService {
                 const top = Math.min(y0, y1);
                 const bw = Math.max(0.01, Math.abs(x1 - x0));
                 const bh = Math.max(0.01, Math.abs(y1 - y0));
-                parts.push(`drawbox=x=iw*${this.f(left)}:y=ih*${this.f(top)}:w=iw*${this.f(bw)}:h=ih*${this.f(bh)}:color=${color}@0.35:t=fill:${enable}`);
-                parts.push(`drawbox=x=iw*${this.f(left)}:y=ih*${this.f(top)}:w=iw*${this.f(bw)}:h=ih*${this.f(bh)}:color=${color}:t=6:${enable}`);
-                parts.push(`drawbox=x=iw*${this.f(x1)}-14:y=ih*${this.f(y1)}-14:w=28:h=28:color=${color}:t=fill:${enable}`);
+                parts.push(`drawbox=x=${X(left)}:y=${Y(top)}:w=${W(bw)}:h=${H(bh)}:color=${color}@0.35:t=fill:${enable}`);
+                parts.push(`drawbox=x=${X(left)}:y=${Y(top)}:w=${W(bw)}:h=${H(bh)}:color=${color}:t=6:${enable}`);
+                parts.push(`drawbox=x=${X(x1)}-14:y=${Y(y1)}-14:w=28:h=28:color=${color}:t=fill:${enable}`);
                 continue;
             }
             if (a.shape === 'TEXT' && a.text) {
@@ -242,15 +317,19 @@ let AnnotationRenderService = class AnnotationRenderService {
                 // explicit font file on this ffmpeg.
                 const font = escapeFilterValue(exports.ANNOTATION_FONT_PATH);
                 const text = escapeFilterValue(String(a.text));
-                parts.push(`drawtext=fontfile=${font}:text=${text}:expansion=none:x=w*${this.f(g.x)}:y=h*${this.f(g.y)}:fontcolor=${color}:fontsize=28:${enable}`);
+                const gx = Number(g.x) || 0;
+                const gy = Number(g.y) || 0;
+                const tx = box ? `x=${X(gx)}` : `x=w*${this.f(gx)}`;
+                const ty = box ? `y=${Y(gy)}` : `y=h*${this.f(gy)}`;
+                parts.push(`drawtext=fontfile=${font}:text=${text}:expansion=none:${tx}:${ty}:fontcolor=${color}:fontsize=28:${enable}`);
                 continue;
             }
             // RECT + FREEHAND (bounding box) — filled wash + thick border so burn-in
             // stays obvious after yuv420 / downscale.
-            const x = `iw*${this.f(g.x)}`;
-            const y = `ih*${this.f(g.y)}`;
-            const w = `iw*${this.f(g.w)}`;
-            const h = `ih*${this.f(g.h)}`;
+            const x = X(Number(g.x) || 0);
+            const y = Y(Number(g.y) || 0);
+            const w = W(Number(g.w) || 0);
+            const h = H(Number(g.h) || 0);
             parts.push(`drawbox=x=${x}:y=${y}:w=${w}:h=${h}:color=${color}@0.35:t=fill:${enable}`);
             parts.push(`drawbox=x=${x}:y=${y}:w=${w}:h=${h}:color=${color}:t=6:${enable}`);
         }
@@ -310,13 +389,23 @@ let AnnotationRenderService = class AnnotationRenderService {
     }
     renderToFile(sourcePath, outPath, annotations) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a;
             // Probe the recorded span so late marks (timecode past EOF) get clamped in
             // instead of vanishing. Best-effort: without a duration the timecodes are
             // used unclamped (prior behavior).
             const durationSec = yield this.probeDurationSec(sourcePath);
             const imageFor = (a) => this.imageFor(sourcePath, a);
-            const plan = this.buildRenderGraph(annotations, durationSec, imageFor);
+            yield this.renderPlan(sourcePath, outPath, (withText) => this.buildRenderGraph(withText ? annotations : this.withoutUndrawableText(annotations, imageFor), durationSec, imageFor));
+        });
+    }
+    /**
+     * Run a graph, or copy the source when there is nothing to draw. If it fails
+     * with text in it, retry once without the text marks: one undrawable text
+     * mark must not cost every other mark.
+     */
+    renderPlan(sourcePath, outPath, build) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const plan = build(true);
             if (!plan) {
                 fs.copyFileSync(sourcePath, outPath);
                 return;
@@ -327,11 +416,8 @@ let AnnotationRenderService = class AnnotationRenderService {
             catch (err) {
                 if (!plan.hasText)
                     throw err;
-                // One undrawable text mark must not cost every other mark: the bundled
-                // ffmpeg has freetype but no fontconfig, so drawtext cannot find a font.
                 renderLog.warn(`Text marks could not be drawn, rendering without them: ${(_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : err}`);
-                const noText = annotations.filter((a) => a.shape !== 'TEXT' || !!imageFor(a));
-                const retry = this.buildRenderGraph(noText, durationSec, imageFor);
+                const retry = build(false);
                 if (!retry) {
                     fs.copyFileSync(sourcePath, outPath);
                     return;
@@ -340,6 +426,52 @@ let AnnotationRenderService = class AnnotationRenderService {
             }
         });
     }
+    withoutUndrawableText(annotations, imageFor) {
+        return annotations.filter((a) => a.shape !== 'TEXT' || !!imageFor(a));
+    }
+    /**
+     * One graph over the whole composite: every cell's box-drawn marks first,
+     * then each image mark scaled to its cell's picture and overlaid there.
+     */
+    buildCompositeGraph(cells, videoDurationSec) {
+        const parts = [];
+        const images = [];
+        for (const cell of cells) {
+            const drawn = [];
+            for (const a of cell.annotations) {
+                const file = cell.imageFor(a);
+                if (!file) {
+                    drawn.push(a);
+                    continue;
+                }
+                const enable = this.enableExpr(a, videoDurationSec);
+                if (enable)
+                    images.push({ file, enable, box: cell.box });
+            }
+            parts.push(...this.buildFilterParts(drawn, videoDurationSec, cell.box));
+        }
+        const hasText = parts.some((p) => p.startsWith('drawtext='));
+        const chunks = [];
+        let cur = '[0:v]';
+        if (parts.length > 0) {
+            chunks.push(`[0:v]${parts.join(',')}[d0]`);
+            cur = '[d0]';
+        }
+        images.forEach(({ enable, box }, i) => {
+            const k = i + 1;
+            chunks.push(`[${k}:v]scale=${box.w}:${box.h}[o${k}]`);
+            chunks.push(`${cur}[o${k}]overlay=${box.x}:${box.y}:${enable}[v${k}]`);
+            cur = `[v${k}]`;
+        });
+        if (cur === '[0:v]')
+            return null;
+        return { inputs: images.map((i) => i.file), graph: chunks.join(';'), output: cur, hasText };
+    }
+    probeFrameSize(filePath) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return (0, probeDuration_1.probeVideoFrameSize)(filePath);
+        });
+    }
     imageFor(sourcePath, a) {
         if (!a.id)
             return undefined;
@@ -449,17 +581,27 @@ let AnnotationRenderService = class AnnotationRenderService {
     }
     cacheStamp(sourcePath, annotations) {
         const srcMtime = fs.statSync(sourcePath).mtimeMs;
-        const parts = annotations.map((a) => {
-            var _a, _b, _c, _d, _e;
-            // A late-arriving image or a later clear must bust the cache.
-            const img = this.imageFor(sourcePath, a);
-            const imgMtime = img ? fs.statSync(img).mtimeMs : 0;
-            return `${(_a = a.id) !== null && _a !== void 0 ? _a : ''}:${(_b = a.timecode_ms) !== null && _b !== void 0 ? _b : 0}:${(_c = a.end_timecode_ms) !== null && _c !== void 0 ? _c : ''}:${a.shape}:${a.geometry}:${(_d = a.color) !== null && _d !== void 0 ? _d : ''}:${(_e = a.text) !== null && _e !== void 0 ? _e : ''}:${imgMtime}`;
-        });
+        const parts = annotations.map((a) => this.markStamp(a, (m) => this.imageFor(sourcePath, m)));
         // Bump prefix when burn-in style changes so cached .annotated.mp4 is rebuilt.
         // v3: time windows + image overlays.
         return `v3|${srcMtime}|${parts.join('|')}`;
     }
+    /** Composite cache stamp: the source, each cell's box, and every mark in it. */
+    compositeStamp(compositePath, cells) {
+        const srcMtime = fs.statSync(compositePath).mtimeMs;
+        const perCell = cells.map((c) => {
+            const b = `${c.box.x},${c.box.y},${c.box.w},${c.box.h}`;
+            return `${b}|${c.annotations.map((a) => this.markStamp(a, c.imageFor)).join('|')}`;
+        });
+        return `c1|${srcMtime}|${perCell.join('#')}`;
+    }
+    /** A late-arriving image or a later clear must bust the cache. */
+    markStamp(a, imageFor) {
+        var _a, _b, _c, _d, _e;
+        const img = imageFor(a);
+        const imgMtime = img ? fs.statSync(img).mtimeMs : 0;
+        return `${(_a = a.id) !== null && _a !== void 0 ? _a : ''}:${(_b = a.timecode_ms) !== null && _b !== void 0 ? _b : 0}:${(_c = a.end_timecode_ms) !== null && _c !== void 0 ? _c : ''}:${a.shape}:${a.geometry}:${(_d = a.color) !== null && _d !== void 0 ? _d : ''}:${(_e = a.text) !== null && _e !== void 0 ? _e : ''}:${imgMtime}`;
+    }
     f(n) {
         const num = Number(n);
         if (!Number.isFinite(num))

package/lib/src/services/recording/probeDuration.js

@@ -14,9 +14,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PROBE_TIMEOUT_MS = void 0;
 exports.parseFfmpegHeaderDurationSec = parseFfmpegHeaderDurationSec;
+exports.parseFfmpegFrameSize = parseFfmpegFrameSize;
 exports.parseFfmpegProgressDurationSec = parseFfmpegProgressDurationSec;
 exports.probeVideoDurationSec = probeVideoDurationSec;
 exports.probeVideoDurationMs = probeVideoDurationMs;
+exports.probeVideoFrameSize = probeVideoFrameSize;
 const child_process_1 = require("child_process");
 const path_1 = __importDefault(require("path"));
 const typedi_1 = require("typedi");
@@ -48,6 +50,18 @@ function parseFfmpegHeaderDurationSec(stderr) {
     // 0 is not an answer — let the caller fall back rather than record a zero.
     return Number.isFinite(sec) && sec > 0 ? sec : undefined;
 }
+/**
+ * Frame size from the first video stream line of `ffmpeg -i`, e.g.
+ * `Video: h264 (High) (avc1 / 0x31637661), yuv420p(tv, …), 720x1480, …`. The
+ * size is the first `, WxH` followed by a separator, which skips codec tags
+ * like `0x31637661`.
+ */
+function parseFfmpegFrameSize(stderr) {
+    const m = stderr.match(/Video: .*?, (\d{2,5})x(\d{2,5})(?=[,\s\]])/);
+    if (!m)
+        return undefined;
+    return { w: Number(m[1]), h: Number(m[2]) };
+}
 /** Duration from the last `out_time_us` of an `-f null` decode pass. */
 function parseFfmpegProgressDurationSec(stdout) {
     const matches = [...stdout.matchAll(/out_time_us=(\d+)/g)];
@@ -147,3 +161,10 @@ function probeVideoDurationMs(filePath_1) {
         return sec === undefined ? undefined : Math.round(sec * 1000);
     });
 }
+/** A video's frame size, from its container header. Undefined on failure. */
+function probeVideoFrameSize(filePath_1) {
+    return __awaiter(this, arguments, void 0, function* (filePath, opts = {}) {
+        var _a;
+        return runProbe(['-hide_banner', '-i', filePath], `probe-size:${path_1.default.basename(filePath)}`, ({ stderr }) => parseFfmpegFrameSize(stderr), (_a = opts.timeoutMs) !== null && _a !== void 0 ? _a : exports.PROBE_TIMEOUT_MS);
+    });
+}

package/lib/src/services/recording/proof-bundle.js

@@ -112,19 +112,43 @@ let ProofBundleService = class ProofBundleService {
         this.populateVideosOnly(archive, groupId).catch((err) => archive.emit('error', err));
         return archive;
     }
-    collectVideoEntries(groupId) {
+    /**
+     * The composite every download gets: with the devices' marks burned in when
+     * that render works, otherwise the raw composite. Null when the group has
+     * none (single-device groups never do).
+     */
+    resolveCompositeFile(groupId) {
         return __awaiter(this, void 0, void 0, function* () {
-            const recordings = (yield this.store.listGroup(groupId));
-            const entries = [];
+            var _a;
+            let compositePath;
             try {
-                const compositePath = (0, RecordingOrchestrator_1.compositeOutputPath)(groupId);
-                if (fs.existsSync(compositePath) && fs.statSync(compositePath).size > 0) {
-                    entries.push({ filePath: compositePath, name: 'composite.mp4' });
-                }
+                compositePath = (0, RecordingOrchestrator_1.compositeOutputPath)(groupId);
+            }
+            catch (_b) {
+                return null; // ArtifactStore unset (unit tests)
             }
-            catch (_a) {
-                /* ArtifactStore may be unset in unit tests; skip composite. */
+            if (!fs.existsSync(compositePath) || fs.statSync(compositePath).size === 0)
+                return null;
+            try {
+                const { AnnotationRenderService } = yield Promise.resolve().then(() => __importStar(require('./annotation-render')));
+                return (yield typedi_1.Container.get(AnnotationRenderService).resolveCompositePath(groupId)).filePath;
             }
+            catch (err) {
+                const { default: log } = yield Promise.resolve().then(() => __importStar(require('../../logger')));
+                log
+                    .scope('ProofBundle')
+                    .warn(`Composite burn-in skipped for ${groupId}: ${(_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : err}`);
+                return compositePath;
+            }
+        });
+    }
+    collectVideoEntries(groupId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const recordings = (yield this.store.listGroup(groupId));
+            const entries = [];
+            const composite = yield this.resolveCompositeFile(groupId);
+            if (composite)
+                entries.push({ filePath: composite, name: 'composite.mp4' });
             for (const r of recordings) {
                 try {
                     if (r.file_path && fs.existsSync(r.file_path) && fs.statSync(r.file_path).size > 0) {
@@ -134,7 +158,7 @@ let ProofBundleService = class ProofBundleService {
                             const rendered = yield typedi_1.Container.get(AnnotationRenderService).resolvePlayablePath(r.id);
                             filePath = rendered.filePath;
                         }
-                        catch (_b) {
+                        catch (_a) {
                             /* keep clean source */
                         }
                         entries.push({
@@ -143,7 +167,7 @@ let ProofBundleService = class ProofBundleService {
                         });
                     }
                 }
-                catch (_c) {
+                catch (_b) {
                     /* skip */
                 }
             }
@@ -234,10 +258,9 @@ let ProofBundleService = class ProofBundleService {
                 name: 'README.md',
             });
             // Mosaic-wide composite mp4 (only present for multi-device groups).
-            const compositePath = (0, RecordingOrchestrator_1.compositeOutputPath)(groupId);
-            if (fs.existsSync(compositePath)) {
-                archive.file(compositePath, { name: 'composite.mp4' });
-            }
+            const composite = yield this.resolveCompositeFile(groupId);
+            if (composite)
+                archive.file(composite, { name: 'composite.mp4' });
             for (const r of recordings) {
                 const base = `devices/${r.device_udid}`;
                 if (r.file_path && fs.existsSync(r.file_path)) {

package/lib/src/services/recording/recordingTiming.js

@@ -0,0 +1,86 @@
+"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.recordingTimingPath = recordingTimingPath;
+exports.writeRecordingTiming = writeRecordingTiming;
+exports.readRecordingTiming = readRecordingTiming;
+exports.markShiftMs = markShiftMs;
+exports.shiftAnnotations = shiftAnnotations;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/** Beyond this the file is corrupt, not a real start-up gap. */
+const MAX_SHIFT_MS = 5 * 60 * 1000;
+/** `<recordings>/<id>/timing.json`, removed with the recording's directory. */
+function recordingTimingPath(videoFilePath) {
+    return path.join(path.dirname(path.dirname(videoFilePath)), 'timing.json');
+}
+/** Best effort: without the file the video is rendered unshifted, as before. */
+function writeRecordingTiming(videoFilePath, timing) {
+    const file = recordingTimingPath(videoFilePath);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(Object.assign({ version: 1 }, timing)));
+}
+function readRecordingTiming(videoFilePath) {
+    try {
+        const t = JSON.parse(fs.readFileSync(recordingTimingPath(videoFilePath), 'utf8'));
+        if ((t === null || t === void 0 ? void 0 : t.version) === 1 && Number.isFinite(t.spawnedAtMs) && Number.isFinite(t.groupT0Ms)) {
+            return { version: 1, spawnedAtMs: t.spawnedAtMs, groupT0Ms: t.groupT0Ms };
+        }
+    }
+    catch (_a) {
+        /* missing or unreadable: no timing */
+    }
+    return undefined;
+}
+/**
+ * How far to move a mark in this recording's own video: a mark at timecode T
+ * happened T + (t0 - spawn) into it. Negative for a device added after t=0.
+ */
+function markShiftMs(timing) {
+    if (!timing)
+        return 0;
+    const shift = Math.round(timing.groupT0Ms - timing.spawnedAtMs);
+    return Math.abs(shift) > MAX_SHIFT_MS ? 0 : shift;
+}
+function shiftAnnotations(annotations, shiftMs) {
+    if (shiftMs === 0)
+        return annotations;
+    return annotations.map((a) => {
+        var _a;
+        return (Object.assign(Object.assign({}, a), { timecode_ms: ((_a = a.timecode_ms) !== null && _a !== void 0 ? _a : 0) + shiftMs, end_timecode_ms: a.end_timecode_ms === null || a.end_timecode_ms === undefined
+                ? a.end_timecode_ms
+                : a.end_timecode_ms + shiftMs }));
+    });
+}

package/lib/test/unit/active-recordings.spec.js

@@ -72,4 +72,12 @@ describe('selectOwnActiveGroups', () => {
             userId: 'alice',
         })).to.deep.equal([]);
     });
+    // A reload must keep the dashboard's timebase: its t=0 is when start()
+    // returned, not when the first device's ffmpeg spawned (about 1.2 s earlier
+    // with two devices), or marks drawn after a reload land late.
+    it("resumes on the group's recorded t=0 when there is one", () => {
+        const t0 = Date.parse('2026-09-25T10:00:02.350Z');
+        const out = (0, activeRecordings_1.selectOwnActiveGroups)([row('r1', 'g1', 'U1', '2026-09-25T10:00:01Z')], lockOf, { userId: 'alice' }, () => t0);
+        (0, chai_1.expect)(out[0].startedAt).to.equal('2026-09-25T10:00:02.350Z');
+    });
 });