Playback performance and sync

apps/desktop/src/utils/frame-order.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import {
+	frameNumberForwardDelta,
+	isFrameNumberNewer,
+	shouldDropOutOfOrderFrame,
+} from "./frame-order";
+
+describe("frame-order utilities", () => {
+	it("treats positive forward deltas as newer", () => {
+		expect(frameNumberForwardDelta(41, 40)).toBe(1);
+		expect(isFrameNumberNewer(41, 40)).toBe(true);
+	});
+
+	it("treats wraparound forward deltas as newer", () => {
+		expect(frameNumberForwardDelta(2, 0xffffffff)).toBe(3);
+		expect(isFrameNumberNewer(2, 0xffffffff)).toBe(true);
+	});
+
+	it("drops duplicate frame numbers", () => {
+		expect(shouldDropOutOfOrderFrame(120, 120)).toBe(true);
+	});
+
+	it("drops slightly older out-of-order frames inside stale window", () => {
+		expect(shouldDropOutOfOrderFrame(119, 120, 30)).toBe(true);
+		expect(shouldDropOutOfOrderFrame(90, 120, 30)).toBe(true);
+	});
+
+	it("keeps older frames beyond stale window as seek candidates", () => {
+		expect(shouldDropOutOfOrderFrame(89, 120, 30)).toBe(false);
+	});
+
+	it("keeps forward frames", () => {
+		expect(shouldDropOutOfOrderFrame(121, 120, 30)).toBe(false);
+	});
+});

apps/desktop/src/utils/frame-order.ts

@@ -0,0 +1,27 @@
+export const FRAME_ORDER_STALE_WINDOW = 30;
+
+export function frameNumberForwardDelta(
+	candidate: number,
+	reference: number,
+): number {
+	return (candidate - reference) >>> 0;
+}
+
+export function isFrameNumberNewer(
+	candidate: number,
+	reference: number,
+): boolean {
+	const delta = frameNumberForwardDelta(candidate, reference);
+	return delta !== 0 && delta < 0x80000000;
+}
+
+export function shouldDropOutOfOrderFrame(
+	candidate: number,
+	reference: number,
+	staleWindow: number = FRAME_ORDER_STALE_WINDOW,
+): boolean {
+	if (candidate === reference) return true;
+	if (isFrameNumberNewer(candidate, reference)) return false;
+	const backwardDelta = frameNumberForwardDelta(reference, candidate);
+	return backwardDelta <= staleWindow;
+}

apps/desktop/src/utils/frame-transport-config.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import {
+	DEFAULT_FRAME_BUFFER_CONFIG,
+	FRAME_BUFFER_MAX_SLOT_SIZE,
+	FRAME_BUFFER_MAX_TOTAL_BYTES,
+	computeSharedBufferConfig,
+} from "./frame-transport-config";
+
+describe("frame-transport-config", () => {
+	it("keeps default config for small frames", () => {
+		const config = computeSharedBufferConfig(4 * 1024 * 1024);
+		expect(config.slotSize).toBe(DEFAULT_FRAME_BUFFER_CONFIG.slotSize);
+		expect(config.slotCount).toBe(DEFAULT_FRAME_BUFFER_CONFIG.slotCount);
+	});
+
+	it("increases slot size with aligned headroom", () => {
+		const config = computeSharedBufferConfig(22 * 1024 * 1024);
+		expect(config.slotSize).toBe(28 * 1024 * 1024);
+		expect(config.slotCount).toBe(4);
+	});
+
+	it("caps slot size and total memory budget", () => {
+		const config = computeSharedBufferConfig(80 * 1024 * 1024);
+		expect(config.slotSize).toBe(FRAME_BUFFER_MAX_SLOT_SIZE);
+		expect(config.slotCount).toBe(2);
+		expect(config.slotSize * config.slotCount).toBeLessThanOrEqual(
+			FRAME_BUFFER_MAX_TOTAL_BYTES,
+		);
+	});
+});

apps/desktop/src/utils/frame-transport-config.ts

