fix(editor): wait for preview before voiceover recording

Author: mikemikimike

src/components/ai-edition/NewEditorShell.tsx

@@ -1015,7 +1015,7 @@ export function NewEditorShell() {
 	// where it is passed to the preview.
 	const [voiceoverRecording, setVoiceoverRecording] = useState(false);
 
-	const handleVoiceoverRecordingStart = useCallback(() => {
+	const handleVoiceoverRecordingStart = useCallback(async () => {
 		// Re-capture: the user may have scrubbed between opening the dialog and
 		// hitting Record, and playback starts from wherever the playhead is now.
 		const doc = useProjectStore.getState().document;
@@ -1026,10 +1026,9 @@ export function NewEditorShell() {
 			setVoiceoverFlow({ maxDurationSec: Math.max(0.5, total - playhead) });
 		}
 		setVoiceoverRecording(true);
-		if (videoElement) {
-			videoElement.playbackRate = 1;
-			if (videoElement.paused) void videoElement.play().catch(() => undefined);
-		}
+		if (!videoElement) throw new Error("The preview is not ready.");
+		videoElement.playbackRate = 1;
+		if (videoElement.paused) await videoElement.play();
 	}, [videoElement]);
 
 	const handleVoiceoverRecordingStop = useCallback(() => {

src/components/ai-edition/NewEditorShell.voiceover.test.tsx

@@ -12,6 +12,7 @@ import { buildSceneDescription } from "@/native/sceneDescription";
 
 const mocks = vi.hoisted(() => ({
 	nativePlaybackSync: vi.fn(),
+	previewPlay: vi.fn(async () => undefined),
 }));
 
 vi.mock("@/contexts/ShortcutsContext", async () => {
@@ -38,13 +39,31 @@ vi.mock("@/native/useNativePlaybackSync", () => ({
 	useNativePlaybackSync: mocks.nativePlaybackSync,
 }));
 
-vi.mock("./Preview", () => ({
-	Preview: ({ playUneditedTimeline }: { playUneditedTimeline?: boolean }) =>
-		createElement("div", {
-			"data-testid": "preview-recording-mode",
-			"data-unedited": String(playUneditedTimeline ?? false),
-		}),
-}));
+vi.mock("./Preview", async () => {
+	const { createElement, useEffect } = await import("react");
+	return {
+		Preview: ({
+			playUneditedTimeline,
+			onVideoElement,
+		}: {
+			playUneditedTimeline?: boolean;
+			onVideoElement: (element: HTMLVideoElement | null) => void;
+		}) => {
+			useEffect(() => {
+				const element = document.createElement("video");
+				Object.defineProperty(element, "paused", { configurable: true, value: true });
+				element.play = mocks.previewPlay;
+				element.pause = vi.fn();
+				onVideoElement(element);
+				return () => onVideoElement(null);
+			}, [onVideoElement]);
+			return createElement("div", {
+				"data-testid": "preview-recording-mode",
+				"data-unedited": String(playUneditedTimeline ?? false),
+			});
+		},
+	};
+});
 
 vi.mock("./v4/V4Timeline", () => ({
 	V4Timeline: ({ onAddVoiceover }: { onAddVoiceover: () => void }) =>
@@ -60,7 +79,7 @@ vi.mock("./v4/AddAudioLayerDialog", () => ({
 	}: {
 		open: boolean;
 		onComplete: (assetId: string, durationSec: number) => void;
-		onRecordingStart: () => void;
+		onRecordingStart: () => void | Promise<void>;
 		onRecordingStop: () => void;
 	}) =>
 		open
@@ -200,6 +219,7 @@ describe("NewEditorShell voiceover placement", () => {
 		fireEvent.click(screen.getByRole("button", { name: "start-recording" }));
 
 		expect(screen.getByTestId("preview-recording-mode")).toHaveAttribute("data-unedited", "true");
+		expect(mocks.previewPlay).toHaveBeenCalledOnce();
 		expect(mocks.nativePlaybackSync).toHaveBeenLastCalledWith(false, 2, rawClips, rawClips);
 
 		act(() => {

src/components/ai-edition/v4/AddAudioLayerDialog.test.tsx

@@ -1,9 +1,12 @@
 // @vitest-environment jsdom
 import "@testing-library/jest-dom";
 import { fireEvent, render, screen } from "@testing-library/react";
+import { toast } from "sonner";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { AddAudioLayerDialog } from "./AddAudioLayerDialog";
 
+vi.mock("sonner", () => ({ toast: { error: vi.fn() } }));
+
 vi.mock("@/contexts/I18nContext", () => ({
 	useScopedT: () => (key: string) => key,
 	useI18n: () => ({ locale: "en", setLocale: () => undefined }),
@@ -24,6 +27,7 @@ vi.mock("@/lib/ai-edition/timeline/duration", () => ({
 class FakeRecorder {
 	static instances: FakeRecorder[] = [];
 	state: "inactive" | "recording" = "inactive";
+	started = false;
 	stopped = false;
 	ondataavailable: ((e: { data: Blob }) => void) | null = null;
 	onstop: (() => void) | null = null;
@@ -35,6 +39,7 @@ class FakeRecorder {
 		return true;
 	}
 	start() {
+		this.started = true;
 		this.state = "recording";
 	}
 	stop() {
@@ -50,6 +55,7 @@ beforeEach(() => {
 	FakeRecorder.instances = [];
 	stopTrack.mockClear();
 	addAudioAsset.mockReset();
+	vi.mocked(toast.error).mockClear();
 	vi.stubGlobal("MediaRecorder", FakeRecorder);
 	Object.defineProperty(navigator, "mediaDevices", {
 		configurable: true,
@@ -85,6 +91,37 @@ describe("AddAudioLayerDialog", () => {
 		await vi.waitFor(() => expect(props.onRecordingStart).toHaveBeenCalledTimes(1));
 	});
 
+	it("waits for preview playback before starting the recorder", async () => {
+		let allowStart: (() => void) | undefined;
+		const onRecordingStart = vi.fn(
+			() =>
+				new Promise<void>((resolve) => {
+					allowStart = resolve;
+				}),
+		);
+		renderDialog({ onRecordingStart });
+
+		fireEvent.click(screen.getByText("audio.record"));
+		await vi.waitFor(() => expect(onRecordingStart).toHaveBeenCalledOnce());
+		expect(FakeRecorder.instances[0].started).toBe(false);
+
+		allowStart?.();
+		await vi.waitFor(() => expect(FakeRecorder.instances[0].started).toBe(true));
+	});
+
+	it("releases the microphone and aborts when preview playback fails", async () => {
+		const onRecordingStart = vi.fn().mockRejectedValue(new Error("playback failed"));
+		const { props } = renderDialog({ onRecordingStart });
+
+		fireEvent.click(screen.getByText("audio.record"));
+		await vi.waitFor(() => expect(toast.error).toHaveBeenCalledWith("audio.recordingUnavailable"));
+
+		expect(FakeRecorder.instances).toHaveLength(1);
+		expect(FakeRecorder.instances[0].started).toBe(false);
+		expect(stopTrack).toHaveBeenCalledOnce();
+		expect(props.onRecordingStop).toHaveBeenCalledOnce();
+	});
+
 	it("does not cover the video it is recording against", () => {
 		// It used to be a modal over a dimmed backdrop, which hid the one thing a
 		// voiceover needs you to watch. It is a docked bar now: no backdrop, and

src/components/ai-edition/v4/AddAudioLayerDialog.tsx

@@ -54,7 +54,7 @@ export function AddAudioLayerDialog({
 	maxDurationSec: number;
 	onClose: () => void;
 	onComplete: (assetId: string, durationSec: number) => void;
-	onRecordingStart: () => void;
+	onRecordingStart: () => void | Promise<void>;
 	onRecordingStop: () => void;
 }) {
 	const t = useScopedT("timeline");
@@ -212,13 +212,22 @@ export function AddAudioLayerDialog({
 					}
 				})();
 			};
+			try {
+				await onRecordingStart();
+			} catch {
+				for (const track of streamRef.current?.getTracks() ?? []) track.stop();
+				streamRef.current = null;
+				recorderRef.current = null;
+				onRecordingStop();
+				toast.error(t("audio.recordingUnavailable"));
+				return;
+			}
 			startedAtRef.current = performance.now();
 			discardRef.current = false;
 			recorder.start(250);
 			setRecording(true);
 			recordingRef.current = true;
 			setElapsedSec(0);
-			onRecordingStart();
 			timerRef.current = setInterval(() => {
 				setElapsedSec((performance.now() - startedAtRef.current) / 1000);
 			}, 200);