Skip to content

armgit / Cap

Public Imported from GitHub
0

Open source Loom alternative. Beautiful, shareable screen recordings.

refactor(web): keep only comments that explain playback constraints

Richie McIlroyda967749835f
diff --git a/apps/web/app/api/playlist/route.ts b/apps/web/app/api/playlist/route.ts
index 9ae76c839..724c4c42a 100644
--- a/apps/web/app/api/playlist/route.ts
+++ b/apps/web/app/api/playlist/route.ts
@@ -250,9 +250,6 @@ 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, {
@@ -276,8 +273,6 @@ const getPlaylistResponse = (
"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),
@@ -401,8 +396,8 @@ 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 (earlyPlayback) {
- // EVENT keeps the type stable as the playlist grows and ends, and
- // tells players they may seek anywhere from the first segment.
+ // A playlist type must not change, and EVENT lets players seek
+ // anywhere from the first segment while it grows.
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";
diff --git a/apps/web/app/s/[videoId]/_components/EarlyUploadOverlay.tsx b/apps/web/app/s/[videoId]/_components/EarlyUploadOverlay.tsx
index 1bb42214d..8c856f675 100644
--- a/apps/web/app/s/[videoId]/_components/EarlyUploadOverlay.tsx
+++ b/apps/web/app/s/[videoId]/_components/EarlyUploadOverlay.tsx
@@ -6,7 +6,6 @@ import { formatClock } from "./early-playback";
const FRAME_WIDTH = 48;
-/** Counts up to `value` (whole seconds) instead of jumping between polls. */
function useCountUp(value: number): number {
const [shown, setShown] = useState(Math.floor(value));
const currentRef = useRef(value);
@@ -34,12 +33,8 @@ function useCountUp(value: number): number {
return shown;
}
-/**
- * Shown over an early-playback recording when a seek or playback reaches a
- * part that hasn't uploaded yet. The paused frame is drawn once into a tiny
- * canvas and scaled up, so the blur costs nothing per frame; the grain and
- * sheen only move layers.
- */
+// The paused frame is drawn once into a tiny canvas and scaled up, so the
+// blur costs nothing per frame; the grain and sheen only move layers.
export function EarlyUploadOverlay({
videoRef,
target,
@@ -52,7 +47,6 @@ export function EarlyUploadOverlay({
target: number | null;
ready: number;
recorded: number | null;
- /** Everything has uploaded and the player is fetching the last part. */
uploadComplete: boolean;
stalled: boolean;
}) {
diff --git a/apps/web/app/s/[videoId]/_components/HLSVideoPlayer.tsx b/apps/web/app/s/[videoId]/_components/HLSVideoPlayer.tsx
index c0401120a..0993959fd 100644
--- a/apps/web/app/s/[videoId]/_components/HLSVideoPlayer.tsx
+++ b/apps/web/app/s/[videoId]/_components/HLSVideoPlayer.tsx
@@ -108,10 +108,6 @@ interface Props {
hasActiveUpload?: boolean;
isLiveSegments?: boolean;
allowSegmentProbeDuringUpload?: boolean;
- /**
- * Plays a stopped recording from its first segment while the playlist is
- * still growing, instead of waiting for the last segments to upload.
- */
earlyPlayback?: boolean;
onSourceComplete?: () => void;
enhancedAudioUrl?: string | null;
diff --git a/apps/web/app/s/[videoId]/_components/ShareVideo.tsx b/apps/web/app/s/[videoId]/_components/ShareVideo.tsx
index 18c0b46a3..30ab8682f 100644
--- a/apps/web/app/s/[videoId]/_components/ShareVideo.tsx
+++ b/apps/web/app/s/[videoId]/_components/ShareVideo.tsx
@@ -478,9 +478,6 @@ export const ShareVideo = forwardRef<
let enableCrossOrigin = false;
if (isSegmentsSource) {
- // A stopped recording either waits for its complete manifest or,
- // with early playback, starts from its first segment while the
- // last ones finish uploading.
const stoppedMode = userConfirmedStopped
? earlySegmentPlayback
? "&earlyPlayback=1"
diff --git a/apps/web/app/s/[videoId]/_components/early-playback.ts b/apps/web/app/s/[videoId]/_components/early-playback.ts
index 37d125310..f02cbfd66 100644
--- a/apps/web/app/s/[videoId]/_components/early-playback.ts
+++ b/apps/web/app/s/[videoId]/_components/early-playback.ts
@@ -2,12 +2,8 @@
import { type RefObject, useEffect, useRef, useState } from "react";
-/**
- * Early playback plays a stopped recording from its start while its last
- * segments are still uploading. The playlist only holds what has uploaded, so
- * a seek past it is held here until that part arrives instead of letting the
- * browser clamp it to the end of the uploaded part.
- */
+// The playlist only holds what has uploaded, so a seek past it is held until
+// that part arrives instead of letting the browser clamp it to the end.
const STATUS_POLL_MS = 2_000;
const STALLED_AFTER_MS = 30_000;
@@ -19,17 +15,11 @@ export type EarlyPlaybackStatus = {
};
export type EarlyPlaybackState = {
- /** Seconds that play from the start without a gap. */
ready: number;
- /** The full length, once the desktop app or the complete upload says. */
recorded: number | null;
- /** Every segment has uploaded. */
uploadComplete: boolean;
- /** A seek target waiting for its part to upload. */
held: number | null;
- /** Playback has caught up with the end of the uploaded part. */
atEdge: boolean;
- /** Nothing new has uploaded for a while. */
stalled: boolean;
};
@@ -51,7 +41,6 @@ export function parseEarlyPlaybackStatus(response: {
};
}
-/** How far the player can seek right now. */
export function getMediaEnd(
video: Pick<HTMLMediaElement, "duration" | "seekable">,
): number {
@@ -63,11 +52,8 @@ export function getMediaEnd(
return Math.max(duration, seekable, 0);
}
-/**
- * Seeks the browser can carry out as asked. Before the duration is known
- * (hls.js placing its start position) and once the player holds the whole
- * recording, every seek goes through untouched.
- */
+// hls.js places its start position before the duration is known, so seeks
+// pass untouched until then.
export function canSeekNow(
target: number,
mediaEnd: number,
@@ -76,11 +62,6 @@ export function canSeekNow(
return playerComplete || mediaEnd <= 0 || target <= mediaEnd - 0.05;
}
-/**
- * A held seek resolves once its part has uploaded with a second to play (or
- * the upload is complete) and the player's playlist reaches it. Once the
- * player holds the whole recording, a target past its end lands on the end.
- */
export function canResolveHold(
target: number,
{
@@ -140,7 +121,6 @@ export function useEarlyPlayback({
}: {
enabled: boolean;
statusUrl: string | null;
- /** The player's playlist has ended, so it holds the whole recording. */
playerComplete: boolean;
videoRef: RefObject<HTMLVideoElement | null>;
}): EarlyPlaybackState {
@@ -292,7 +272,6 @@ export function useEarlyPlayback({
});
}
- // Pressing play while a seek is held keeps watching from here.
const onPlay = () => {
if (heldRef.current !== null) releaseHold();
updateEdge();
diff --git a/apps/web/app/s/[videoId]/_components/video/media-player.tsx b/apps/web/app/s/[videoId]/_components/video/media-player.tsx
index 4fa0aa0da..f63ba4d74 100644
--- a/apps/web/app/s/[videoId]/_components/video/media-player.tsx
+++ b/apps/web/app/s/[videoId]/_components/video/media-player.tsx
@@ -1577,17 +1577,8 @@ interface MediaPlayerSeekProps
withoutChapter?: boolean;
withoutTooltip?: boolean;
fallbackDuration?: number | null;
- /**
- * The full length while only part of the media has loaded, so the bar
- * spans the whole recording.
- */
expectedDuration?: number | null;
- /** Where the not-yet-available part of the bar starts. */
pendingFrom?: number | null;
- /**
- * A seek the player is holding. The thumb stays on it while it is held and
- * returns to the playhead once the hold is dropped.
- */
heldSeekTime?: number | null;
tooltipThumbnailSrc?: string | ((time: number) => string | undefined | null);
tooltipTimeVariant?: "current" | "progress";
@@ -2575,7 +2566,6 @@ interface MediaPlayerTimeProps extends React.ComponentProps<"div"> {
variant?: "progress" | "remaining" | "duration";
asChild?: boolean;
fallbackDuration?: number | null;
- /** The full length while only part of the media has loaded. */
expectedDuration?: number | null;
}
diff --git a/apps/web/lib/early-instant-playback.ts b/apps/web/lib/early-instant-playback.ts
index aea5c4a24..71a7b8da2 100644
--- a/apps/web/lib/early-instant-playback.ts
+++ b/apps/web/lib/early-instant-playback.ts
@@ -1,9 +1,3 @@
-/**
- * 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;
diff --git a/apps/web/lib/segment-playback.ts b/apps/web/lib/segment-playback.ts
index 9f45f6d61..2bb7e52b3 100644
--- a/apps/web/lib/segment-playback.ts
+++ b/apps/web/lib/segment-playback.ts
@@ -15,12 +15,10 @@ export function getSegmentPlaybackState(
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.
- */
+// 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, which HLS players
+// cannot follow.
export function contiguousSegmentPrefix(
entries: Video.SegmentManifestType["video_segments"],
): SegmentEntry[] {
@@ -35,12 +33,8 @@ export function contiguousSegmentPrefix(
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.
- */
+// Audio only proves it exists once it starts uploading, so a manifest without
+// any audio yet waits: its recording may still have audio on the way.
export function getEarlySegmentTracks(
manifest: Video.SegmentManifestType,
): { video: SegmentEntry[]; audio: SegmentEntry[] } | null {
@@ -60,11 +54,6 @@ export function totalSegmentDuration(
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,