Skip to content

armgit / Cap

Public Imported from GitHub
0

Open source Loom alternative. Beautiful, shareable screen recordings.

feat(web): let an admin rebuild a desktop recording's missing manifest from its uploaded segments

Richie McIlroyead55328471f
diff --git a/apps/web/__tests__/fixtures/fmp4.ts b/apps/web/__tests__/fixtures/fmp4.ts
new file mode 100644
index 000000000..a14c23eb5
--- /dev/null
+++ b/apps/web/__tests__/fixtures/fmp4.ts
@@ -0,0 +1,132 @@
+const u32 = (value: number) => {
+ const bytes = new Uint8Array(4);
+ new DataView(bytes.buffer).setUint32(0, value);
+ return bytes;
+};
+
+const u64 = (value: number) => {
+ const bytes = new Uint8Array(8);
+ new DataView(bytes.buffer).setBigUint64(0, BigInt(value));
+ return bytes;
+};
+
+function concat(parts: Uint8Array[]) {
+ const output = new Uint8Array(
+ parts.reduce((sum, part) => sum + part.length, 0),
+ );
+ let offset = 0;
+ for (const part of parts) {
+ output.set(part, offset);
+ offset += part.length;
+ }
+ return output;
+}
+
+export function box(type: string, ...payload: Uint8Array[]) {
+ const body = concat(payload);
+ return concat([u32(body.length + 8), new TextEncoder().encode(type), body]);
+}
+
+function fullBox(
+ type: string,
+ version: number,
+ flags: number,
+ ...payload: Uint8Array[]
+) {
+ return box(type, u32((version << 24) | flags), ...payload);
+}
+
+export function initSegment({
+ timescale,
+ defaultSampleDuration = 0,
+ mdhdVersion = 0,
+}: {
+ timescale: number;
+ defaultSampleDuration?: number;
+ mdhdVersion?: 0 | 1;
+}) {
+ const mdhd =
+ mdhdVersion === 1
+ ? fullBox("mdhd", 1, 0, u64(0), u64(0), u32(timescale), u64(0), u32(0))
+ : fullBox("mdhd", 0, 0, u32(0), u32(0), u32(timescale), u32(0), u32(0));
+ return concat([
+ box("ftyp", new TextEncoder().encode("iso6"), u32(0)),
+ box(
+ "moov",
+ fullBox("mvhd", 0, 0, new Uint8Array(96)),
+ box("trak", box("mdia", mdhd, fullBox("hdlr", 0, 0, new Uint8Array(20)))),
+ box(
+ "mvex",
+ fullBox(
+ "trex",
+ 0,
+ 0,
+ u32(1),
+ u32(1),
+ u32(defaultSampleDuration),
+ u32(0),
+ u32(0),
+ ),
+ ),
+ ),
+ ]);
+}
+
+export function moof({
+ durations,
+ count = durations?.length ?? 0,
+ tfhdDefaultDuration,
+}: {
+ durations?: number[];
+ count?: number;
+ tfhdDefaultDuration?: number;
+}) {
+ const tfhdFlags = tfhdDefaultDuration === undefined ? 0 : 0x08;
+ const tfhd = fullBox(
+ "tfhd",
+ 0,
+ tfhdFlags,
+ u32(1),
+ ...(tfhdDefaultDuration === undefined ? [] : [u32(tfhdDefaultDuration)]),
+ );
+ // Each sample carries a duration (when present) and a size, like FFmpeg's fragments.
+ const trunFlags = 0x01 | 0x200 | (durations ? 0x100 : 0);
+ const samples = Array.from({ length: count }, (_, index) =>
+ durations ? concat([u32(durations[index] ?? 0), u32(100)]) : u32(100),
+ );
+ const trun = fullBox("trun", 0, trunFlags, u32(count), u32(0), ...samples);
+ return box("moof", fullBox("mfhd", 0, 0, u32(1)), box("traf", tfhd, trun));
+}
+
+export function mdat(size: number, { large = false } = {}) {
+ if (!large)
+ return concat([
+ u32(size + 8),
+ new TextEncoder().encode("mdat"),
+ new Uint8Array(size),
+ ]);
+ return concat([
+ u32(1),
+ new TextEncoder().encode("mdat"),
+ u64(size + 16),
+ new Uint8Array(size),
+ ]);
+}
+
+export function segment(...parts: Uint8Array[]) {
+ return concat([
+ box("styp", new TextEncoder().encode("msdh"), u32(0)),
+ ...parts,
+ ]);
+}
+
+export function rangeReader(bytes: Uint8Array) {
+ const reads: [number, number][] = [];
+ return {
+ reads,
+ read: async (start: number, end: number) => {
+ reads.push([start, end]);
+ return bytes.slice(start, end);
+ },
+ };
+}
diff --git a/apps/web/__tests__/unit/desktop-manifest-rebuild.test.ts b/apps/web/__tests__/unit/desktop-manifest-rebuild.test.ts
new file mode 100644
index 000000000..573ed0788
--- /dev/null
+++ b/apps/web/__tests__/unit/desktop-manifest-rebuild.test.ts
@@ -0,0 +1,416 @@
+import type { Video } from "@cap/web-domain";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { initSegment, mdat, moof, segment } from "../fixtures/fmp4";
+
+const mocks = vi.hoisted(() => ({
+ db: vi.fn(),
+ queue: vi.fn(),
+ objects: new Map<string, Uint8Array | string>(),
+ put: vi.fn(),
+ updates: [] as { set: unknown; where: unknown }[],
+ row: undefined as unknown,
+ storage: { provider: "s3", custom: false },
+}));
+
+vi.mock("@cap/database", () => ({ db: mocks.db }));
+vi.mock("@cap/database/schema", () => ({
+ videos: {
+ id: "video.id",
+ bucket: "video.bucket",
+ storageIntegrationId: "video.storageIntegrationId",
+ createdAt: "video.createdAt",
+ },
+ videoUploads: {
+ videoId: "upload.videoId",
+ processingError: "upload.processingError",
+ },
+ videoProcessingJobs: { videoId: "job.videoId" },
+}));
+vi.mock("drizzle-orm", () => ({
+ and: (...args: unknown[]) => ({ and: args }),
+ asc: (value: unknown) => value,
+ eq: (left: unknown, right: unknown) => ({ eq: [left, right] }),
+ isNull: (value: unknown) => ({ null: value }),
+ like: (left: unknown, right: unknown) => ({ like: [left, right] }),
+}));
+vi.mock("@cap/web-backend", async () => {
+ const { Effect, Option } = await import("effect");
+ const bucket = {
+ get provider() {
+ return mocks.storage.provider;
+ },
+ getObject: (key: string) =>
+ Effect.succeed(
+ Option.fromNullable(
+ typeof mocks.objects.get(key) === "string"
+ ? (mocks.objects.get(key) as string)
+ : undefined,
+ ),
+ ),
+ putObject: (key: string, body: string) =>
+ Effect.sync(() => {
+ mocks.put(key, body);
+ mocks.objects.set(key, body);
+ }),
+ listObjects: ({ prefix }: { prefix: string }) =>
+ Effect.succeed({
+ Contents: [...mocks.objects.entries()]
+ .filter(([key]) => key.startsWith(prefix))
+ .map(([Key, value]) => ({ Key, Size: value.length })),
+ IsTruncated: false,
+ }),
+ getInternalSignedObjectUrl: (key: string) =>
+ Effect.succeed(`https://storage.test/${key}`),
+ };
+ return {
+ Storage: {
+ getAccessForVideo: () =>
+ Effect.succeed([
+ bucket,
+ mocks.storage.custom ? Option.some({}) : Option.none(),
+ ]),
+ },
+ };
+});
+vi.mock("@/lib/server", async () => ({
+ runPromise: (await import("effect")).Effect.runPromise,
+}));
+vi.mock("@/lib/video-storage", () => ({ decodeStorageVideo: () => ({}) }));
+vi.mock("@/lib/desktop-segments-finalization", () => ({
+ queueDesktopSegmentsFinalization: mocks.queue,
+}));
+vi.mock("@/lib/desktop-recording-jobs", () => ({
+ DESKTOP_RECORDING_SOURCE_REUPLOAD_REQUIRED: "source-reupload-required",
+ SourceCommitPendingError: class SourceCommitPendingError extends Error {},
+ DesktopRecordingSourceBlockedError: class DesktopRecordingSourceBlockedError extends Error {},
+}));
+
+import {
+ inspectMissingManifestRecording,
+ MISSING_MANIFEST_ERROR_PREFIX,
+ rebuildMissingManifest,
+} from "@/lib/desktop-manifest-rebuild";
+import { SourceCommitPendingError } from "@/lib/desktop-recording-jobs";
+
+const videoId = "video" as Video.VideoId;
+const prefix = "owner/video/segments";
+const missingReason = `${MISSING_MANIFEST_ERROR_PREFIX}. Automatic recovery cannot continue.`;
+const blockedJob = {
+ state: "source-blocked",
+ errorCode: "source-reupload-required",
+ source: null,
+ verification: null,
+};
+
+function dbFixture() {
+ const select = {
+ select: vi.fn(),
+ from: vi.fn(),
+ leftJoin: vi.fn(),
+ where: vi.fn(),
+ limit: vi.fn(),
+ };
+ for (const key of ["select", "from", "leftJoin", "where"] as const)
+ select[key].mockReturnValue(select);
+ select.limit.mockImplementation(async () => (mocks.row ? [mocks.row] : []));
+ return {
+ ...select,
+ update: vi.fn(() => ({
+ set: (set: unknown) => ({
+ where: async (where: unknown) => {
+ mocks.updates.push({ set, where });
+ },
+ }),
+ })),
+ };
+}
+
+function seedTrack(
+ track: "video" | "audio",
+ durations: number[],
+ timescale = 1_000,
+) {
+ mocks.objects.set(`${prefix}/${track}/init.mp4`, initSegment({ timescale }));
+ durations.forEach((duration, position) => {
+ mocks.objects.set(
+ `${prefix}/${track}/segment_${String(position + 1).padStart(3, "0")}.m4s`,
+ segment(moof({ durations: [duration] }), mdat(64)),
+ );
+ });
+}
+
+beforeEach(() => {
+ mocks.objects.clear();
+ mocks.updates.length = 0;
+ mocks.put.mockReset();
+ mocks.queue.mockReset().mockResolvedValue("queued");
+ mocks.storage = { provider: "s3", custom: false };
+ mocks.row = {
+ video: {
+ id: videoId,
+ ownerId: "owner",
+ source: { type: "desktopSegments" },
+ },
+ processingError: missingReason,
+ job: blockedJob,
+ };
+ mocks.db.mockImplementation(dbFixture);
+ vi.stubGlobal(
+ "fetch",
+ vi.fn(async (url: string, init?: RequestInit) => {
+ const key = url.replace("https://storage.test/", "");
+ const value = mocks.objects.get(key);
+ if (!(value instanceof Uint8Array))
+ return new Response(null, { status: 404 });
+ const [, start, end] =
+ /bytes=(\d+)-(\d+)/.exec(
+ String((init?.headers as Record<string, string>)?.Range),
+ ) ?? [];
+ return new Response(value.slice(Number(start), Number(end) + 1), {
+ status: 206,
+ });
+ }),
+ );
+});
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe("inspectMissingManifestRecording", () => {
+ it("builds a complete v2 manifest with durations read from the fragments", async () => {
+ seedTrack("video", [2_000, 2_000, 1_500]);
+ seedTrack("audio", [2_000, 2_000, 1_520]);
+ const result = await inspectMissingManifestRecording(videoId);
+ expect(result).toMatchObject({
+ status: "ready",
+ videoSegments: 3,
+ audioSegments: 3,
+ durationSeconds: 5.5,
+ });
+ if (result.status !== "ready") throw new Error("not ready");
+ expect(JSON.parse(result.manifest)).toEqual({
+ version: 2,
+ video_init_uploaded: true,
+ audio_init_uploaded: true,
+ video_segments: [
+ { index: 1, duration: 2 },
+ { index: 2, duration: 2 },
+ { index: 3, duration: 1.5 },
+ ],
+ audio_segments: [
+ { index: 1, duration: 2 },
+ { index: 2, duration: 2 },
+ { index: 3, duration: 1.52 },
+ ],
+ is_complete: true,
+ });
+ });
+
+ it("builds a video-only manifest when no audio was uploaded", async () => {
+ seedTrack("video", [2_000]);
+ const result = await inspectMissingManifestRecording(videoId);
+ if (result.status !== "ready") throw new Error(JSON.stringify(result));
+ expect(JSON.parse(result.manifest)).toMatchObject({
+ audio_init_uploaded: false,
+ audio_segments: [],
+ });
+ });
+
+ it.each([
+ [
+ "a gap in the video",
+ () => {
+ seedTrack("video", [2_000, 2_000, 2_000]);
+ mocks.objects.delete(`${prefix}/video/segment_002.m4s`);
+ },
+ "video segment 2 is missing",
+ ],
+ [
+ "no video init",
+ () => {
+ seedTrack("video", [2_000]);
+ mocks.objects.delete(`${prefix}/video/init.mp4`);
+ },
+ "video init segment is missing",
+ ],
+ [
+ "audio segments without an init",
+ () => {
+ seedTrack("video", [2_000]);
+ seedTrack("audio", [2_000]);
+ mocks.objects.delete(`${prefix}/audio/init.mp4`);
+ },
+ "audio init segment is missing",
+ ],
+ [
+ "an audio init without segments",
+ () => {
+ seedTrack("video", [2_000]);
+ mocks.objects.set(
+ `${prefix}/audio/init.mp4`,
+ initSegment({ timescale: 48_000 }),
+ );
+ },
+ "audio init was uploaded without any audio segments",
+ ],
+ [
+ "audio that stopped early",
+ () => {
+ seedTrack("video", Array(30).fill(2_000));
+ seedTrack("audio", Array(10).fill(2_000));
+ },
+ "audio covers 20.0 s of 60.0 s of video",
+ ],
+ [
+ "an unreadable segment",
+ () => {
+ seedTrack("video", [2_000]);
+ mocks.objects.set(
+ `${prefix}/video/segment_001.m4s`,
+ new Uint8Array(40),
+ );
+ },
+ "video segment 1 is unreadable",
+ ],
+ [
+ "a misnamed segment",
+ () => {
+ seedTrack("video", [2_000]);
+ mocks.objects.set(
+ `${prefix}/video/segment_1.m4s`,
+ segment(moof({ durations: [1] }), mdat(1)),
+ );
+ },
+ "does not match its expected name",
+ ],
+ ["no video at all", () => {}, "no video segments were uploaded"],
+ ])("refuses %s", async (_name, seed, reason) => {
+ seed();
+ const result = await inspectMissingManifestRecording(videoId);
+ expect(result.status).toBe("incomplete");
+ expect(result).toMatchObject({ reason: expect.stringContaining(reason) });
+ });
+
+ it("only accepts uploads blocked on a missing manifest in Cap's bucket", async () => {
+ seedTrack("video", [2_000]);
+ mocks.row = {
+ ...(mocks.row as object),
+ processingError:
+ "source-reupload-required: The recording manifest is not marked complete.",
+ };
+ await expect(
+ inspectMissingManifestRecording(videoId),
+ ).resolves.toMatchObject({ status: "not-eligible" });
+ mocks.row = {
+ ...(mocks.row as object),
+ processingError: missingReason,
+ job: { ...blockedJob, source: { kind: "segments" } },
+ };
+ await expect(
+ inspectMissingManifestRecording(videoId),
+ ).resolves.toMatchObject({ status: "not-eligible" });
+ mocks.row = {
+ ...(mocks.row as object),
+ job: { ...blockedJob, state: "processing" },
+ };
+ await expect(
+ inspectMissingManifestRecording(videoId),
+ ).resolves.toMatchObject({ status: "not-eligible" });
+ mocks.row = { ...(mocks.row as object), job: blockedJob };
+ mocks.storage = { provider: "s3", custom: true };
+ await expect(inspectMissingManifestRecording(videoId)).resolves.toEqual({
+ status: "unsupported-storage",
+ });
+ mocks.storage = { provider: "s3", custom: false };
+ mocks.objects.set(`${prefix}/manifest.json`, "{}");
+ await expect(inspectMissingManifestRecording(videoId)).resolves.toEqual({
+ status: "manifest-exists",
+ });
+ });
+});
+
+describe("rebuildMissingManifest", () => {
+ it("writes nothing on a dry run", async () => {
+ seedTrack("video", [2_000, 2_000]);
+ await expect(
+ rebuildMissingManifest(videoId, { dryRun: true }),
+ ).resolves.toMatchObject({
+ status: "checked",
+ videoSegments: 2,
+ });
+ expect(mocks.put).not.toHaveBeenCalled();
+ expect(mocks.queue).not.toHaveBeenCalled();
+ expect(mocks.updates).toHaveLength(0);
+ });
+
+ it("writes the manifest, queues processing and clears the missing-manifest reason", async () => {
+ seedTrack("video", [2_000, 2_000]);
+ mocks.queue.mockRejectedValueOnce(new SourceCommitPendingError());
+ await expect(
+ rebuildMissingManifest(videoId, { dryRun: false }),
+ ).resolves.toMatchObject({
+ status: "queued",
+ videoSegments: 2,
+ durationSeconds: 4,
+ });
+ expect(mocks.put).toHaveBeenCalledWith(
+ `${prefix}/manifest.json`,
+ expect.stringContaining('"is_complete": true'),
+ );
+ expect(mocks.queue).toHaveBeenCalledWith({ videoId, userId: "owner" });
+ expect(mocks.updates).toEqual([
+ {
+ set: expect.objectContaining({
+ phase: "processing",
+ processingError: null,
+ }),
+ where: {
+ and: [
+ { eq: ["upload.videoId", videoId] },
+ {
+ like: [
+ "upload.processingError",
+ `${MISSING_MANIFEST_ERROR_PREFIX}%`,
+ ],
+ },
+ ],
+ },
+ },
+ ]);
+ });
+
+ it("records why an incomplete recording was refused so it leaves the candidate list", async () => {
+ seedTrack("video", [2_000, 2_000]);
+ mocks.objects.delete(`${prefix}/video/segment_001.m4s`);
+ await expect(
+ rebuildMissingManifest(videoId, { dryRun: false }),
+ ).resolves.toMatchObject({ status: "incomplete" });
+ expect(mocks.put).not.toHaveBeenCalled();
+ expect(mocks.queue).not.toHaveBeenCalled();
+ expect(mocks.updates).toHaveLength(1);
+ expect(mocks.updates[0]?.set).toMatchObject({
+ processingError: expect.stringContaining(
+ "could not be rebuilt: video segment 1 is missing",
+ ),
+ });
+ });
+
+ it("never overwrites a manifest that appeared after inspection", async () => {
+ seedTrack("video", [2_000]);
+ const original = mocks.db.getMockImplementation();
+ let selects = 0;
+ mocks.db.mockImplementation(() => {
+ const fixture = dbFixture();
+ fixture.limit.mockImplementation(async () => {
+ if (++selects === 2) mocks.objects.set(`${prefix}/manifest.json`, "{}");
+ return [mocks.row];
+ });
+ return fixture;
+ });
+ await expect(
+ rebuildMissingManifest(videoId, { dryRun: false }),
+ ).resolves.toEqual({ status: "manifest-exists" });
+ expect(mocks.put).not.toHaveBeenCalled();
+ expect(mocks.queue).not.toHaveBeenCalled();
+ mocks.db.mockImplementation(original ?? dbFixture);
+ });
+});
diff --git a/apps/web/__tests__/unit/fragmented-mp4-duration.test.ts b/apps/web/__tests__/unit/fragmented-mp4-duration.test.ts
new file mode 100644
index 000000000..06c0ae420
--- /dev/null
+++ b/apps/web/__tests__/unit/fragmented-mp4-duration.test.ts
@@ -0,0 +1,113 @@
+import { describe, expect, it } from "vitest";
+import {
+ FragmentedMp4Error,
+ readFragmentDuration,
+ readInitTiming,
+} from "@/lib/fragmented-mp4-duration";
+import {
+ initSegment,
+ mdat,
+ moof,
+ rangeReader,
+ segment,
+} from "../fixtures/fmp4";
+
+describe("readInitTiming", () => {
+ it("reads the track timescale and trex default duration", () => {
+ expect(
+ readInitTiming(
+ initSegment({ timescale: 15_360, defaultSampleDuration: 256 }),
+ ),
+ ).toEqual({ timescale: 15_360, defaultSampleDuration: 256 });
+ });
+
+ it("reads a version 1 mdhd and omits a zero default duration", () => {
+ expect(
+ readInitTiming(initSegment({ timescale: 48_000, mdhdVersion: 1 })),
+ ).toEqual({
+ timescale: 48_000,
+ });
+ });
+
+ it("rejects bytes that are not an init segment", () => {
+ expect(() =>
+ readInitTiming(segment(moof({ durations: [1] }), mdat(4))),
+ ).toThrow(FragmentedMp4Error);
+ });
+});
+
+describe("readFragmentDuration", () => {
+ it("sums per-sample durations from trun", async () => {
+ const bytes = segment(moof({ durations: [512, 512, 1024] }), mdat(1_000));
+ const { read } = rangeReader(bytes);
+ await expect(
+ readFragmentDuration(read, bytes.length, { timescale: 1_024 }),
+ ).resolves.toBe(2);
+ });
+
+ it("falls back to the tfhd default and then the trex default", async () => {
+ const fromTfhd = segment(
+ moof({ count: 120, tfhdDefaultDuration: 256 }),
+ mdat(10),
+ );
+ await expect(
+ readFragmentDuration(rangeReader(fromTfhd).read, fromTfhd.length, {
+ timescale: 15_360,
+ defaultSampleDuration: 1,
+ }),
+ ).resolves.toBe(2);
+ const fromTrex = segment(moof({ count: 94 }), mdat(10));
+ await expect(
+ readFragmentDuration(rangeReader(fromTrex).read, fromTrex.length, {
+ timescale: 48_000,
+ defaultSampleDuration: 1_024,
+ }),
+ ).resolves.toBeCloseTo(2.005333, 6);
+ });
+
+ it("adds every fragment and skips media data instead of reading it", async () => {
+ const bytes = segment(
+ moof({ durations: [1_000] }),
+ mdat(200_000),
+ moof({ durations: [3_000] }),
+ mdat(300_000, { large: true }),
+ );
+ const reader = rangeReader(bytes);
+ await expect(
+ readFragmentDuration(reader.read, bytes.length, { timescale: 1_000 }),
+ ).resolves.toBe(4);
+ const fetched = reader.reads.reduce(
+ (sum, [start, end]) => sum + end - start,
+ 0,
+ );
+ expect(fetched).toBeLessThan(200 * 1024);
+ });
+
+ it("rejects a fragment whose samples have no duration", async () => {
+ const bytes = segment(moof({ count: 3 }), mdat(10));
+ await expect(
+ readFragmentDuration(rangeReader(bytes).read, bytes.length, {
+ timescale: 1_000,
+ }),
+ ).rejects.toThrow("no duration");
+ });
+
+ it("rejects a segment cut off inside a box", async () => {
+ const bytes = segment(moof({ durations: [1_000] }), mdat(1_000));
+ const truncated = bytes.slice(0, bytes.length - 10);
+ await expect(
+ readFragmentDuration(rangeReader(truncated).read, truncated.length, {
+ timescale: 1_000,
+ }),
+ ).rejects.toThrow(FragmentedMp4Error);
+ });
+
+ it("rejects a segment without any fragment", async () => {
+ const bytes = segment(mdat(10));
+ await expect(
+ readFragmentDuration(rangeReader(bytes).read, bytes.length, {
+ timescale: 1_000,
+ }),
+ ).rejects.toThrow("no moof");
+ });
+});
diff --git a/apps/web/actions/admin/rebuild-missing-manifests.ts b/apps/web/actions/admin/rebuild-missing-manifests.ts
new file mode 100644
index 000000000..817601001
--- /dev/null
+++ b/apps/web/actions/admin/rebuild-missing-manifests.ts
@@ -0,0 +1,82 @@
+"use server";
+
+import { serverEnv } from "@cap/env";
+import { parseAdminVideoId, requireAdmin } from "@/lib/admin-access";
+import {
+ listMissingManifestCandidates,
+ type ManifestRebuildResult,
+ rebuildMissingManifest,
+} from "@/lib/desktop-manifest-rebuild";
+
+// Each recording reads one ranged header per segment, so a long recording can take a while.
+const MAX_RECORDINGS_PER_REQUEST = 10;
+
+export type RebuildManifestRow = {
+ input: string;
+ videoId?: string;
+ status: ManifestRebuildResult["status"] | "failed";
+ detail?: string;
+ shareUrl?: string;
+};
+
+function describe(result: ManifestRebuildResult) {
+ if ("reason" in result) return result.reason;
+ if ("videoSegments" in result)
+ return `${result.videoSegments} video / ${result.audioSegments} audio segments, ${Math.round(result.durationSeconds)} s`;
+ return undefined;
+}
+
+export async function adminListMissingManifestCandidates(): Promise<string[]> {
+ await requireAdmin();
+ return listMissingManifestCandidates(MAX_RECORDINGS_PER_REQUEST);
+}
+
+export async function adminRebuildMissingManifests(
+ input: string,
+ mode: "check" | "rebuild",
+): Promise<RebuildManifestRow[]> {
+ await requireAdmin();
+ const entries = [
+ ...new Set(
+ input
+ .split(/[\s,]+/)
+ .map((entry) => entry.trim())
+ .filter(Boolean),
+ ),
+ ];
+ if (entries.length === 0) throw new Error("Enter at least one video ID");
+ if (entries.length > MAX_RECORDINGS_PER_REQUEST)
+ throw new Error(
+ `Rebuild at most ${MAX_RECORDINGS_PER_REQUEST} recordings at a time`,
+ );
+
+ const rows: RebuildManifestRow[] = [];
+ const seen = new Set<string>();
+ for (const entry of entries) {
+ try {
+ const videoId = parseAdminVideoId(entry);
+ if (seen.has(videoId)) continue;
+ seen.add(videoId);
+ const result = await rebuildMissingManifest(videoId, {
+ dryRun: mode === "check",
+ });
+ rows.push({
+ input: entry,
+ videoId,
+ status: result.status,
+ detail: describe(result),
+ shareUrl:
+ result.status === "queued" || result.status === "already-processing"
+ ? `${serverEnv().WEB_URL}/s/${videoId}`
+ : undefined,
+ });
+ } catch (error) {
+ rows.push({
+ input: entry,
+ status: "failed",
+ detail: error instanceof Error ? error.message : String(error),
+ });
+ }
+ }
+ return rows;
+}
diff --git a/apps/web/app/admin/AdminPanel.tsx b/apps/web/app/admin/AdminPanel.tsx
index bff610345..6a46666cd 100644
--- a/apps/web/app/admin/AdminPanel.tsx
+++ b/apps/web/app/admin/AdminPanel.tsx
@@ -601,6 +601,12 @@ export function AdminPanel({
>
Retry blocked recordings
</Link>
+ <Link
+ href="/admin/rebuild-manifests"
+ className="rounded-lg border border-gray-300 px-3 py-2 text-sm font-medium text-gray-700 transition hover:bg-gray-50"
+ >
+ Rebuild missing manifests
+ </Link>
</div>
</div>
</div>
diff --git a/apps/web/app/admin/rebuild-manifests/page.tsx b/apps/web/app/admin/rebuild-manifests/page.tsx
new file mode 100644
index 000000000..752f018e8
--- /dev/null
+++ b/apps/web/app/admin/rebuild-manifests/page.tsx
@@ -0,0 +1,15 @@
+import { buildEnv } from "@cap/env";
+import { notFound } from "next/navigation";
+import { getViewerContext } from "@/lib/messenger/data";
+import { RebuildManifestsPanel } from "./rebuild-manifests-panel";
+
+export const maxDuration = 300;
+
+export default async function RebuildManifestsPage() {
+ if (buildEnv.NEXT_PUBLIC_IS_CAP !== "true") notFound();
+
+ const viewer = await getViewerContext();
+ if (!viewer.user || !viewer.isAdmin) notFound();
+
+ return <RebuildManifestsPanel />;
+}
diff --git a/apps/web/app/admin/rebuild-manifests/rebuild-manifests-panel.tsx b/apps/web/app/admin/rebuild-manifests/rebuild-manifests-panel.tsx
new file mode 100644
index 000000000..f85ee3617
--- /dev/null
+++ b/apps/web/app/admin/rebuild-manifests/rebuild-manifests-panel.tsx
@@ -0,0 +1,163 @@
+"use client";
+
+import Link from "next/link";
+import { useCallback, useId, useState } from "react";
+import {
+ adminListMissingManifestCandidates,
+ adminRebuildMissingManifests,
+ type RebuildManifestRow,
+} from "@/actions/admin/rebuild-missing-manifests";
+
+type Status =
+ | { type: "idle" }
+ | { type: "working"; label: string }
+ | { type: "done"; mode: "check" | "rebuild"; rows: RebuildManifestRow[] }
+ | { type: "error"; message: string };
+
+const SUCCESS = new Set(["checked", "queued", "already-processing"]);
+
+export function RebuildManifestsPanel() {
+ const [input, setInput] = useState("");
+ const [status, setStatus] = useState<Status>({ type: "idle" });
+ const inputId = useId();
+ const working = status.type === "working";
+
+ const run = useCallback(
+ async (mode: "check" | "rebuild") => {
+ if (!input.trim() || working) return;
+ setStatus({
+ type: "working",
+ label: mode === "check" ? "Checking..." : "Rebuilding...",
+ });
+ try {
+ setStatus({
+ type: "done",
+ mode,
+ rows: await adminRebuildMissingManifests(input, mode),
+ });
+ } catch (err) {
+ setStatus({
+ type: "error",
+ message: err instanceof Error ? err.message : "Something went wrong",
+ });
+ }
+ },
+ [input, working],
+ );
+
+ const loadNext = useCallback(async () => {
+ if (working) return;
+ setStatus({ type: "working", label: "Loading..." });
+ try {
+ const ids = await adminListMissingManifestCandidates();
+ setInput(ids.join("\n"));
+ setStatus({ type: "idle" });
+ } catch (err) {
+ setStatus({
+ type: "error",
+ message: err instanceof Error ? err.message : "Something went wrong",
+ });
+ }
+ }, [working]);
+
+ return (
+ <div className="mx-auto w-full max-w-xl px-5 py-8 md:px-8 md:py-10">
+ <div className="mb-6">
+ <Link
+ href="/admin"
+ className="mb-4 inline-flex text-sm font-medium text-gray-500 transition hover:text-gray-900"
+ >
+ Back to admin
+ </Link>
+ <h1 className="text-2xl font-semibold tracking-tight text-gray-900">
+ Rebuild missing manifests
+ </h1>
+ <p className="mt-1 text-sm text-gray-500">
+ For desktop recordings whose segments uploaded but whose manifest
+ never did. Check reads the uploaded segments and reports what a
+ rebuilt manifest would contain. Rebuild writes it and starts
+ processing. Recordings with missing segments are refused. Up to 10 at
+ a time.
+ </p>
+ </div>
+
+ <div className="space-y-5">
+ <div>
+ <label
+ htmlFor={inputId}
+ className="mb-1.5 block text-sm font-medium text-gray-700"
+ >
+ Video IDs or share URLs
+ </label>
+ <textarea
+ id={inputId}
+ value={input}
+ onChange={(e) => setInput(e.target.value)}
+ rows={6}
+ placeholder="One per line"
+ className="w-full rounded-lg border border-gray-300 px-3.5 py-2.5 text-sm text-gray-900 outline-none transition placeholder:text-gray-400 hover:border-gray-400 focus:border-blue-500 focus:ring-2 focus:ring-blue-100"
+ />
+ </div>
+ <div className="flex gap-2">
+ <button
+ type="button"
+ onClick={loadNext}
+ disabled={working}
+ className="rounded-lg border border-gray-300 px-4 py-2.5 text-sm font-medium text-gray-700 transition hover:bg-gray-50 disabled:opacity-40"
+ >
+ Load next 10
+ </button>
+ <button
+ type="button"
+ onClick={() => run("check")}
+ disabled={!input.trim() || working}
+ className="flex-1 rounded-lg border border-gray-300 px-4 py-2.5 text-sm font-medium text-gray-700 transition hover:bg-gray-50 disabled:opacity-40"
+ >
+ Check
+ </button>
+ <button
+ type="button"
+ onClick={() => run("rebuild")}
+ disabled={!input.trim() || working}
+ className="flex-1 rounded-lg bg-gray-900 px-4 py-2.5 text-sm font-medium text-white transition hover:bg-gray-800 disabled:opacity-40"
+ >
+ {working ? status.label : "Rebuild"}
+ </button>
+ </div>
+ </div>
+
+ {status.type === "done" && (
+ <ul className="mt-4 space-y-2 text-sm">
+ {status.rows.map((row) => (
+ <li
+ key={row.input}
+ className={`rounded-lg border px-4 py-2 ${
+ SUCCESS.has(row.status)
+ ? "border-emerald-200 bg-emerald-50 text-emerald-700"
+ : "border-amber-200 bg-amber-50 text-amber-800"
+ }`}
+ >
+ <span className="font-medium">{row.videoId ?? row.input}</span>:{" "}
+ {row.status}
+ {row.detail ? ` (${row.detail})` : ""}
+ {row.shareUrl && (
+ <Link
+ href={row.shareUrl}
+ className="ml-2 underline underline-offset-2"
+ >
+ Open
+ </Link>
+ )}
+ </li>
+ ))}
+ </ul>
+ )}
+
+ {status.type === "error" && (
+ <div className="mt-4 rounded-lg border border-red-200 bg-red-50 px-4 py-3 text-sm text-red-700">
+ {status.message}
+ </div>
+ )}
+ </div>
+ );
+}
diff --git a/apps/web/lib/desktop-manifest-rebuild.ts b/apps/web/lib/desktop-manifest-rebuild.ts
new file mode 100644
index 000000000..faf47a707
--- /dev/null
+++ b/apps/web/lib/desktop-manifest-rebuild.ts
@@ -0,0 +1,431 @@
+import { db } from "@cap/database";
+import {
+ videoProcessingJobs,
+ videos,
+ videoUploads,
+} from "@cap/database/schema";
+import { Storage } from "@cap/web-backend";
+import { type User, Video } from "@cap/web-domain";
+import { and, asc, eq, isNull, like } from "drizzle-orm";
+import { Option } from "effect";
+import {
+ DESKTOP_RECORDING_SOURCE_REUPLOAD_REQUIRED,
+ DesktopRecordingSourceBlockedError,
+ SourceCommitPendingError,
+} from "@/lib/desktop-recording-jobs";
+import { readCompletedRecordingManifest } from "@/lib/desktop-recording-verification";
+import { queueDesktopSegmentsFinalization } from "@/lib/desktop-segments-finalization";
+import {
+ type FragmentedTrackTiming,
+ readFragmentDuration,
+ readInitTiming,
+} from "@/lib/fragmented-mp4-duration";
+import { runPromise } from "@/lib/server";
+import { decodeStorageVideo } from "@/lib/video-storage";
+
+// The September backfill wrote this exact reason for uploads whose segments exist but whose manifest never arrived.
+export const MISSING_MANIFEST_ERROR_PREFIX = `${DESKTOP_RECORDING_SOURCE_REUPLOAD_REQUIRED}: The recording manifest is missing`;
+const INCOMPLETE_REBUILD_ERROR_PREFIX = `${DESKTOP_RECORDING_SOURCE_REUPLOAD_REQUIRED}: The missing manifest could not be rebuilt`;
+
+const MAX_INIT_BYTES = 1024 * 1024;
+const MAX_SEGMENT_SECONDS = 30;
+const DURATION_READ_CONCURRENCY = 32;
+// Video and audio segments are cut on the same schedule, so a large gap means one track stopped uploading early.
+const MAX_TRACK_DURATION_GAP_SECONDS = 5;
+const MAX_TRACK_DURATION_GAP_RATIO = 0.05;
+
+type Track = "video" | "audio";
+
+interface SegmentObject {
+ index: number;
+ size: number;
+}
+
+interface TrackInventory {
+ initSize?: number;
+ segments: SegmentObject[];
+}
+
+export type ManifestRebuildInspection =
+ | {
+ status: "ready";
+ videoId: Video.VideoId;
+ ownerId: User.UserId;
+ manifest: string;
+ videoSegments: number;
+ audioSegments: number;
+ durationSeconds: number;
+ }
+ | { status: "not-found" }
+ | { status: "not-eligible"; reason: string }
+ | { status: "unsupported-storage" }
+ | { status: "manifest-exists" }
+ | { status: "incomplete"; reason: string };
+
+export type ManifestRebuildResult =
+ | Exclude<ManifestRebuildInspection, { status: "ready" }>
+ | {
+ status: "checked" | "queued" | "already-processing";
+ videoSegments: number;
+ audioSegments: number;
+ durationSeconds: number;
+ }
+ | { status: "blocked"; reason: string };
+
+class IncompleteSegmentsError extends Error {}
+
+function incomplete(reason: string): never {
+ throw new IncompleteSegmentsError(reason);
+}
+
+async function mapBounded<T, R>(
+ items: T[],
+ limit: number,
+ operation: (item: T) => Promise<R>,
+) {
+ const output = new Array<R>(items.length);
+ let next = 0;
+ await Promise.all(
+ Array.from({ length: Math.min(limit, items.length) }, async () => {
+ while (next < items.length) {
+ const index = next++;
+ output[index] = await operation(items[index] as T);
+ }
+ }),
+ );
+ return output;
+}
+
+type RecordingBucket = Awaited<ReturnType<typeof loadStorage>>["bucket"];
+
+async function loadStorage(video: typeof videos.$inferSelect) {
+ const [bucket, customBucket] = await Storage.getAccessForVideo(
+ decodeStorageVideo(video),
+ { resolvePublishedOutput: false },
+ ).pipe(runPromise);
+ return {
+ bucket,
+ cap: bucket.provider === "s3" && Option.isNone(customBucket),
+ };
+}
+
+async function listTrack(
+ bucket: RecordingBucket,
+ source: Video.SegmentsSource,
+ track: Track,
+): Promise<TrackInventory> {
+ const prefix = `${source.ownerId}/${source.videoId}/segments/${track}/`;
+ const inventory: TrackInventory = { segments: [] };
+ const seen = new Set<number>();
+ let continuationToken: string | undefined;
+ do {
+ const page = await bucket
+ .listObjects({ prefix, maxKeys: 1000, continuationToken })
+ .pipe(runPromise);
+ for (const object of page.Contents ?? []) {
+ const key = object.Key ?? "";
+ const name = key.slice(prefix.length);
+ const size = object.Size ?? 0;
+ if (name === "init.mp4") {
+ inventory.initSize = size;
+ continue;
+ }
+ const match = /^segment_(\d+)\.m4s$/.exec(name);
+ if (!match) continue;
+ const index = Number(match[1]);
+ const expected =
+ track === "video"
+ ? source.getVideoSegmentKey(index)
+ : source.getAudioSegmentKey(index);
+ if (key !== expected || seen.has(index))
+ incomplete(`${track} segment ${name} does not match its expected name`);
+ if (size <= 0) incomplete(`${track} segment ${index} is empty`);
+ seen.add(index);
+ inventory.segments.push({ index, size });
+ }
+ continuationToken = page.IsTruncated
+ ? page.NextContinuationToken
+ : undefined;
+ } while (continuationToken);
+ inventory.segments.sort((left, right) => left.index - right.index);
+ inventory.segments.forEach((segment, position) => {
+ if (segment.index !== position + 1)
+ incomplete(`${track} segment ${position + 1} is missing`);
+ });
+ return inventory;
+}
+
+function rangeReader(bucket: RecordingBucket, key: string) {
+ let url: Promise<string | undefined> | undefined;
+ return async (start: number, end: number) => {
+ url ??= bucket
+ .getInternalSignedObjectUrl(key, { expiresIn: 600 })
+ .pipe(runPromise);
+ const signedUrl = await url;
+ if (!signedUrl) throw new Error("Segment URL could not be signed");
+ const response = await fetch(signedUrl, {
+ headers: { Range: `bytes=${start}-${end - 1}` },
+ });
+ if (response.status !== 206 && response.status !== 200)
+ throw new Error(`Segment read failed with HTTP ${response.status}`);
+ const bytes = new Uint8Array(await response.arrayBuffer());
+ // A server that ignores Range returns the whole object from byte 0.
+ return response.status === 200 ? bytes.subarray(start, end) : bytes;
+ };
+}
+
+async function trackDurations(
+ bucket: RecordingBucket,
+ source: Video.SegmentsSource,
+ track: Track,
+ inventory: TrackInventory,
+) {
+ const initKey =
+ track === "video" ? source.getVideoInitKey() : source.getAudioInitKey();
+ if (!inventory.initSize || inventory.initSize > MAX_INIT_BYTES)
+ incomplete(`${track} init segment is missing or too large`);
+ let timing: FragmentedTrackTiming;
+ try {
+ timing = readInitTiming(
+ await rangeReader(bucket, initKey)(0, inventory.initSize),
+ );
+ } catch (error) {
+ incomplete(
+ `${track} init segment is unreadable (${error instanceof Error ? error.message : String(error)})`,
+ );
+ }
+ return mapBounded(
+ inventory.segments,
+ DURATION_READ_CONCURRENCY,
+ async (segment) => {
+ const key =
+ track === "video"
+ ? source.getVideoSegmentKey(segment.index)
+ : source.getAudioSegmentKey(segment.index);
+ let duration: number;
+ try {
+ duration = await readFragmentDuration(
+ rangeReader(bucket, key),
+ segment.size,
+ timing,
+ );
+ } catch (error) {
+ incomplete(
+ `${track} segment ${segment.index} is unreadable (${error instanceof Error ? error.message : String(error)})`,
+ );
+ }
+ if (!(duration > 0 && duration <= MAX_SEGMENT_SECONDS))
+ incomplete(`${track} segment ${segment.index} lasts ${duration} s`);
+ return { index: segment.index, duration: Number(duration.toFixed(6)) };
+ },
+ );
+}
+
+async function loadCandidate(videoId: Video.VideoId) {
+ const [row] = await db()
+ .select({
+ video: videos,
+ processingError: videoUploads.processingError,
+ job: videoProcessingJobs,
+ })
+ .from(videos)
+ .leftJoin(videoUploads, eq(videoUploads.videoId, videos.id))
+ .leftJoin(videoProcessingJobs, eq(videoProcessingJobs.videoId, videos.id))
+ .where(eq(videos.id, videoId))
+ .limit(1);
+ return row;
+}
+
+export async function inspectMissingManifestRecording(
+ videoId: Video.VideoId,
+): Promise<ManifestRebuildInspection> {
+ const row = await loadCandidate(videoId);
+ if (!row) return { status: "not-found" };
+ const { video, processingError, job } = row;
+ if (video.source.type !== "desktopSegments")
+ return { status: "not-eligible", reason: `source is ${video.source.type}` };
+ if (!processingError?.startsWith(MISSING_MANIFEST_ERROR_PREFIX))
+ return {
+ status: "not-eligible",
+ reason: "the upload is not waiting on a missing manifest",
+ };
+ if (
+ job &&
+ (job.state !== "source-blocked" ||
+ job.errorCode !== DESKTOP_RECORDING_SOURCE_REUPLOAD_REQUIRED ||
+ job.source !== null ||
+ job.verification !== null)
+ )
+ return {
+ status: "not-eligible",
+ reason: `processing job is ${job.state}${job.errorCode ? ` (${job.errorCode})` : ""}`,
+ };
+ const { bucket, cap } = await loadStorage(video);
+ if (!cap) return { status: "unsupported-storage" };
+ const source = new Video.SegmentsSource({ videoId, ownerId: video.ownerId });
+ if (
+ Option.isSome(
+ await bucket.getObject(source.getManifestKey()).pipe(runPromise),
+ )
+ )
+ return { status: "manifest-exists" };
+
+ try {
+ const [videoTrack, audioTrack] = await Promise.all([
+ listTrack(bucket, source, "video"),
+ listTrack(bucket, source, "audio"),
+ ]);
+ if (videoTrack.segments.length === 0)
+ incomplete("no video segments were uploaded");
+ const hasAudio = audioTrack.segments.length > 0;
+ if (!hasAudio && audioTrack.initSize !== undefined)
+ incomplete("audio init was uploaded without any audio segments");
+ const [videoSegments, audioSegments] = await Promise.all([
+ trackDurations(bucket, source, "video", videoTrack),
+ hasAudio
+ ? trackDurations(bucket, source, "audio", audioTrack)
+ : Promise.resolve([]),
+ ]);
+ const total = (entries: { duration: number }[]) =>
+ entries.reduce((sum, entry) => sum + entry.duration, 0);
+ const videoSeconds = total(videoSegments);
+ if (hasAudio) {
+ const gap = Math.abs(videoSeconds - total(audioSegments));
+ if (
+ gap >
+ Math.max(
+ MAX_TRACK_DURATION_GAP_SECONDS,
+ videoSeconds * MAX_TRACK_DURATION_GAP_RATIO,
+ )
+ )
+ incomplete(
+ `audio covers ${total(audioSegments).toFixed(1)} s of ${videoSeconds.toFixed(1)} s of video`,
+ );
+ }
+ const manifest = `${JSON.stringify(
+ {
+ version: 2,
+ video_init_uploaded: true,
+ audio_init_uploaded: hasAudio,
+ video_segments: videoSegments,
+ audio_segments: audioSegments,
+ is_complete: true,
+ },
+ null,
+ 2,
+ )}\n`;
+ readCompletedRecordingManifest(manifest);
+ return {
+ status: "ready",
+ videoId,
+ ownerId: video.ownerId as User.UserId,
+ manifest,
+ videoSegments: videoSegments.length,
+ audioSegments: audioSegments.length,
+ durationSeconds: Number(videoSeconds.toFixed(3)),
+ };
+ } catch (error) {
+ if (error instanceof IncompleteSegmentsError)
+ return { status: "incomplete", reason: error.message };
+ throw error;
+ }
+}
+
+export async function rebuildMissingManifest(
+ videoId: Video.VideoId,
+ { dryRun }: { dryRun: boolean },
+): Promise<ManifestRebuildResult> {
+ const inspected = await inspectMissingManifestRecording(videoId);
+ if (inspected.status === "incomplete" && !dryRun) {
+ // Recording why it was refused keeps it out of the next candidate batch.
+ await db()
+ .update(videoUploads)
+ .set({
+ processingError: `${INCOMPLETE_REBUILD_ERROR_PREFIX}: ${inspected.reason}. Uploaded files are retained.`,
+ updatedAt: new Date(),
+ })
+ .where(
+ and(
+ eq(videoUploads.videoId, videoId),
+ like(
+ videoUploads.processingError,
+ `${MISSING_MANIFEST_ERROR_PREFIX}%`,
+ ),
+ ),
+ );
+ }
+ if (inspected.status !== "ready") return inspected;
+ const summary = {
+ videoSegments: inspected.videoSegments,
+ audioSegments: inspected.audioSegments,
+ durationSeconds: inspected.durationSeconds,
+ };
+ if (dryRun) return { status: "checked", ...summary };
+
+ const row = await loadCandidate(videoId);
+ if (!row) return { status: "not-found" };
+ const { bucket } = await loadStorage(row.video);
+ const source = new Video.SegmentsSource({
+ videoId,
+ ownerId: inspected.ownerId,
+ });
+ // The desktop client that owned this upload stopped months ago, so the only writer to race is another operator run.
+ if (
+ Option.isSome(
+ await bucket.getObject(source.getManifestKey()).pipe(runPromise),
+ )
+ )
+ return { status: "manifest-exists" };
+ await bucket
+ .putObject(source.getManifestKey(), inspected.manifest, {
+ contentType: "application/json",
+ })
+ .pipe(runPromise);
+
+ let status: "queued" | "already-processing";
+ try {
+ status = await queueDesktopSegmentsFinalization({
+ videoId,
+ userId: inspected.ownerId,
+ });
+ } catch (error) {
+ if (error instanceof DesktopRecordingSourceBlockedError)
+ return { status: "blocked", reason: error.message };
+ if (!(error instanceof SourceCommitPendingError)) throw error;
+ status = "queued";
+ }
+ // A reset job keeps its old upload row; only clear it while it still shows the missing-manifest reason.
+ await db()
+ .update(videoUploads)
+ .set({
+ phase: "processing",
+ processingProgress: 0,
+ processingMessage: "Securing recording source...",
+ processingError: null,
+ updatedAt: new Date(),
+ })
+ .where(
+ and(
+ eq(videoUploads.videoId, videoId),
+ like(videoUploads.processingError, `${MISSING_MANIFEST_ERROR_PREFIX}%`),
+ ),
+ );
+ return { status, ...summary };
+}
+
+export async function listMissingManifestCandidates(limit: number) {
+ const rows = await db()
+ .select({ videoId: videoUploads.videoId })
+ .from(videoUploads)
+ .innerJoin(videos, eq(videos.id, videoUploads.videoId))
+ .where(
+ and(
+ like(videoUploads.processingError, `${MISSING_MANIFEST_ERROR_PREFIX}%`),
+ isNull(videos.bucket),
+ isNull(videos.storageIntegrationId),
+ ),
+ )
+ .orderBy(asc(videos.createdAt))
+ .limit(limit);
+ return rows.map((row: { videoId: string }) => row.videoId);
+}
diff --git a/apps/web/lib/fragmented-mp4-duration.ts b/apps/web/lib/fragmented-mp4-duration.ts
new file mode 100644
index 000000000..7371f7b6b
--- /dev/null
+++ b/apps/web/lib/fragmented-mp4-duration.ts
@@ -0,0 +1,190 @@
+export type ReadRange = (start: number, end: number) => Promise<Uint8Array>;
+
+export interface FragmentedTrackTiming {
+ timescale: number;
+ defaultSampleDuration?: number;
+}
+
+export class FragmentedMp4Error extends Error {}
+
+const HEADER_WINDOW_BYTES = 64 * 1024;
+const MAX_BOX_READ_BYTES = 8 * 1024 * 1024;
+
+interface Box {
+ type: string;
+ start: number;
+ contentStart: number;
+ end: number;
+}
+
+function readBoxHeader(bytes: Uint8Array, offset: number) {
+ if (offset + 8 > bytes.byteLength)
+ throw new FragmentedMp4Error("Truncated MP4 box header");
+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+ const type = String.fromCharCode(...bytes.subarray(offset + 4, offset + 8));
+ const declared = view.getUint32(offset);
+ if (declared !== 1) return { type, size: declared, header: 8 };
+ if (offset + 16 > bytes.byteLength)
+ throw new FragmentedMp4Error("Truncated MP4 box header");
+ const large = view.getBigUint64(offset + 8);
+ if (large > BigInt(Number.MAX_SAFE_INTEGER))
+ throw new FragmentedMp4Error("MP4 box is too large");
+ return { type, size: Number(large), header: 16 };
+}
+
+function readBox(bytes: Uint8Array, offset: number, limit: number): Box {
+ const header = readBoxHeader(bytes, offset);
+ const size = header.size === 0 ? limit - offset : header.size;
+ if (size < header.header || offset + size > limit)
+ throw new FragmentedMp4Error(`Invalid MP4 ${header.type} box size`);
+ return {
+ type: header.type,
+ start: offset,
+ contentStart: offset + header.header,
+ end: offset + size,
+ };
+}
+
+function children(bytes: Uint8Array, box: Pick<Box, "contentStart" | "end">) {
+ const result: Box[] = [];
+ for (let offset = box.contentStart; offset < box.end; ) {
+ const child = readBox(bytes, offset, box.end);
+ result.push(child);
+ offset = child.end;
+ }
+ return result;
+}
+
+function child(bytes: Uint8Array, box: Box, type: string) {
+ return children(bytes, box).find((entry) => entry.type === type);
+}
+
+function fullBox(bytes: Uint8Array, box: Box) {
+ if (box.contentStart + 4 > box.end)
+ throw new FragmentedMp4Error(`Truncated MP4 ${box.type} box`);
+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+ const word = view.getUint32(box.contentStart);
+ return {
+ view,
+ version: word >>> 24,
+ flags: word & 0xffffff,
+ body: box.contentStart + 4,
+ };
+}
+
+export function readInitTiming(bytes: Uint8Array): FragmentedTrackTiming {
+ const top = children(bytes, { contentStart: 0, end: bytes.byteLength });
+ const moov = top.find((box) => box.type === "moov");
+ if (!moov) throw new FragmentedMp4Error("Init segment has no moov box");
+ const traks = children(bytes, moov).filter((box) => box.type === "trak");
+ if (traks.length !== 1)
+ throw new FragmentedMp4Error("Init segment must hold exactly one track");
+ const mdia = child(bytes, traks[0] as Box, "mdia");
+ const mdhd = mdia && child(bytes, mdia, "mdhd");
+ if (!mdhd) throw new FragmentedMp4Error("Init segment has no mdhd box");
+ const header = fullBox(bytes, mdhd);
+ const timescaleOffset = header.body + (header.version === 1 ? 16 : 8);
+ if (timescaleOffset + 4 > mdhd.end)
+ throw new FragmentedMp4Error("Truncated mdhd box");
+ const timescale = header.view.getUint32(timescaleOffset);
+ if (timescale === 0) throw new FragmentedMp4Error("Track timescale is zero");
+
+ const mvex = child(bytes, moov, "mvex");
+ const trex = mvex && child(bytes, mvex, "trex");
+ if (!trex) return { timescale };
+ const defaults = fullBox(bytes, trex);
+ if (defaults.body + 12 > trex.end)
+ throw new FragmentedMp4Error("Truncated trex box");
+ const defaultSampleDuration = defaults.view.getUint32(defaults.body + 8);
+ return defaultSampleDuration > 0
+ ? { timescale, defaultSampleDuration }
+ : { timescale };
+}
+
+function moofTicks(
+ bytes: Uint8Array,
+ moof: Box,
+ timing: FragmentedTrackTiming,
+) {
+ let ticks = 0;
+ for (const traf of children(bytes, moof).filter(
+ (box) => box.type === "traf",
+ )) {
+ const tfhd = child(bytes, traf, "tfhd");
+ if (!tfhd) throw new FragmentedMp4Error("Fragment has no tfhd box");
+ const header = fullBox(bytes, tfhd);
+ let offset = header.body + 4;
+ if (header.flags & 0x01) offset += 8;
+ if (header.flags & 0x02) offset += 4;
+ let defaultDuration = timing.defaultSampleDuration;
+ if (header.flags & 0x08) {
+ if (offset + 4 > tfhd.end)
+ throw new FragmentedMp4Error("Truncated tfhd box");
+ defaultDuration = header.view.getUint32(offset);
+ }
+ for (const trun of children(bytes, traf).filter(
+ (box) => box.type === "trun",
+ )) {
+ const run = fullBox(bytes, trun);
+ if (run.body + 4 > trun.end)
+ throw new FragmentedMp4Error("Truncated trun box");
+ const count = run.view.getUint32(run.body);
+ let cursor = run.body + 4;
+ if (run.flags & 0x01) cursor += 4;
+ if (run.flags & 0x04) cursor += 4;
+ const fields = [0x100, 0x200, 0x400, 0x800].filter(
+ (flag) => run.flags & flag,
+ );
+ if (cursor + count * fields.length * 4 > trun.end)
+ throw new FragmentedMp4Error("Truncated trun samples");
+ if (!(run.flags & 0x100)) {
+ if (!defaultDuration)
+ throw new FragmentedMp4Error("Fragment samples have no duration");
+ ticks += count * defaultDuration;
+ continue;
+ }
+ for (let sample = 0; sample < count; sample++) {
+ ticks += run.view.getUint32(cursor);
+ cursor += fields.length * 4;
+ }
+ }
+ }
+ return ticks;
+}
+
+// Walks top-level boxes with ranged reads, so media data is skipped instead of downloaded.
+export async function readFragmentDuration(
+ read: ReadRange,
+ size: number,
+ timing: FragmentedTrackTiming,
+): Promise<number> {
+ let ticks = 0;
+ let moofs = 0;
+ let window: Uint8Array = new Uint8Array();
+ let windowStart = 0;
+ for (let offset = 0; offset < size; ) {
+ if (offset + 16 > windowStart + window.byteLength) {
+ windowStart = offset;
+ window = await read(offset, Math.min(size, offset + HEADER_WINDOW_BYTES));
+ if (window.byteLength === 0)
+ throw new FragmentedMp4Error("Segment read returned no data");
+ }
+ const header = readBoxHeader(window, offset - windowStart);
+ const boxSize = header.size === 0 ? size - offset : header.size;
+ if (boxSize < header.header || offset + boxSize > size)
+ throw new FragmentedMp4Error(`Invalid MP4 ${header.type} box size`);
+ if (header.type === "moof") {
+ if (boxSize > MAX_BOX_READ_BYTES)
+ throw new FragmentedMp4Error("Fragment header is too large");
+ const inWindow = offset + boxSize <= windowStart + window.byteLength;
+ const bytes = inWindow ? window : await read(offset, offset + boxSize);
+ const start = inWindow ? offset - windowStart : 0;
+ ticks += moofTicks(bytes, readBox(bytes, start, start + boxSize), timing);
+ moofs++;
+ }
+ offset += boxSize;
+ }
+ if (moofs === 0) throw new FragmentedMp4Error("Segment has no moof box");
+ if (ticks <= 0) throw new FragmentedMp4Error("Segment has no samples");
+ return ticks / timing.timescale;
+}