feat: add voiceover and background music layers to the editor

electron/ai-edition/document-service.test.ts

@@ -266,13 +266,29 @@ describe("DocumentService", () => {
 			expect(path.isAbsolute(updated.assets[0]?.originalPath ?? "")).toBe(true);
 		});
 
-		it("rejects unsupported video extensions", async () => {
+		it("rejects unsupported media extensions", async () => {
 			const doc = await service.createProject("P");
 			await expect(
-				service.addAsset(doc.project.id, { path: "/tmp/audio.mp3" }),
+				service.addAsset(doc.project.id, { path: "/tmp/notes.txt" }),
 			).rejects.toBeInstanceOf(ProjectFileError);
 		});
 
+		it("appends an audio asset with kind 'audio' without claiming primaryAssetId", async () => {
+			const doc = await service.createProject("P");
+			const updated = await service.addAsset(doc.project.id, { path: "/tmp/music.mp3" });
+			expect(updated.assets).toHaveLength(1);
+			expect(updated.assets[0]?.kind).toBe("audio");
+			expect(updated.project.primaryAssetId).toBeUndefined();
+		});
+
+		it("an audio asset does not displace the primary video", async () => {
+			const doc = await service.createProject("P");
+			const withVideo = await service.addAsset(doc.project.id, { path: "/tmp/a.mp4" });
+			const after = await service.addAsset(withVideo.project.id, { path: "/tmp/b.mp3" });
+			expect(after.project.primaryAssetId).toBe(withVideo.project.primaryAssetId);
+			expect(after.assets.at(-1)?.kind).toBe("audio");
+		});
+
 		it("preserves primaryAssetId when adding a second asset", async () => {
 			const doc = await service.createProject("P");
 			const first = await service.addAsset(doc.project.id, { path: "/tmp/a.mp4" });
@@ -342,13 +358,33 @@ describe("DocumentService", () => {
 						},
 					],
 				},
+				audioRanges: [
+					{
+						id: "aud_1",
+						clipId: "clip_1",
+						sourceStartSec: 0,
+						sourceEndSec: 1,
+						startMs: 0,
+						endMs: 1000,
+						assetId,
+						kind: "music",
+						offsetMs: 0,
+						gainDb: 0,
+						loop: false,
+						fadeInMs: 0,
+						fadeOutMs: 0,
+						muted: false,
+						origin: "user",
+					},
+				],
 			});
 
 			const after = await service.removeAsset(docWithTimeline.project.id, assetId);
 			expect(after.assets).toHaveLength(0);
 			expect(after.timeline.clips).toHaveLength(0);
 			expect(after.timeline.trimRanges).toHaveLength(0);
 			expect(after.zoomRanges).toHaveLength(0);
+			expect(after.audioRanges).toHaveLength(0);
 			expect((after.legacyEditor as { speedRegions: unknown[] }).speedRegions).toHaveLength(0);
 			expect(after.project.primaryAssetId).toBeUndefined();
 		});

electron/ai-edition/document-service.ts