@@ -0,0 +1,37 @@
+import type { SharedFrameBufferConfig } from "./shared-frame-buffer";
+
+export const DEFAULT_FRAME_BUFFER_CONFIG: SharedFrameBufferConfig = {
+	slotCount: 6,
+	slotSize: 16 * 1024 * 1024,
+};
+
+export const FRAME_BUFFER_RESIZE_ALIGNMENT = 2 * 1024 * 1024;
+export const FRAME_BUFFER_MAX_SLOT_SIZE = 64 * 1024 * 1024;
+export const FRAME_BUFFER_MAX_TOTAL_BYTES = 128 * 1024 * 1024;
+export const FRAME_BUFFER_MIN_SLOT_COUNT = 2;
+
+export function alignUp(value: number, alignment: number): number {
+	if (alignment <= 0) return value;
+	return Math.ceil(value / alignment) * alignment;
+}
+
+export function computeSharedBufferConfig(
+	requiredBytes: number,
+	baseConfig: SharedFrameBufferConfig = DEFAULT_FRAME_BUFFER_CONFIG,
+): SharedFrameBufferConfig {
+	const safeRequired = Math.max(requiredBytes, 0);
+	const withHeadroom = Math.ceil(safeRequired * 1.25);
+	const alignedBytes = alignUp(withHeadroom, FRAME_BUFFER_RESIZE_ALIGNMENT);
+	const slotSize = Math.max(
+		baseConfig.slotSize,
+		Math.min(FRAME_BUFFER_MAX_SLOT_SIZE, alignedBytes),
+	);
+
+	const maxSlotsByBudget = Math.max(
+		FRAME_BUFFER_MIN_SLOT_COUNT,
+		Math.floor(FRAME_BUFFER_MAX_TOTAL_BYTES / slotSize),
+	);
+	const slotCount = Math.min(baseConfig.slotCount, maxSlotsByBudget);
+
+	return { slotCount, slotSize };
+}

apps/desktop/src/utils/frame-transport-inflight.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import {
+	decideWorkerInflightDispatch,
+	updateWorkerInflightPeaks,
+} from "./frame-transport-inflight";
+
+describe("frame-transport-inflight", () => {
+	it("dispatches when worker inflight is below limit", () => {
+		expect(decideWorkerInflightDispatch(1, 2, false)).toEqual({
+			action: "dispatch",
+			nextWorkerFramesInFlight: 2,
+			backpressureHitsIncrement: 0,
+			supersededDropsIncrement: 0,
+		});
+	});
+
+	it("returns backpressure without superseded increment when queue empty", () => {
+		expect(decideWorkerInflightDispatch(2, 2, false)).toEqual({
+			action: "backpressure",
+			nextWorkerFramesInFlight: 2,
+			backpressureHitsIncrement: 1,
+			supersededDropsIncrement: 0,
+		});
+	});
+
+	it("returns backpressure with superseded increment when queue occupied", () => {
+		expect(decideWorkerInflightDispatch(4, 2, true)).toEqual({
+			action: "backpressure",
+			nextWorkerFramesInFlight: 4,
+			backpressureHitsIncrement: 1,
+			supersededDropsIncrement: 1,
+		});
+	});
+
+	it("updates worker inflight peaks", () => {
+		expect(updateWorkerInflightPeaks(3, 2, 5)).toEqual({
+			peakWindow: 3,
+			peakTotal: 5,
+		});
+	});
+});

apps/desktop/src/utils/frame-transport-inflight.ts

@@ -0,0 +1,39 @@
+export type WorkerInflightDispatchDecision = {
+	action: "dispatch" | "backpressure";
+	nextWorkerFramesInFlight: number;
+	backpressureHitsIncrement: number;
+	supersededDropsIncrement: number;
+};
+
+export function decideWorkerInflightDispatch(
+	workerFramesInFlight: number,
+	limit: number,
+	hasQueuedNextFrame: boolean,
+): WorkerInflightDispatchDecision {
+	if (workerFramesInFlight >= limit) {
+		return {
+			action: "backpressure",
+			nextWorkerFramesInFlight: workerFramesInFlight,
+			backpressureHitsIncrement: 1,
+			supersededDropsIncrement: hasQueuedNextFrame ? 1 : 0,
+		};
+	}
+
+	return {
+		action: "dispatch",
+		nextWorkerFramesInFlight: workerFramesInFlight + 1,
+		backpressureHitsIncrement: 0,
+		supersededDropsIncrement: 0,
+	};
+}
+
+export function updateWorkerInflightPeaks(
+	workerFramesInFlight: number,
+	peakWindow: number,
+	peakTotal: number,
+) {
+	return {
+		peakWindow: Math.max(peakWindow, workerFramesInFlight),
+		peakTotal: Math.max(peakTotal, workerFramesInFlight),
+	};
+}

