Open source Loom alternative. Beautiful, shareable screen recordings.
Rust appcapcossloommacnextjsnextjs15open-sourceossreactrecordrustscreen-capturescreen-recorderscreenshotsolidjstauritauri-apptypescriptvite
feat(web): add an early playback mode to the segment playlist API
Richie McIlroy1079e0847e2a
diff --git a/apps/web/__tests__/unit/early-segment-playback.test.ts b/apps/web/__tests__/unit/early-segment-playback.test.tsnew file mode 100644index 000000000..81b13b5ca--- /dev/null+++ b/apps/web/__tests__/unit/early-segment-playback.test.ts@@ -0,0 +1,119 @@+import { afterEach, describe, expect, it, vi } from "vitest";+import { isEarlyInstantPlaybackEnabled } from "@/lib/early-instant-playback";+import {+ contiguousSegmentPrefix,+ getEarlySegmentTracks,+} from "@/lib/segment-playback";++const uploading = {+ version: 2,+ video_init_uploaded: true,+ audio_init_uploaded: true,+ video_segments: [+ { index: 1, duration: 2 },+ { index: 2, duration: 2 },+ ],+ audio_segments: [{ index: 1, duration: 2 }],+ is_complete: false,+};++describe("Contiguous segment prefix", () => {+ it("stops at the first segment still in flight", () => {+ expect(+ contiguousSegmentPrefix([+ { index: 1, duration: 2 },+ { index: 2, duration: 2 },+ { index: 4, duration: 2 },+ ]).map((segment) => segment.index),+ ).toEqual([1, 2]);+ });++ it("is empty while the first segment is still uploading", () => {+ expect(contiguousSegmentPrefix([{ index: 2, duration: 2 }])).toEqual([]);+ });++ it("orders entries and reads legacy bare indexes", () => {+ expect(contiguousSegmentPrefix([2, 1, 3])).toEqual([+ { index: 1, duration: 3 },+ { index: 2, duration: 3 },+ { index: 3, duration: 3 },+ ]);+ });++ it("does not treat a 0-based list as a playable run", () => {+ expect(contiguousSegmentPrefix([0, 1, 2])).toEqual([]);+ });++ it("stops at a repeated index", () => {+ expect(contiguousSegmentPrefix([1, 1, 2]).map((s) => s.index)).toEqual([1]);+ });+});++describe("Early segment tracks", () => {+ it("plays the uploaded start of a stopped recording", () => {+ expect(getEarlySegmentTracks(uploading)).toEqual({+ video: uploading.video_segments,+ audio: uploading.audio_segments,+ });+ });++ it("leaves complete manifests to the regular playlist", () => {+ expect(getEarlySegmentTracks({ ...uploading, is_complete: true })).toBe(+ null,+ );+ });++ it("waits while audio has not started uploading", () => {+ expect(+ getEarlySegmentTracks({+ ...uploading,+ audio_init_uploaded: false,+ audio_segments: [],+ }),+ ).toBe(null);+ expect(getEarlySegmentTracks({ ...uploading, audio_segments: [] })).toBe(+ null,+ );+ expect(+ getEarlySegmentTracks({+ ...uploading,+ audio_segments: [{ index: 2, duration: 2 }],+ }),+ ).toBe(null);+ });++ it("waits for the video init and first video segment", () => {+ expect(+ getEarlySegmentTracks({ ...uploading, video_init_uploaded: false }),+ ).toBe(null);+ expect(+ getEarlySegmentTracks({+ ...uploading,+ video_segments: [{ index: 2, duration: 2 }],+ }),+ ).toBe(null);+ });+});++describe("Early instant playback flag", () => {+ afterEach(() => vi.unstubAllEnvs());++ it("is off unless configured", () => {+ vi.stubEnv("CAP_EARLY_INSTANT_PLAYBACK", "");+ expect(isEarlyInstantPlaybackEnabled("owner")).toBe(false);+ vi.stubEnv("CAP_EARLY_INSTANT_PLAYBACK", "true");+ expect(isEarlyInstantPlaybackEnabled("owner")).toBe(false);+ });++ it("can be enabled for everyone", () => {+ vi.stubEnv("CAP_EARLY_INSTANT_PLAYBACK", " enabled ");+ expect(isEarlyInstantPlaybackEnabled("owner")).toBe(true);+ });++ it("can be rolled out to listed owners", () => {+ vi.stubEnv("CAP_EARLY_INSTANT_PLAYBACK", "first, owner");+ expect(isEarlyInstantPlaybackEnabled("owner")).toBe(true);+ expect(isEarlyInstantPlaybackEnabled("other")).toBe(false);+ expect(isEarlyInstantPlaybackEnabled("own")).toBe(false);+ });+});diff --git a/apps/web/__tests__/unit/segment-playlist-route.test.ts b/apps/web/__tests__/unit/segment-playlist-route.test.tsindex d079178e3..391d9eb06 100644--- a/apps/web/__tests__/unit/segment-playlist-route.test.ts+++ b/apps/web/__tests__/unit/segment-playlist-route.test.ts@@ -4,6 +4,8 @@ import { afterAll, beforeEach, describe, expect, it, vi } from "vitest";const mocks = vi.hoisted(() => ({manifest: {} as Record<string, unknown>,+ recordedLength: null as string | null,+ recordedLengthFails: false,audioInitExists: false,storageUnavailable: false,denied: false,@@ -29,11 +31,17 @@ vi.mock("@cap/web-backend", async (importOriginal) => {const { Policy, Storage: StorageDomain } = await import("@cap/web-domain");const bucket = {provider: "s3",- getObject: () =>- Effect.sync(() => {- mocks.read();- return Option.some(JSON.stringify(mocks.manifest));- }),+ getObject: (key: string) =>+ key.endsWith("/segments/recording.json")+ ? mocks.recordedLengthFails+ ? Effect.fail(+ new StorageDomain.StorageError({ cause: "storage unavailable" }),+ )+ : Effect.succeed(Option.fromNullable(mocks.recordedLength))+ : Effect.sync(() => {+ mocks.read();+ return Option.some(JSON.stringify(mocks.manifest));+ }),getSignedObjectUrl: (key: string) =>Effect.sync(() => {mocks.sign(key);@@ -129,6 +137,8 @@ describe("Instant playlist readiness API", () => {is_complete: true,};mocks.audioInitExists = false;+ mocks.recordedLength = null;+ mocks.recordedLengthFails = false;mocks.storageUnavailable = false;mocks.denied = false;mocks.defaultBucket = false;@@ -159,6 +169,164 @@ describe("Instant playlist readiness API", () => {expect((await request("segments-master", "")).status).toBe(200);});+ it("keeps the regular playlists unchanged without early playback", async () => {+ mocks.manifest.is_complete = false;+ const video = await (await request("segments-video", "")).text();+ expect(video).not.toContain("#EXT-X-PLAYLIST-TYPE");+ expect(video).not.toContain("#EXT-X-START");+ expect(video).not.toContain("#EXT-X-ENDLIST");+ mocks.manifest.is_complete = true;+ const complete = await (await request("segments-video", "")).text();+ expect(complete).toContain("#EXT-X-PLAYLIST-TYPE:VOD");+ expect(complete).not.toContain("#EXT-X-START");+ const master = await (+ await request("segments-master", "&requireComplete=1")+ ).text();+ expect(master).not.toContain("earlyPlayback");+ expect(master).not.toContain("#EXT-X-START");+ });++ describe("early playback", () => {+ const early = "&earlyPlayback=1";+ beforeEach(() => {+ mocks.manifest.is_complete = false;+ mocks.manifest.video_segments = [+ { index: 1, duration: 2 },+ { index: 2, duration: 2 },+ { index: 4, duration: 2 },+ ];+ mocks.manifest.audio_segments = [{ index: 1, duration: 2 }];+ });++ it("is ready once the start of a stopped recording has uploaded", async () => {+ const response = await request("segments-status", early);+ expect(response.status).toBe(204);+ expect(response.headers.get("X-Cap-Recording-Complete")).toBe("0");+ });++ it("starts at the beginning and keeps every playlist in early mode", async () => {+ const master = await (await request("segments-master", early)).text();+ expect(master).toContain("#EXT-X-START:TIME-OFFSET=0");+ expect(master).toContain("videoType=segments-audio&earlyPlayback=1");+ expect(master).toContain("videoType=segments-video&earlyPlayback=1");+ });++ it("lists only the segments with no gap before them", async () => {+ const video = await (await request("segments-video", early)).text();+ expect(video).toContain("#EXT-X-PLAYLIST-TYPE:EVENT");+ expect(video).toContain("#EXT-X-START:TIME-OFFSET=0");+ expect(video).not.toContain("#EXT-X-ENDLIST");+ expect(video).toContain("segment_001.m4s");+ expect(video).toContain("segment_002.m4s");+ expect(video).not.toContain("segment_004.m4s");+ });++ it("ends the same playlist once the recording is complete", async () => {+ mocks.manifest.is_complete = true;+ mocks.manifest.video_segments = [1, 2, 3];+ mocks.manifest.audio_segments = [1, 2, 3];+ const status = await request("segments-status", early);+ expect(status.status).toBe(204);+ expect(status.headers.get("X-Cap-Recording-Complete")).toBe("1");+ const video = await (await request("segments-video", early)).text();+ expect(video).toContain("#EXT-X-PLAYLIST-TYPE:EVENT");+ expect(video).toContain("#EXT-X-ENDLIST");+ expect(video.match(/#EXTINF/g)).toHaveLength(3);+ });++ it("waits for the complete manifest while audio has not started", async () => {+ mocks.manifest.audio_init_uploaded = false;+ mocks.manifest.audio_segments = [];+ expect((await request("segments-status", early)).status).toBe(202);+ expect((await request("segments-master", early)).status).toBe(404);+ expect((await request("segments-video", early)).status).toBe(404);+ });++ it("plays a complete silent recording", async () => {+ mocks.manifest.is_complete = true;+ mocks.manifest.audio_init_uploaded = false;+ mocks.manifest.audio_segments = [];+ mocks.manifest.video_segments = [1, 2];+ expect((await request("segments-status", early)).status).toBe(204);+ const master = await (await request("segments-master", early)).text();+ expect(master).not.toContain("#EXT-X-MEDIA:TYPE=AUDIO");+ });++ it("still rejects a complete manifest with missing segments", async () => {+ mocks.manifest.is_complete = true;+ expect((await request("segments-status", early)).status).toBe(409);+ });++ it("reports what plays from the start and the recorded length", async () => {+ mocks.manifest.audio_segments = [+ { index: 1, duration: 2 },+ { index: 2, duration: 1.5 },+ ];+ mocks.recordedLength = JSON.stringify({+ version: 1,+ duration: 120.04,+ video_segments: 61,+ audio_segments: 61,+ });+ const response = await request("segments-status", early);+ expect(response.headers.get("X-Cap-Ready-Duration")).toBe("3.500");+ expect(response.headers.get("X-Cap-Recorded-Duration")).toBe("120.040");+ });++ it.each([+ ["missing", null],+ ["malformed", "{"],+ [+ "from a newer format",+ '{"version":2,"duration":120,"video_segments":61}',+ ],+ [+ "shorter than what uploaded",+ '{"version":1,"duration":1,"video_segments":1}',+ ],+ ["implausibly long", '{"version":1,"duration":90000,"video_segments":1}'],+ ])("leaves the recorded length out when it is %s", async (_, content) => {+ mocks.recordedLength = content;+ const response = await request("segments-status", early);+ expect(response.status).toBe(204);+ // Audio has only uploaded its first segment.+ expect(response.headers.get("X-Cap-Ready-Duration")).toBe("2.000");+ expect(response.headers.get("X-Cap-Recorded-Duration")).toBe(null);+ });++ it("still answers when the recorded length cannot be read", async () => {+ mocks.recordedLengthFails = true;+ const response = await request("segments-status", early);+ expect(response.status).toBe(204);+ expect(response.headers.get("X-Cap-Recorded-Duration")).toBe(null);+ });++ it("reports the full length once complete without reading the file", async () => {+ mocks.manifest.is_complete = true;+ mocks.manifest.video_segments = [1, 2, 3];+ mocks.manifest.audio_segments = [1, 2, 3];+ mocks.recordedLengthFails = true;+ const response = await request("segments-status", early);+ expect(response.headers.get("X-Cap-Ready-Duration")).toBe("9.000");+ expect(response.headers.get("X-Cap-Recorded-Duration")).toBe("9.000");+ });++ it("adds no length headers outside early playback", async () => {+ mocks.manifest.is_complete = true;+ mocks.manifest.video_segments = [1, 2, 3];+ mocks.manifest.audio_segments = [1, 2, 3];+ const response = await request("segments-status");+ expect(response.headers.get("X-Cap-Ready-Duration")).toBe(null);+ expect(response.headers.get("X-Cap-Recorded-Duration")).toBe(null);+ });++ it("defers to an explicit complete requirement", async () => {+ expect(+ (await request("segments-status", `${early}&requireComplete=1`)).status,+ ).toBe(202);+ });+ });+it("preserves legacy audio only when the missing init flag is contradicted by stored bytes", async () => {mocks.manifest.version = 1;mocks.manifest.audio_init_uploaded = false;diff --git a/apps/web/app/api/playlist/route.ts b/apps/web/app/api/playlist/route.tsindex 4a8c3c7f3..9ae76c839 100644--- a/apps/web/app/api/playlist/route.ts+++ b/apps/web/app/api/playlist/route.ts@@ -21,7 +21,12 @@ import {resolveMobileRequestOrigin,resolveMobileWebResourceUrl,} from "@/lib/mobile-request-origin";-import { getSegmentPlaybackState } from "@/lib/segment-playback";+import {+ getEarlySegmentTracks,+ getSegmentPlaybackState,+ readRecordedLength,+ totalSegmentDuration,+} from "@/lib/segment-playback";import { apiToHandler } from "@/lib/server";import { CACHE_CONTROL_HEADERS } from "@/utils/helpers";import {@@ -45,6 +50,7 @@ const GetPlaylistParams = Schema.Struct({"segments-status",),requireComplete: Schema.OptionFromUndefinedOr(Schema.String),+ earlyPlayback: Schema.OptionFromUndefinedOr(Schema.String),thumbnail: Schema.OptionFromUndefinedOr(Schema.String),fileType: Schema.OptionFromUndefinedOr(Schema.String),});@@ -244,21 +250,67 @@ const getPlaylistResponse = (onNone: () => false,onSome: (value) => value === "1" || value === "true",});+ // Early playback starts a stopped recording from its first segment+ // while the last ones are still uploading: the playlist grows in+ // place until the complete manifest ends it.+ const earlyPlayback =+ !requireComplete &&+ Option.match(urlParams.earlyPlayback, {+ onNone: () => false,+ onSome: (value) => value === "1",+ });+ const earlyTracks = earlyPlayback+ ? getEarlySegmentTracks(manifest)+ : null;+ const waitsForComplete = requireComplete || earlyPlayback;const hasVideoSegments =manifest.video_init_uploaded && manifest.video_segments.length > 0;if (urlParams.videoType === "segments-status") {- return HttpServerResponse.empty({- status:- hasVideoSegments && (!requireComplete || playbackState === "ready")- ? 204- : 202,- headers: {- ...CACHE_CONTROL_HEADERS,- "X-Cap-Recording-Complete": playbackState === "ready" ? "1" : "0",- },- });+ const status =+ earlyTracks !== null ||+ (hasVideoSegments && (!waitsForComplete || playbackState === "ready"))+ ? 204+ : 202;+ const headers: Record<string, string> = {+ ...CACHE_CONTROL_HEADERS,+ "X-Cap-Recording-Complete": playbackState === "ready" ? "1" : "0",+ };+ if (earlyPlayback && status === 204) {+ // What plays from the start right now, and the full length the+ // player can show while the rest uploads.+ const complete = playbackState === "ready";+ const fullLength = totalSegmentDuration(+ manifest.video_segments.map(Video.normalizeSegmentEntry),+ );+ const readyDuration = earlyTracks+ ? Math.min(+ totalSegmentDuration(earlyTracks.video),+ totalSegmentDuration(earlyTracks.audio),+ )+ : fullLength;+ const recordedDuration = complete+ ? fullLength+ : yield* bucket+ .getObject(+ `${video.ownerId}/${video.id}/segments/recording.json`,+ )+ .pipe(+ Effect.map(+ Option.match({+ onNone: () => null,+ onSome: (content) =>+ readRecordedLength(content, readyDuration),+ }),+ ),+ Effect.catchAll(() => Effect.succeed(null)),+ );+ headers["X-Cap-Ready-Duration"] = readyDuration.toFixed(3);+ if (recordedDuration !== null)+ headers["X-Cap-Recorded-Duration"] = recordedDuration.toFixed(3);+ }+ return HttpServerResponse.empty({ status, headers });}- if (requireComplete && !manifest.is_complete) {+ if (waitsForComplete && !manifest.is_complete && earlyTracks === null) {return yield* Effect.fail(new HttpApiError.NotFound());}@@ -270,14 +322,18 @@ const getPlaylistResponse = (const videoPlaylistUrl = `/api/playlist?videoId=${video.id}&videoType=segments-video`;const requireCompleteSuffix = requireComplete? "&requireComplete=1"- : "";+ : earlyPlayback+ ? "&earlyPlayback=1"+ : "";const audioPlaylistUrl =- manifest.audio_init_uploaded && manifest.audio_segments.length > 0+ earlyTracks !== null ||+ (manifest.audio_init_uploaded && manifest.audio_segments.length > 0)? `/api/playlist?videoId=${video.id}&videoType=segments-audio${requireCompleteSuffix}`: null;let playlist ="#EXTM3U\n#EXT-X-VERSION:7\n#EXT-X-INDEPENDENT-SEGMENTS\n";+ if (earlyPlayback) playlist += "#EXT-X-START:TIME-OFFSET=0\n";if (audioPlaylistUrl) {playlist += `#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="audio",NAME="default",DEFAULT=YES,AUTOSELECT=YES,URI="${audioPlaylistUrl}"\n`;playlist += `#EXT-X-STREAM-INF:BANDWIDTH=2000000,AUDIO="audio"\n`;@@ -298,10 +354,13 @@ const getPlaylistResponse = (const initKey = isVideo? segSource.getVideoInitKey(): segSource.getAudioInitKey();- const rawSegments = isVideo- ? manifest.video_segments- : manifest.audio_segments;- const segments = rawSegments.map(Video.normalizeSegmentEntry);+ const segments = earlyTracks+ ? isVideo+ ? earlyTracks.video+ : earlyTracks.audio+ : (isVideo ? manifest.video_segments : manifest.audio_segments).map(+ Video.normalizeSegmentEntry,+ );const initUploaded = isVideo? manifest.video_init_uploaded: manifest.audio_init_uploaded;@@ -341,7 +400,11 @@ const getPlaylistResponse = ();let playlist = `#EXTM3U\n#EXT-X-VERSION:7\n#EXT-X-TARGETDURATION:${Math.max(targetDuration, 1)}\n#EXT-X-MEDIA-SEQUENCE:0\n`;- if (manifest.is_complete) {+ if (earlyPlayback) {+ // EVENT keeps the type stable as the playlist grows and ends, and+ // tells players they may seek anywhere from the first segment.+ playlist += "#EXT-X-PLAYLIST-TYPE:EVENT\n#EXT-X-START:TIME-OFFSET=0\n";+ } else if (manifest.is_complete) {playlist += "#EXT-X-PLAYLIST-TYPE:VOD\n";}playlist += `#EXT-X-MAP:URI="${initUrl}"\n`;diff --git a/apps/web/lib/early-instant-playback.ts b/apps/web/lib/early-instant-playback.tsnew file mode 100644index 000000000..aea5c4a24--- /dev/null+++ b/apps/web/lib/early-instant-playback.ts@@ -0,0 +1,15 @@+/**+ * Whether a stopped instant recording may start playing from its first+ * segment while its last segments are still uploading.+ * `CAP_EARLY_INSTANT_PLAYBACK` is "enabled" for everyone, or a comma-separated+ * list of owner user ids to roll it out to; anything else leaves it off.+ */+export function isEarlyInstantPlaybackEnabled(ownerId: string): boolean {+ const setting = process.env.CAP_EARLY_INSTANT_PLAYBACK?.trim();+ if (!setting) return false;+ if (setting === "enabled") return true;+ return setting+ .split(",")+ .map((id) => id.trim())+ .includes(ownerId);+}diff --git a/apps/web/lib/segment-playback.ts b/apps/web/lib/segment-playback.tsindex 1060ac6a1..9f45f6d61 100644--- a/apps/web/lib/segment-playback.ts+++ b/apps/web/lib/segment-playback.ts@@ -1,4 +1,4 @@-import type { Video } from "@cap/web-domain";+import { Video } from "@cap/web-domain";import { readCompletedRecordingManifest } from "./desktop-recording-verification";export function getSegmentPlaybackState(@@ -12,3 +12,86 @@ export function getSegmentPlaybackState(return "incomplete";}}++type SegmentEntry = { index: number; duration: number };++/**+ * The run of segments numbered 1, 2, 3... with no gap. Uploads finish out of+ * order, so a progress manifest can list segment 12 while 11 is still in+ * flight. A playlist that skipped 11 would play the wrong media at that time,+ * then have to insert 11 mid-list later, which HLS players cannot follow.+ */+export function contiguousSegmentPrefix(+ entries: Video.SegmentManifestType["video_segments"],+): SegmentEntry[] {+ const sorted = entries+ .map(Video.normalizeSegmentEntry)+ .sort((a, b) => a.index - b.index);+ const prefix: SegmentEntry[] = [];+ for (const entry of sorted) {+ if (entry.index !== prefix.length + 1) break;+ prefix.push(entry);+ }+ return prefix;+}++/**+ * What can play from the start of a recording whose last segments are still+ * uploading, or null to keep waiting for the complete manifest. Audio only+ * proves it exists once it starts uploading, so a manifest without any audio+ * yet waits: it may belong to a recording whose audio is still on its way.+ */+export function getEarlySegmentTracks(+ manifest: Video.SegmentManifestType,+): { video: SegmentEntry[]; audio: SegmentEntry[] } | null {+ if (manifest.is_complete || !manifest.video_init_uploaded) return null;+ if (!manifest.audio_init_uploaded) return null;+ const video = contiguousSegmentPrefix(manifest.video_segments);+ const audio = contiguousSegmentPrefix(manifest.audio_segments);+ if (video.length === 0 || audio.length === 0) return null;+ return { video, audio };+}++export function totalSegmentDuration(+ entries: readonly { duration: number }[],+): number {+ return entries.reduce((total, entry) => total + entry.duration, 0);+}++const MAX_RECORDED_LENGTH_SECONDS = 24 * 60 * 60;++/**+ * The full length the desktop app records when a recording stops, before its+ * last segments finish uploading (`segments/recording.json`). Anything+ * malformed, implausible or shorter than what has already uploaded is ignored.+ */+export function readRecordedLength(+ content: string,+ readyDuration: number,+): number | null {+ let parsed: unknown;+ try {+ parsed = JSON.parse(content);+ } catch {+ return null;+ }+ if (typeof parsed !== "object" || parsed === null) return null;+ const { version, duration, video_segments } = parsed as Record<+ string,+ unknown+ >;+ if (+ version !== 1 ||+ typeof duration !== "number" ||+ !Number.isFinite(duration) ||+ duration <= 0 ||+ duration > MAX_RECORDED_LENGTH_SECONDS ||+ typeof video_segments !== "number" ||+ !Number.isInteger(video_segments) ||+ video_segments < 1 ||+ duration + 0.5 < readyDuration+ ) {+ return null;+ }+ return duration;+}