@@ -38,6 +38,13 @@ export interface ProjectSummary {
 export interface AddAssetInput {
 	path: string;
 	label?: string;
+	/**
+	 * What the caller KNOWS the file is. Optional: without it the extension
+	 * decides — which misclassifies ambiguous containers (a recorded voiceover
+	 * is `.webm`, the same extension as a screen recording). Callers that know
+	 * (the audio-layer import flow) say so.
+	 */
+	kind?: "video" | "audio";
 }
 
 export class DocumentNotFoundError extends Error {
@@ -67,9 +74,27 @@ const SUPPORTED_VIDEO_EXTENSIONS = new Set([
 	".wmv",
 ]);
 
-function isSupportedVideoPath(filePath: string): boolean {
+// Audio-only media for editor audio layers (voiceover / background music).
+// Anything decodeAudioData / an <audio> element can play in Chromium.
+const SUPPORTED_AUDIO_EXTENSIONS = new Set([
+	".mp3",
+	".wav",
+	".m4a",
+	".aac",
+	".ogg",
+	".oga",
+	".opus",
+	".flac",
+	".webm",
+]);
+
+function classifyMediaPath(
+	filePath: string,
+): { kind: "video" | "audio"; extension: string } | null {
 	const ext = path.extname(filePath).toLowerCase();
-	return SUPPORTED_VIDEO_EXTENSIONS.has(ext);
+	if (SUPPORTED_VIDEO_EXTENSIONS.has(ext)) return { kind: "video", extension: ext };
+	if (SUPPORTED_AUDIO_EXTENSIONS.has(ext)) return { kind: "audio", extension: ext };
+	return null;
 }
 
 function safeProjectId(raw: string): string {
@@ -283,9 +308,17 @@ export class DocumentService {
 		if (!input.path) {
 			throw new ProjectFileError("Asset path is required.", projectId);
 		}
-		if (!isSupportedVideoPath(input.path)) {
+		// The caller's explicit kind wins; otherwise the extension decides. Both
+		// fall out of the same classifier so the rest of the method sees one shape.
+		const media: { kind: "video" | "audio"; extension: string } | null = input.kind
+			? { kind: input.kind, extension: path.extname(input.path).toLowerCase() }
+			: classifyMediaPath(input.path);
+		if (!media) {
 			throw new ProjectFileError(
-				`Unsupported video extension: ${path.extname(input.path)} (supported: ${[...SUPPORTED_VIDEO_EXTENSIONS].join(", ")})`,
+				`Unsupported media extension: ${path.extname(input.path)} (supported: ${[
+					...SUPPORTED_VIDEO_EXTENSIONS,
+					...SUPPORTED_AUDIO_EXTENSIONS,
+				].join(", ")})`,
 				projectId,
 			);
 		}
@@ -300,7 +333,7 @@ export class DocumentService {
 		}
 		const asset: AxcutAsset = {
 			id: createId("asset"),
-			kind: "video",
+			kind: media.kind,
 			label: input.label?.trim() || path.basename(absolutePath),
 			originalPath: absolutePath,
 			sizeBytes,
@@ -311,7 +344,13 @@ export class DocumentService {
 			assets: [...doc.assets, asset],
 			project: {
 				...doc.project,
-				...(doc.project.primaryAssetId ? {} : { primaryAssetId: asset.id }),
+				// An audio asset is never a timeline clip, so it must not become the
+				// primary asset either — everything downstream (export scene, ratio
+				// picker, "add video before exporting") reads primaryAssetId as a
+				// VIDEO. Only a video import can claim the slot.
+				...(doc.project.primaryAssetId || media.kind !== "video"
+					? {}
+					: { primaryAssetId: asset.id }),
 				updatedAt: new Date().toISOString(),
 			},
 		};
@@ -338,6 +377,10 @@ export class DocumentService {
 				...withoutAssetClips.timeline,
 				trimRanges: withoutAssetClips.timeline.trimRanges.filter((r) => r.assetId !== assetId),
 			},
+			// Same rule as trimRanges: an audio layer over a deleted asset has
+			// nothing left to play, and keeping it would leave a pill on the ruler
+			// that fails silently at preview and export.
+			audioRanges: withoutAssetClips.audioRanges.filter((r) => r.assetId !== assetId),
 			project: {
 				...withoutAssetClips.project,
 				primaryAssetId,

electron/electron-env.d.ts

@@ -286,6 +286,19 @@ interface Window {
 			name?: string;
 			canceled?: boolean;
 		}>;
+		openAudioFilePicker: () => Promise<{
+			success: boolean;
+			path?: string;
+			name?: string;
+			canceled?: boolean;
+			message?: string;
+		}>;
+		saveRecordedVoiceover: (data: ArrayBuffer) => Promise<{
+			success: boolean;
+			path?: string;
+			message?: string;
+			error?: string;
+		}>;
 		setCurrentVideoPath: (path: string) => Promise<{ success: boolean }>;
 		setCurrentRecordingSession: (
 			session: import("../src/lib/recordingSession").RecordingSession | null,

electron/ipc/handlers.ts

@@ -103,6 +103,18 @@ const ALLOWED_IMPORT_VIDEO_EXTENSIONS = new Set([
 	".flv",
 	".ts",
 ]);
+// Mirrors DocumentService's audio set — anything an <audio> element can decode.
+const ALLOWED_IMPORT_AUDIO_EXTENSIONS = new Set([
+	".mp3",
+	".wav",
+	".m4a",
+	".aac",
+	".ogg",
+	".oga",
+	".opus",
+	".flac",
+	".webm",
+]);
 const PREVIEW_AUDIO_DIR = path.join(app.getPath("userData"), "preview-audio");
 const nativeMacCaptureEvents = new EventEmitter();
 
@@ -180,7 +192,12 @@ function buildDialogOptions<T extends Electron.OpenDialogOptions | Electron.Save
 }
 
 function hasAllowedImportVideoExtension(filePath: string): boolean {
-	return ALLOWED_IMPORT_VIDEO_EXTENSIONS.has(path.extname(filePath).toLowerCase());
+	const ext = path.extname(filePath).toLowerCase();
+	// Audio extensions ride the same approval gate: the read-binary-file /
+	// get-readable-file-info handlers serve audio-layer assets (voiceover /
+	// music) exactly like video assets, and both go through
+	// `approveReadableVideoPath`.
+	return ALLOWED_IMPORT_VIDEO_EXTENSIONS.has(ext) || ALLOWED_IMPORT_AUDIO_EXTENSIONS.has(ext);
 }
 
 function runProcess(
@@ -3620,6 +3637,74 @@ export function registerIpcHandlers(
 		}
 	});
 
+	// Audio-layer import (voiceover file / background music). Same shape as
+	// open-video-file-picker, with audio filters and an audio extension gate.
+	ipcMain.handle("open-audio-file-picker", async () => {
+		try {
+			const dialogOptions = buildDialogOptions(
+				{
+					title: mainT("dialogs", "fileDialogs.selectAudio"),
+					defaultPath: RECORDINGS_DIR,
+					filters: [
+						{
+							name: mainT("dialogs", "fileDialogs.audioFiles"),
+							extensions: [...ALLOWED_IMPORT_AUDIO_EXTENSIONS],
+						},
+						{ name: mainT("dialogs", "fileDialogs.allFiles"), extensions: ["*"] },
+					],
+					properties: ["openFile"],
+				},
+				getMainWindow(),
+			);
+			const result = await dialog.showOpenDialog(dialogOptions);
+			if (result.canceled || result.filePaths.length === 0) {
+				return { success: false, canceled: true };
+			}
+			const picked = result.filePaths[0];
+			if (!ALLOWED_IMPORT_AUDIO_EXTENSIONS.has(path.extname(picked).toLowerCase())) {
+				return {
+					success: false,
+					message: "Selected file is not a supported audio file",
+				};
+			}
+			return {
+				success: true,
+				path: picked,
+			};
+		} catch (error) {
+			console.error("Failed to open audio file picker:", error);
+			return {
+				success: false,
+				message: "Failed to open audio file picker",
+				error: String(error),
+			};
+		}
+	});
+
+	// In-editor voiceover recording: the renderer hands over the raw
+	// MediaRecorder blob (webm/opus) and gets back the path it landed at, under
+	// the recordings dir so it lives with the project's other media and survives
+	// relaunches.
+	ipcMain.handle("save-recorded-voiceover", async (_event, data: ArrayBuffer) => {
+		try {
+			if (!(data instanceof ArrayBuffer) || data.byteLength === 0) {
+				return { success: false, message: "Empty recording" };
+			}
+			await fs.mkdir(RECORDINGS_DIR, { recursive: true });
+			const fileName = `voiceover-${new Date().toISOString().replace(/[:.]/g, "-")}.webm`;
+			const target = path.join(RECORDINGS_DIR, fileName);
+			await fs.writeFile(target, Buffer.from(data));
+			return { success: true, path: target };
+		} catch (error) {
+			console.error("Failed to save recorded voiceover:", error);
+			return {
+				success: false,
+				message: "Failed to save recorded voiceover",
+				error: String(error),
+			};
+		}
+	});
+
 	ipcMain.handle("reveal-in-folder", async (_, filePath: string) => {
 		try {
 			// showItemInFolder returns nothing, it throws on error

electron/ipc/nativeBridge.ts

@@ -483,6 +483,7 @@ export function registerNativeBridgeHandlers(context: NativeBridgeContext) {
 									request.payload.projectId,
 									request.payload.path,
 									request.payload.label,
+									request.payload.kind,
 								),
 							);
 						case "document.removeAsset":

electron/native-bridge/services/aiEditionService.ts

@@ -151,8 +151,13 @@ export class AiEditionService {
 		}
 	}
 
-	async addAsset(projectId: string, path: string, label?: string): Promise<AiEditionAssetResult> {
-		const document = await this.options.documents.addAsset(projectId, { path, label });
+	async addAsset(
+		projectId: string,
+		path: string,
+		label?: string,
+		kind?: "video" | "audio",
+	): Promise<AiEditionAssetResult> {
+		const document = await this.options.documents.addAsset(projectId, { path, label, kind });
 		const assetId = document.project.primaryAssetId ?? document.assets.at(-1)?.id ?? "";
 		return { assetId, document };
 	}

electron/preload.ts

@@ -276,6 +276,12 @@ contextBridge.exposeInMainWorld("electronAPI", {
 	openVideoFilePicker: () => {
 		return ipcRenderer.invoke("open-video-file-picker");
 	},
+	openAudioFilePicker: () => {
+		return ipcRenderer.invoke("open-audio-file-picker");
+	},
+	saveRecordedVoiceover: (data: ArrayBuffer) => {
+		return ipcRenderer.invoke("save-recorded-voiceover", data);
+	},
 	setCurrentVideoPath: (path: string) => {
 		return ipcRenderer.invoke("set-current-video-path", path);
 	},