apps/desktop/src/utils/frame-transport-order.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import { decideFrameOrder } from "./frame-transport-order";
+
+describe("decideFrameOrder", () => {
+	it("accepts frame when candidate is missing", () => {
+		const decision = decideFrameOrder(null, 120, 30);
+		expect(decision).toEqual({
+			action: "accept",
+			nextLatestFrameNumber: 120,
+			dropsIncrement: 0,
+		});
+	});
+
+	it("accepts first frame and seeds latest", () => {
+		const decision = decideFrameOrder(120, null, 30);
+		expect(decision).toEqual({
+			action: "accept",
+			nextLatestFrameNumber: 120,
+			dropsIncrement: 0,
+		});
+	});
+
+	it("drops short backward stale frames", () => {
+		const decision = decideFrameOrder(119, 120, 30);
+		expect(decision).toEqual({
+			action: "drop",
+			nextLatestFrameNumber: 120,
+			dropsIncrement: 1,
+		});
+	});
+
+	it("drops duplicate frame numbers", () => {
+		const decision = decideFrameOrder(120, 120, 30);
+		expect(decision).toEqual({
+			action: "drop",
+			nextLatestFrameNumber: 120,
+			dropsIncrement: 1,
+		});
+	});
+
+	it("accepts large backward jumps for seeks", () => {
+		const decision = decideFrameOrder(80, 120, 30);
+		expect(decision).toEqual({
+			action: "accept",
+			nextLatestFrameNumber: 80,
+			dropsIncrement: 0,
+		});
+	});
+
+	it("accepts forward progression", () => {
+		const decision = decideFrameOrder(121, 120, 30);
+		expect(decision).toEqual({
+			action: "accept",
+			nextLatestFrameNumber: 121,
+			dropsIncrement: 0,
+		});
+	});
+
+	it("accepts wraparound forward progression", () => {
+		const decision = decideFrameOrder(2, 0xffffffff, 30);
+		expect(decision).toEqual({
+			action: "accept",
+			nextLatestFrameNumber: 2,
+			dropsIncrement: 0,
+		});
+	});
+});

apps/desktop/src/utils/frame-transport-order.ts

@@ -0,0 +1,49 @@
+import { shouldDropOutOfOrderFrame } from "./frame-order";
+
+export type FrameOrderDecision = {
+	action: "accept" | "drop";
+	nextLatestFrameNumber: number | null;
+	dropsIncrement: number;
+};
+
+export function decideFrameOrder(
+	candidateFrameNumber: number | null,
+	latestFrameNumber: number | null,
+	staleWindow: number,
+): FrameOrderDecision {
+	if (candidateFrameNumber === null) {
+		return {
+			action: "accept",
+			nextLatestFrameNumber: latestFrameNumber,
+			dropsIncrement: 0,
+		};
+	}
+
+	if (latestFrameNumber === null) {
+		return {
+			action: "accept",
+			nextLatestFrameNumber: candidateFrameNumber,
+			dropsIncrement: 0,
+		};
+	}
+
+	if (
+		shouldDropOutOfOrderFrame(
+			candidateFrameNumber,
+			latestFrameNumber,
+			staleWindow,
+		)
+	) {
+		return {
+			action: "drop",
+			nextLatestFrameNumber: latestFrameNumber,
+			dropsIncrement: 1,
+		};
+	}
+
+	return {
+		action: "accept",
+		nextLatestFrameNumber: candidateFrameNumber,
+		dropsIncrement: 0,
+	};
+}

apps/desktop/src/utils/frame-transport-retry.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { decideSabWriteFailure } from "./frame-transport-retry";
+
+describe("frame-transport-retry", () => {
+	it("falls back immediately for oversized frames", () => {
+		const decision = decideSabWriteFailure(true, 0, 2);
+		expect(decision).toEqual({
+			action: "fallback_oversize",
+			nextRetryCount: 0,
+		});
+	});
+
+	it("retries while below retry limit", () => {
+		const decision = decideSabWriteFailure(false, 1, 2);
+		expect(decision).toEqual({
+			action: "retry",
+			nextRetryCount: 2,
+		});
+	});
+
+	it("falls back when retry limit is reached", () => {
+		const decision = decideSabWriteFailure(false, 2, 2);
+		expect(decision).toEqual({
+			action: "fallback_retry_limit",
+			nextRetryCount: 0,
+		});
+	});
+});

apps/desktop/src/utils/frame-transport-retry.ts

@@ -0,0 +1,20 @@
+export type SabWriteFailureDecision =
+	| { action: "retry"; nextRetryCount: number }
+	| { action: "fallback_oversize"; nextRetryCount: number }
+	| { action: "fallback_retry_limit"; nextRetryCount: number };
+
+export function decideSabWriteFailure(
+	isOversized: boolean,
+	currentRetryCount: number,
+	retryLimit: number,
+): SabWriteFailureDecision {
+	if (isOversized) {
+		return { action: "fallback_oversize", nextRetryCount: 0 };
+	}
+
+	if (currentRetryCount >= retryLimit) {
+		return { action: "fallback_retry_limit", nextRetryCount: 0 };
+	}
+
+	return { action: "retry", nextRetryCount: currentRetryCount + 1 };
+}