From cea46c2bd9efe41ca7a79359b0390b9d590d7d07 Mon Sep 17 00:00:00 2001
From: Ola Adebayo <olamideadebayo2001@gmail.com>
Date: Fri, 28 Aug 2026 15:16:10 +0100
Subject: [PATCH 1/6] feat(schema): add audio layers and audio assets to the
 document model
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Audio regions (voiceover / background music) join zoom/annotation as
clip-anchored timeline modifiers: {clipId, sourceStartSec, sourceEndSec}
is the source of truth, startMs/endMs the derived ruler cache, so layers
travel with their clip through reorder/trim (rederiveRegionMs). Assets
gain an "audio" kind — additive, no schema-version bump, and only video
imports claim the primary-asset slot. RegionKind gains "audio"; removal
cascades like every other kind.
---
 .../ai-edition/EditorEmptyState.test.tsx      |  3 +
 .../ExportDialog.showInFolder.test.tsx        |  1 +
 .../ai-edition/ExportDialog.test.ts           |  1 +
 .../ai-edition/WebcamOverlay.test.tsx         |  1 +
 .../ai-edition/document/outputFormat.test.ts  |  1 +
 src/lib/ai-edition/document/timeline.test.ts  |  1 +
 src/lib/ai-edition/document/timeline.ts       | 11 ++-
 .../ai-edition/document/transcribe.test.ts    |  1 +
 src/lib/ai-edition/schema/index.test.ts       | 57 +++++++++++-
 src/lib/ai-edition/schema/index.ts            | 46 +++++++++-
 .../ai-edition/store/editorSettings.test.ts   |  1 +
 src/lib/ai-edition/store/projectStore.test.ts |  1 +
 .../ai-edition/store/undo.modalGuard.test.tsx |  1 +
 src/lib/ai-edition/store/useCaptions.test.ts  |  1 +
 .../store/useEditorSettings.test.ts           |  1 +
 src/lib/ai-edition/store/useTimeline.test.ts  | 88 +++++++++++++++++++
 .../ai-edition/transcription/status.test.ts   |  1 +
 src/native/sceneDescription.test.ts           |  1 +
 18 files changed, 213 insertions(+), 5 deletions(-)

diff --git a/src/components/ai-edition/EditorEmptyState.test.tsx b/src/components/ai-edition/EditorEmptyState.test.tsx
index acb513e4b..09364bb74 100644
--- a/src/components/ai-edition/EditorEmptyState.test.tsx
+++ b/src/components/ai-edition/EditorEmptyState.test.tsx
@@ -53,6 +53,7 @@ const sampleDoc = vi.hoisted(
 		},
 		annotations: [],
 		zoomRanges: [],
+		audioRanges: [],
 		legacyEditor: null,
 	}),
 );
@@ -178,6 +179,7 @@ describe("EditorEmptyState (new editor)", () => {
 				"proj_test",
 				"/tmp/recording.mp4",
 				"recording.mp4",
+				undefined,
 			);
 		});
 	});
@@ -205,6 +207,7 @@ describe("EditorEmptyState (new editor)", () => {
 				"proj_test",
 				"/tmp/recording.mp4",
 				"recording.mp4",
+				undefined,
 			);
 		});
 	});
diff --git a/src/components/ai-edition/ExportDialog.showInFolder.test.tsx b/src/components/ai-edition/ExportDialog.showInFolder.test.tsx
index 835d9c8fd..f08d03362 100644
--- a/src/components/ai-edition/ExportDialog.showInFolder.test.tsx
+++ b/src/components/ai-edition/ExportDialog.showInFolder.test.tsx
@@ -75,6 +75,7 @@ const DOC: AxcutDocument = {
 	},
 	annotations: [],
 	zoomRanges: [],
+	audioRanges: [],
 	legacyEditor: null,
 };
 
diff --git a/src/components/ai-edition/ExportDialog.test.ts b/src/components/ai-edition/ExportDialog.test.ts
index 3aa8d85b5..41557e7ec 100644
--- a/src/components/ai-edition/ExportDialog.test.ts
+++ b/src/components/ai-edition/ExportDialog.test.ts
@@ -57,6 +57,7 @@ function doc(assets: AxcutAsset[], clips: AxcutClip[]): AxcutDocument {
 		},
 		annotations: [],
 		zoomRanges: [],
+		audioRanges: [],
 		legacyEditor: null,
 	};
 }
diff --git a/src/components/ai-edition/WebcamOverlay.test.tsx b/src/components/ai-edition/WebcamOverlay.test.tsx
index bdd36a558..51581165d 100644
--- a/src/components/ai-edition/WebcamOverlay.test.tsx
+++ b/src/components/ai-edition/WebcamOverlay.test.tsx
@@ -74,6 +74,7 @@ function makeDocument(): AxcutDocument {
 		},
 		annotations: [],
 		zoomRanges: [],
+		audioRanges: [],
 		legacyEditor: null,
 	};
 }
diff --git a/src/lib/ai-edition/document/outputFormat.test.ts b/src/lib/ai-edition/document/outputFormat.test.ts
index 4ceac442f..6064b7c60 100644
--- a/src/lib/ai-edition/document/outputFormat.test.ts
+++ b/src/lib/ai-edition/document/outputFormat.test.ts
@@ -67,6 +67,7 @@ function doc(assets: AxcutAsset[], clips: AxcutClip[]): AxcutDocument {
 		},
 		annotations: [],
 		zoomRanges: [],
+		audioRanges: [],
 		legacyEditor: null,
 	};
 }
diff --git a/src/lib/ai-edition/document/timeline.test.ts b/src/lib/ai-edition/document/timeline.test.ts
index a561dd2f9..c4b173b5e 100644
--- a/src/lib/ai-edition/document/timeline.test.ts
+++ b/src/lib/ai-edition/document/timeline.test.ts
@@ -57,6 +57,7 @@ function makeDoc(overrides: Partial<AxcutDocument> = {}): AxcutDocument {
 		},
 		annotations: [],
 		zoomRanges: [],
+		audioRanges: [],
 		legacyEditor: null,
 		...overrides,
 	};
diff --git a/src/lib/ai-edition/document/timeline.ts b/src/lib/ai-edition/document/timeline.ts
index 232bcb6ee..ee74abefc 100644
--- a/src/lib/ai-edition/document/timeline.ts
+++ b/src/lib/ai-edition/document/timeline.ts
@@ -17,7 +17,7 @@ import { createId } from "./ids";
  *  exist" has exactly one definition. `trim` is a source-time cut; the rest are pill-merged
  *  effects (zoom / speed / annotation / camera-fullscreen). Clips are removed via
  *  {@link removeClip}, not here — deleting a clip reflows the whole timeline. */
-export type RegionKind = "zoom" | "trim" | "annotation" | "speed" | "cameraFullscreen";
+export type RegionKind = "zoom" | "trim" | "annotation" | "speed" | "cameraFullscreen" | "audio";
 
 /** Length a clip is given before its media has been probed. Lives here, in the pure
  *  document layer, because that layer decides which clips are still waiting for a real
@@ -259,6 +259,10 @@ function mapAllRegionCollections(
 			document.annotations as unknown as StoredRegion[],
 			"ann",
 		) as unknown as AxcutDocument["annotations"],
+		audioRanges: fn(
+			document.audioRanges as unknown as StoredRegion[],
+			"aud",
+		) as unknown as AxcutDocument["audioRanges"],
 		legacyEditor:
 			legacy && (speedRegions || cameraFullscreenRegions)
 				? {
@@ -879,6 +883,11 @@ export function removeRegion(document: AxcutDocument, kind: RegionKind, id: stri
 			};
 		case "annotation":
 			return { ...document, annotations: dropPillById(document.annotations, id) };
+		case "audio":
+			return {
+				...document,
+				audioRanges: dropPillById(document.audioRanges, id) as AxcutDocument["audioRanges"],
+			};
 		case "trim":
 			return {
 				...document,
diff --git a/src/lib/ai-edition/document/transcribe.test.ts b/src/lib/ai-edition/document/transcribe.test.ts
index 72dc8d00b..da74ca338 100644
--- a/src/lib/ai-edition/document/transcribe.test.ts
+++ b/src/lib/ai-edition/document/transcribe.test.ts
@@ -49,6 +49,7 @@ function makeDoc(): AxcutDocument {
 		},
 		annotations: [],
 		zoomRanges: [],
+		audioRanges: [],
 		legacyEditor: null,
 	};
 }
diff --git a/src/lib/ai-edition/schema/index.test.ts b/src/lib/ai-edition/schema/index.test.ts
index bbba94fd8..90fb18872 100644
--- a/src/lib/ai-edition/schema/index.test.ts
+++ b/src/lib/ai-edition/schema/index.test.ts
@@ -3,6 +3,7 @@ import { migrateRawDocumentToCurrent } from "../document/migrate";
 import {
 	annotationRegionSchema,
 	assetSchema,
+	audioRegionSchema,
 	axcutSchemaVersion,
 	clipSchema,
 	createEmptyDocument,
@@ -73,15 +74,65 @@ describe("axcut-schema v7", () => {
 		).toThrow();
 	});
 
-	it("assetSchema requires kind = 'video'", () => {
+	it("assetSchema accepts kind 'video' and 'audio' but rejects anything else", () => {
 		expect(() =>
 			assetSchema.parse({
 				id: "asset_1",
-				kind: "audio",
+				kind: "image",
 				label: "x",
-				originalPath: "/x.mp4",
+				originalPath: "/x.png",
 			}),
 		).toThrow();
+		const audioAsset = assetSchema.parse({
+			id: "asset_2",
+			kind: "audio",
+			label: "music",
+			originalPath: "/m.mp3",
+		});
+		expect(audioAsset.kind).toBe("audio");
+		expect(audioAsset.cameraTrack).toBeNull();
+	});
+
+	it("audioRegionSchema defaults payload fields and validates monotonicity", () => {
+		const region = audioRegionSchema.parse({
+			id: "aud_1",
+			startMs: 0,
+			endMs: 2000,
+			assetId: "asset_2",
+			kind: "voiceover",
+		});
+		expect(region).toMatchObject({
+			offsetMs: 0,
+			gainDb: 0,
+			loop: false,
+			fadeInMs: 0,
+			fadeOutMs: 0,
+			muted: false,
+			origin: "user",
+		});
+		expect(() =>
+			audioRegionSchema.parse({
+				id: "aud_2",
+				startMs: 3000,
+				endMs: 2000,
+				assetId: "asset_2",
+				kind: "music",
+			}),
+		).toThrow();
+	});
+
+	it("documentSchema defaults audioRanges to [] when absent", () => {
+		const doc = documentSchema.parse({
+			schemaVersion: axcutSchemaVersion,
+			project: {
+				id: "proj_1",
+				title: "Test",
+				createdAt: "2026-06-26T10:00:00Z",
+				updatedAt: "2026-06-26T10:00:00Z",
+			},
+			timeline: {},
+		});
+		expect(doc.audioRanges).toEqual([]);
 	});
 
 	it("trimRangeSchema carries assetId and origin", () => {
diff --git a/src/lib/ai-edition/schema/index.ts b/src/lib/ai-edition/schema/index.ts
index dd6936fde..f4d0007bc 100644
--- a/src/lib/ai-edition/schema/index.ts
+++ b/src/lib/ai-edition/schema/index.ts
@@ -148,9 +148,19 @@ export const assetTranscriptionFailureSchema = z.object({
 	at: isoDateSchema.optional(),
 });
 
+// Audio-only media imported as an edit layer (voiceover / background music).
+// Same shape as a video asset minus the video-specific links — an audio asset
+// never appears as a timeline CLIP (the ruler's clip row is video only); it is
+// referenced by `audioRanges` regions, which place it on the timeline.
+export const assetAudioKindSchema = z.literal("audio");
+
 export const assetSchema = z.object({
 	id: z.string().min(1),
-	kind: z.literal("video"),
+	// "video" for every asset written before audio layers existed — the enum is
+	// additive, so an older build parsing a new document simply sees the one
+	// new value it doesn't know and drops the key on save (same window as
+	// `cameraTrack.width` above).
+	kind: z.enum(["video", "audio"]),
 	label: z.string().min(1),
 	originalPath: z.string().min(1),
 	proxyPath: z.string().optional(),
@@ -471,6 +481,33 @@ export const zoomRegionSchema = endGteStart(
 	"startMs",
 );
 
+// Audio layers (voiceover / background music) placed on the timeline. Same
+// v5 clip-anchor contract as zoom/annotation: `{clipId, sourceStartSec,
+// sourceEndSec}` is the source of truth, `startMs`/`endMs` the derived ruler
+// cache, so a layer travels with the clip it covers through reorder/trim.
+// `offsetMs` skips INTO the audio file (start the music at its chorus); the
+// region's own span is where it plays on the timeline. Music longer than its
+// span is trimmed to the span unless `loop` is set, in which case it repeats.
+export const audioRegionSchema = endGteStart(
+	z.object({
+		id: z.string().min(1),
+		startMs: z.number().nonnegative(),
+		endMs: z.number().nonnegative(),
+		...clipAnchorShape,
+		assetId: z.string().min(1),
+		kind: z.enum(["voiceover", "music"]),
+		offsetMs: z.number().int().nonnegative().default(0),
+		gainDb: z.number().min(-60).max(12).default(0),
+		loop: z.boolean().default(false),
+		fadeInMs: z.number().int().nonnegative().default(0),
+		fadeOutMs: z.number().int().nonnegative().default(0),
+		muted: z.boolean().default(false),
+		origin: z.enum(["system", "agent", "user"]).default("user"),
+	}),
+	"endMs",
+	"startMs",
+);
+
 // Legacy OpenScreen appearance / export settings that the v3 schema doesn't
 // normalize into the timeline / assets model. They are applied at export time
 // by the existing pipeline (see technical-documentation/architecture/document-model.md).
@@ -503,6 +540,10 @@ const documentSchemaShape = z.object({
 	}),
 	annotations: z.array(annotationRegionSchema).default([]),
 	zoomRanges: z.array(zoomRegionSchema).default([]),
+	// Audio layers. Additive with a default, so documents written before audio
+	// layers existed load unchanged (absent key → []) and no schema-version
+	// bump is needed — same convention as `cameraTrack.width`.
+	audioRanges: z.array(audioRegionSchema).default([]),
 	legacyEditor: legacyEditorSchema.nullable().default(null),
 });
 
@@ -943,6 +984,8 @@ export type AxcutTimeline = z.infer<typeof timelineSchema>;
 export type AxcutTimelineOperation = z.infer<typeof timelineOperationSchema>;
 export type AxcutAnnotationRegion = z.infer<typeof annotationRegionSchema>;
 export type AxcutZoomRegion = z.infer<typeof zoomRegionSchema>;
+export type AxcutAudioRegion = z.infer<typeof audioRegionSchema>;
+export type AxcutAudioLayerKind = AxcutAudioRegion["kind"];
 export type AxcutCameraTrack = z.infer<typeof cameraTrackSchema>;
 export type AxcutLegacyEditor = z.infer<typeof legacyEditorSchema>;
 export type AxcutDocument = z.infer<typeof documentSchema>;
@@ -979,6 +1022,7 @@ export function createEmptyDocument(
 		},
 		annotations: [],
 		zoomRanges: [],
+		audioRanges: [],
 		legacyEditor: null,
 	});
 }
diff --git a/src/lib/ai-edition/store/editorSettings.test.ts b/src/lib/ai-edition/store/editorSettings.test.ts
index 07982f47a..fa1b9b1b9 100644
--- a/src/lib/ai-edition/store/editorSettings.test.ts
+++ b/src/lib/ai-edition/store/editorSettings.test.ts
@@ -29,6 +29,7 @@ const baseDoc: AxcutDocument = {
 	},
 	annotations: [],
 	zoomRanges: [],
+	audioRanges: [],
 	transcripts: [],
 	transcript: null,
 	legacyEditor: null,
diff --git a/src/lib/ai-edition/store/projectStore.test.ts b/src/lib/ai-edition/store/projectStore.test.ts
index a46a6b535..b21222e60 100644
--- a/src/lib/ai-edition/store/projectStore.test.ts
+++ b/src/lib/ai-edition/store/projectStore.test.ts
@@ -62,6 +62,7 @@ const sampleDoc = {
 	},
 	annotations: [],
 	zoomRanges: [],
+	audioRanges: [],
 	legacyEditor: null,
 };
 
diff --git a/src/lib/ai-edition/store/undo.modalGuard.test.tsx b/src/lib/ai-edition/store/undo.modalGuard.test.tsx
index f54b12389..5c6251347 100644
--- a/src/lib/ai-edition/store/undo.modalGuard.test.tsx
+++ b/src/lib/ai-edition/store/undo.modalGuard.test.tsx
@@ -35,6 +35,7 @@ function doc(title: string): AxcutDocument {
 		},
 		annotations: [],
 		zoomRanges: [],
+		audioRanges: [],
 		legacyEditor: null,
 	};
 }
diff --git a/src/lib/ai-edition/store/useCaptions.test.ts b/src/lib/ai-edition/store/useCaptions.test.ts
index b4063d68c..78ffa2a12 100644
--- a/src/lib/ai-edition/store/useCaptions.test.ts
+++ b/src/lib/ai-edition/store/useCaptions.test.ts
@@ -71,6 +71,7 @@ const docA: AxcutDocument = {
 	},
 	annotations: [],
 	zoomRanges: [],
+	audioRanges: [],
 	legacyEditor: null,
 };
 
diff --git a/src/lib/ai-edition/store/useEditorSettings.test.ts b/src/lib/ai-edition/store/useEditorSettings.test.ts
index bd47cb452..a5b76b512 100644
--- a/src/lib/ai-edition/store/useEditorSettings.test.ts
+++ b/src/lib/ai-edition/store/useEditorSettings.test.ts
@@ -74,6 +74,7 @@ const docA: AxcutDocument = {
 	},
 	annotations: [],
 	zoomRanges: [],
+	audioRanges: [],
 	legacyEditor: null,
 };
 
diff --git a/src/lib/ai-edition/store/useTimeline.test.ts b/src/lib/ai-edition/store/useTimeline.test.ts
index 78854e817..03a0462dd 100644
--- a/src/lib/ai-edition/store/useTimeline.test.ts
+++ b/src/lib/ai-edition/store/useTimeline.test.ts
@@ -110,6 +110,7 @@ const sampleDoc: AxcutDocument = {
 	},
 	annotations: [],
 	zoomRanges: [],
+	audioRanges: [],
 	legacyEditor: null,
 };
 
@@ -547,6 +548,93 @@ describe("useTimeline.addCameraFullscreen (camera gate)", () => {
 	});
 });
 
+describe("useTimeline.addAudioRegion", () => {
+	beforeEach(() => {
+		useProjectStore.getState().clear();
+		for (const mock of Object.values(bridgeMocks)) mock.mockReset();
+		bridgeMocks.save.mockImplementation(async (doc: typeof sampleDoc) => ({
+			success: true,
+			document: doc,
+		}));
+		useProjectStore.setState({
+			projectId: "proj_test",
+			document: {
+				...sampleDoc,
+				assets: [
+					...sampleDoc.assets,
+					{
+						id: "asset_music",
+						kind: "audio",
+						label: "bgm.mp3",
+						originalPath: "/tmp/bgm.mp3",
+						durationSec: 120,
+						cameraTrack: null,
+					},
+				],
+			},
+			currentTimeSec: 1,
+			revision: 1,
+			status: "ready",
+			error: null,
+		});
+	});
+
+	afterEach(() => {
+		vi.clearAllMocks();
+	});
+
+	it("places an anchored layer at the playhead with the given span", async () => {
+		const { result } = renderTimeline();
+		await act(async () => {
+			await result.current.addAudioRegion("music", "asset_music", 5);
+		});
+		const layers = useProjectStore.getState().document?.audioRanges ?? [];
+		expect(layers).toHaveLength(1);
+		expect(layers[0]).toMatchObject({
+			assetId: "asset_music",
+			kind: "music",
+			startMs: 1000,
+			endMs: 6000,
+			gainDb: 0,
+			loop: false,
+			muted: false,
+			// Anchored to the covered clip, like every other modifier kind.
+			clipId: "clip_a",
+		});
+		// Auto-selected so its inspector opens, matching addAnnotation.
+		expect(result.current.selection).toEqual({ kind: "audio", id: layers[0]?.id });
+	});
+
+	it("refuses an asset that is not in the document", async () => {
+		const { result } = renderTimeline();
+		await act(async () => {
+			await result.current.addAudioRegion("voiceover", "asset_missing", 3);
+		});
+		expect(useProjectStore.getState().document?.audioRanges ?? []).toHaveLength(0);
+	});
+
+	it("updates payload fields group-wide and moves spans", async () => {
+		const { result } = renderTimeline();
+		await act(async () => {
+			await result.current.addAudioRegion("voiceover", "asset_music", 5);
+		});
+		const id = useProjectStore.getState().document?.audioRanges[0]?.id ?? "";
+		expect(id).toBeTruthy();
+		await act(async () => {
+			await result.current.updateAudioRegion(id, { gainDb: 6, loop: true, fadeInMs: 250 });
+			await result.current.updateAudioSpan(id, 2000, 9000);
+		});
+		const layer = useProjectStore.getState().document?.audioRanges[0];
+		expect(layer).toMatchObject({
+			gainDb: 6,
+			loop: true,
+			fadeInMs: 250,
+			startMs: 2000,
+			endMs: 9000,
+		});
+	});
+});
+
 describe("useTimeline.addAnnotation", () => {
 	beforeEach(() => {
 		useProjectStore.getState().clear();
diff --git a/src/lib/ai-edition/transcription/status.test.ts b/src/lib/ai-edition/transcription/status.test.ts
index 00261712e..4b88b94ff 100644
--- a/src/lib/ai-edition/transcription/status.test.ts
+++ b/src/lib/ai-edition/transcription/status.test.ts
@@ -243,6 +243,7 @@ describe("transcriptRelevantAssetIds", () => {
 		transcripts: [],
 		annotations: [],
 		zoomRanges: [],
+		audioRanges: [],
 		legacyEditor: null,
 	};
 
diff --git a/src/native/sceneDescription.test.ts b/src/native/sceneDescription.test.ts
index 570ae71ee..d15b85af3 100644
--- a/src/native/sceneDescription.test.ts
+++ b/src/native/sceneDescription.test.ts
@@ -91,6 +91,7 @@ function makeDoc(
 		},
 		annotations: overrides.annotations ?? [],
 		zoomRanges: overrides.zoomRanges ?? [],
+		audioRanges: overrides.audioRanges ?? [],
 		legacyEditor: overrides.legacyEditor ?? null,
 	};
 }

From d74baa360fdb1dee66bdc26c65efd58d308075f8 Mon Sep 17 00:00:00 2001
From: Ola Adebayo <olamideadebayo2001@gmail.com>
Date: Fri, 28 Aug 2026 15:16:20 +0100
Subject: [PATCH 2/6] feat(electron): import audio assets and persist recorded
 voiceovers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

DocumentService.addAsset accepts audio files (mp3/wav/m4a/ogg/flac/…)
with an explicit caller-side kind hint, so an ambiguous container (a
recorded voiceover is .webm, like a screen recording) is filed as audio
instead of video. New IPC: open-audio-file-picker (audio filters) and
save-recorded-voiceover (writes the MediaRecorder blob under the
recordings dir). read-binary-file's approval gate now covers audio
extensions so the export post-pass can read layer assets. Removing an
asset drops the layers that played it.
---
 electron/ai-edition/document-service.test.ts  | 40 ++++++++-
 electron/ai-edition/document-service.ts       | 55 ++++++++++--
 electron/electron-env.d.ts                    | 13 +++
 electron/ipc/handlers.ts                      | 87 ++++++++++++++++++-
 electron/ipc/nativeBridge.ts                  |  1 +
 .../services/aiEditionService.ts              |  9 +-
 electron/preload.ts                           |  6 ++
 src/native/browserShim.ts                     | 31 +++++--
 src/native/client.ts                          |  4 +-
 src/native/contracts.ts                       |  2 +-
 10 files changed, 228 insertions(+), 20 deletions(-)

diff --git a/electron/ai-edition/document-service.test.ts b/electron/ai-edition/document-service.test.ts
index 6cbdb97c9..5a4640883 100644
--- a/electron/ai-edition/document-service.test.ts
+++ b/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,6 +358,25 @@ 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);
@@ -349,6 +384,7 @@ describe("DocumentService", () => {
 			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();
 		});
diff --git a/electron/ai-edition/document-service.ts b/electron/ai-edition/document-service.ts
index 3c93e3bc0..b969f89bd 100644
--- a/electron/ai-edition/document-service.ts
+++ b/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,
diff --git a/electron/electron-env.d.ts b/electron/electron-env.d.ts
index 4eb288e14..ef1ab559f 100644
--- a/electron/electron-env.d.ts
+++ b/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,
diff --git a/electron/ipc/handlers.ts b/electron/ipc/handlers.ts
index 958ef6d96..bb6d7ba46 100644
--- a/electron/ipc/handlers.ts
+++ b/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
diff --git a/electron/ipc/nativeBridge.ts b/electron/ipc/nativeBridge.ts
index 47d66e270..884b50afd 100644
--- a/electron/ipc/nativeBridge.ts
+++ b/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":
diff --git a/electron/native-bridge/services/aiEditionService.ts b/electron/native-bridge/services/aiEditionService.ts
index 0fbbccc9c..e11879d25 100644
--- a/electron/native-bridge/services/aiEditionService.ts
+++ b/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 };
 	}
diff --git a/electron/preload.ts b/electron/preload.ts
index 6aff16407..7873bef90 100644
--- a/electron/preload.ts
+++ b/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);
 	},
diff --git a/src/native/browserShim.ts b/src/native/browserShim.ts
index 8ef5989a8..99e28276f 100644
--- a/src/native/browserShim.ts
+++ b/src/native/browserShim.ts
@@ -77,11 +77,21 @@ type PickVideoResult =
 	| { success: false; canceled: true };
 
 function pickVideoFileViaInput(): Promise<PickVideoResult> {
+	return pickMediaFileViaInput(
+		"video/mp4,video/quicktime,video/webm,video/x-matroska,video/x-msvideo,video/x-ms-wmv,video/*",
+	);
+}
+
+// Same shim for audio-layer imports (voiceover file / background music).
+function pickAudioFileViaInput(): Promise<PickVideoResult> {
+	return pickMediaFileViaInput("audio/*");
+}
+
+function pickMediaFileViaInput(accept: string): Promise<PickVideoResult> {
 	return new Promise((resolve) => {
 		const input = document.createElement("input");
 		input.type = "file";
-		input.accept =
-			"video/mp4,video/quicktime,video/webm,video/x-matroska,video/x-msvideo,video/x-ms-wmv,video/*";
+		input.accept = accept;
 		input.style.position = "fixed";
 		input.style.top = "-9999px";
 		let settled = false;
@@ -110,6 +120,8 @@ function createShimElectronAPI() {
 	return {
 		assetBaseUrl: "",
 		openVideoFilePicker: pickVideoFileViaInput,
+		openAudioFilePicker: pickAudioFileViaInput,
+		saveRecordedVoiceover: () => Promise.resolve({ success: false, message: "Not available" }),
 		openProjectFile: () => Promise.resolve({ success: false, canceled: true }),
 		pickExportSavePath: () => Promise.resolve({ success: false, canceled: true }),
 		writeExportToPath: () => Promise.resolve({ success: false }),
@@ -186,7 +198,7 @@ function createShimBridgeClient() {
 			updatedAt: string;
 			primaryAssetId?: string;
 		};
-		assets: Array<{ id: string; kind: "video"; label: string; originalPath: string }>;
+		assets: Array<{ id: string; kind: "video" | "audio"; label: string; originalPath: string }>;
 		[key: string]: unknown;
 	};
 	const projectsStorageKey = "browser-shim-projects-v2";
@@ -407,20 +419,27 @@ function createShimBridgeClient() {
 				saveProjectsState();
 				return Promise.resolve({ success: true });
 			},
-			addAsset: (projectId: string, path: string, label?: string) => {
+			addAsset: (projectId: string, path: string, label?: string, kind?: "video" | "audio") => {
 				const doc = documentsByProject[projectId];
 				if (!doc) return Promise.resolve({ assetId: "", document: null });
 				const assetId = `asset_${Math.random().toString(36).slice(2, 10)}`;
 				const asset = {
 					id: assetId,
-					kind: "video" as const,
+					// The caller's kind wins — the shim's paths are blob: URLs with
+					// no meaningful extension, so extension guessing is unavailable.
+					kind: (kind ?? "video") as "video" | "audio",
 					label: label || path.split(/[\\/]/).pop() || "Recording",
 					originalPath: path,
 				};
 				const next: ShimDocument = {
 					...doc,
 					assets: [...doc.assets, asset],
-					project: { ...doc.project, primaryAssetId: doc.project.primaryAssetId ?? assetId },
+					project: {
+						...doc.project,
+						// Same rule as DocumentService: only a VIDEO import claims the
+						// primary-asset slot.
+						primaryAssetId: doc.project.primaryAssetId ?? (kind === "audio" ? undefined : assetId),
+					},
 				};
 				documentsByProject[projectId] = next;
 				saveProjectsState();
diff --git a/src/native/client.ts b/src/native/client.ts
index eed5d68d7..fce40fa6c 100644
--- a/src/native/client.ts
+++ b/src/native/client.ts
@@ -181,11 +181,11 @@ export const nativeBridgeClient = {
 				action: "document.delete",
 				payload: { projectId },
 			}),
-		addAsset: (projectId: string, path: string, label?: string) =>
+		addAsset: (projectId: string, path: string, label?: string, kind?: "video" | "audio") =>
 			requireNativeBridgeData<AiEditionAssetResult>({
 				domain: "aiEdition",
 				action: "document.addAsset",
-				payload: { projectId, path, label },
+				payload: { projectId, path, label, kind },
 			}),
 		removeAsset: (projectId: string, assetId: string) =>
 			requireNativeBridgeData<AiEditionAssetResult>({
diff --git a/src/native/contracts.ts b/src/native/contracts.ts
index ede052f32..7cd15b1f7 100644
--- a/src/native/contracts.ts
+++ b/src/native/contracts.ts
@@ -516,7 +516,7 @@ export type NativeBridgeRequest =
 	| {
 			domain: "aiEdition";
 			action: "document.addAsset";
-			payload: { projectId: string; path: string; label?: string };
+			payload: { projectId: string; path: string; label?: string; kind?: "video" | "audio" };
 			requestId?: string;
 	  }
 	| {

From bba8e4ebf6107929b180af33a78566ac17f2f197 Mon Sep 17 00:00:00 2001
From: Ola Adebayo <olamideadebayo2001@gmail.com>
Date: Fri, 28 Aug 2026 15:16:30 +0100
Subject: [PATCH 3/6] feat(editor): voiceover and background music layers on
 the timeline

Two new lanes (voiceover, music) with drag/resize pills, V/B shortcuts
(remappable, advertised by the empty-lane hints), and toolbar buttons
that open the add flow: record a voiceover live from the mic (video
plays along so you can narrate what you see, auto-stops at the end of
the timeline) or import an audio file. The inspector edits volume,
mute, start offset, fades and music looping. A headless playback
component plays the layers against the timeline clock, synced to the
preview. Strings shipped in all 13 locales.
---
 .../ai-edition/AudioLayersPlayback.test.ts    |  64 ++++
 .../ai-edition/AudioLayersPlayback.tsx        | 170 ++++++++++
 src/components/ai-edition/NewEditorShell.tsx  |  98 +++++-
 .../ai-edition/v4/AddAudioLayerDialog.tsx     | 321 ++++++++++++++++++
 .../ai-edition/v4/EditorShellV4.module.css    |   8 +
 .../ai-edition/v4/FloatingInspector.tsx       | 121 ++++++-
 .../v4/V4Timeline.geometry.test.tsx           |   1 +
 src/components/ai-edition/v4/V4Timeline.tsx   |  66 +++-
 .../v4/V4Timeline.waveform.test.tsx           |   1 +
 src/i18n/locales/ar/dialogs.json              |   4 +-
 src/i18n/locales/ar/shortcuts.json            |   4 +-
 src/i18n/locales/ar/timeline.json             |  31 +-
 src/i18n/locales/en/dialogs.json              |   5 +-
 src/i18n/locales/en/shortcuts.json            |   4 +-
 src/i18n/locales/en/timeline.json             |  31 +-
 src/i18n/locales/es/dialogs.json              |   4 +-
 src/i18n/locales/es/shortcuts.json            |   4 +-
 src/i18n/locales/es/timeline.json             |  31 +-
 src/i18n/locales/fr/dialogs.json              |   4 +-
 src/i18n/locales/fr/shortcuts.json            |   4 +-
 src/i18n/locales/fr/timeline.json             |  31 +-
 src/i18n/locales/it/dialogs.json              |   4 +-
 src/i18n/locales/it/shortcuts.json            |   4 +-
 src/i18n/locales/it/timeline.json             |  31 +-
 src/i18n/locales/ja-JP/dialogs.json           |   4 +-
 src/i18n/locales/ja-JP/shortcuts.json         |   4 +-
 src/i18n/locales/ja-JP/timeline.json          |  31 +-
 src/i18n/locales/ko-KR/dialogs.json           |   4 +-
 src/i18n/locales/ko-KR/shortcuts.json         |   4 +-
 src/i18n/locales/ko-KR/timeline.json          |  31 +-
 src/i18n/locales/pt-BR/dialogs.json           |   4 +-
 src/i18n/locales/pt-BR/shortcuts.json         |   4 +-
 src/i18n/locales/pt-BR/timeline.json          |  31 +-
 src/i18n/locales/ru/dialogs.json              |   4 +-
 src/i18n/locales/ru/shortcuts.json            |   4 +-
 src/i18n/locales/ru/timeline.json             |  31 +-
 src/i18n/locales/tr/dialogs.json              |   4 +-
 src/i18n/locales/tr/shortcuts.json            |   4 +-
 src/i18n/locales/tr/timeline.json             |  31 +-
 src/i18n/locales/vi/dialogs.json              |   4 +-
 src/i18n/locales/vi/shortcuts.json            |   4 +-
 src/i18n/locales/vi/timeline.json             |  31 +-
 src/i18n/locales/zh-CN/dialogs.json           |   4 +-
 src/i18n/locales/zh-CN/shortcuts.json         |   4 +-
 src/i18n/locales/zh-CN/timeline.json          |  31 +-
 src/i18n/locales/zh-TW/dialogs.json           |   4 +-
 src/i18n/locales/zh-TW/shortcuts.json         |   4 +-
 src/i18n/locales/zh-TW/timeline.json          |  31 +-
 .../store/documentWriteAudit.test.ts          |   4 +
 src/lib/ai-edition/store/regionClipboard.ts   |   3 +
 src/lib/ai-edition/store/useTimeline.ts       | 113 ++++++
 src/lib/ai-edition/timeline/duration.ts       |  51 ++-
 src/lib/shortcuts.test.ts                     |  22 +-
 src/lib/shortcuts.ts                          |   6 +
 54 files changed, 1490 insertions(+), 67 deletions(-)
 create mode 100644 src/components/ai-edition/AudioLayersPlayback.test.ts
 create mode 100644 src/components/ai-edition/AudioLayersPlayback.tsx
 create mode 100644 src/components/ai-edition/v4/AddAudioLayerDialog.tsx

diff --git a/src/components/ai-edition/AudioLayersPlayback.test.ts b/src/components/ai-edition/AudioLayersPlayback.test.ts
new file mode 100644
index 000000000..535a5711c
--- /dev/null
+++ b/src/components/ai-edition/AudioLayersPlayback.test.ts
@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import type { AxcutAudioRegion } from "@/lib/ai-edition/schema";
+import { layerSourcePosition, layerVolumeAt } from "./AudioLayersPlayback";
+
+function region(overrides: Partial<AxcutAudioRegion> = {}): AxcutAudioRegion {
+	return {
+		id: "aud_1",
+		startMs: 10_000,
+		endMs: 20_000,
+		assetId: "asset_m",
+		kind: "music",
+		offsetMs: 0,
+		gainDb: 0,
+		loop: false,
+		fadeInMs: 0,
+		fadeOutMs: 0,
+		muted: false,
+		origin: "user",
+		...overrides,
+	};
+}
+
+describe("layerSourcePosition", () => {
+	it("maps timeline time to the source via the layer start and offset", () => {
+		expect(layerSourcePosition(region({ offsetMs: 2000 }), 13, 60)).toBeCloseTo(5);
+	});
+
+	it("clamps a non-looping layer to the end of its source", () => {
+		expect(layerSourcePosition(region(), 40, 30)).toBeCloseTo(30);
+	});
+
+	it("folds a looping layer back into the source", () => {
+		// offset 0, source 4s: timeline 13 (= local 3) → 3; timeline 14.5 → 0.5.
+		expect(layerSourcePosition(region({ loop: true }), 13, 4)).toBeCloseTo(3);
+		expect(layerSourcePosition(region({ loop: true }), 14.5, 4)).toBeCloseTo(0.5);
+	});
+
+	it("is undefined-safe for unloaded metadata (0 duration)", () => {
+		expect(layerSourcePosition(region(), 12, 0)).toBeCloseTo(2);
+	});
+});
+
+describe("layerVolumeAt", () => {
+	it("is unity mid-span with no fades", () => {
+		expect(layerVolumeAt(region(), 5)).toBe(1);
+	});
+
+	it("ramps in over the fade-in", () => {
+		const r = region({ fadeInMs: 1000 });
+		expect(layerVolumeAt(r, 0)).toBe(0);
+		expect(layerVolumeAt(r, 0.5)).toBeCloseTo(0.5);
+		expect(layerVolumeAt(r, 1)).toBe(1);
+	});
+
+	it("ramps out over the fade-out", () => {
+		const r = region({ fadeOutMs: 1000 });
+		expect(layerVolumeAt(r, 9.5)).toBeCloseTo(0.5);
+		expect(layerVolumeAt(r, 10)).toBe(0);
+	});
+
+	it("is zero when muted", () => {
+		expect(layerVolumeAt(region({ muted: true }), 5)).toBe(0);
+	});
+});
diff --git a/src/components/ai-edition/AudioLayersPlayback.tsx b/src/components/ai-edition/AudioLayersPlayback.tsx
new file mode 100644
index 000000000..bc2d07b8b
--- /dev/null
+++ b/src/components/ai-edition/AudioLayersPlayback.tsx
@@ -0,0 +1,170 @@
+// Audio-layer playback: renders nothing, and plays the document's voiceover
+// and music layers against the timeline clock. One <audio> element per region
+// (imperatively created — they are not React nodes, so nothing re-renders at
+// 60 Hz), steered by a store subscription: every `currentTimeSec` write (the
+// rAF tick during playback, a scrub while paused) re-positions each element to
+// its layer's local position and ramps its volume through the fades.
+//
+// Deliberately OUTSIDE VirtualPreview: the preview syncs its own audio to the
+// SOURCE clock of the underlying <video>, while a layer lives in TIMELINE time
+// — `currentTimeSec`, the same coordinate the ruler and the pills use. Mixing
+// the two in one component would have coupled layer playback to the active
+// video asset swap.
+
+import { useEffect, useMemo, useRef } from "react";
+import { toFileUrl } from "@/components/video-editor/projectPersistence";
+import type { AxcutAsset, AxcutAudioRegion } from "@/lib/ai-edition/schema";
+import { useProjectStore } from "@/lib/ai-edition/store/projectStore";
+
+const SYNC_EPSILON_SEC = 0.03;
+
+interface LayerElement {
+	region: AxcutAudioRegion;
+	assetId: string;
+	element: HTMLAudioElement;
+}
+
+function gainScalar(gainDb: number): number {
+	return 10 ** (gainDb / 20);
+}
+
+/** Fraction 0..1 of the full volume at `t` (seconds into the layer's span),
+ *  applying the fade in/out ramps. */
+export function layerVolumeAt(region: AxcutAudioRegion, localSec: number): number {
+	if (region.muted) return 0;
+	let v = 1;
+	if (region.fadeInMs > 0) {
+		const fadeInSec = region.fadeInMs / 1000;
+		if (localSec < fadeInSec) v = Math.min(v, localSec / fadeInSec);
+	}
+	if (region.fadeOutMs > 0) {
+		const spanSec = (region.endMs - region.startMs) / 1000;
+		const fadeOutSec = region.fadeOutMs / 1000;
+		const remaining = spanSec - localSec;
+		if (remaining < fadeOutSec) v = Math.min(v, Math.max(0, remaining / fadeOutSec));
+	}
+	return v;
+}
+
+/**
+ * Local source position (seconds) for a layer at `timelineSec`. Loop folds the
+ * position back into the source; without it the position clamps to the source
+ * length. `sourceDurationSec` comes from the element's real metadata.
+ */
+export function layerSourcePosition(
+	region: AxcutAudioRegion,
+	timelineSec: number,
+	sourceDurationSec: number,
+): number {
+	const offset = region.offsetMs / 1000;
+	const local = Math.max(0, timelineSec - region.startMs / 1000);
+	const raw = offset + local;
+	if (sourceDurationSec <= 0) return raw;
+	if (region.loop) return offset + (local % sourceDurationSec);
+	return Math.min(raw, sourceDurationSec);
+}
+
+export function AudioLayersPlayback({
+	regions,
+	assets,
+}: {
+	regions: AxcutAudioRegion[];
+	assets: AxcutAsset[];
+}) {
+	const elementsRef = useRef<LayerElement[]>([]);
+	const assetPathById = useMemo(() => new Map(assets.map((a) => [a.id, a.originalPath])), [assets]);
+
+	// Rebuild the element set only when the layer LIST changes (or an asset's
+	// path does) — payload edits (gain, fades) are read live from `regions`
+	// through the ref below, never through element re-creation.
+	useEffect(() => {
+		const existing = new Map(elementsRef.current.map((l) => [l.region.id, l]));
+		const next: LayerElement[] = [];
+		for (const region of regions) {
+			const path = assetPathById.get(region.assetId);
+			if (!path) continue;
+			const kept = existing.get(region.id);
+			if (kept && kept.assetId === region.assetId) {
+				kept.region = region;
+				next.push(kept);
+				existing.delete(region.id);
+				continue;
+			}
+			const element = new Audio(toFileUrl(path));
+			element.preload = "auto";
+			element.volume = 0;
+			next.push({ region, assetId: region.assetId, element });
+		}
+		// Drop layers that no longer exist (or lost their asset).
+		for (const stale of existing.values()) {
+			stale.element.pause();
+			stale.element.removeAttribute("src");
+			try {
+				stale.element.load();
+			} catch {
+				// ignore — element is being released
+			}
+		}
+		elementsRef.current = next;
+	}, [regions, assetPathById]);
+
+	// Live payload + playhead sync. The store writes `currentTimeSec` every rAF
+	// during playback, so this subscription fires at frame rate — direct DOM
+	// mutation, no React state anywhere in the loop.
+	useEffect(() => {
+		const unsubscribe = useProjectStore.subscribe((state, prev) => {
+			const timeSec = state.currentTimeSec;
+			const playing = state.playing;
+			if (timeSec === prev.currentTimeSec && playing === prev.playing) return;
+			for (const { region, element } of elementsRef.current) {
+				const startSec = region.startMs / 1000;
+				const endSec = region.endMs / 1000;
+				const active = timeSec >= startSec && timeSec < endSec;
+				if (!active) {
+					if (!element.paused) element.pause();
+					continue;
+				}
+				const sourceDuration = Number.isFinite(element.duration) ? element.duration : 0;
+				const target = layerSourcePosition(region, timeSec, sourceDuration);
+				if (Math.abs(element.currentTime - target) > SYNC_EPSILON_SEC) {
+					try {
+						element.currentTime = target;
+					} catch {
+						// metadata not ready yet
+					}
+				}
+				// Clamped to 1: an HTML element cannot boost past 0 dB. The export
+				// applies the full scalar; the preview is the approximation.
+				element.volume = Math.min(
+					1,
+					gainScalar(region.gainDb) * layerVolumeAt(region, timeSec - startSec),
+				);
+				if (playing && element.paused) {
+					const play = element.play();
+					if (play) void play.catch(() => undefined);
+				} else if (!playing && !element.paused) {
+					element.pause();
+				}
+			}
+		});
+		return unsubscribe;
+	}, []);
+
+	// Release everything on unmount.
+	useEffect(() => {
+		return () => {
+			for (const { element } of elementsRef.current) {
+				element.pause();
+				element.removeAttribute("src");
+				try {
+					element.load();
+				} catch {
+					// ignore
+				}
+			}
+			elementsRef.current = [];
+		};
+	}, []);
+
+	return null;
+}
diff --git a/src/components/ai-edition/NewEditorShell.tsx b/src/components/ai-edition/NewEditorShell.tsx
index 64987dea9..9aa74ad56 100644
--- a/src/components/ai-edition/NewEditorShell.tsx
+++ b/src/components/ai-edition/NewEditorShell.tsx
@@ -31,6 +31,7 @@ import { nativeBridgeClient } from "@/native";
 import type { AiEditionProjectSummary } from "@/native/contracts";
 import { resolveVisibleClips } from "@/native/sceneDescription";
 import { useNativePlaybackSync } from "@/native/useNativePlaybackSync";
+import { AudioLayersPlayback } from "./AudioLayersPlayback";
 import { ExportDialog } from "./ExportDialog";
 import { LeftPanel } from "./LeftPanel";
 import {
@@ -44,6 +45,7 @@ import {
 import { Preview } from "./Preview";
 import type { TrimTarget } from "./RightPanes";
 import { importPendingRecording } from "./recordingImport";
+import { AddAudioLayerDialog } from "./v4/AddAudioLayerDialog";
 import v4 from "./v4/EditorShellV4.module.css";
 import { type EditorMode, EditorTopBar } from "./v4/EditorTopBar";
 import { type Facet, FloatingInspector } from "./v4/FloatingInspector";
@@ -127,6 +129,15 @@ export function NewEditorShell() {
 	// mounted per trigger site.
 	const [editClipTarget, setEditClipTarget] = useState<AxcutClip | null>(null);
 	const [exportOpen, setExportOpen] = useState(false);
+	// Which add-audio-layer flow is on screen (voiceover record/import, music
+	// import). `null` = closed. Lifted to the shell so the toolbar buttons AND
+	// the V/B shortcuts drive the same dialog instance. `maxDurationSec` is the
+	// timeline left to cover when the flow opened — the voiceover recorder stops
+	// itself at the end of the video instead of recording into the void.
+	const [audioLayerFlow, setAudioLayerFlow] = useState<{
+		kind: "voiceover" | "music";
+		maxDurationSec: number;
+	} | null>(null);
 	const [unsavedPrompt, setUnsavedPrompt] = useState<{
 		action: "close" | "new" | "open" | "record";
 		resolve: (choice: UnsavedChoice) => void;
@@ -496,6 +507,46 @@ export function NewEditorShell() {
 		}
 	}, [videoElement]);
 
+	// ── audio layers ──────────────────────────────────────────────────────
+	// V / B (or the timeline toolbar) open the add flow; the dialog resolves an
+	// audio ASSET and its duration and hands them back via onComplete, where the
+	// region actually gets placed (span at the playhead, clip anchor, inspector
+	// selection) — the same split every other add* flow uses.
+	const openAudioLayerFlow = useCallback((kind: "voiceover" | "music") => {
+		const doc = useProjectStore.getState().document;
+		if (!doc) return;
+		const total = Math.max(
+			0.001,
+			doc.timeline.clips.reduce((max, c) => Math.max(max, c.timelineEndSec), 0),
+		);
+		const playhead = useProjectStore.getState().currentTimeSec;
+		setAudioLayerFlow({
+			kind,
+			maxDurationSec: Math.max(0.5, total - playhead),
+		});
+	}, []);
+
+	const handleAudioLayerReady = useCallback(
+		async (kind: "voiceover" | "music", assetId: string, durationSec: number) => {
+			setAudioLayerFlow(null);
+			const dur = durationSec > 0 ? durationSec : newRegionDurationSec();
+			await tl.addAudioRegion(kind, assetId, dur);
+		},
+		[tl],
+	);
+
+	// While a voiceover is being recorded the video plays from the playhead, so
+	// the user can narrate what they see; stopping the recording pauses it
+	// again. The dialog owns the mic, the shell owns the transport.
+	const handleVoiceoverRecordingStart = useCallback(() => {
+		if (videoElement && videoElement.paused) {
+			void videoElement.play().catch(() => undefined);
+		}
+	}, [videoElement]);
+	const handleVoiceoverRecordingStop = useCallback(() => {
+		videoElement?.pause();
+	}, [videoElement]);
+
 	const handlePrevClip = useCallback(() => {
 		if (clips.length === 0) return;
 		// ponytail: navigate in virtual timeline space, not source-media time.
@@ -792,7 +843,8 @@ export function NewEditorShell() {
 		// Land it at the playhead, keeping the copied length.
 		const timeMs = Math.round(useProjectStore.getState().currentTimeSec * 1000);
 		const src = snapshot.region as { startMs: number; endMs: number };
-		const prefix = snapshot.kind === "annotation" ? "ann" : snapshot.kind;
+		const prefix =
+			snapshot.kind === "annotation" ? "ann" : snapshot.kind === "audio" ? "aud" : snapshot.kind;
 		const pasted = {
 			...snapshot.region,
 			id: createId(prefix),
@@ -825,6 +877,16 @@ export function NewEditorShell() {
 				},
 				{ history: true },
 			);
+		} else if (snapshot.kind === "audio") {
+			// An audio layer pastes with its payload intact (asset, gain, fades)
+			// at the playhead — the same deal every other kind gets.
+			await saveDocument(
+				{
+					...doc,
+					audioRanges: [...doc.audioRanges, ...anchored] as typeof doc.audioRanges,
+				},
+				{ history: true },
+			);
 		} else {
 			// speed and cameraFullscreen are both plain spans on legacyEditor.
 			const key = snapshot.kind === "speed" ? "speedRegions" : "cameraFullscreenRegions";
@@ -877,7 +939,9 @@ export function NewEditorShell() {
 					? tl.annotationRegions
 					: sel.kind === "speed"
 						? tl.speedRegions
-						: tl.cameraFullscreenRegions;
+						: sel.kind === "audio"
+							? tl.audioRegions
+							: tl.cameraFullscreenRegions;
 		const region = (source as Array<{ id: string }>).find((r) => r.id === sel.id);
 		if (!region) return;
 		copyRegion({ kind: sel.kind, region: region as unknown as Record<string, unknown> });
@@ -1042,6 +1106,16 @@ export function NewEditorShell() {
 				void tl.addCameraFullscreen(newRegionDurationSec());
 				return;
 			}
+			if (matchesShortcut(e, shortcuts.addVoiceover, isMac)) {
+				e.preventDefault();
+				openAudioLayerFlow("voiceover");
+				return;
+			}
+			if (matchesShortcut(e, shortcuts.addMusic, isMac)) {
+				e.preventDefault();
+				openAudioLayerFlow("music");
+				return;
+			}
 
 			// Fixed (non-configurable) shortcuts advertised in the shortcuts dialog.
 			if (e.key === "Tab") {
@@ -1086,6 +1160,7 @@ export function NewEditorShell() {
 		isMac,
 		togglePlay,
 		handleSeek,
+		openAudioLayerFlow,
 	]);
 
 	const showTimeline = mode !== "rec";
@@ -1325,6 +1400,7 @@ export function NewEditorShell() {
 						onPrevClip={handlePrevClip}
 						onNextClip={handleNextClip}
 						onEditClip={setEditClipTarget}
+						onAddAudioLayer={openAudioLayerFlow}
 					/>
 				</div>
 			) : null}
@@ -1383,6 +1459,24 @@ export function NewEditorShell() {
 				onChoose={handleConfirmUnsaved}
 			/>
 			<ExportDialog open={exportOpen} onClose={() => setExportOpen(false)} document={document} />
+
+			{/* Voiceover / music layers: the playback engine is a headless
+			    component next to the preview, and the add-flow dialog is shell
+			    level so V/B and the timeline toolbar share it. */}
+			{showTimeline ? <AudioLayersPlayback regions={tl.audioRegions} assets={tl.assets} /> : null}
+			<AddAudioLayerDialog
+				open={audioLayerFlow !== null}
+				kind={audioLayerFlow?.kind ?? "voiceover"}
+				maxDurationSec={audioLayerFlow?.maxDurationSec ?? 0}
+				onClose={() => setAudioLayerFlow(null)}
+				onComplete={(assetId, durationSec) => {
+					if (audioLayerFlow) {
+						void handleAudioLayerReady(audioLayerFlow.kind, assetId, durationSec);
+					}
+				}}
+				onRecordingStart={handleVoiceoverRecordingStart}
+				onRecordingStop={handleVoiceoverRecordingStop}
+			/>
 		</div>
 	);
 }
diff --git a/src/components/ai-edition/v4/AddAudioLayerDialog.tsx b/src/components/ai-edition/v4/AddAudioLayerDialog.tsx
new file mode 100644
index 000000000..edd090d85
--- /dev/null
+++ b/src/components/ai-edition/v4/AddAudioLayerDialog.tsx
@@ -0,0 +1,321 @@
+// Add-audio-layer dialog: the single entry point for placing a voiceover or a
+// background-music layer on the timeline. Two ways in:
+//
+//   - voiceover: record live from the microphone (MediaRecorder → webm/opus,
+//     written to the recordings dir by the main process) or import an audio file;
+//   - music: import an audio file.
+//
+// The dialog resolves the AUDIO ASSET and its duration, then reports back via
+// `onComplete` — placing the region on the timeline (span, anchor, inspector
+// selection) is the caller's job, exactly like the other add* flows.
+
+import { Mic, Music, StopCircle, Upload } from "lucide-react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { toast } from "sonner";
+import { toFileUrl } from "@/components/video-editor/projectPersistence";
+import { useScopedT } from "@/contexts/I18nContext";
+import type { AxcutAsset } from "@/lib/ai-edition/schema";
+import { useProjectStore } from "@/lib/ai-edition/store/projectStore";
+import { probeAudioDuration } from "@/lib/ai-edition/timeline/duration";
+import { ModalShell } from "../Modals";
+
+type AudioLayerKind = "voiceover" | "music";
+
+const RECORDER_MIME_PREFERENCES = ["audio/webm;codecs=opus", "audio/webm", "audio/mp4"];
+
+function pickRecorderMimeType(): string {
+	if (typeof MediaRecorder === "undefined") return "";
+	for (const mime of RECORDER_MIME_PREFERENCES) {
+		if (MediaRecorder.isTypeSupported(mime)) return mime;
+	}
+	return "";
+}
+
+/** Reuse an already-imported asset over importing the same file twice. */
+function findExistingAsset(path: string): AxcutAsset | null {
+	const doc = useProjectStore.getState().document;
+	if (!doc) return null;
+	return (
+		doc.assets.find((a) => a.kind === "audio" && a.originalPath === path) ??
+		doc.assets.find((a) => a.originalPath === path) ??
+		null
+	);
+}
+
+export function AddAudioLayerDialog({
+	open,
+	kind,
+	/** Timeline length in seconds — recording stops by itself when reached. */
+	maxDurationSec,
+	onClose,
+	onComplete,
+	onRecordingStart,
+	onRecordingStop,
+}: {
+	open: boolean;
+	kind: AudioLayerKind;
+	maxDurationSec: number;
+	onClose: () => void;
+	onComplete: (assetId: string, durationSec: number) => void;
+	onRecordingStart: () => void;
+	onRecordingStop: () => void;
+}) {
+	const t = useScopedT("timeline");
+	const [busy, setBusy] = useState(false);
+	const [recording, setRecording] = useState(false);
+	const [elapsedSec, setElapsedSec] = useState(0);
+	const recorderRef = useRef<MediaRecorder | null>(null);
+	const streamRef = useRef<MediaStream | null>(null);
+	const chunksRef = useRef<Blob[]>([]);
+	const startedAtRef = useRef(0);
+	const timerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+	// Set when the user cancels (closes the dialog mid-take) — the stop handler
+	// then discards the blob instead of importing it as a layer.
+	const discardRef = useRef(false);
+
+	// Reset whenever the dialog opens again — a cancelled recording must not
+	// leak its stream or timer into the next session.
+	useEffect(() => {
+		if (open) {
+			setBusy(false);
+			setRecording(false);
+			setElapsedSec(0);
+		}
+		return () => {
+			if (timerRef.current) clearInterval(timerRef.current);
+			timerRef.current = null;
+			for (const track of streamRef.current?.getTracks() ?? []) track.stop();
+			streamRef.current = null;
+			recorderRef.current = null;
+		};
+	}, [open]);
+
+	const stopRecording = useCallback(() => {
+		if (timerRef.current) {
+			clearInterval(timerRef.current);
+			timerRef.current = null;
+		}
+		const recorder = recorderRef.current;
+		// `recorder.onstop` (registered at start) owns the save path.
+		if (recorder && recorder.state !== "inactive") {
+			recorder.stop();
+		}
+		for (const track of streamRef.current?.getTracks() ?? []) track.stop();
+		streamRef.current = null;
+	}, []);
+
+	const cancelRecording = useCallback(() => {
+		discardRef.current = true;
+		stopRecording();
+		onRecordingStop();
+		setRecording(false);
+		setElapsedSec(0);
+	}, [stopRecording, onRecordingStop]);
+
+	const finishWithPath = useCallback(
+		async (path: string, durationSec: number) => {
+			setBusy(true);
+			try {
+				const existing = findExistingAsset(path);
+				// The kind is explicit: a recorded voiceover lands as `.webm`, the
+				// same extension as a screen recording, so extension guessing
+				// would file it as a video asset.
+				const asset =
+					existing ?? (await useProjectStore.getState().addAsset(path, undefined, "audio"));
+				if (!asset) {
+					toast.error(t("audio.importFailed"));
+					return;
+				}
+				onComplete(asset.id, durationSec);
+			} catch (err) {
+				toast.error(t("audio.importFailed"), {
+					description: err instanceof Error ? err.message : String(err),
+				});
+			} finally {
+				setBusy(false);
+			}
+		},
+		[onComplete, t],
+	);
+
+	const startRecording = useCallback(async () => {
+		if (typeof navigator === "undefined" || !navigator.mediaDevices?.getUserMedia) {
+			toast.error(t("audio.recordingUnavailable"));
+			return;
+		}
+		try {
+			const stream = await navigator.mediaDevices.getUserMedia({
+				audio: { echoCancellation: true, noiseSuppression: true },
+			});
+			streamRef.current = stream;
+			const mimeType = pickRecorderMimeType();
+			const recorder = mimeType
+				? new MediaRecorder(stream, { mimeType })
+				: new MediaRecorder(stream);
+			recorderRef.current = recorder;
+			chunksRef.current = [];
+			recorder.ondataavailable = (event) => {
+				if (event.data.size > 0) chunksRef.current.push(event.data);
+			};
+			recorder.onstop = () => {
+				const blob = new Blob(chunksRef.current, {
+					type: recorder.mimeType || "audio/webm",
+				});
+				const duration = (performance.now() - startedAtRef.current) / 1000;
+				const discarded = discardRef.current;
+				discardRef.current = false;
+				setRecording(false);
+				setElapsedSec(0);
+				onRecordingStop();
+				if (discarded) return;
+				void (async () => {
+					try {
+						const data = await blob.arrayBuffer();
+						const saved = window.electronAPI?.saveRecordedVoiceover
+							? await window.electronAPI.saveRecordedVoiceover(data)
+							: { success: false as const };
+						if (saved.success && saved.path) {
+							await finishWithPath(saved.path, duration);
+						} else {
+							// Browser-mode fallback: no main process to persist the
+							// blob, so the layer references the in-memory blob URL —
+							// good for the session, gone on reload.
+							const url = URL.createObjectURL(blob);
+							await finishWithPath(url, duration);
+						}
+					} catch (err) {
+						toast.error(t("audio.saveFailed"), {
+							description: err instanceof Error ? err.message : String(err),
+						});
+					}
+				})();
+			};
+			startedAtRef.current = performance.now();
+			discardRef.current = false;
+			recorder.start(250);
+			setRecording(true);
+			setElapsedSec(0);
+			onRecordingStart();
+			timerRef.current = setInterval(() => {
+				setElapsedSec((performance.now() - startedAtRef.current) / 1000);
+			}, 200);
+		} catch {
+			toast.error(t("audio.micDenied"));
+		}
+	}, [finishWithPath, onRecordingStart, onRecordingStop, t]);
+
+	// Stop by itself at the end of the timeline so a layer can never outlive
+	// the video it was recorded over.
+	useEffect(() => {
+		if (!recording || !Number.isFinite(maxDurationSec) || maxDurationSec <= 0) return;
+		if (elapsedSec >= maxDurationSec) {
+			stopRecording();
+			// `onRecordingStop` fires from the recorder's stop handler.
+		}
+	}, [recording, elapsedSec, maxDurationSec, stopRecording]);
+
+	const importFile = useCallback(async () => {
+		const picker = await window.electronAPI?.openAudioFilePicker?.();
+		if (!picker?.success || !picker.path) return;
+		const url = toFileUrl(picker.path);
+		// The probe needs the real duration to size the layer; when it fails the
+		// caller falls back to the default span.
+		const duration = (await probeAudioDuration(url)) ?? 0;
+		await finishWithPath(picker.path, duration);
+	}, [finishWithPath]);
+
+	// Music has nothing to record — open the picker as soon as the dialog is up.
+	useEffect(() => {
+		if (open && kind === "music" && !busy && !recording) {
+			void importFile();
+		}
+	}, [open, kind, busy, recording, importFile]);
+
+	const isVoiceover = kind === "voiceover";
+	const buttonStyle: React.CSSProperties = {
+		display: "flex",
+		alignItems: "center",
+		justifyContent: "center",
+		gap: 8,
+		padding: "10px 14px",
+		borderRadius: 10,
+		border: "1px solid var(--border)",
+		background: "var(--bg-2)",
+		color: "var(--fg-1)",
+		font: "600 13px var(--font-display)",
+		cursor: "pointer",
+	};
+
+	return (
+		<ModalShell
+			open={open}
+			onClose={() => {
+				if (recording) cancelRecording();
+				onClose();
+			}}
+			title={isVoiceover ? t("audio.addVoiceover") : t("audio.addMusic")}
+			subtitle={t("audio.subtitle")}
+		>
+			<div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+				{recording ? (
+					<div
+						style={{
+							display: "flex",
+							flexDirection: "column",
+							alignItems: "center",
+							gap: 12,
+							padding: "18px 0 8px",
+						}}
+					>
+						<span
+							style={{
+								display: "inline-flex",
+								alignItems: "center",
+								gap: 8,
+								color: "var(--danger)",
+								font: "600 13px var(--font-display)",
+							}}
+						>
+							<span
+								className="animate-pulse"
+								style={{
+									width: 10,
+									height: 10,
+									borderRadius: 999,
+									background: "var(--danger)",
+								}}
+							/>
+							{t("audio.recording")} {elapsedSec.toFixed(1)}s
+						</span>
+						<button
+							type="button"
+							onClick={stopRecording}
+							style={{ ...buttonStyle, borderColor: "var(--danger)", color: "var(--danger)" }}
+						>
+							<StopCircle size={16} />
+							{t("audio.stop")}
+						</button>
+					</div>
+				) : (
+					<>
+						{isVoiceover ? (
+							<button type="button" onClick={() => void startRecording()} style={buttonStyle}>
+								<Mic size={16} />
+								{t("audio.record")}
+							</button>
+						) : null}
+						<button
+							type="button"
+							onClick={() => void importFile()}
+							disabled={busy}
+							style={buttonStyle}
+						>
+							{isVoiceover ? <Upload size={16} /> : <Music size={16} />}
+							{isVoiceover ? t("audio.importFile") : t("audio.chooseMusic")}
+						</button>
+					</>
+				)}
+			</div>
+		</ModalShell>
+	);
+}
diff --git a/src/components/ai-edition/v4/EditorShellV4.module.css b/src/components/ai-edition/v4/EditorShellV4.module.css
index 1e313e34c..44660a9c3 100644
--- a/src/components/ai-edition/v4/EditorShellV4.module.css
+++ b/src/components/ai-edition/v4/EditorShellV4.module.css
@@ -1496,6 +1496,14 @@
 	border-color: #a855f7;
 	background: rgba(168, 85, 247, 0.14);
 }
+.laneVoiceover {
+	border-color: #22c55e;
+	background: rgba(34, 197, 94, 0.14);
+}
+.laneMusic {
+	border-color: #eab308;
+	background: rgba(234, 179, 8, 0.14);
+}
 .tlClips {
 	position: relative;
 	/* NOT a flex row. Clips are absolutely positioned by percentage of the
diff --git a/src/components/ai-edition/v4/FloatingInspector.tsx b/src/components/ai-edition/v4/FloatingInspector.tsx
index ac162d322..f7ed7804f 100644
--- a/src/components/ai-edition/v4/FloatingInspector.tsx
+++ b/src/components/ai-edition/v4/FloatingInspector.tsx
@@ -5,7 +5,9 @@ import {
 	FileText,
 	Layout as LayoutIcon,
 	Maximize2,
+	Mic,
 	MousePointer2,
+	Music,
 	Pencil,
 	Scissors,
 	SlidersHorizontal,
@@ -33,7 +35,7 @@ import {
 	type AnnotationTextAnimation,
 	TEXT_ANIMATION_VALUES,
 } from "@/lib/ai-edition/annotations/textAnimation";
-import type { AxcutAnnotationRegion, AxcutClip } from "@/lib/ai-edition/schema";
+import type { AxcutAnnotationRegion, AxcutAudioRegion, AxcutClip } from "@/lib/ai-edition/schema";
 import { rafCoalesce } from "@/lib/ai-edition/store/rafCoalesce";
 import { useEditorSettings } from "@/lib/ai-edition/store/useEditorSettings";
 import type { useTimeline } from "@/lib/ai-edition/store/useTimeline";
@@ -442,6 +444,93 @@ export function SpeedControl({
 	);
 }
 
+/**
+ * Per-layer controls for a selected audio region (gain, mute, start offset,
+ * fades, loop). Sliders drag against a LOCAL draft and commit once on release
+ * — the same reason annotations use `updateAnnotationLive`: a range input
+ * emits one event per pixel, and one `saveDocument` (IPC + disk + re-parse)
+ * per pixel turns a smooth drag into a write flood.
+ */
+function AudioRegionControls({ region, tl }: { region: AxcutAudioRegion; tl: TimelineApi }) {
+	const tt = useScopedT("timeline");
+	const [gainDraft, setGainDraft] = useState(region.gainDb);
+	const [offsetDraft, setOffsetDraft] = useState(region.offsetMs / 1000);
+	const [fadeInDraft, setFadeInDraft] = useState(region.fadeInMs / 1000);
+	const [fadeOutDraft, setFadeOutDraft] = useState(region.fadeOutMs / 1000);
+
+	return (
+		<>
+			<SliderCell
+				label={tt("audio.gain")}
+				value={gainDraft}
+				min={-60}
+				max={12}
+				decimals={0}
+				suffix=" dB"
+				onChange={setGainDraft}
+				onCommit={() => void tl.updateAudioRegion(region.id, { gainDb: gainDraft })}
+			/>
+			{paneRow(
+				tt("audio.mute"),
+				<Toggle
+					checked={region.muted}
+					ariaLabel={tt("audio.mute")}
+					onChange={(next) => void tl.updateAudioRegion(region.id, { muted: next })}
+				/>,
+			)}
+			<SliderCell
+				label={tt("audio.offset")}
+				value={offsetDraft}
+				min={0}
+				max={30}
+				step={0.1}
+				decimals={1}
+				suffix=" s"
+				onChange={setOffsetDraft}
+				onCommit={() =>
+					void tl.updateAudioRegion(region.id, { offsetMs: Math.round(offsetDraft * 1000) })
+				}
+			/>
+			<SliderCell
+				label={tt("audio.fadeIn")}
+				value={fadeInDraft}
+				min={0}
+				max={5}
+				step={0.05}
+				decimals={2}
+				suffix=" s"
+				onChange={setFadeInDraft}
+				onCommit={() =>
+					void tl.updateAudioRegion(region.id, { fadeInMs: Math.round(fadeInDraft * 1000) })
+				}
+			/>
+			<SliderCell
+				label={tt("audio.fadeOut")}
+				value={fadeOutDraft}
+				min={0}
+				max={5}
+				step={0.05}
+				decimals={2}
+				suffix=" s"
+				onChange={setFadeOutDraft}
+				onCommit={() =>
+					void tl.updateAudioRegion(region.id, { fadeOutMs: Math.round(fadeOutDraft * 1000) })
+				}
+			/>
+			{region.kind === "music"
+				? paneRow(
+						tt("audio.loop"),
+						<Toggle
+							checked={region.loop}
+							ariaLabel={tt("audio.loop")}
+							onChange={(next) => void tl.updateAudioRegion(region.id, { loop: next })}
+						/>,
+					)
+				: null}
+		</>
+	);
+}
+
 function SelectionPane({ tl, onClose }: { tl: TimelineApi; onClose: () => void }) {
 	const ts = useScopedT("settings");
 	const tt = useScopedT("timeline");
@@ -978,6 +1067,36 @@ function SelectionPane({ tl, onClose }: { tl: TimelineApi; onClose: () => void }
 		);
 	}
 
+	if (selection.kind === "audio") {
+		const region = tl.audioRegions.find((a) => a.id === selection.id);
+		if (!region) return null;
+		const asset = tl.assets.find((a) => a.id === region.assetId);
+		const isMusic = region.kind === "music";
+		const Icon = isMusic ? Music : Mic;
+		return (
+			<div style={{ display: "flex", flexDirection: "column", minHeight: 0 }}>
+				{paneHeader(
+					<Icon size={15} />,
+					isMusic ? tt("audio.musicLabel") : tt("audio.voiceoverLabel"),
+					onClose,
+					tc("actions.close"),
+				)}
+				<div style={bodyStyle}>
+					{asset ? (
+						<p style={{ margin: 0, fontSize: 11.5, lineHeight: 1.5, color: "var(--muted)" }}>
+							{asset.label}
+						</p>
+					) : null}
+					<AudioRegionControls key={region.id} region={region} tl={tl} />
+					<button type="button" onClick={deleteAndClose} style={deleteBtnStyle}>
+						<Trash2 size={14} />
+						{tt("audio.deleteLayer")}
+					</button>
+				</div>
+			</div>
+		);
+	}
+
 	// trim — a trim ventilated across a clip boundary is 2+ DSL rows that render
 	// as one coalesced pill (see V4Timeline's trimPills), so the DURATION shown has to be
 	// the group's, not the clicked row's. Deleting no longer needs the same expansion here:
diff --git a/src/components/ai-edition/v4/V4Timeline.geometry.test.tsx b/src/components/ai-edition/v4/V4Timeline.geometry.test.tsx
index 8e515568c..e162098fe 100644
--- a/src/components/ai-edition/v4/V4Timeline.geometry.test.tsx
+++ b/src/components/ai-edition/v4/V4Timeline.geometry.test.tsx
@@ -80,6 +80,7 @@ function renderTimeline(
 		speedRegions: [],
 		cameraFullscreenRegions: [],
 		zoomRegions: [],
+		audioRegions: [],
 		trimRanges: [],
 		selection: null,
 		multiSelection: [],
diff --git a/src/components/ai-edition/v4/V4Timeline.tsx b/src/components/ai-edition/v4/V4Timeline.tsx
index f6c94e2ca..502906298 100644
--- a/src/components/ai-edition/v4/V4Timeline.tsx
+++ b/src/components/ai-edition/v4/V4Timeline.tsx
@@ -4,6 +4,8 @@ import {
 	Loader2,
 	Maximize2,
 	MessageSquare,
+	Mic,
+	Music,
 	Pencil,
 	Scissors,
 	Sparkles,
@@ -337,7 +339,7 @@ const ClipWaveform = memo(function ClipWaveform({
 
 interface LanePill {
 	id: string;
-	kind: "annotation" | "speed" | "trim" | "zoom" | "cameraFullscreen";
+	kind: "annotation" | "speed" | "trim" | "zoom" | "cameraFullscreen" | "voiceover" | "music";
 	start: number;
 	end: number;
 	label: string;
@@ -356,6 +358,7 @@ export function V4Timeline({
 	onPrevClip,
 	onNextClip,
 	onEditClip,
+	onAddAudioLayer,
 }: {
 	tl: TimelineApi;
 	setCurrentTime: (sec: number) => void;
@@ -369,6 +372,8 @@ export function V4Timeline({
 	/** Opens the (now single, shell-level) EditClipModal for this clip —
 	 * trim in/out and crop both live there per-clip. */
 	onEditClip: (clip: AxcutClip) => void;
+	/** Opens the add-audio-layer flow (voiceover record/import, music import). */
+	onAddAudioLayer?: (kind: "voiceover" | "music") => void;
 }) {
 	const t = useScopedT("timeline");
 	// The camera lane borrows the Layout pane's "No Webcam" wording when there is no
@@ -523,6 +528,22 @@ export function V4Timeline({
 		sourceIds: g.ids,
 	}));
 
+	// Audio layers: one lane per kind, labelled by the asset they play (the
+	// inspector carries the full payload — gain, fades, loop, mute).
+	const audioPills = (kind: "voiceover" | "music"): LanePill[] =>
+		coalesceRegionsForRuler(tl.audioRegions.filter((r) => r.kind === kind)).map((p) => ({
+			id: p.ids[0],
+			kind,
+			start: p.start,
+			end: p.end,
+			label:
+				tl.assets.find((a) => a.id === (p.member as { assetId?: string }).assetId)?.label ??
+				(kind === "voiceover" ? t("audio.voiceoverLabel") : t("audio.musicLabel")),
+			sourceIds: p.ids,
+		}));
+	const voiceoverPills = audioPills("voiceover");
+	const musicPills = audioPills("music");
+
 	// Ruler ticks are chosen from what is actually ON SCREEN, not from the clip
 	// length: the canvas is widened by 1/navSpan, so the same recording shows one
 	// label per 30s zoomed out and one per tenth of a second zoomed in. The step
@@ -664,7 +685,11 @@ export function V4Timeline({
 		(e: ReactPointerEvent, pill: LanePill, dragMode: "move" | "l" | "r") => {
 			e.preventDefault();
 			e.stopPropagation();
-			tl.selectRegion(pill.kind, pill.id, { additive: e.shiftKey });
+			// Voiceover and music render on separate lanes but are the SAME region
+			// kind in the document ("audio") — selection and deletion key off the
+			// document kind, the payload's own `kind` tells the lanes apart.
+			const regionKind = pill.kind === "voiceover" || pill.kind === "music" ? "audio" : pill.kind;
+			tl.selectRegion(regionKind, pill.id, { additive: e.shiftKey });
 			// Scale drag deltas against the canvas (full zoomed timeline) width, so a
 			// drag tracks the cursor exactly regardless of padding, scrollbar or zoom.
 			const el = canvasRef.current;
@@ -717,6 +742,8 @@ export function V4Timeline({
 					await tl.updateAnnotationSpan(pill.id, s * 1000, en * 1000);
 				else if (pill.kind === "cameraFullscreen")
 					await tl.updateCameraFullscreenSpan(pill.id, s * 1000, en * 1000);
+				else if (pill.kind === "voiceover" || pill.kind === "music")
+					await tl.updateAudioSpan(pill.id, s * 1000, en * 1000);
 				else {
 					// Trims are stored in source-time per asset but manipulated on the
 					// timeline like every other pill. Ventilate the new span across the
@@ -901,7 +928,11 @@ export function V4Timeline({
 					? styles.laneTrim
 					: kind === "cameraFullscreen"
 						? styles.laneCameraFullscreen
-						: styles.laneZoom;
+						: kind === "voiceover"
+							? styles.laneVoiceover
+							: kind === "music"
+								? styles.laneMusic
+								: styles.laneZoom;
 	const pillIcon = (kind: LanePill["kind"]) =>
 		kind === "annotation" ? (
 			<MessageSquare size={11} />
@@ -911,6 +942,10 @@ export function V4Timeline({
 			<Scissors size={11} />
 		) : kind === "cameraFullscreen" ? (
 			<Maximize2 size={11} />
+		) : kind === "voiceover" ? (
+			<Mic size={11} />
+		) : kind === "music" ? (
+			<Music size={11} />
 		) : (
 			<ZoomIn size={11} />
 		);
@@ -1382,6 +1417,25 @@ export function V4Timeline({
 						>
 							<Maximize2 size={15} />
 						</button>
+						<span className={styles.tlToolSep} aria-hidden />
+						<button
+							type="button"
+							className={styles.tlToolBtn}
+							title={t("buttons.addVoiceover")}
+							aria-label={t("buttons.addVoiceover")}
+							onClick={() => onAddAudioLayer?.("voiceover")}
+						>
+							<Mic size={15} />
+						</button>
+						<button
+							type="button"
+							className={styles.tlToolBtn}
+							title={t("buttons.addMusic")}
+							aria-label={t("buttons.addMusic")}
+							onClick={() => onAddAudioLayer?.("music")}
+						>
+							<Music size={15} />
+						</button>
 					</div>
 				) : (
 					// Media is an ARRANGING surface: add, remove, reorder. Nothing here
@@ -1482,6 +1536,12 @@ export function V4Timeline({
 										hasAnyCamera ? t("hints.pressCameraFullscreen") : ts("layout.noWebcam"),
 									)}
 								</div>
+								<div className={styles.tlLane}>
+									{renderPills(voiceoverPills, t("hints.pressVoiceover"))}
+								</div>
+								<div className={styles.tlLane}>
+									{renderPills(musicPills, t("hints.pressMusic"))}
+								</div>
 							</>
 						) : null}
 
diff --git a/src/components/ai-edition/v4/V4Timeline.waveform.test.tsx b/src/components/ai-edition/v4/V4Timeline.waveform.test.tsx
index b5b2d9949..dc9d61f0c 100644
--- a/src/components/ai-edition/v4/V4Timeline.waveform.test.tsx
+++ b/src/components/ai-edition/v4/V4Timeline.waveform.test.tsx
@@ -111,6 +111,7 @@ function renderBars(atGainDb: number): string[] {
 		speedRegions: [],
 		cameraFullscreenRegions: [],
 		zoomRegions: [],
+		audioRegions: [],
 		trimRanges: [],
 		selection: null,
 		multiSelection: [],
diff --git a/src/i18n/locales/ar/dialogs.json b/src/i18n/locales/ar/dialogs.json
index 43caf5938..6868dfb43 100644
--- a/src/i18n/locales/ar/dialogs.json
+++ b/src/i18n/locales/ar/dialogs.json
@@ -85,6 +85,8 @@
 		"mp4Video": "فيديو MP4",
 		"videoFiles": "ملفات فيديو",
 		"openscreenProject": "مشروع OpenScreen",
-		"allFiles": "جميع الملفات"
+		"allFiles": "جميع الملفات",
+		"selectAudio": "اختر ملفًا صوتيًا",
+		"audioFiles": "ملفات صوتية"
 	}
 }
diff --git a/src/i18n/locales/ar/shortcuts.json b/src/i18n/locales/ar/shortcuts.json
index d8c063784..079c3062e 100644
--- a/src/i18n/locales/ar/shortcuts.json
+++ b/src/i18n/locales/ar/shortcuts.json
@@ -25,7 +25,9 @@
 		"deleteSelected": "حذف المحدد",
 		"playPause": "تشغيل / إيقاف مؤقت",
 		"copySelected": "نسخ المحدد",
-		"paste": "لصق"
+		"paste": "لصق",
+		"addVoiceover": "إضافة تعليق صوتي",
+		"addMusic": "إضافة موسيقى"
 	},
 	"fixedActions": {
 		"undo": "تراجع",
diff --git a/src/i18n/locales/ar/timeline.json b/src/i18n/locales/ar/timeline.json
index 4412a0a0b..9e8a2fc27 100644
--- a/src/i18n/locales/ar/timeline.json
+++ b/src/i18n/locales/ar/timeline.json
@@ -9,14 +9,18 @@
 		"addTrim": "إضافة قص (T)",
 		"addAnnotation": "إضافة شرح (A)",
 		"addSpeed": "إضافة سرعة (S)",
-		"addCameraFullscreen": "إضافة كاميرا كاملة الشاشة (C)"
+		"addCameraFullscreen": "إضافة كاميرا كاملة الشاشة (C)",
+		"addVoiceover": "إضافة تعليق صوتي (V)",
+		"addMusic": "إضافة موسيقى (B)"
 	},
 	"hints": {
 		"pressZoom": "اضغط Z لإضافة تكبير",
 		"pressTrim": "اضغط T لإضافة قص",
 		"pressAnnotation": "اضغط A لإضافة شرح",
 		"pressSpeed": "اضغط S لإضافة سرعة",
-		"pressCameraFullscreen": "اضغط C لإضافة مقطع كاميرا كاملة الشاشة"
+		"pressCameraFullscreen": "اضغط C لإضافة مقطع كاميرا كاملة الشاشة",
+		"pressVoiceover": "اضغط V لإضافة تعليق صوتي",
+		"pressMusic": "اضغط B لإضافة موسيقى"
 	},
 	"labels": {
 		"pan": "تحريك",
@@ -86,5 +90,28 @@
 		"smartCutsNoAudio": "لا يحتوي هذا الملف على صوت",
 		"smartCutsNoSpeech": "لم يتم اكتشاف كلام",
 		"smartCutsFailed": "فشل النسخ — أعد المحاولة من قسم الوسائط"
+	},
+	"audio": {
+		"addVoiceover": "إضافة تعليق صوتي",
+		"addMusic": "إضافة موسيقى خلفية",
+		"subtitle": "ضع تعليقًا صوتيًا أو موسيقى خلفية على المخطط الزمني",
+		"record": "تسجيل تعليق صوتي",
+		"importFile": "استيراد ملف صوتي",
+		"chooseMusic": "اختر ملف موسيقى",
+		"recording": "جارٍ التسجيل",
+		"stop": "إيقاف",
+		"micDenied": "تم رفض الوصول إلى الميكروفون",
+		"recordingUnavailable": "التسجيل غير متاح هنا",
+		"saveFailed": "تعذر حفظ التسجيل",
+		"importFailed": "تعذر استيراد الملف الصوتي",
+		"voiceoverLabel": "تعليق صوتي",
+		"musicLabel": "موسيقى",
+		"gain": "مستوى الصوت",
+		"mute": "كتم",
+		"offset": "إزاحة البداية",
+		"fadeIn": "تلاشي للداخل",
+		"fadeOut": "تلاشي للخارج",
+		"loop": "تكرار",
+		"deleteLayer": "حذف طبقة الصوت"
 	}
 }
diff --git a/src/i18n/locales/en/dialogs.json b/src/i18n/locales/en/dialogs.json
index 90599af16..0575c7914 100644
--- a/src/i18n/locales/en/dialogs.json
+++ b/src/i18n/locales/en/dialogs.json
@@ -42,7 +42,6 @@
 		"step1Title": "1. Add Trim",
 		"step1DescriptionBefore": "Press ",
 		"step1DescriptionAfter": " or click the scissors icon to mark a section for removal.",
-
 		"step2Title": "2. Adjust",
 		"step2Description": "Drag the edges of the red region to cover exactly what you want to cut out."
 	},
@@ -86,6 +85,8 @@
 		"mp4Video": "MP4 Video",
 		"videoFiles": "Video Files",
 		"openscreenProject": "OpenScreen Project",
-		"allFiles": "All Files"
+		"allFiles": "All Files",
+		"selectAudio": "Select Audio File",
+		"audioFiles": "Audio Files"
 	}
 }
diff --git a/src/i18n/locales/en/shortcuts.json b/src/i18n/locales/en/shortcuts.json
index 081aceada..1743125fd 100644
--- a/src/i18n/locales/en/shortcuts.json
+++ b/src/i18n/locales/en/shortcuts.json
@@ -25,7 +25,9 @@
 		"deleteSelected": "Delete Selected",
 		"playPause": "Play / Pause",
 		"copySelected": "Copy Selected",
-		"paste": "Paste"
+		"paste": "Paste",
+		"addVoiceover": "Add Voiceover",
+		"addMusic": "Add Music"
 	},
 	"fixedActions": {
 		"undo": "Undo",
diff --git a/src/i18n/locales/en/timeline.json b/src/i18n/locales/en/timeline.json
index c41966115..11a61f835 100644
--- a/src/i18n/locales/en/timeline.json
+++ b/src/i18n/locales/en/timeline.json
@@ -9,14 +9,18 @@
 		"addTrim": "Add Trim (T)",
 		"addAnnotation": "Add Annotation (A)",
 		"addSpeed": "Add Speed (S)",
-		"addCameraFullscreen": "Add Full Camera (C)"
+		"addCameraFullscreen": "Add Full Camera (C)",
+		"addVoiceover": "Add Voiceover (V)",
+		"addMusic": "Add Music (B)"
 	},
 	"hints": {
 		"pressZoom": "Press Z to add zoom",
 		"pressTrim": "Press T to add trim",
 		"pressAnnotation": "Press A to add annotation",
 		"pressSpeed": "Press S to add speed",
-		"pressCameraFullscreen": "Press C to add a Full Camera segment"
+		"pressCameraFullscreen": "Press C to add a Full Camera segment",
+		"pressVoiceover": "Press V to add voiceover",
+		"pressMusic": "Press B to add music"
 	},
 	"labels": {
 		"pan": "Pan",
@@ -86,5 +90,28 @@
 		"smartCutsNoAudio": "This media has no audio",
 		"smartCutsNoSpeech": "No speech detected",
 		"smartCutsFailed": "Transcription failed — retry it from Media"
+	},
+	"audio": {
+		"addVoiceover": "Add Voiceover",
+		"addMusic": "Add Background Music",
+		"subtitle": "Place a voiceover or background music layer on the timeline",
+		"record": "Record voiceover",
+		"importFile": "Import audio file",
+		"chooseMusic": "Choose music file",
+		"recording": "Recording",
+		"stop": "Stop",
+		"micDenied": "Microphone access was denied",
+		"recordingUnavailable": "Recording is not available here",
+		"saveFailed": "Could not save the recording",
+		"importFailed": "Could not import the audio file",
+		"voiceoverLabel": "Voiceover",
+		"musicLabel": "Music",
+		"gain": "Volume",
+		"mute": "Mute",
+		"offset": "Start offset",
+		"fadeIn": "Fade in",
+		"fadeOut": "Fade out",
+		"loop": "Loop",
+		"deleteLayer": "Delete audio layer"
 	}
 }
diff --git a/src/i18n/locales/es/dialogs.json b/src/i18n/locales/es/dialogs.json
index 954121938..b00a695b2 100644
--- a/src/i18n/locales/es/dialogs.json
+++ b/src/i18n/locales/es/dialogs.json
@@ -85,6 +85,8 @@
 		"mp4Video": "Video MP4",
 		"videoFiles": "Archivos de video",
 		"openscreenProject": "Proyecto OpenScreen",
-		"allFiles": "Todos los archivos"
+		"allFiles": "Todos los archivos",
+		"selectAudio": "Seleccionar archivo de audio",
+		"audioFiles": "Archivos de audio"
 	}
 }
diff --git a/src/i18n/locales/es/shortcuts.json b/src/i18n/locales/es/shortcuts.json
index 970c52306..10a7893fb 100644
--- a/src/i18n/locales/es/shortcuts.json
+++ b/src/i18n/locales/es/shortcuts.json
@@ -25,7 +25,9 @@
 		"deleteSelected": "Eliminar seleccionado",
 		"playPause": "Reproducir / Pausar",
 		"copySelected": "Copiar selección",
-		"paste": "Pegar"
+		"paste": "Pegar",
+		"addVoiceover": "Añadir voz en off",
+		"addMusic": "Añadir música"
 	},
 	"fixedActions": {
 		"undo": "Deshacer",
diff --git a/src/i18n/locales/es/timeline.json b/src/i18n/locales/es/timeline.json
index 989289e00..84d26e2e0 100644
--- a/src/i18n/locales/es/timeline.json
+++ b/src/i18n/locales/es/timeline.json
@@ -9,14 +9,18 @@
 		"addTrim": "Agregar recorte (T)",
 		"addAnnotation": "Agregar anotación (A)",
 		"addSpeed": "Agregar velocidad (S)",
-		"addCameraFullscreen": "Agregar cámara a pantalla completa (C)"
+		"addCameraFullscreen": "Agregar cámara a pantalla completa (C)",
+		"addVoiceover": "Añadir voz en off (V)",
+		"addMusic": "Añadir música (B)"
 	},
 	"hints": {
 		"pressZoom": "Presiona Z para agregar zoom",
 		"pressTrim": "Presiona T para agregar recorte",
 		"pressAnnotation": "Presiona A para agregar anotación",
 		"pressSpeed": "Presiona S para agregar velocidad",
-		"pressCameraFullscreen": "Presiona C para agregar un segmento de cámara a pantalla completa"
+		"pressCameraFullscreen": "Presiona C para agregar un segmento de cámara a pantalla completa",
+		"pressVoiceover": "Pulsa V para añadir voz en off",
+		"pressMusic": "Pulsa B para añadir música"
 	},
 	"labels": {
 		"pan": "Desplazar",
@@ -86,5 +90,28 @@
 		"smartCutsNoAudio": "Este medio no tiene audio",
 		"smartCutsNoSpeech": "No se detectó voz",
 		"smartCutsFailed": "La transcripción falló: reinténtala desde Medios"
+	},
+	"audio": {
+		"addVoiceover": "Añadir voz en off",
+		"addMusic": "Añadir música de fondo",
+		"subtitle": "Coloca una capa de voz en off o de música de fondo en la línea de tiempo",
+		"record": "Grabar voz en off",
+		"importFile": "Importar archivo de audio",
+		"chooseMusic": "Elegir archivo de música",
+		"recording": "Grabando",
+		"stop": "Detener",
+		"micDenied": "Se denegó el acceso al micrófono",
+		"recordingUnavailable": "La grabación no está disponible aquí",
+		"saveFailed": "No se pudo guardar la grabación",
+		"importFailed": "No se pudo importar el archivo de audio",
+		"voiceoverLabel": "Voz en off",
+		"musicLabel": "Música",
+		"gain": "Volumen",
+		"mute": "Silenciar",
+		"offset": "Desplazamiento inicial",
+		"fadeIn": "Fundido de entrada",
+		"fadeOut": "Fundido de salida",
+		"loop": "Bucle",
+		"deleteLayer": "Eliminar capa de audio"
 	}
 }
diff --git a/src/i18n/locales/fr/dialogs.json b/src/i18n/locales/fr/dialogs.json
index 82fc95dcb..242c657d5 100644
--- a/src/i18n/locales/fr/dialogs.json
+++ b/src/i18n/locales/fr/dialogs.json
@@ -85,6 +85,8 @@
 		"mp4Video": "Vidéo MP4",
 		"videoFiles": "Fichiers vidéo",
 		"openscreenProject": "Projet OpenScreen",
-		"allFiles": "Tous les fichiers"
+		"allFiles": "Tous les fichiers",
+		"selectAudio": "Sélectionner un fichier audio",
+		"audioFiles": "Fichiers audio"
 	}
 }
diff --git a/src/i18n/locales/fr/shortcuts.json b/src/i18n/locales/fr/shortcuts.json
index 659ef13b8..b86da73cd 100644
--- a/src/i18n/locales/fr/shortcuts.json
+++ b/src/i18n/locales/fr/shortcuts.json
@@ -25,7 +25,9 @@
 		"deleteSelected": "Supprimer la sélection",
 		"playPause": "Lecture / Pause",
 		"copySelected": "Copier la sélection",
-		"paste": "Coller"
+		"paste": "Coller",
+		"addVoiceover": "Ajouter une voix off",
+		"addMusic": "Ajouter de la musique"
 	},
 	"fixedActions": {
 		"undo": "Annuler",
diff --git a/src/i18n/locales/fr/timeline.json b/src/i18n/locales/fr/timeline.json
index a35b8858a..0dde8e990 100644
--- a/src/i18n/locales/fr/timeline.json
+++ b/src/i18n/locales/fr/timeline.json
@@ -9,14 +9,18 @@
 		"addTrim": "Ajouter une coupe (T)",
 		"addAnnotation": "Ajouter une annotation (A)",
 		"addSpeed": "Ajouter une vitesse (S)",
-		"addCameraFullscreen": "Ajouter Caméra plein écran (C)"
+		"addCameraFullscreen": "Ajouter Caméra plein écran (C)",
+		"addVoiceover": "Ajouter une voix off (V)",
+		"addMusic": "Ajouter de la musique (B)"
 	},
 	"hints": {
 		"pressZoom": "Appuyez sur Z pour ajouter un zoom",
 		"pressTrim": "Appuyez sur T pour ajouter une coupe",
 		"pressAnnotation": "Appuyez sur A pour ajouter une annotation",
 		"pressSpeed": "Appuyez sur S pour ajouter une vitesse",
-		"pressCameraFullscreen": "Appuyez sur C pour ajouter un segment Caméra plein écran"
+		"pressCameraFullscreen": "Appuyez sur C pour ajouter un segment Caméra plein écran",
+		"pressVoiceover": "Appuyez sur V pour ajouter une voix off",
+		"pressMusic": "Appuyez sur B pour ajouter de la musique"
 	},
 	"labels": {
 		"pan": "Panoramique",
@@ -86,5 +90,28 @@
 		"smartCutsNoAudio": "Ce média n'a pas d'audio",
 		"smartCutsNoSpeech": "Aucune parole détectée",
 		"smartCutsFailed": "Échec de la transcription — relancez-la depuis Médias"
+	},
+	"audio": {
+		"addVoiceover": "Ajouter une voix off",
+		"addMusic": "Ajouter une musique de fond",
+		"subtitle": "Placez une couche de voix off ou de musique de fond sur la timeline",
+		"record": "Enregistrer une voix off",
+		"importFile": "Importer un fichier audio",
+		"chooseMusic": "Choisir un fichier musical",
+		"recording": "Enregistrement",
+		"stop": "Arrêter",
+		"micDenied": "L'accès au micro a été refusé",
+		"recordingUnavailable": "L'enregistrement n'est pas disponible ici",
+		"saveFailed": "Impossible d'enregistrer la capture",
+		"importFailed": "Impossible d'importer le fichier audio",
+		"voiceoverLabel": "Voix off",
+		"musicLabel": "Musique",
+		"gain": "Volume",
+		"mute": "Couper le son",
+		"offset": "Décalage de début",
+		"fadeIn": "Fondu d'entrée",
+		"fadeOut": "Fondu de sortie",
+		"loop": "Boucle",
+		"deleteLayer": "Supprimer la couche audio"
 	}
 }
diff --git a/src/i18n/locales/it/dialogs.json b/src/i18n/locales/it/dialogs.json
index 0fad7d36e..80a567e5c 100644
--- a/src/i18n/locales/it/dialogs.json
+++ b/src/i18n/locales/it/dialogs.json
@@ -85,6 +85,8 @@
 		"mp4Video": "Video MP4",
 		"videoFiles": "File video",
 		"openscreenProject": "Progetto OpenScreen",
-		"allFiles": "Tutti i file"
+		"allFiles": "Tutti i file",
+		"selectAudio": "Seleziona file audio",
+		"audioFiles": "File audio"
 	}
 }
diff --git a/src/i18n/locales/it/shortcuts.json b/src/i18n/locales/it/shortcuts.json
index 6a2da2208..d654eeed3 100644
--- a/src/i18n/locales/it/shortcuts.json
+++ b/src/i18n/locales/it/shortcuts.json
@@ -25,7 +25,9 @@
 		"deleteSelected": "Elimina selezionato",
 		"playPause": "Riproduci / Pausa",
 		"copySelected": "Copia selezione",
-		"paste": "Incolla"
+		"paste": "Incolla",
+		"addVoiceover": "Aggiungi voce fuori campo",
+		"addMusic": "Aggiungi musica"
 	},
 	"fixedActions": {
 		"undo": "Annulla",
diff --git a/src/i18n/locales/it/timeline.json b/src/i18n/locales/it/timeline.json
index 09bb116ee..f47d64102 100644
--- a/src/i18n/locales/it/timeline.json
+++ b/src/i18n/locales/it/timeline.json
@@ -9,14 +9,18 @@
 		"addTrim": "Aggiungi taglio (T)",
 		"addAnnotation": "Aggiungi annotazione (A)",
 		"addSpeed": "Aggiungi velocità (S)",
-		"addCameraFullscreen": "Aggiungi Camera a schermo intero (C)"
+		"addCameraFullscreen": "Aggiungi Camera a schermo intero (C)",
+		"addVoiceover": "Aggiungi voce fuori campo (V)",
+		"addMusic": "Aggiungi musica (B)"
 	},
 	"hints": {
 		"pressZoom": "Premi Z per aggiungere zoom",
 		"pressTrim": "Premi T per aggiungere taglio",
 		"pressAnnotation": "Premi A per aggiungere annotazione",
 		"pressSpeed": "Premi S per aggiungere velocità",
-		"pressCameraFullscreen": "Premi C per aggiungere un segmento Camera a schermo intero"
+		"pressCameraFullscreen": "Premi C per aggiungere un segmento Camera a schermo intero",
+		"pressVoiceover": "Premi V per aggiungere una voce fuori campo",
+		"pressMusic": "Premi B per aggiungere musica"
 	},
 	"labels": {
 		"pan": "Panoramica",
@@ -86,5 +90,28 @@
 		"smartCutsNoAudio": "Questo contenuto non ha audio",
 		"smartCutsNoSpeech": "Nessun parlato rilevato",
 		"smartCutsFailed": "Trascrizione non riuscita: riprova da Contenuti multimediali"
+	},
+	"audio": {
+		"addVoiceover": "Aggiungi voce fuori campo",
+		"addMusic": "Aggiungi musica di sottofondo",
+		"subtitle": "Posiziona un livello di voce fuori campo o di musica di sottofondo sulla timeline",
+		"record": "Registra voce fuori campo",
+		"importFile": "Importa file audio",
+		"chooseMusic": "Scegli file musicale",
+		"recording": "Registrazione",
+		"stop": "Ferma",
+		"micDenied": "Accesso al microfono negato",
+		"recordingUnavailable": "La registrazione non è disponibile qui",
+		"saveFailed": "Impossibile salvare la registrazione",
+		"importFailed": "Impossibile importare il file audio",
+		"voiceoverLabel": "Voce fuori campo",
+		"musicLabel": "Musica",
+		"gain": "Volume",
+		"mute": "Muto",
+		"offset": "Offset iniziale",
+		"fadeIn": "Dissolvenza in entrata",
+		"fadeOut": "Dissolvenza in uscita",
+		"loop": "Ripeti",
+		"deleteLayer": "Elimina livello audio"
 	}
 }
diff --git a/src/i18n/locales/ja-JP/dialogs.json b/src/i18n/locales/ja-JP/dialogs.json
index 7ee976a77..cdffab1fd 100644
--- a/src/i18n/locales/ja-JP/dialogs.json
+++ b/src/i18n/locales/ja-JP/dialogs.json
@@ -85,6 +85,8 @@
 		"mp4Video": "MP4 動画",
 		"videoFiles": "動画ファイル",
 		"openscreenProject": "OpenScreen プロジェクト",
-		"allFiles": "すべてのファイル"
+		"allFiles": "すべてのファイル",
+		"selectAudio": "音声ファイルを選択",
+		"audioFiles": "音声ファイル"
 	}
 }
diff --git a/src/i18n/locales/ja-JP/shortcuts.json b/src/i18n/locales/ja-JP/shortcuts.json
index 173355c66..e70f25341 100644
--- a/src/i18n/locales/ja-JP/shortcuts.json
+++ b/src/i18n/locales/ja-JP/shortcuts.json
@@ -25,7 +25,9 @@
 		"deleteSelected": "選択を削除",
 		"playPause": "再生 / 一時停止",
 		"copySelected": "選択をコピー",
-		"paste": "貼り付け"
+		"paste": "貼り付け",
+		"addVoiceover": "ナレーションを追加",
+		"addMusic": "音楽を追加"
 	},
 	"fixedActions": {
 		"undo": "元に戻す",
diff --git a/src/i18n/locales/ja-JP/timeline.json b/src/i18n/locales/ja-JP/timeline.json
index 68911ba91..3a18c221f 100644
--- a/src/i18n/locales/ja-JP/timeline.json
+++ b/src/i18n/locales/ja-JP/timeline.json
@@ -9,14 +9,18 @@
 		"addTrim": "トリムを追加 (T)",
 		"addAnnotation": "注釈を追加 (A)",
 		"addSpeed": "再生速度を追加 (S)",
-		"addCameraFullscreen": "フルスクリーンカメラを追加 (C)"
+		"addCameraFullscreen": "フルスクリーンカメラを追加 (C)",
+		"addVoiceover": "ナレーションを追加（V）",
+		"addMusic": "音楽を追加（B）"
 	},
 	"hints": {
 		"pressZoom": "Zキーを押してズームを追加",
 		"pressTrim": "Tキーを押してトリムを追加",
 		"pressAnnotation": "Aキーを押して注釈を追加",
 		"pressSpeed": "Sキーを押して再生速度を追加",
-		"pressCameraFullscreen": "Cキーを押してフルスクリーンカメラのセグメントを追加"
+		"pressCameraFullscreen": "Cキーを押してフルスクリーンカメラのセグメントを追加",
+		"pressVoiceover": "V キーでナレーションを追加",
+		"pressMusic": "B キーで音楽を追加"
 	},
 	"labels": {
 		"pan": "移動",
@@ -86,5 +90,28 @@
 		"smartCutsNoAudio": "このメディアには音声がありません",
 		"smartCutsNoSpeech": "音声が検出されませんでした",
 		"smartCutsFailed": "文字起こしに失敗しました — メディアから再試行してください"
+	},
+	"audio": {
+		"addVoiceover": "ナレーションを追加",
+		"addMusic": "BGM を追加",
+		"subtitle": "タイムラインにナレーションまたは BGM のレイヤーを配置します",
+		"record": "ナレーションを録音",
+		"importFile": "音声ファイルを読み込む",
+		"chooseMusic": "音楽ファイルを選択",
+		"recording": "録音中",
+		"stop": "停止",
+		"micDenied": "マイクへのアクセスが拒否されました",
+		"recordingUnavailable": "ここでは録音できません",
+		"saveFailed": "録音を保存できませんでした",
+		"importFailed": "音声ファイルを読み込めませんでした",
+		"voiceoverLabel": "ナレーション",
+		"musicLabel": "音楽",
+		"gain": "音量",
+		"mute": "ミュート",
+		"offset": "開始オフセット",
+		"fadeIn": "フェードイン",
+		"fadeOut": "フェードアウト",
+		"loop": "ループ",
+		"deleteLayer": "音声レイヤーを削除"
 	}
 }
diff --git a/src/i18n/locales/ko-KR/dialogs.json b/src/i18n/locales/ko-KR/dialogs.json
index 5891f44c1..afa6aa7aa 100644
--- a/src/i18n/locales/ko-KR/dialogs.json
+++ b/src/i18n/locales/ko-KR/dialogs.json
@@ -85,6 +85,8 @@
 		"mp4Video": "MP4 비디오",
 		"videoFiles": "비디오 파일",
 		"openscreenProject": "OpenScreen 프로젝트",
-		"allFiles": "모든 파일"
+		"allFiles": "모든 파일",
+		"selectAudio": "오디오 파일 선택",
+		"audioFiles": "오디오 파일"
 	}
 }
diff --git a/src/i18n/locales/ko-KR/shortcuts.json b/src/i18n/locales/ko-KR/shortcuts.json
index 00e8f689d..7ae29b316 100644
--- a/src/i18n/locales/ko-KR/shortcuts.json
+++ b/src/i18n/locales/ko-KR/shortcuts.json
@@ -25,7 +25,9 @@
 		"deleteSelected": "선택 항목 삭제",
 		"playPause": "재생 / 일시정지",
 		"copySelected": "선택 항목 복사",
-		"paste": "붙여넣기"
+		"paste": "붙여넣기",
+		"addVoiceover": "내레이션 추가",
+		"addMusic": "음악 추가"
 	},
 	"fixedActions": {
 		"undo": "실행 취소",
diff --git a/src/i18n/locales/ko-KR/timeline.json b/src/i18n/locales/ko-KR/timeline.json
index 8a100ee6d..750fbf9f5 100644
--- a/src/i18n/locales/ko-KR/timeline.json
+++ b/src/i18n/locales/ko-KR/timeline.json
@@ -9,14 +9,18 @@
 		"addTrim": "트림 추가 (T)",
 		"addAnnotation": "주석 추가 (A)",
 		"addSpeed": "속도 추가 (S)",
-		"addCameraFullscreen": "전체 화면 카메라 추가 (C)"
+		"addCameraFullscreen": "전체 화면 카메라 추가 (C)",
+		"addVoiceover": "내레이션 추가 (V)",
+		"addMusic": "음악 추가 (B)"
 	},
 	"hints": {
 		"pressZoom": "Z를 눌러 줌 추가",
 		"pressTrim": "T를 눌러 트림 추가",
 		"pressAnnotation": "A를 눌러 주석 추가",
 		"pressSpeed": "S를 눌러 속도 추가",
-		"pressCameraFullscreen": "C를 눌러 전체 화면 카메라 구간을 추가하세요"
+		"pressCameraFullscreen": "C를 눌러 전체 화면 카메라 구간을 추가하세요",
+		"pressVoiceover": "V 키로 내레이션 추가",
+		"pressMusic": "B 키로 음악 추가"
 	},
 	"labels": {
 		"pan": "이동",
@@ -86,5 +90,28 @@
 		"smartCutsNoAudio": "이 미디어에는 오디오가 없습니다",
 		"smartCutsNoSpeech": "음성이 감지되지 않음",
 		"smartCutsFailed": "받아쓰기에 실패했습니다 — 미디어에서 다시 시도하세요"
+	},
+	"audio": {
+		"addVoiceover": "내레이션 추가",
+		"addMusic": "배경 음악 추가",
+		"subtitle": "타임라인에 내레이션 또는 배경 음악 레이어를 배치합니다",
+		"record": "내레이션 녹음",
+		"importFile": "오디오 파일 가져오기",
+		"chooseMusic": "음악 파일 선택",
+		"recording": "녹음 중",
+		"stop": "중지",
+		"micDenied": "마이크 접근이 거부되었습니다",
+		"recordingUnavailable": "여기에서는 녹음할 수 없습니다",
+		"saveFailed": "녹음을 저장하지 못했습니다",
+		"importFailed": "오디오 파일을 가져오지 못했습니다",
+		"voiceoverLabel": "내레이션",
+		"musicLabel": "음악",
+		"gain": "볼륨",
+		"mute": "음소거",
+		"offset": "시작 오프셋",
+		"fadeIn": "페이드 인",
+		"fadeOut": "페이드 아웃",
+		"loop": "반복",
+		"deleteLayer": "오디오 레이어 삭제"
 	}
 }
diff --git a/src/i18n/locales/pt-BR/dialogs.json b/src/i18n/locales/pt-BR/dialogs.json
index ba77d90a9..e6470caa8 100644
--- a/src/i18n/locales/pt-BR/dialogs.json
+++ b/src/i18n/locales/pt-BR/dialogs.json
@@ -85,6 +85,8 @@
 		"mp4Video": "Vídeo MP4",
 		"videoFiles": "Arquivos de Vídeo",
 		"openscreenProject": "Projeto OpenScreen",
-		"allFiles": "Todos os Arquivos"
+		"allFiles": "Todos os Arquivos",
+		"selectAudio": "Selecionar arquivo de áudio",
+		"audioFiles": "Arquivos de áudio"
 	}
 }
diff --git a/src/i18n/locales/pt-BR/shortcuts.json b/src/i18n/locales/pt-BR/shortcuts.json
index a21fe7bed..a47fd3a86 100644
--- a/src/i18n/locales/pt-BR/shortcuts.json
+++ b/src/i18n/locales/pt-BR/shortcuts.json
@@ -25,7 +25,9 @@
 		"deleteSelected": "Excluir Selecionado",
 		"playPause": "Reproduzir / Pausar",
 		"copySelected": "Copiar seleção",
-		"paste": "Colar"
+		"paste": "Colar",
+		"addVoiceover": "Adicionar narração",
+		"addMusic": "Adicionar música"
 	},
 	"fixedActions": {
 		"undo": "Desfazer",
diff --git a/src/i18n/locales/pt-BR/timeline.json b/src/i18n/locales/pt-BR/timeline.json
index 5359feba9..8f40ad889 100644
--- a/src/i18n/locales/pt-BR/timeline.json
+++ b/src/i18n/locales/pt-BR/timeline.json
@@ -9,14 +9,18 @@
 		"addTrim": "Adicionar Recorte (T)",
 		"addAnnotation": "Adicionar Anotação (A)",
 		"addSpeed": "Adicionar Velocidade (S)",
-		"addCameraFullscreen": "Adicionar Câmera em Tela Cheia (C)"
+		"addCameraFullscreen": "Adicionar Câmera em Tela Cheia (C)",
+		"addVoiceover": "Adicionar narração (V)",
+		"addMusic": "Adicionar música (B)"
 	},
 	"hints": {
 		"pressZoom": "Pressione Z para adicionar zoom",
 		"pressTrim": "Pressione T para adicionar recorte",
 		"pressAnnotation": "Pressione A para adicionar anotação",
 		"pressSpeed": "Pressione S para adicionar velocidade",
-		"pressCameraFullscreen": "Pressione C para adicionar um segmento de Câmera em Tela Cheia"
+		"pressCameraFullscreen": "Pressione C para adicionar um segmento de Câmera em Tela Cheia",
+		"pressVoiceover": "Pressione V para adicionar narração",
+		"pressMusic": "Pressione B para adicionar música"
 	},
 	"labels": {
 		"pan": "Mover",
@@ -86,5 +90,28 @@
 		"smartCutsNoAudio": "Esta mídia não tem áudio",
 		"smartCutsNoSpeech": "Nenhuma fala detectada",
 		"smartCutsFailed": "Falha na transcrição — tente de novo em Mídia"
+	},
+	"audio": {
+		"addVoiceover": "Adicionar narração",
+		"addMusic": "Adicionar música de fundo",
+		"subtitle": "Coloque uma camada de narração ou de música de fundo na linha do tempo",
+		"record": "Gravar narração",
+		"importFile": "Importar arquivo de áudio",
+		"chooseMusic": "Escolher arquivo de música",
+		"recording": "Gravando",
+		"stop": "Parar",
+		"micDenied": "Acesso ao microfone negado",
+		"recordingUnavailable": "A gravação não está disponível aqui",
+		"saveFailed": "Não foi possível salvar a gravação",
+		"importFailed": "Não foi possível importar o arquivo de áudio",
+		"voiceoverLabel": "Narração",
+		"musicLabel": "Música",
+		"gain": "Volume",
+		"mute": "Silenciar",
+		"offset": "Deslocamento inicial",
+		"fadeIn": "Fade in",
+		"fadeOut": "Fade out",
+		"loop": "Repetir",
+		"deleteLayer": "Excluir camada de áudio"
 	}
 }
diff --git a/src/i18n/locales/ru/dialogs.json b/src/i18n/locales/ru/dialogs.json
index a821771e9..b64b8ba58 100644
--- a/src/i18n/locales/ru/dialogs.json
+++ b/src/i18n/locales/ru/dialogs.json
@@ -85,6 +85,8 @@
 		"mp4Video": "MP4 видео",
 		"videoFiles": "Видеофайлы",
 		"openscreenProject": "Проект OpenScreen",
-		"allFiles": "Все файлы"
+		"allFiles": "Все файлы",
+		"selectAudio": "Выбрать аудиофайл",
+		"audioFiles": "Аудиофайлы"
 	}
 }
diff --git a/src/i18n/locales/ru/shortcuts.json b/src/i18n/locales/ru/shortcuts.json
index dabb06801..83476f18f 100644
--- a/src/i18n/locales/ru/shortcuts.json
+++ b/src/i18n/locales/ru/shortcuts.json
@@ -25,7 +25,9 @@
 		"deleteSelected": "Удалить выбранное",
 		"playPause": "Воспроизведение / Пауза",
 		"copySelected": "Копировать выбранное",
-		"paste": "Вставить"
+		"paste": "Вставить",
+		"addVoiceover": "Добавить озвучку",
+		"addMusic": "Добавить музыку"
 	},
 	"fixedActions": {
 		"undo": "Отменить",
diff --git a/src/i18n/locales/ru/timeline.json b/src/i18n/locales/ru/timeline.json
index 387086953..4d354b523 100644
--- a/src/i18n/locales/ru/timeline.json
+++ b/src/i18n/locales/ru/timeline.json
@@ -9,14 +9,18 @@
 		"addTrim": "Добавить обрезку (T)",
 		"addAnnotation": "Добавить аннотацию (A)",
 		"addSpeed": "Изменить скорость (S)",
-		"addCameraFullscreen": "Добавить камеру на весь экран (C)"
+		"addCameraFullscreen": "Добавить камеру на весь экран (C)",
+		"addVoiceover": "Добавить озвучку (V)",
+		"addMusic": "Добавить музыку (B)"
 	},
 	"hints": {
 		"pressZoom": "Нажмите Z для добавления масштабирования",
 		"pressTrim": "Нажмите T для добавления обрезки",
 		"pressAnnotation": "Нажмите A для добавления аннотации",
 		"pressSpeed": "Нажмите S для изменения скорости",
-		"pressCameraFullscreen": "Нажмите C, чтобы добавить сегмент камеры на весь экран"
+		"pressCameraFullscreen": "Нажмите C, чтобы добавить сегмент камеры на весь экран",
+		"pressVoiceover": "Нажмите V, чтобы добавить озвучку",
+		"pressMusic": "Нажмите B, чтобы добавить музыку"
 	},
 	"labels": {
 		"pan": "Панорамирование",
@@ -86,5 +90,28 @@
 		"smartCutsNoAudio": "В этом медиафайле нет звука",
 		"smartCutsNoSpeech": "Речь не обнаружена",
 		"smartCutsFailed": "Не удалось расшифровать — повторите из раздела «Медиа»"
+	},
+	"audio": {
+		"addVoiceover": "Добавить озвучку",
+		"addMusic": "Добавить фоновую музыку",
+		"subtitle": "Разместите слой озвучки или фоновой музыки на таймлайне",
+		"record": "Записать озвучку",
+		"importFile": "Импортировать аудиофайл",
+		"chooseMusic": "Выбрать музыкальный файл",
+		"recording": "Запись",
+		"stop": "Остановить",
+		"micDenied": "Доступ к микрофону запрещён",
+		"recordingUnavailable": "Запись здесь недоступна",
+		"saveFailed": "Не удалось сохранить запись",
+		"importFailed": "Не удалось импортировать аудиофайл",
+		"voiceoverLabel": "Озвучка",
+		"musicLabel": "Музыка",
+		"gain": "Громкость",
+		"mute": "Без звука",
+		"offset": "Начальное смещение",
+		"fadeIn": "Появление",
+		"fadeOut": "Затухание",
+		"loop": "Повтор",
+		"deleteLayer": "Удалить аудиослой"
 	}
 }
diff --git a/src/i18n/locales/tr/dialogs.json b/src/i18n/locales/tr/dialogs.json
index 196807fd3..4e4ca21dc 100644
--- a/src/i18n/locales/tr/dialogs.json
+++ b/src/i18n/locales/tr/dialogs.json
@@ -85,6 +85,8 @@
 		"mp4Video": "MP4 Video",
 		"videoFiles": "Video Dosyaları",
 		"openscreenProject": "OpenScreen Projesi",
-		"allFiles": "Tüm Dosyalar"
+		"allFiles": "Tüm Dosyalar",
+		"selectAudio": "Ses dosyası seç",
+		"audioFiles": "Ses dosyaları"
 	}
 }
diff --git a/src/i18n/locales/tr/shortcuts.json b/src/i18n/locales/tr/shortcuts.json
index 6b1db110d..588ffba86 100644
--- a/src/i18n/locales/tr/shortcuts.json
+++ b/src/i18n/locales/tr/shortcuts.json
@@ -25,7 +25,9 @@
 		"deleteSelected": "Seçileni Sil",
 		"playPause": "Oynat / Duraklat",
 		"copySelected": "Seçileni Kopyala",
-		"paste": "Yapıştır"
+		"paste": "Yapıştır",
+		"addVoiceover": "Seslendirme ekle",
+		"addMusic": "Müzik ekle"
 	},
 	"fixedActions": {
 		"undo": "Geri Al",
diff --git a/src/i18n/locales/tr/timeline.json b/src/i18n/locales/tr/timeline.json
index d5a531f3e..cc6742571 100644
--- a/src/i18n/locales/tr/timeline.json
+++ b/src/i18n/locales/tr/timeline.json
@@ -9,14 +9,18 @@
 		"addTrim": "Kırpma Ekle (T)",
 		"addAnnotation": "Açıklama Ekle (A)",
 		"addSpeed": "Hız Ekle (S)",
-		"addCameraFullscreen": "Tam Ekran Kamera Ekle (C)"
+		"addCameraFullscreen": "Tam Ekran Kamera Ekle (C)",
+		"addVoiceover": "Seslendirme ekle (V)",
+		"addMusic": "Müzik ekle (B)"
 	},
 	"hints": {
 		"pressZoom": "Yakınlaştırma eklemek için Z tuşuna basın",
 		"pressTrim": "Kırpma eklemek için T tuşuna basın",
 		"pressAnnotation": "Açıklama eklemek için A tuşuna basın",
 		"pressSpeed": "Hız eklemek için S tuşuna basın",
-		"pressCameraFullscreen": "Tam Ekran Kamera bölümü eklemek için C tuşuna basın"
+		"pressCameraFullscreen": "Tam Ekran Kamera bölümü eklemek için C tuşuna basın",
+		"pressVoiceover": "Seslendirme eklemek için V tuşuna basın",
+		"pressMusic": "Müzik eklemek için B tuşuna basın"
 	},
 	"labels": {
 		"pan": "Kaydır",
@@ -86,5 +90,28 @@
 		"smartCutsNoAudio": "Bu medyada ses yok",
 		"smartCutsNoSpeech": "Konuşma algılanmadı",
 		"smartCutsFailed": "Metne dökme başarısız — Medya bölümünden yeniden deneyin"
+	},
+	"audio": {
+		"addVoiceover": "Seslendirme ekle",
+		"addMusic": "Fon müziği ekle",
+		"subtitle": "Zaman çizelgesine seslendirme veya fon müziği katmanı yerleştirin",
+		"record": "Seslendirme kaydet",
+		"importFile": "Ses dosyası içe aktar",
+		"chooseMusic": "Müzik dosyası seç",
+		"recording": "Kaydediliyor",
+		"stop": "Durdur",
+		"micDenied": "Mikrofon erişimi reddedildi",
+		"recordingUnavailable": "Burada kayıt kullanılamıyor",
+		"saveFailed": "Kayıt kaydedilemedi",
+		"importFailed": "Ses dosyası içe aktarılamadı",
+		"voiceoverLabel": "Seslendirme",
+		"musicLabel": "Müzik",
+		"gain": "Ses düzeyi",
+		"mute": "Sessize al",
+		"offset": "Başlangıç kaydırması",
+		"fadeIn": "Giriş solması",
+		"fadeOut": "Çıkış solması",
+		"loop": "Döngü",
+		"deleteLayer": "Ses katmanını sil"
 	}
 }
diff --git a/src/i18n/locales/vi/dialogs.json b/src/i18n/locales/vi/dialogs.json
index 644d2ba02..d48034d94 100644
--- a/src/i18n/locales/vi/dialogs.json
+++ b/src/i18n/locales/vi/dialogs.json
@@ -85,6 +85,8 @@
 		"mp4Video": "Video MP4",
 		"videoFiles": "Tệp Video",
 		"openscreenProject": "Dự án OpenScreen",
-		"allFiles": "Tất cả các tệp"
+		"allFiles": "Tất cả các tệp",
+		"selectAudio": "Chọn tệp âm thanh",
+		"audioFiles": "Tệp âm thanh"
 	}
 }
diff --git a/src/i18n/locales/vi/shortcuts.json b/src/i18n/locales/vi/shortcuts.json
index cf49f2526..106773a3e 100644
--- a/src/i18n/locales/vi/shortcuts.json
+++ b/src/i18n/locales/vi/shortcuts.json
@@ -25,7 +25,9 @@
 		"deleteSelected": "Xóa mục đã chọn",
 		"playPause": "Phát / Tạm dừng",
 		"copySelected": "Sao chép mục đã chọn",
-		"paste": "Dán"
+		"paste": "Dán",
+		"addVoiceover": "Thêm thuyết minh",
+		"addMusic": "Thêm nhạc"
 	},
 	"fixedActions": {
 		"undo": "Hoàn tác",
diff --git a/src/i18n/locales/vi/timeline.json b/src/i18n/locales/vi/timeline.json
index 1d963e585..b062d1e04 100644
--- a/src/i18n/locales/vi/timeline.json
+++ b/src/i18n/locales/vi/timeline.json
@@ -9,14 +9,18 @@
 		"addTrim": "Thêm Cắt (T)",
 		"addAnnotation": "Thêm Chú thích (A)",
 		"addSpeed": "Thêm Tốc độ (S)",
-		"addCameraFullscreen": "Thêm Camera Toàn màn hình (C)"
+		"addCameraFullscreen": "Thêm Camera Toàn màn hình (C)",
+		"addVoiceover": "Thêm thuyết minh (V)",
+		"addMusic": "Thêm nhạc (B)"
 	},
 	"hints": {
 		"pressZoom": "Nhấn Z để thêm thu phóng",
 		"pressTrim": "Nhấn T để thêm cắt",
 		"pressAnnotation": "Nhấn A để thêm chú thích",
 		"pressSpeed": "Nhấn S để thêm tốc độ",
-		"pressCameraFullscreen": "Nhấn C để thêm một đoạn Camera Toàn màn hình"
+		"pressCameraFullscreen": "Nhấn C để thêm một đoạn Camera Toàn màn hình",
+		"pressVoiceover": "Nhấn V để thêm thuyết minh",
+		"pressMusic": "Nhấn B để thêm nhạc"
 	},
 	"labels": {
 		"pan": "Xoay",
@@ -86,5 +90,28 @@
 		"smartCutsNoAudio": "Media này không có âm thanh",
 		"smartCutsNoSpeech": "Không phát hiện giọng nói",
 		"smartCutsFailed": "Phiên âm thất bại — thử lại trong Media"
+	},
+	"audio": {
+		"addVoiceover": "Thêm thuyết minh",
+		"addMusic": "Thêm nhạc nền",
+		"subtitle": "Đặt lớp thuyết minh hoặc nhạc nền lên dòng thời gian",
+		"record": "Ghi âm thuyết minh",
+		"importFile": "Nhập tệp âm thanh",
+		"chooseMusic": "Chọn tệp nhạc",
+		"recording": "Đang ghi",
+		"stop": "Dừng",
+		"micDenied": "Quyền truy cập micrô bị từ chối",
+		"recordingUnavailable": "Không thể ghi âm ở đây",
+		"saveFailed": "Không thể lưu bản ghi",
+		"importFailed": "Không thể nhập tệp âm thanh",
+		"voiceoverLabel": "Thuyết minh",
+		"musicLabel": "Nhạc",
+		"gain": "Âm lượng",
+		"mute": "Tắt tiếng",
+		"offset": "Độ lệch bắt đầu",
+		"fadeIn": "Mờ vào",
+		"fadeOut": "Mờ ra",
+		"loop": "Lặp lại",
+		"deleteLayer": "Xóa lớp âm thanh"
 	}
 }
diff --git a/src/i18n/locales/zh-CN/dialogs.json b/src/i18n/locales/zh-CN/dialogs.json
index 645ebf9d8..67d7fcf64 100644
--- a/src/i18n/locales/zh-CN/dialogs.json
+++ b/src/i18n/locales/zh-CN/dialogs.json
@@ -85,6 +85,8 @@
 		"mp4Video": "MP4 视频",
 		"videoFiles": "视频文件",
 		"openscreenProject": "OpenScreen 项目",
-		"allFiles": "所有文件"
+		"allFiles": "所有文件",
+		"selectAudio": "选择音频文件",
+		"audioFiles": "音频文件"
 	}
 }
diff --git a/src/i18n/locales/zh-CN/shortcuts.json b/src/i18n/locales/zh-CN/shortcuts.json
index 95ec1c07e..470b177f2 100644
--- a/src/i18n/locales/zh-CN/shortcuts.json
+++ b/src/i18n/locales/zh-CN/shortcuts.json
@@ -25,7 +25,9 @@
 		"deleteSelected": "删除所选",
 		"playPause": "播放 / 暂停",
 		"copySelected": "复制所选",
-		"paste": "粘贴"
+		"paste": "粘贴",
+		"addVoiceover": "添加配音",
+		"addMusic": "添加音乐"
 	},
 	"fixedActions": {
 		"undo": "撤销",
diff --git a/src/i18n/locales/zh-CN/timeline.json b/src/i18n/locales/zh-CN/timeline.json
index 1451e6d31..818a95ced 100644
--- a/src/i18n/locales/zh-CN/timeline.json
+++ b/src/i18n/locales/zh-CN/timeline.json
@@ -9,14 +9,18 @@
 		"addTrim": "添加剪辑 (T)",
 		"addAnnotation": "添加标注 (A)",
 		"addSpeed": "添加速度 (S)",
-		"addCameraFullscreen": "添加全屏摄像头 (C)"
+		"addCameraFullscreen": "添加全屏摄像头 (C)",
+		"addVoiceover": "添加配音（V）",
+		"addMusic": "添加音乐（B）"
 	},
 	"hints": {
 		"pressZoom": "按 Z 添加缩放",
 		"pressTrim": "按 T 添加剪辑",
 		"pressAnnotation": "按 A 添加标注",
 		"pressSpeed": "按 S 添加速度",
-		"pressCameraFullscreen": "按 C 添加一个全屏摄像头片段"
+		"pressCameraFullscreen": "按 C 添加一个全屏摄像头片段",
+		"pressVoiceover": "按 V 添加配音",
+		"pressMusic": "按 B 添加音乐"
 	},
 	"labels": {
 		"pan": "平移",
@@ -86,5 +90,28 @@
 		"smartCutsNoAudio": "此媒体没有音频",
 		"smartCutsNoSpeech": "未检测到语音",
 		"smartCutsFailed": "转录失败 — 请在“媒体”中重试"
+	},
+	"audio": {
+		"addVoiceover": "添加配音",
+		"addMusic": "添加背景音乐",
+		"subtitle": "在时间轴上放置配音或背景音乐图层",
+		"record": "录制配音",
+		"importFile": "导入音频文件",
+		"chooseMusic": "选择音乐文件",
+		"recording": "正在录制",
+		"stop": "停止",
+		"micDenied": "麦克风访问被拒绝",
+		"recordingUnavailable": "此处无法录音",
+		"saveFailed": "无法保存录音",
+		"importFailed": "无法导入音频文件",
+		"voiceoverLabel": "配音",
+		"musicLabel": "音乐",
+		"gain": "音量",
+		"mute": "静音",
+		"offset": "起始偏移",
+		"fadeIn": "淡入",
+		"fadeOut": "淡出",
+		"loop": "循环",
+		"deleteLayer": "删除音频图层"
 	}
 }
diff --git a/src/i18n/locales/zh-TW/dialogs.json b/src/i18n/locales/zh-TW/dialogs.json
index 14fc364a0..a7d26088b 100644
--- a/src/i18n/locales/zh-TW/dialogs.json
+++ b/src/i18n/locales/zh-TW/dialogs.json
@@ -85,6 +85,8 @@
 		"mp4Video": "MP4 影片",
 		"videoFiles": "影片檔案",
 		"openscreenProject": "OpenScreen 專案",
-		"allFiles": "所有檔案"
+		"allFiles": "所有檔案",
+		"selectAudio": "選取音訊檔案",
+		"audioFiles": "音訊檔案"
 	}
 }
diff --git a/src/i18n/locales/zh-TW/shortcuts.json b/src/i18n/locales/zh-TW/shortcuts.json
index fd8c6434b..1574845ec 100644
--- a/src/i18n/locales/zh-TW/shortcuts.json
+++ b/src/i18n/locales/zh-TW/shortcuts.json
@@ -25,7 +25,9 @@
 		"deleteSelected": "刪除所選",
 		"playPause": "播放 / 暫停",
 		"copySelected": "複製所選",
-		"paste": "貼上"
+		"paste": "貼上",
+		"addVoiceover": "新增旁白",
+		"addMusic": "新增音樂"
 	},
 	"fixedActions": {
 		"undo": "復原",
diff --git a/src/i18n/locales/zh-TW/timeline.json b/src/i18n/locales/zh-TW/timeline.json
index 7f4ba9874..7d25d37f2 100644
--- a/src/i18n/locales/zh-TW/timeline.json
+++ b/src/i18n/locales/zh-TW/timeline.json
@@ -9,14 +9,18 @@
 		"addTrim": "新增剪輯 (T)",
 		"addAnnotation": "新增標註 (A)",
 		"addSpeed": "新增速度 (S)",
-		"addCameraFullscreen": "新增全螢幕攝影機 (C)"
+		"addCameraFullscreen": "新增全螢幕攝影機 (C)",
+		"addVoiceover": "新增旁白（V）",
+		"addMusic": "新增音樂（B）"
 	},
 	"hints": {
 		"pressZoom": "按 Z 新增縮放",
 		"pressTrim": "按 T 新增剪輯",
 		"pressAnnotation": "按 A 新增標註",
 		"pressSpeed": "按 S 新增速度",
-		"pressCameraFullscreen": "按 C 新增一個全螢幕攝影機片段"
+		"pressCameraFullscreen": "按 C 新增一個全螢幕攝影機片段",
+		"pressVoiceover": "按 V 新增旁白",
+		"pressMusic": "按 B 新增音樂"
 	},
 	"labels": {
 		"pan": "平移",
@@ -86,5 +90,28 @@
 		"smartCutsNoAudio": "此媒體沒有音訊",
 		"smartCutsNoSpeech": "未偵測到語音",
 		"smartCutsFailed": "轉錄失敗 — 請在「媒體」中重試"
+	},
+	"audio": {
+		"addVoiceover": "新增旁白",
+		"addMusic": "新增背景音樂",
+		"subtitle": "在時間軸上放置旁白或背景音樂圖層",
+		"record": "錄製旁白",
+		"importFile": "匯入音訊檔案",
+		"chooseMusic": "選擇音樂檔案",
+		"recording": "錄製中",
+		"stop": "停止",
+		"micDenied": "麥克風存取遭拒絕",
+		"recordingUnavailable": "此處無法錄音",
+		"saveFailed": "無法儲存錄音",
+		"importFailed": "無法匯入音訊檔案",
+		"voiceoverLabel": "旁白",
+		"musicLabel": "音樂",
+		"gain": "音量",
+		"mute": "靜音",
+		"offset": "起始偏移",
+		"fadeIn": "淡入",
+		"fadeOut": "淡出",
+		"loop": "循環",
+		"deleteLayer": "刪除音訊圖層"
 	}
 }
diff --git a/src/lib/ai-edition/store/documentWriteAudit.test.ts b/src/lib/ai-edition/store/documentWriteAudit.test.ts
index 6a76e8013..3f93d73ad 100644
--- a/src/lib/ai-edition/store/documentWriteAudit.test.ts
+++ b/src/lib/ai-edition/store/documentWriteAudit.test.ts
@@ -138,6 +138,7 @@ const DECLARED: WritePath[] = [
 	w("src/components/ai-edition/NewEditorShell.tsx", "pasteRegion", "save", "gesture"),
 	w("src/components/ai-edition/NewEditorShell.tsx", "pasteRegion", "save", "gesture"),
 	w("src/components/ai-edition/NewEditorShell.tsx", "pasteRegion", "save", "gesture"),
+	w("src/components/ai-edition/NewEditorShell.tsx", "pasteRegion", "save", "gesture"),
 	// The window is closing and the user answered "save".
 	w("src/components/ai-edition/NewEditorShell.tsx", "unsubSaveBeforeClose", "save", "gesture"),
 
@@ -217,6 +218,7 @@ const DECLARED: WritePath[] = [
 	// where they used to be two writes that overwrote each other.
 	w("src/lib/ai-edition/store/useTimeline.ts", "applyClipEdit", "save", "gesture"),
 	w("src/lib/ai-edition/store/useTimeline.ts", "addAnnotation", "save", "gesture"),
+	w("src/lib/ai-edition/store/useTimeline.ts", "addAudioRegion", "save", "gesture"),
 	w("src/lib/ai-edition/store/useTimeline.ts", "addCameraFullscreen", "save", "gesture"),
 	w("src/lib/ai-edition/store/useTimeline.ts", "addSpeed", "save", "gesture"),
 	w("src/lib/ai-edition/store/useTimeline.ts", "addTrim", "save", "gesture"),
@@ -244,6 +246,8 @@ const DECLARED: WritePath[] = [
 	// The live halves of the two drags.
 	w("src/lib/ai-edition/store/useTimeline.ts", "updateAnnotationLive", "set", "automatic"),
 	w("src/lib/ai-edition/store/useTimeline.ts", "updateAnnotationSpan", "save", "gesture"),
+	w("src/lib/ai-edition/store/useTimeline.ts", "updateAudioRegion", "save", "gesture"),
+	w("src/lib/ai-edition/store/useTimeline.ts", "updateAudioSpan", "save", "gesture"),
 	w("src/lib/ai-edition/store/useTimeline.ts", "updateCameraFullscreenSpan", "save", "gesture"),
 	w("src/lib/ai-edition/store/useTimeline.ts", "updateSpeedSpan", "save", "gesture"),
 	w("src/lib/ai-edition/store/useTimeline.ts", "updateSpeedValue", "save", "gesture"),
diff --git a/src/lib/ai-edition/store/regionClipboard.ts b/src/lib/ai-edition/store/regionClipboard.ts
index ef1116ff8..69209b087 100644
--- a/src/lib/ai-edition/store/regionClipboard.ts
+++ b/src/lib/ai-edition/store/regionClipboard.ts
@@ -11,6 +11,9 @@ export type RegionSnapshot =
 	| { kind: "annotation"; region: Record<string, unknown> }
 	| { kind: "speed"; region: Record<string, unknown> }
 	| { kind: "cameraFullscreen"; region: Record<string, unknown> }
+	// An audio layer copies its whole payload (asset, gain, fades, loop) so a
+	// paste is a second placement of the same audio, like every other kind.
+	| { kind: "audio"; region: Record<string, unknown> }
 	// A trim carries no user-visible properties, so all there is to copy is how
 	// LONG it was — `{ durationSec }`. That is not a special case so much as the
 	// general one made obvious: every paste keeps the copied properties and takes
diff --git a/src/lib/ai-edition/store/useTimeline.ts b/src/lib/ai-edition/store/useTimeline.ts
index 7823459ec..79b6ad6e3 100644
--- a/src/lib/ai-edition/store/useTimeline.ts
+++ b/src/lib/ai-edition/store/useTimeline.ts
@@ -438,6 +438,112 @@ export function useTimeline() {
 		[document, saveDocument],
 	);
 
+	// Audio layers (voiceover / background music). The region's span defaults to
+	// the audio file's own duration when the caller knows it (a fresh voiceover
+	// recording, an imported asset that has been probed) so the layer covers what
+	// it has to play — the caller decides, because only it knows whether the
+	// duration is real yet.
+	const addAudioRegion = useCallback(
+		async (kind: "voiceover" | "music", assetId: string, durationSec = DEFAULT_NEW_REGION_SEC) => {
+			if (!document) return;
+			if (!document.assets.some((a) => a.id === assetId)) return;
+			const timeMs = Math.round(playheadSec() * 1000);
+			const endMs = timeMs + Math.max(1, Math.round(durationSec * 1000));
+			const anchored = anchorRegionsWithDerivedMs(
+				[
+					{
+						id: createId("aud"),
+						startMs: timeMs,
+						endMs,
+						assetId,
+						kind,
+						offsetMs: 0,
+						gainDb: 0,
+						loop: false,
+						fadeInMs: 0,
+						fadeOutMs: 0,
+						muted: false,
+						origin: "user" as const,
+					},
+				],
+				document.timeline.clips,
+				() => createId("aud"),
+			);
+			const next: AxcutDocument = {
+				...document,
+				audioRanges: [...document.audioRanges, ...anchored] as AxcutDocument["audioRanges"],
+			};
+			if (!(await saveDocument(next, { history: true }))) return;
+			// Select the new layer so its inspector opens — same affordance as
+			// addAnnotation.
+			const newId = anchored[0]?.id;
+			if (newId) {
+				setMultiSelection([{ kind: "audio", id: newId }]);
+				setSelection({ kind: "audio", id: newId });
+			}
+		},
+		[document, saveDocument],
+	);
+
+	// Payload edits (gain, offset, loop, fades, mute) hit every fragment under
+	// the pill, exactly like updateZoomDepth — a layer dragged across a clip
+	// boundary is 2+ rows that must not disagree.
+	const updateAudioRegion = useCallback(
+		async (
+			id: string,
+			patch: Partial<
+				Pick<
+					AxcutDocument["audioRanges"][number],
+					"gainDb" | "offsetMs" | "loop" | "fadeInMs" | "fadeOutMs" | "muted"
+				>
+			>,
+		) => {
+			// Read the store, not the render closure: two actions fired back to
+			// back (e.g. a slider commit right after a pill drag) each captured
+			// the same pre-edit document, so whichever write landed last silently
+			// dropped the other's patch — the same clobber applyClipEdit composes
+			// around.
+			const doc = useProjectStore.getState().document;
+			if (!doc) return;
+			const next: AxcutDocument = {
+				...doc,
+				audioRanges: patchPillById(
+					doc.audioRanges,
+					id,
+					// Every key in the pick exists on the region, so widening the
+					// partial is safe; it is what `patchPillById` expects.
+					patch as Partial<AxcutDocument["audioRanges"][number]>,
+				) as AxcutDocument["audioRanges"],
+			};
+			await saveDocument(next, { history: true });
+		},
+		[saveDocument],
+	);
+
+	// Drag/resize on the ruler — group-aware like the other span updates.
+	const updateAudioSpan = useCallback(
+		async (id: string, startMs: number, endMs: number) => {
+			// Store-read for the same reason as updateAudioRegion above.
+			const doc = useProjectStore.getState().document;
+			if (!doc) return;
+			const s = finiteMs(startMs);
+			const e = finiteMs(endMs);
+			const next: AxcutDocument = {
+				...doc,
+				audioRanges: replacePillSpan(
+					doc.audioRanges,
+					id,
+					Math.min(s, e),
+					Math.max(s, e),
+					doc.timeline.clips,
+					() => createId("aud"),
+				) as AxcutDocument["audioRanges"],
+			};
+			await saveDocument(next, { history: true });
+		},
+		[saveDocument],
+	);
+
 	// Like updateTrimRange but also re-attaches the trim to a (possibly different) CLIP —
 	// needed when a trim is dragged across a clip boundary, whether or not the landing clip
 	// is backed by another asset. Re-pointing `clipId` as well as `assetId` is what makes a
@@ -847,6 +953,7 @@ export function useTimeline() {
 			const cameraFullscreenIds = new Set(
 				handles.filter((h) => h.kind === "cameraFullscreen").map((h) => h.id),
 			);
+			const audioIds = new Set(handles.filter((h) => h.kind === "audio").map((h) => h.id));
 			const legacy = (document.legacyEditor as Record<string, unknown>) ?? {};
 			const prevSpeed = dropPillsByIds(
 				(legacy.speedRegions as Array<{ id: string; startMs: number; endMs: number }>) ?? [],
@@ -861,6 +968,7 @@ export function useTimeline() {
 				...document,
 				zoomRanges: dropPillsByIds(document.zoomRanges, zoomIds) as AxcutDocument["zoomRanges"],
 				annotations: dropPillsByIds(document.annotations, annotationIds),
+				audioRanges: dropPillsByIds(document.audioRanges, audioIds) as AxcutDocument["audioRanges"],
 				timeline: {
 					...document.timeline,
 					// Whole-pill delete, same as the zoom/annotation lines above — a trim grown
@@ -1179,6 +1287,8 @@ export function useTimeline() {
 		annotationRegions: (document?.annotations ?? []) as unknown as AnnotationRegion[],
 		speedRegions,
 		cameraFullscreenRegions,
+		audioRegions: document?.audioRanges ?? [],
+		audioAssets: (document?.assets ?? []).filter((a) => a.kind === "audio"),
 		clips: document?.timeline.clips ?? [],
 		assets: document?.assets ?? [],
 		hasDoc,
@@ -1191,6 +1301,7 @@ export function useTimeline() {
 		addAnnotation,
 		addSpeed,
 		addCameraFullscreen,
+		addAudioRegion,
 		removeRegion,
 		removeRegions,
 		selectRegion,
@@ -1215,6 +1326,8 @@ export function useTimeline() {
 		updateSpeedSpan,
 		updateSpeedValue,
 		updateCameraFullscreenSpan,
+		updateAudioRegion,
+		updateAudioSpan,
 		// T19 — drives the preview video during trim-edge resize.
 		setCurrentTime: useProjectStore((s) => s.setCurrentTime),
 	};
diff --git a/src/lib/ai-edition/timeline/duration.ts b/src/lib/ai-edition/timeline/duration.ts
index 950d2ae3b..020bf269d 100644
--- a/src/lib/ai-edition/timeline/duration.ts
+++ b/src/lib/ai-edition/timeline/duration.ts
@@ -66,8 +66,7 @@ export function probeVideoDuration(
  *  cheap, one-shot, not worth merging into a combined probe for the one extra caller that
  *  needs both). `asset.video` was otherwise left permanently unset for most recordings (nothing
  *  else populates it), silently breaking anything that reads it — e.g. the export dialog's
- *  downscale/upscale badges, which need real source dimensions to compare against. */
-export function probeVideoDimensions(
+ *  downscale/upscale badges, which need real source dimensions to compare against. */ export function probeVideoDimensions(
 	src: string,
 	timeoutMs: number = DEFAULT_TIMEOUT_MS,
 ): Promise<{ width: number; height: number } | null> {
@@ -113,3 +112,51 @@ export function probeVideoDimensions(
 		video.src = src;
 	});
 }
+
+/**
+ * Probe an audio file's duration with a throwaway <audio> element — the
+ * audio-layer answer to `probeVideoDuration`. A freshly imported voiceover or
+ * music file has no `durationSec` yet (DocumentService only captures the
+ * path), and the layer's initial span wants the real length so it covers what
+ * it plays. Same null-on-failure contract.
+ */
+export function probeAudioDuration(
+	src: string,
+	timeoutMs: number = DEFAULT_TIMEOUT_MS,
+): Promise<number | null> {
+	return new Promise((resolve) => {
+		if (typeof document === "undefined" || !src) {
+			resolve(null);
+			return;
+		}
+		const audio = document.createElement("audio");
+		audio.preload = "metadata";
+		let settled = false;
+		const cleanup = () => {
+			audio.onloadedmetadata = null;
+			audio.onerror = null;
+			clearTimeout(timer);
+			try {
+				audio.removeAttribute("src");
+				audio.load();
+			} catch {
+				// ignore — browser may refuse if already detached
+			}
+			if (audio.parentNode) audio.parentNode.removeChild(audio);
+		};
+		const settle = (value: number | null) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			resolve(value);
+		};
+		const timer = setTimeout(() => settle(null), timeoutMs);
+		audio.onloadedmetadata = () => {
+			const d = audio.duration;
+			settle(Number.isFinite(d) && d > 0 ? d : null);
+		};
+		audio.onerror = () => settle(null);
+		document.body.appendChild(audio);
+		audio.src = src;
+	});
+}
diff --git a/src/lib/shortcuts.test.ts b/src/lib/shortcuts.test.ts
index 1fe3896e8..817b63e68 100644
--- a/src/lib/shortcuts.test.ts
+++ b/src/lib/shortcuts.test.ts
@@ -21,12 +21,22 @@ describe("shortcut registry", () => {
 		expect(Object.keys(DEFAULT_SHORTCUTS).sort()).toEqual([...SHORTCUT_ACTIONS].sort());
 	});
 
-	it("leaves a plain 'b' free to bind", () => {
-		// The blur *region* was never implemented — blur ships as an annotation
-		// type. While `addBlur: {key: "b"}` was still in the registry, binding B to
-		// any real action reported "Already used by Add Blur" and offered a Swap
-		// that handed the old binding to a hidden, undispatched action.
-		expect(findConflict({ key: "b" }, "addZoom", DEFAULT_SHORTCUTS)).toBeNull();
+	it("binds V and B to the audio layers", () => {
+		expect(DEFAULT_SHORTCUTS.addVoiceover).toEqual({ key: "v" });
+		expect(DEFAULT_SHORTCUTS.addMusic).toEqual({ key: "b" });
+		// The keys really are claimed: re-binding them collides with the layers.
+		expect(findConflict({ key: "v" }, "addZoom", DEFAULT_SHORTCUTS)).toEqual({
+			type: "configurable",
+			action: "addVoiceover",
+		});
+		expect(findConflict({ key: "b" }, "addZoom", DEFAULT_SHORTCUTS)).toEqual({
+			type: "configurable",
+			action: "addMusic",
+		});
+	});
+
+	it("leaves a plain 'q' free to bind", () => {
+		expect(findConflict({ key: "q" }, "addZoom", DEFAULT_SHORTCUTS)).toBeNull();
 	});
 
 	it("still reports a real collision", () => {
diff --git a/src/lib/shortcuts.ts b/src/lib/shortcuts.ts
index 0487b91c7..56d95fc17 100644
--- a/src/lib/shortcuts.ts
+++ b/src/lib/shortcuts.ts
@@ -5,6 +5,8 @@ export const SHORTCUT_ACTIONS = [
 	"addSpeed",
 	"addCameraFullscreen",
 	"addAnnotation",
+	"addVoiceover",
+	"addMusic",
 	"deleteSelected",
 	"playPause",
 	"copySelected",
@@ -113,6 +115,8 @@ export const DEFAULT_SHORTCUTS: ShortcutsConfig = {
 	addSpeed: { key: "s" },
 	addCameraFullscreen: { key: "c" },
 	addAnnotation: { key: "a" },
+	addVoiceover: { key: "v" },
+	addMusic: { key: "b" },
 	deleteSelected: { key: "d", ctrl: true },
 	playPause: { key: " " },
 	copySelected: { key: "c", ctrl: true },
@@ -126,6 +130,8 @@ export const SHORTCUT_LABELS: Record<ShortcutAction, string> = {
 	addSpeed: "Add Speed",
 	addCameraFullscreen: "Add Full Camera",
 	addAnnotation: "Add Annotation",
+	addVoiceover: "Add Voiceover",
+	addMusic: "Add Music",
 	deleteSelected: "Delete Selected",
 	playPause: "Play / Pause",
 	copySelected: "Copy Selected",

From 6a855e826dcd7b193bd894bb2bcf2bd016e657e2 Mon Sep 17 00:00:00 2001
From: Ola Adebayo <olamideadebayo2001@gmail.com>
Date: Fri, 28 Aug 2026 15:16:38 +0100
Subject: [PATCH 4/6] feat(export): mix audio layers into MP4 exports
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The native pipeline has no extra-audio-track concept, so layers join the
CLI's post-export mix path: after exportMultiNative writes the MP4, the
editor renders a new audio track (original bed + every layer at its
projected export-time position, with gain, offset, fades and looping)
via OfflineAudioContext and re-muxes it with mediabunny — video packets
copied untouched. Ruler spans are projected onto the assembled
(trim-compressed) timeline first; speed regions are deliberately
ignored, so a layer plays at 1x under a sped-up stretch (documented
v1 limitation). GIF exports are unaffected.
---
 src/components/ai-edition/ExportDialog.tsx  |  60 +++++
 src/lib/exporter/audioLayerTimeline.test.ts |  66 +++++
 src/lib/exporter/audioLayerTimeline.ts      |  92 +++++++
 src/lib/exporter/voiceoverMix.test.ts       | 118 +++++++++
 src/lib/exporter/voiceoverMix.ts            | 254 ++++++++++++++++++--
 5 files changed, 575 insertions(+), 15 deletions(-)
 create mode 100644 src/lib/exporter/audioLayerTimeline.test.ts
 create mode 100644 src/lib/exporter/audioLayerTimeline.ts
 create mode 100644 src/lib/exporter/voiceoverMix.test.ts

diff --git a/src/components/ai-edition/ExportDialog.tsx b/src/components/ai-edition/ExportDialog.tsx
index c661933f1..af8312c0e 100644
--- a/src/components/ai-edition/ExportDialog.tsx
+++ b/src/components/ai-edition/ExportDialog.tsx
@@ -32,7 +32,9 @@ import {
 	type GifFrameRate,
 	type GifSizePreset,
 } from "@/lib/exporter";
+import { buildExportTimelineMapping, rawToExportTime } from "@/lib/exporter/audioLayerTimeline";
 import { calculateMp4ExportSettings, wouldUpscale } from "@/lib/exporter/mp4ExportSettings";
+import { mixAudioLayersIntoVideo } from "@/lib/exporter/voiceoverMix";
 import { exportGifNative, exportMultiNative, useIsCpuCompositor } from "@/native";
 import type { CompositorClipInput } from "@/native/contracts";
 import { buildSceneDescription, resolveVisibleClips } from "@/native/sceneDescription";
@@ -330,6 +332,64 @@ export function ExportDialog({ open, onClose, document }: ExportDialogProps) {
 								fps,
 								codec,
 							});
+				// Audio layers (voiceover / background music) are a renderer-side
+				// post-pass: the native pipeline has no extra-audio-track concept, so
+				// the layers are mixed into the finished MP4 here — same re-mux the
+				// CLI uses for `--audio`. Video packets stay untouched.
+				if (format === "mp4") {
+					const layerAssets = document.audioRanges
+						.filter((r) => !r.muted)
+						.map((r) => ({
+							region: r,
+							asset: document.assets.find((a) => a.id === r.assetId),
+						}))
+						.filter((entry): entry is typeof entry & { asset: NonNullable<typeof entry.asset> } =>
+							Boolean(entry.asset),
+						);
+					if (layerAssets.length > 0) {
+						setPhase("writing");
+						const mapping = buildExportTimelineMapping(
+							document.timeline.clips,
+							document.timeline.trimRanges,
+						);
+						const layerInputs = [];
+						for (const { region, asset } of layerAssets) {
+							const bytes = await window.electronAPI?.readBinaryFile?.(asset.originalPath);
+							if (!bytes?.success || !bytes.data) {
+								// A layer whose file vanished degrades to silence rather
+								// than failing the whole export.
+								console.warn("[export] audio layer asset unreadable:", asset.originalPath);
+								continue;
+							}
+							layerInputs.push({
+								data: bytes.data,
+								startSec: rawToExportTime(region.startMs / 1000, mapping),
+								endSec: rawToExportTime(region.endMs / 1000, mapping),
+								offsetSec: region.offsetMs / 1000,
+								gainDb: region.gainDb,
+								loop: region.loop,
+								fadeInMs: region.fadeInMs,
+								fadeOutMs: region.fadeOutMs,
+							});
+						}
+						if (layerInputs.length > 0) {
+							const exported = await window.electronAPI?.readBinaryFile?.(pickedPath);
+							if (exported?.success && exported.data) {
+								const mixed = await mixAudioLayersIntoVideo(
+									new Blob([exported.data], { type: "video/mp4" }),
+									{ layers: layerInputs },
+								);
+								const write = await window.electronAPI?.writeExportToPath?.(
+									await mixed.arrayBuffer(),
+									pickedPath,
+								);
+								if (!write?.success) {
+									throw new Error(write?.message ?? t("exportDialog.exportFailed"));
+								}
+							}
+						}
+					}
+				}
 				setSavedPath(pickedPath);
 				setPhase("done");
 				toast.success(t("exportDialog.exportedVideo"), {
diff --git a/src/lib/exporter/audioLayerTimeline.test.ts b/src/lib/exporter/audioLayerTimeline.test.ts
new file mode 100644
index 000000000..d72af0e99
--- /dev/null
+++ b/src/lib/exporter/audioLayerTimeline.test.ts
@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+import type { AxcutClip, AxcutTrimRange } from "@/lib/ai-edition/schema";
+import { buildExportTimelineMapping, rawToExportTime } from "./audioLayerTimeline";
+
+function clip(
+	id: string,
+	timelineStartSec: number,
+	sourceStartSec: number,
+	sourceEndSec: number,
+): AxcutClip {
+	return {
+		id,
+		assetId: "a1",
+		sourceStartSec,
+		sourceEndSec,
+		timelineStartSec,
+		timelineEndSec: timelineStartSec + (sourceEndSec - sourceStartSec),
+		wordRefs: [],
+		origin: "user",
+		reason: "",
+	};
+}
+
+function trim(id: string, clipId: string, startSec: number, endSec: number): AxcutTrimRange {
+	return { id, assetId: "a1", clipId, startSec, endSec, origin: "user", reason: "" };
+}
+
+describe("buildExportTimelineMapping", () => {
+	it("is the identity when there are no trims", () => {
+		const mapping = buildExportTimelineMapping([clip("c1", 0, 0, 10), clip("c2", 10, 0, 5)], []);
+		expect(mapping).toEqual([
+			{ rawStart: 0, rawEnd: 10, exportStart: 0 },
+			{ rawStart: 10, rawEnd: 15, exportStart: 10 },
+		]);
+	});
+
+	it("compresses trimmed spans onto the assembled timeline", () => {
+		// One 10s clip with the middle 2s (4..6) cut.
+		const mapping = buildExportTimelineMapping([clip("c1", 0, 0, 10)], [trim("t1", "c1", 4, 6)]);
+		expect(mapping).toEqual([
+			{ rawStart: 0, rawEnd: 4, exportStart: 0 },
+			{ rawStart: 6, rawEnd: 10, exportStart: 4 },
+		]);
+	});
+
+	it("maps a raw instant inside a trim to the boundary the video jumps to", () => {
+		const mapping = buildExportTimelineMapping([clip("c1", 0, 0, 10)], [trim("t1", "c1", 4, 6)]);
+		expect(rawToExportTime(2, mapping)).toBeCloseTo(2);
+		// 4..6 is cut: the video jumps from raw 4 to raw 6 — a layer starting
+		// at raw 5 lands where raw 6 resumes (export 4).
+		expect(rawToExportTime(5, mapping)).toBeCloseTo(4);
+		expect(rawToExportTime(8, mapping)).toBeCloseTo(6);
+	});
+
+	it("keeps the mapping per-clip across an edited source range", () => {
+		// Clip starts 3s into the source; raw timeline 0 = source 3.
+		const mapping = buildExportTimelineMapping([clip("c1", 0, 3, 13)], [trim("t1", "c1", 5, 7)]);
+		// Raw 2 = source 5 = start of the trim → next kept starts at raw 4 (source 7).
+		expect(mapping).toEqual([
+			{ rawStart: 0, rawEnd: 2, exportStart: 0 },
+			{ rawStart: 4, rawEnd: 10, exportStart: 2 },
+		]);
+		expect(rawToExportTime(1, mapping)).toBeCloseTo(1);
+		expect(rawToExportTime(5, mapping)).toBeCloseTo(3);
+	});
+});
diff --git a/src/lib/exporter/audioLayerTimeline.ts b/src/lib/exporter/audioLayerTimeline.ts
new file mode 100644
index 000000000..3356a4d8d
--- /dev/null
+++ b/src/lib/exporter/audioLayerTimeline.ts
@@ -0,0 +1,92 @@
+// Raw-ruler → export-timeline mapping for audio layers.
+//
+// A layer's `startMs`/`endMs` are RAW ruler coordinates (the same space the
+// pills and the playhead use). The exported MP4 is the ASSEMBLED timeline:
+// trims removed, so its clock is shorter wherever a cut exists. Before a layer
+// can be mixed into the exported file its span must be projected onto that
+// assembled clock — the same projection `resolvePlaybackSegments` performs for
+// the video itself.
+//
+// Speed regions are deliberately ignored here: a layer plays at 1× in the
+// preview and in the mix, so under a speed region it will drift relative to
+// the sped-up picture. Documented v1 limitation.
+
+import { subtractInterval } from "@/lib/ai-edition/document/timeline";
+import type { AxcutClip, AxcutTrimRange } from "@/lib/ai-edition/schema";
+import { trimAppliesToClip } from "@/lib/ai-edition/timeline/trim-mapping";
+
+export interface ExportMappingSegment {
+	/** Span on the RAW ruler. */
+	rawStart: number;
+	rawEnd: number;
+	/** Where that span lands on the assembled (exported) timeline. */
+	exportStart: number;
+}
+
+/**
+ * The kept spans of each clip, in timeline order, with both their raw-ruler
+ * position and their position on the assembled timeline.
+ */
+export function buildExportTimelineMapping(
+	clips: AxcutClip[],
+	trimRanges: AxcutTrimRange[],
+): ExportMappingSegment[] {
+	const ordered = [...clips].sort((a, b) => a.timelineStartSec - b.timelineStartSec);
+	const result: ExportMappingSegment[] = [];
+	let exportCursor = 0;
+	for (const clip of ordered) {
+		const sourceEnd = clip.sourceEndSec ?? clip.sourceStartSec;
+		// Unprobed clip: no real source window yet — pass its whole width through.
+		if (sourceEnd <= clip.sourceStartSec) {
+			result.push({
+				rawStart: clip.timelineStartSec,
+				rawEnd: clip.timelineEndSec,
+				exportStart: exportCursor,
+			});
+			exportCursor += clip.timelineEndSec - clip.timelineStartSec;
+			continue;
+		}
+		let kept = [{ startSec: clip.sourceStartSec, endSec: sourceEnd }];
+		for (const trim of trimRanges) {
+			if (!trimAppliesToClip(trim, clip)) continue;
+			kept = subtractInterval(kept, { startSec: trim.startSec, endSec: trim.endSec });
+		}
+		for (const iv of kept) {
+			const dur = iv.endSec - iv.startSec;
+			if (dur <= 0) continue;
+			result.push({
+				rawStart: clip.timelineStartSec + (iv.startSec - clip.sourceStartSec),
+				rawEnd: clip.timelineStartSec + (iv.endSec - clip.sourceStartSec),
+				exportStart: exportCursor,
+			});
+			exportCursor += dur;
+		}
+	}
+	return result;
+}
+
+/**
+ * Project one RAW-ruler instant onto the assembled timeline. A point inside a
+ * trim (no segment covers it) clamps to the boundary the video itself jumps
+ * to: the start of the next kept segment, or the end of the previous one.
+ */
+export function rawToExportTime(rawSec: number, mapping: ExportMappingSegment[]): number {
+	for (const seg of mapping) {
+		if (rawSec >= seg.rawStart && rawSec < seg.rawEnd) {
+			return seg.exportStart + (rawSec - seg.rawStart);
+		}
+	}
+	// In a gap: find where the surrounding kept material sits.
+	let after: ExportMappingSegment | null = null;
+	let before: ExportMappingSegment | null = null;
+	for (const seg of mapping) {
+		if (seg.rawStart >= rawSec) {
+			after = seg;
+			break;
+		}
+		before = seg;
+	}
+	if (after) return after.exportStart;
+	if (before) return before.exportStart + (before.rawEnd - before.rawStart);
+	return rawSec;
+}
diff --git a/src/lib/exporter/voiceoverMix.test.ts b/src/lib/exporter/voiceoverMix.test.ts
new file mode 100644
index 000000000..06dcdbac9
--- /dev/null
+++ b/src/lib/exporter/voiceoverMix.test.ts
@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+import { planLayerGain, planLayerIterations } from "./voiceoverMix";
+
+describe("planLayerIterations", () => {
+	const layer = (
+		overrides: Partial<{
+			startSec: number;
+			endSec: number;
+			offsetSec: number;
+			loop: boolean;
+		}> = {},
+	) => ({
+		startSec: 10,
+		endSec: 16,
+		offsetSec: 0,
+		loop: false,
+		...overrides,
+	});
+
+	it("plays once from the layer start, trimmed to the span", () => {
+		expect(planLayerIterations(layer({ endSec: 12 }), 30)).toEqual([
+			{ startSec: 10, offsetSec: 0, playSec: 2 },
+		]);
+	});
+
+	it("skips into the source by the offset", () => {
+		expect(planLayerIterations(layer({ offsetSec: 5, endSec: 13 }), 30)).toEqual([
+			{ startSec: 10, offsetSec: 5, playSec: 3 },
+		]);
+	});
+
+	it("returns nothing for a zero/negative span", () => {
+		expect(planLayerIterations(layer({ endSec: 10 }), 30)).toEqual([]);
+		expect(planLayerIterations(layer({ endSec: 8 }), 30)).toEqual([]);
+	});
+
+	it("loops the source for the whole span", () => {
+		// 4s of source, 7s span → 2 full loops + a 3s tail... 10..17: loops at
+		// 10 (4s), 14 (3s remainder).
+		expect(planLayerIterations(layer({ endSec: 17, loop: true }), 4)).toEqual([
+			{ startSec: 10, offsetSec: 0, playSec: 4 },
+			{ startSec: 14, offsetSec: 0, playSec: 3 },
+		]);
+	});
+
+	it("stops looping when the source is exhausted by the offset", () => {
+		expect(planLayerIterations(layer({ offsetSec: 30, loop: true }), 30)).toEqual([]);
+	});
+});
+
+describe("planLayerGain", () => {
+	it("holds unity with no fades", () => {
+		expect(
+			planLayerGain({
+				startSec: 0,
+				endSec: 10,
+				fadeInMs: 0,
+				fadeOutMs: 0,
+				muted: false,
+				gainDb: 0,
+			}),
+		).toEqual([{ atSec: 0, value: 1 }]);
+	});
+
+	it("ramps in from silence over the fade-in", () => {
+		expect(
+			planLayerGain({
+				startSec: 2,
+				endSec: 10,
+				fadeInMs: 1000,
+				fadeOutMs: 0,
+				muted: false,
+				gainDb: 0,
+			}),
+		).toEqual([
+			{ atSec: 2, value: 0 },
+			{ atSec: 3, value: 1, ramp: true },
+		]);
+	});
+
+	it("ramps out to silence at the end of the span", () => {
+		expect(
+			planLayerGain({
+				startSec: 2,
+				endSec: 10,
+				fadeInMs: 0,
+				fadeOutMs: 2000,
+				muted: false,
+				gainDb: 0,
+			}),
+		).toEqual([
+			{ atSec: 2, value: 1 },
+			{ atSec: 8, value: 1, ramp: true },
+			{ atSec: 10, value: 0 },
+		]);
+	});
+
+	it("scales by gainDb and collapses to silence when muted", () => {
+		const loud = planLayerGain({
+			startSec: 0,
+			endSec: 5,
+			fadeInMs: 0,
+			fadeOutMs: 0,
+			muted: false,
+			gainDb: 6,
+		});
+		expect(loud[0]?.value).toBeCloseTo(10 ** (6 / 20));
+		const muted = planLayerGain({
+			startSec: 0,
+			endSec: 5,
+			fadeInMs: 0,
+			fadeOutMs: 0,
+			muted: true,
+			gainDb: 0,
+		});
+		expect(muted[0]?.value).toBe(0);
+	});
+});
diff --git a/src/lib/exporter/voiceoverMix.ts b/src/lib/exporter/voiceoverMix.ts
index 0c6305627..e1937f35e 100644
--- a/src/lib/exporter/voiceoverMix.ts
+++ b/src/lib/exporter/voiceoverMix.ts
@@ -1,4 +1,6 @@
-// Post-export voiceover mixing for the CLI (`openscreen export --audio`).
+// Post-export voiceover mixing for the CLI (`openscreen export --audio`), and
+// audio-LAYER mixing for the editor (voiceover + background music placed on
+// the timeline).
 //
 // Takes the finished MP4 blob, copies its video packets untouched (no
 // re-encode), renders a new audio track with OfflineAudioContext — the
@@ -79,14 +81,8 @@ async function renderMixedAudio(
 	return context.startRendering();
 }
 
-/**
- * Returns a new MP4 blob with the same video stream and the mixed audio track.
- * The video packets are copied without re-encoding.
- */
-export async function mixVoiceoverIntoVideo(
-	videoBlob: Blob,
-	options: VoiceoverMixOptions,
-): Promise<Blob> {
+/** Shared remux: copy the video packets untouched, replace the audio track. */
+async function remuxWithMixedAudio(videoBlob: Blob, mixedAudio: AudioBuffer): Promise<Blob> {
 	const input = new Input({ source: new BlobSource(videoBlob), formats: ALL_FORMATS });
 	try {
 		const videoTrack = await input.getPrimaryVideoTrack();
@@ -101,12 +97,6 @@ export async function mixVoiceoverIntoVideo(
 		if (!decoderConfig) {
 			throw new Error("Exported file's video decoder config could not be read");
 		}
-		const durationSec = await input.computeDuration();
-
-		// The full-file bytes are only needed to decode the original bed in
-		// "mix" mode; "replace" skips the copy entirely.
-		const videoData = options.mode === "mix" ? await videoBlob.arrayBuffer() : null;
-		const mixedAudio = await renderMixedAudio(videoData, durationSec, options);
 
 		const target = new BufferTarget();
 		const output = new Output({
@@ -145,3 +135,237 @@ export async function mixVoiceoverIntoVideo(
 		input.dispose();
 	}
 }
+
+/**
+ * Returns a new MP4 blob with the same video stream and the mixed audio track.
+ * The video packets are copied without re-encoding.
+ */
+export async function mixVoiceoverIntoVideo(
+	videoBlob: Blob,
+	options: VoiceoverMixOptions,
+): Promise<Blob> {
+	const input = new Input({ source: new BlobSource(videoBlob), formats: ALL_FORMATS });
+	try {
+		const videoTrack = await input.getPrimaryVideoTrack();
+		if (!videoTrack) {
+			throw new Error("Exported file has no video track to remux");
+		}
+		const durationSec = await input.computeDuration();
+
+		// The full-file bytes are only needed to decode the original bed in
+		// "mix" mode; "replace" skips the copy entirely.
+		const videoData = options.mode === "mix" ? await videoBlob.arrayBuffer() : null;
+		const mixedAudio = await renderMixedAudio(videoData, durationSec, options);
+
+		return await remuxWithMixedAudio(videoBlob, mixedAudio);
+	} finally {
+		input.dispose();
+	}
+}
+
+// ── editor audio layers ───────────────────────────────────────────────────
+
+/** One timeline audio layer, already projected onto the EXPORT timeline. */
+export interface AudioLayerMixInput {
+	/** Encoded audio file bytes. */
+	data: ArrayBuffer;
+	/** Layer start on the exported timeline, in seconds. */
+	startSec: number;
+	/** Layer end on the exported timeline, in seconds. */
+	endSec: number;
+	/** Skip into the source file before it starts playing. */
+	offsetSec?: number;
+	/** Volume in dB — applied at full scale, so +12 dB can exceed unity. */
+	gainDb?: number;
+	/** Repeat the source for the layer's whole span. */
+	loop?: boolean;
+	fadeInMs?: number;
+	fadeOutMs?: number;
+	/** A muted layer is silent (and skipped entirely at render time). */
+	muted?: boolean;
+}
+
+export interface MixAudioLayersOptions {
+	layers: AudioLayerMixInput[];
+	/** Gain applied to the original track (0..1). Default 1 — the exported
+	 *  file's own audio (already gain-trimmed by the compositor) is kept
+	 *  as-is, with the layers summed on top. */
+	originalGain?: number;
+}
+
+/** One buffer-source scheduling unit of a layer (one loop iteration, or the
+ *  whole non-looping span). Pure, unit-testable. */
+export interface AudioLayerIteration {
+	/** Start time on the OUTPUT timeline. */
+	startSec: number;
+	/** Offset into the source file. */
+	offsetSec: number;
+	/** Source seconds this iteration plays. */
+	playSec: number;
+}
+
+export function planLayerIterations(
+	layer: {
+		startSec: number;
+		endSec: number;
+		offsetSec: number;
+		loop: boolean;
+	},
+	sourceDurationSec: number,
+): AudioLayerIteration[] {
+	const span = layer.endSec - layer.startSec;
+	if (span <= 0) return [];
+	const source = Math.max(0, sourceDurationSec - layer.offsetSec);
+	if (source <= 0) return [];
+	if (!layer.loop) {
+		return [
+			{
+				startSec: layer.startSec,
+				offsetSec: layer.offsetSec,
+				playSec: Math.min(source, span),
+			},
+		];
+	}
+	const iterations: AudioLayerIteration[] = [];
+	let cursor = 0;
+	// Guard against a pathological tiny loop (sub-millisecond source) never
+	// converging.
+	while (cursor < span && iterations.length < 100_000) {
+		iterations.push({
+			startSec: layer.startSec + cursor,
+			offsetSec: layer.offsetSec,
+			playSec: Math.min(source, span - cursor),
+		});
+		cursor += source;
+	}
+	return iterations;
+}
+
+/** Gain curve for one layer: fades in/out at the span's edges, held at the
+ *  layer's volume in between. A muted layer is silence from the start. */
+export function planLayerGain(layer: {
+	startSec: number;
+	endSec: number;
+	fadeInMs: number;
+	fadeOutMs: number;
+	muted: boolean;
+	gainDb: number;
+}): Array<{ atSec: number; value: number; ramp?: boolean }> {
+	const scalar = layer.muted ? 0 : 10 ** (layer.gainDb / 20);
+	const fadeInSec = layer.fadeInMs / 1000;
+	const fadeOutSec = layer.fadeOutMs / 1000;
+	const events: Array<{ atSec: number; value: number; ramp?: boolean }> = [];
+	events.push({ atSec: layer.startSec, value: fadeInSec > 0 ? 0 : scalar });
+	if (fadeInSec > 0 && layer.startSec + fadeInSec < layer.endSec) {
+		events.push({ atSec: layer.startSec + fadeInSec, value: scalar, ramp: true });
+	}
+	if (fadeOutSec > 0) {
+		const fadeStart = Math.max(layer.startSec, layer.endSec - fadeOutSec);
+		events.push({ atSec: fadeStart, value: scalar, ramp: true });
+		events.push({ atSec: layer.endSec, value: 0 });
+	}
+	return events;
+}
+
+/** Renders the assembled audio: original bed (optional) + every layer. */
+async function renderLayeredAudio(
+	videoData: ArrayBuffer | null,
+	durationSec: number,
+	layers: AudioLayerMixInput[],
+	originalGain: number,
+): Promise<AudioBuffer> {
+	const frameCount = Math.max(1, Math.ceil(durationSec * OUTPUT_SAMPLE_RATE));
+	const context = new OfflineAudioContext(OUTPUT_CHANNELS, frameCount, OUTPUT_SAMPLE_RATE);
+
+	if (videoData) {
+		try {
+			const original = await decodeToBuffer(context, videoData);
+			const originalNode = context.createBufferSource();
+			originalNode.buffer = original;
+			const gainNode = context.createGain();
+			gainNode.gain.value = originalGain;
+			originalNode.connect(gainNode);
+			gainNode.connect(context.destination);
+			originalNode.start(0);
+		} catch {
+			// The exported video has no decodable audio track; the layers
+			// become the only audio.
+		}
+	}
+
+	for (const layer of layers) {
+		if (layer.muted || layer.endSec <= layer.startSec) continue;
+		const decoded = await decodeToBuffer(context, layer.data);
+		const iterations = planLayerIterations(
+			{
+				startSec: layer.startSec,
+				endSec: layer.endSec,
+				offsetSec: Math.max(0, layer.offsetSec ?? 0),
+				loop: layer.loop ?? false,
+			},
+			decoded.duration,
+		);
+		if (iterations.length === 0) continue;
+
+		const gainNode = context.createGain();
+		gainNode.connect(context.destination);
+		for (const event of planLayerGain({
+			startSec: layer.startSec,
+			endSec: layer.endSec,
+			fadeInMs: layer.fadeInMs ?? 0,
+			fadeOutMs: layer.fadeOutMs ?? 0,
+			muted: false,
+			gainDb: layer.gainDb ?? 0,
+		})) {
+			if (event.ramp) {
+				gainNode.gain.linearRampToValueAtTime(event.value, event.atSec);
+			} else {
+				gainNode.gain.setValueAtTime(event.value, event.atSec);
+			}
+		}
+
+		for (const it of iterations) {
+			const source = context.createBufferSource();
+			source.buffer = decoded;
+			source.connect(gainNode);
+			source.start(it.startSec, it.offsetSec, it.playSec);
+		}
+	}
+
+	return context.startRendering();
+}
+
+/**
+ * Mix any number of audio layers (voiceover / background music) into an
+ * already-exported MP4: the video stream is copied untouched, the audio track
+ * is re-rendered as original bed + layers. Positions are EXPRESSED IN EXPORTED
+ * TIMELINE SECONDS — project them from ruler ms with
+ * `audioLayerTimeline.ts` before calling.
+ */
+export async function mixAudioLayersIntoVideo(
+	videoBlob: Blob,
+	options: MixAudioLayersOptions,
+): Promise<Blob> {
+	const layers = options.layers.filter((l) => !l.muted && l.endSec > l.startSec);
+	const input = new Input({ source: new BlobSource(videoBlob), formats: ALL_FORMATS });
+	try {
+		const videoTrack = await input.getPrimaryVideoTrack();
+		if (!videoTrack) {
+			throw new Error("Exported file has no video track to remux");
+		}
+		const videoDuration = await input.computeDuration();
+		const durationSec = Math.max(videoDuration, ...layers.map((l) => l.endSec));
+
+		const videoData = await videoBlob.arrayBuffer();
+		const mixedAudio = await renderLayeredAudio(
+			videoData,
+			durationSec,
+			layers,
+			options.originalGain ?? 1,
+		);
+
+		return await remuxWithMixedAudio(videoBlob, mixedAudio);
+	} finally {
+		input.dispose();
+	}
+}

From 5af120f583b8164c9c693ff88615312e99aaf44c Mon Sep 17 00:00:00 2001
From: Ola Adebayo <olamideadebayo2001@gmail.com>
Date: Fri, 28 Aug 2026 15:16:46 +0100
Subject: [PATCH 5/6] feat(store): thread the asset-kind hint through addAsset

The store's addAsset forwards the caller's kind (audio-layer imports
pass "audio") so the renderer and main process agree on what a file
is, instead of the main process guessing from the extension.
---
 src/lib/ai-edition/store/projectStore.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/lib/ai-edition/store/projectStore.ts b/src/lib/ai-edition/store/projectStore.ts
index 48dad73e2..9080c64ad 100644
--- a/src/lib/ai-edition/store/projectStore.ts
+++ b/src/lib/ai-edition/store/projectStore.ts
@@ -71,7 +71,7 @@ export interface ProjectState {
 	loadProject: (projectId: string) => Promise<void>;
 	createProject: (title: string) => Promise<AxcutDocument>;
 	refresh: () => Promise<void>;
-	addAsset: (path: string, label?: string) => Promise<AxcutAsset | null>;
+	addAsset: (path: string, label?: string, kind?: "video" | "audio") => Promise<AxcutAsset | null>;
 	removeAsset: (assetId: string) => Promise<void>;
 	/**
 	 * Write the document to disk. Resolves `true` when it took effect, `false` when it
@@ -223,7 +223,7 @@ export const useProjectStore = create<ProjectState>((set, get) => ({
 		await get().loadProject(projectId);
 	},
 
-	async addAsset(path, label) {
+	async addAsset(path, label, kind) {
 		const { projectId } = get();
 		if (!projectId) throw new Error("No project loaded");
 		// Everything below awaits: the native add, a camera lookup, a dimension probe and a
@@ -234,7 +234,7 @@ export const useProjectStore = create<ProjectState>((set, get) => ({
 		// superseded the write while it was in flight.
 		const epoch = currentWriteEpoch();
 		const superseded = () => get().projectId !== projectId || currentWriteEpoch() !== epoch;
-		const result = await nativeBridgeClient.aiEdition.addAsset(projectId, path, label);
+		const result = await nativeBridgeClient.aiEdition.addAsset(projectId, path, label, kind);
 		if (superseded()) return null;
 		let document = parseDocument(result.document);
 		const addedAsset =

From 156e407b3091dc551b89a70ccde3887a672d5781 Mon Sep 17 00:00:00 2001
From: Ola Adebayo <olamideadebayo2001@gmail.com>
Date: Fri, 28 Aug 2026 21:35:57 +0100
Subject: [PATCH 6/6] fix(editor): preview sync, picker re-entrancy and
 inspector drafts

- A non-looping layer whose file runs out before its span now holds
  silent instead of replaying its head in a 60 Hz restart loop, and a
  looping layer folds over the post-offset window so it stays in phase
  with the export mix.
- The music dialog's auto-import is guarded against re-firing on parent
  re-renders (inline onComplete churns on every playhead tick), which
  re-opened the native picker and could add duplicate layers.
- Inspector slider drafts follow external region edits (undo/redo).
- The export says so instead of silently dropping layers when a layer
  file or the exported file cannot be read back for the mix.
---
 .../ai-edition/AudioLayersPlayback.test.ts    | 13 +++++++
 .../ai-edition/AudioLayersPlayback.tsx        | 35 ++++++++++++++++---
 src/components/ai-edition/ExportDialog.tsx    | 13 ++++++-
 .../ai-edition/v4/AddAudioLayerDialog.tsx     | 27 ++++++++++----
 .../ai-edition/v4/FloatingInspector.tsx       | 16 +++++++++
 src/i18n/locales/ar/editor.json               |  4 ++-
 src/i18n/locales/en/editor.json               |  4 ++-
 src/i18n/locales/es/editor.json               |  4 ++-
 src/i18n/locales/fr/editor.json               |  4 ++-
 src/i18n/locales/it/editor.json               |  4 ++-
 src/i18n/locales/ja-JP/editor.json            |  4 ++-
 src/i18n/locales/ko-KR/editor.json            |  4 ++-
 src/i18n/locales/pt-BR/editor.json            |  4 ++-
 src/i18n/locales/ru/editor.json               |  4 ++-
 src/i18n/locales/tr/editor.json               |  4 ++-
 src/i18n/locales/vi/editor.json               |  4 ++-
 src/i18n/locales/zh-CN/editor.json            |  4 ++-
 src/i18n/locales/zh-TW/editor.json            |  4 ++-
 18 files changed, 130 insertions(+), 26 deletions(-)

diff --git a/src/components/ai-edition/AudioLayersPlayback.test.ts b/src/components/ai-edition/AudioLayersPlayback.test.ts
index 535a5711c..e332e837d 100644
--- a/src/components/ai-edition/AudioLayersPlayback.test.ts
+++ b/src/components/ai-edition/AudioLayersPlayback.test.ts
@@ -35,6 +35,19 @@ describe("layerSourcePosition", () => {
 		expect(layerSourcePosition(region({ loop: true }), 14.5, 4)).toBeCloseTo(0.5);
 	});
 
+	it("folds a looping layer over the post-offset window, matching the export", () => {
+		// offset 2s into a 6s file → the loop repeats source [2, 6): 4s long.
+		// local 0 → 2; local 4 → 2 (wrapped); local 5 → 3.
+		const r = region({ loop: true, offsetMs: 2000 });
+		expect(layerSourcePosition(r, 10, 6)).toBeCloseTo(2);
+		expect(layerSourcePosition(r, 14, 6)).toBeCloseTo(2);
+		expect(layerSourcePosition(r, 15, 6)).toBeCloseTo(3);
+	});
+
+	it("holds a looping layer at the end when the offset leaves nothing to loop", () => {
+		expect(layerSourcePosition(region({ loop: true, offsetMs: 5000 }), 12, 5)).toBeCloseTo(5);
+	});
+
 	it("is undefined-safe for unloaded metadata (0 duration)", () => {
 		expect(layerSourcePosition(region(), 12, 0)).toBeCloseTo(2);
 	});
diff --git a/src/components/ai-edition/AudioLayersPlayback.tsx b/src/components/ai-edition/AudioLayersPlayback.tsx
index bc2d07b8b..f0a4470dd 100644
--- a/src/components/ai-edition/AudioLayersPlayback.tsx
+++ b/src/components/ai-edition/AudioLayersPlayback.tsx
@@ -48,8 +48,11 @@ export function layerVolumeAt(region: AxcutAudioRegion, localSec: number): numbe
 
 /**
  * Local source position (seconds) for a layer at `timelineSec`. Loop folds the
- * position back into the source; without it the position clamps to the source
- * length. `sourceDurationSec` comes from the element's real metadata.
+ * position back into the source — over `sourceDuration - offset`, the same
+ * window the export's `planLayerIterations` repeats, so a looping layer with a
+ * start offset stays in phase with the mix. Without looping the position
+ * clamps to the source length. `sourceDurationSec` comes from the element's
+ * real metadata.
  */
 export function layerSourcePosition(
 	region: AxcutAudioRegion,
@@ -60,7 +63,12 @@ export function layerSourcePosition(
 	const local = Math.max(0, timelineSec - region.startMs / 1000);
 	const raw = offset + local;
 	if (sourceDurationSec <= 0) return raw;
-	if (region.loop) return offset + (local % sourceDurationSec);
+	if (region.loop) {
+		const loopLen = sourceDurationSec - offset;
+		if (loopLen > 0) return offset + (local % loopLen);
+		// The offset is at/after the end of the file: nothing left to loop.
+		return sourceDurationSec;
+	}
 	return Math.min(raw, sourceDurationSec);
 }
 
@@ -139,12 +147,29 @@ export function AudioLayersPlayback({
 					1,
 					gainScalar(region.gainDb) * layerVolumeAt(region, timeSec - startSec),
 				);
-				if (playing && element.paused) {
+				// A layer whose source has run out (non-looping file shorter than
+				// its span, or a loop offset past the end) sits silent instead of
+				// restarting: `play()` on an ended element seeks it to 0, and the
+				// next tick would reposition it back to the end — a 60 Hz
+				// restart/stutter loop. Hold it paused at the end.
+				const exhausted = sourceDuration > 0 && target >= sourceDuration - SYNC_EPSILON_SEC;
+				if (playing && !exhausted && element.paused) {
 					const play = element.play();
 					if (play) void play.catch(() => undefined);
-				} else if (!playing && !element.paused) {
+				} else if ((!playing || exhausted) && !element.paused) {
 					element.pause();
 				}
+				// A looping layer that reached the file's end between two ticks
+				// (the `ended` event pauses it before the fold catches up):
+				// reposition and resume in the same tick.
+				if (playing && region.loop && element.ended) {
+					try {
+						element.currentTime = target;
+					} catch {
+						// metadata not ready yet
+					}
+					void element.play().catch(() => undefined);
+				}
 			}
 		});
 		return unsubscribe;
diff --git a/src/components/ai-edition/ExportDialog.tsx b/src/components/ai-edition/ExportDialog.tsx
index af8312c0e..68f562267 100644
--- a/src/components/ai-edition/ExportDialog.tsx
+++ b/src/components/ai-edition/ExportDialog.tsx
@@ -353,11 +353,13 @@ export function ExportDialog({ open, onClose, document }: ExportDialogProps) {
 							document.timeline.trimRanges,
 						);
 						const layerInputs = [];
+						let missingLayerFiles = 0;
 						for (const { region, asset } of layerAssets) {
 							const bytes = await window.electronAPI?.readBinaryFile?.(asset.originalPath);
 							if (!bytes?.success || !bytes.data) {
 								// A layer whose file vanished degrades to silence rather
-								// than failing the whole export.
+								// than failing the whole export — but it is said out loud.
+								missingLayerFiles += 1;
 								console.warn("[export] audio layer asset unreadable:", asset.originalPath);
 								continue;
 							}
@@ -372,6 +374,9 @@ export function ExportDialog({ open, onClose, document }: ExportDialogProps) {
 								fadeOutMs: region.fadeOutMs,
 							});
 						}
+						if (missingLayerFiles > 0) {
+							toast.warning(t("exportDialog.audioLayerMissingFile", { count: missingLayerFiles }));
+						}
 						if (layerInputs.length > 0) {
 							const exported = await window.electronAPI?.readBinaryFile?.(pickedPath);
 							if (exported?.success && exported.data) {
@@ -386,6 +391,12 @@ export function ExportDialog({ open, onClose, document }: ExportDialogProps) {
 								if (!write?.success) {
 									throw new Error(write?.message ?? t("exportDialog.exportFailed"));
 								}
+							} else {
+								// The export itself succeeded; only the layer mix could
+								// not run. The video must not silently lose its audio.
+								toast.warning(t("exportDialog.audioLayersSkipped"), {
+									description: exported?.message,
+								});
 							}
 						}
 					}
diff --git a/src/components/ai-edition/v4/AddAudioLayerDialog.tsx b/src/components/ai-edition/v4/AddAudioLayerDialog.tsx
index edd090d85..a1b71b55b 100644
--- a/src/components/ai-edition/v4/AddAudioLayerDialog.tsx
+++ b/src/components/ai-edition/v4/AddAudioLayerDialog.tsx
@@ -214,14 +214,27 @@ export function AddAudioLayerDialog({
 		}
 	}, [recording, elapsedSec, maxDurationSec, stopRecording]);
 
+	// Re-entrancy guard: the auto-open effect below re-runs whenever the shell
+	// re-renders (it passes an inline `onComplete`, and the shell re-renders on
+	// every playhead tick during playback), so without this a music dialog left
+	// open while the video plays would re-invoke the native picker on each
+	// render — stacking showOpenDialog calls and, eventually, duplicate layers.
+	const pickerOpenRef = useRef(false);
+
 	const importFile = useCallback(async () => {
-		const picker = await window.electronAPI?.openAudioFilePicker?.();
-		if (!picker?.success || !picker.path) return;
-		const url = toFileUrl(picker.path);
-		// The probe needs the real duration to size the layer; when it fails the
-		// caller falls back to the default span.
-		const duration = (await probeAudioDuration(url)) ?? 0;
-		await finishWithPath(picker.path, duration);
+		if (pickerOpenRef.current) return;
+		pickerOpenRef.current = true;
+		try {
+			const picker = await window.electronAPI?.openAudioFilePicker?.();
+			if (!picker?.success || !picker.path) return;
+			const url = toFileUrl(picker.path);
+			// The probe needs the real duration to size the layer; when it fails the
+			// caller falls back to the default span.
+			const duration = (await probeAudioDuration(url)) ?? 0;
+			await finishWithPath(picker.path, duration);
+		} finally {
+			pickerOpenRef.current = false;
+		}
 	}, [finishWithPath]);
 
 	// Music has nothing to record — open the picker as soon as the dialog is up.
diff --git a/src/components/ai-edition/v4/FloatingInspector.tsx b/src/components/ai-edition/v4/FloatingInspector.tsx
index f7ed7804f..d2d906301 100644
--- a/src/components/ai-edition/v4/FloatingInspector.tsx
+++ b/src/components/ai-edition/v4/FloatingInspector.tsx
@@ -458,6 +458,22 @@ function AudioRegionControls({ region, tl }: { region: AxcutAudioRegion; tl: Tim
 	const [fadeInDraft, setFadeInDraft] = useState(region.fadeInMs / 1000);
 	const [fadeOutDraft, setFadeOutDraft] = useState(region.fadeOutMs / 1000);
 
+	// An edit from OUTSIDE this pane (undo/redo, an agent write) changes the
+	// region while the controls stay mounted — the drafts must follow it, or
+	// the sliders keep showing (and committing) the stale values.
+	useEffect(() => {
+		setGainDraft(region.gainDb);
+	}, [region.gainDb]);
+	useEffect(() => {
+		setOffsetDraft(region.offsetMs / 1000);
+	}, [region.offsetMs]);
+	useEffect(() => {
+		setFadeInDraft(region.fadeInMs / 1000);
+	}, [region.fadeInMs]);
+	useEffect(() => {
+		setFadeOutDraft(region.fadeOutMs / 1000);
+	}, [region.fadeOutMs]);
+
 	return (
 		<>
 			<SliderCell
diff --git a/src/i18n/locales/ar/editor.json b/src/i18n/locales/ar/editor.json
index 3bfe76664..a9be8f8ee 100644
--- a/src/i18n/locales/ar/editor.json
+++ b/src/i18n/locales/ar/editor.json
@@ -197,7 +197,9 @@
 		"failedToWriteFile": "فشلت كتابة الملف",
 		"qualityUpscaleWarning": "تكبير الدقة",
 		"exportedVideoOf": "من الفيديو تم تصديره في",
-		"nothingToExport": "لا يوجد شيء للتصدير — المخطط الزمني فارغ."
+		"nothingToExport": "لا يوجد شيء للتصدير — المخطط الزمني فارغ.",
+		"audioLayersSkipped": "تم تصدير الفيديو بدون طبقات الصوت — تعذرت قراءة الملف المُصدَّر للمزج",
+		"audioLayerMissingFile": "تم تخطي {{count}} طبقة صوت: تعذرت قراءة ملفها"
 	},
 	"inspector": {
 		"resetFocusPoint": "إعادة تعيين نقطة التركيز",
diff --git a/src/i18n/locales/en/editor.json b/src/i18n/locales/en/editor.json
index 4c3dd14c3..5517d2794 100644
--- a/src/i18n/locales/en/editor.json
+++ b/src/i18n/locales/en/editor.json
@@ -197,7 +197,9 @@
 		"exportFailed": "Export failed",
 		"failedToWriteFile": "Failed to write file",
 		"qualityUpscaleWarning": "Upscale",
-		"nothingToExport": "Nothing to export — the timeline is empty."
+		"nothingToExport": "Nothing to export — the timeline is empty.",
+		"audioLayersSkipped": "Video exported without audio layers — the exported file could not be read back for mixing",
+		"audioLayerMissingFile": "{{count}} audio layer(s) skipped: file could not be read"
 	},
 	"inspector": {
 		"resetFocusPoint": "Reset focus point",
diff --git a/src/i18n/locales/es/editor.json b/src/i18n/locales/es/editor.json
index e2ef21429..1aa5995c2 100644
--- a/src/i18n/locales/es/editor.json
+++ b/src/i18n/locales/es/editor.json
@@ -197,7 +197,9 @@
 		"failedToWriteFile": "No se pudo escribir el archivo",
 		"qualityUpscaleWarning": "Upscaling",
 		"exportedVideoOf": "de vídeo exportado en",
-		"nothingToExport": "Nada que exportar: la línea de tiempo está vacía."
+		"nothingToExport": "Nada que exportar: la línea de tiempo está vacía.",
+		"audioLayersSkipped": "Vídeo exportado sin capas de audio — no se pudo volver a leer el archivo exportado para mezclarlo",
+		"audioLayerMissingFile": "{{count}} capa(s) de audio omitidas: no se pudo leer el archivo"
 	},
 	"inspector": {
 		"resetFocusPoint": "Restablecer punto de enfoque",
diff --git a/src/i18n/locales/fr/editor.json b/src/i18n/locales/fr/editor.json
index 61694c0d2..4f7647c65 100644
--- a/src/i18n/locales/fr/editor.json
+++ b/src/i18n/locales/fr/editor.json
@@ -197,7 +197,9 @@
 		"exportFailed": "Échec de l'export",
 		"failedToWriteFile": "Échec de l'écriture du fichier",
 		"qualityUpscaleWarning": "Upscaling",
-		"nothingToExport": "Rien à exporter — la timeline est vide."
+		"nothingToExport": "Rien à exporter — la timeline est vide.",
+		"audioLayersSkipped": "Vidéo exportée sans les couches audio — le fichier exporté n'a pas pu être relu pour le mixage",
+		"audioLayerMissingFile": "{{count}} couche(s) audio ignorée(s) : fichier illisible"
 	},
 	"inspector": {
 		"resetFocusPoint": "Réinitialiser le point de focus",
diff --git a/src/i18n/locales/it/editor.json b/src/i18n/locales/it/editor.json
index 81603e049..30f35d587 100644
--- a/src/i18n/locales/it/editor.json
+++ b/src/i18n/locales/it/editor.json
@@ -197,7 +197,9 @@
 		"failedToWriteFile": "Impossibile scrivere il file",
 		"qualityUpscaleWarning": "Upscaling",
 		"exportedVideoOf": "di video esportato in",
-		"nothingToExport": "Niente da esportare: la timeline è vuota."
+		"nothingToExport": "Niente da esportare: la timeline è vuota.",
+		"audioLayersSkipped": "Video esportato senza i livelli audio — impossibile rileggere il file esportato per il mix",
+		"audioLayerMissingFile": "{{count}} livello(i) audio saltati: file non leggibile"
 	},
 	"inspector": {
 		"resetFocusPoint": "Reimposta punto di messa a fuoco",
diff --git a/src/i18n/locales/ja-JP/editor.json b/src/i18n/locales/ja-JP/editor.json
index d053b2fb3..11dcbbd40 100644
--- a/src/i18n/locales/ja-JP/editor.json
+++ b/src/i18n/locales/ja-JP/editor.json
@@ -197,7 +197,9 @@
 		"failedToWriteFile": "ファイルの書き込みに失敗しました",
 		"qualityUpscaleWarning": "アップスケール",
 		"exportedVideoOf": "の動画を書き出しました。所要時間:",
-		"nothingToExport": "書き出す内容がありません — タイムラインが空です。"
+		"nothingToExport": "書き出す内容がありません — タイムラインが空です。",
+		"audioLayersSkipped": "音声レイヤーなしで書き出されました — 書き出したファイルを読み戻せず、ミックスできませんでした",
+		"audioLayerMissingFile": "音声レイヤーを {{count}} 件スキップ：ファイルを読み込めませんでした"
 	},
 	"inspector": {
 		"resetFocusPoint": "フォーカスポイントをリセット",
diff --git a/src/i18n/locales/ko-KR/editor.json b/src/i18n/locales/ko-KR/editor.json
index c45d8d74b..8af2f8508 100644
--- a/src/i18n/locales/ko-KR/editor.json
+++ b/src/i18n/locales/ko-KR/editor.json
@@ -197,7 +197,9 @@
 		"failedToWriteFile": "파일 쓰기에 실패했습니다",
 		"qualityUpscaleWarning": "업스케일",
 		"exportedVideoOf": "분량의 영상을 내보냈습니다. 소요 시간:",
-		"nothingToExport": "내보낼 항목이 없습니다 — 타임라인이 비어 있습니다."
+		"nothingToExport": "내보낼 항목이 없습니다 — 타임라인이 비어 있습니다.",
+		"audioLayersSkipped": "오디오 레이어 없이 내보냈습니다 — 내보낸 파일을 다시 읽을 수 없어 믹스하지 못했습니다",
+		"audioLayerMissingFile": "오디오 레이어 {{count}}개 건너뜀: 파일을 읽을 수 없습니다"
 	},
 	"inspector": {
 		"resetFocusPoint": "포커스 지점 재설정",
diff --git a/src/i18n/locales/pt-BR/editor.json b/src/i18n/locales/pt-BR/editor.json
index 5551edf96..e23a95b41 100644
--- a/src/i18n/locales/pt-BR/editor.json
+++ b/src/i18n/locales/pt-BR/editor.json
@@ -197,7 +197,9 @@
 		"failedToWriteFile": "Falha ao gravar o arquivo",
 		"qualityUpscaleWarning": "Upscaling",
 		"exportedVideoOf": "de vídeo exportado em",
-		"nothingToExport": "Nada para exportar — a linha do tempo está vazia."
+		"nothingToExport": "Nada para exportar — a linha do tempo está vazia.",
+		"audioLayersSkipped": "Vídeo exportado sem as camadas de áudio — não foi possível reler o arquivo exportado para mixar",
+		"audioLayerMissingFile": "{{count}} camada(s) de áudio ignoradas: arquivo não pôde ser lido"
 	},
 	"inspector": {
 		"resetFocusPoint": "Redefinir ponto de foco",
diff --git a/src/i18n/locales/ru/editor.json b/src/i18n/locales/ru/editor.json
index e6eeae171..7be9773eb 100644
--- a/src/i18n/locales/ru/editor.json
+++ b/src/i18n/locales/ru/editor.json
@@ -197,7 +197,9 @@
 		"failedToWriteFile": "Не удалось записать файл",
 		"qualityUpscaleWarning": "Апскейл",
 		"exportedVideoOf": "видео экспортировано за",
-		"nothingToExport": "Нечего экспортировать — таймлайн пуст."
+		"nothingToExport": "Нечего экспортировать — таймлайн пуст.",
+		"audioLayersSkipped": "Видео экспортировано без аудиослоёв — не удалось перечитать экспортированный файл для сведения",
+		"audioLayerMissingFile": "Пропущено аудиослоёв: {{count}} — файл не удалось прочитать"
 	},
 	"inspector": {
 		"resetFocusPoint": "Сбросить точку фокуса",
diff --git a/src/i18n/locales/tr/editor.json b/src/i18n/locales/tr/editor.json
index 555fc7de0..c1935f025 100644
--- a/src/i18n/locales/tr/editor.json
+++ b/src/i18n/locales/tr/editor.json
@@ -197,7 +197,9 @@
 		"failedToWriteFile": "Dosya yazılamadı",
 		"qualityUpscaleWarning": "Upscale",
 		"exportedVideoOf": "video şu sürede dışa aktarıldı:",
-		"nothingToExport": "Dışa aktarılacak bir şey yok — zaman çizelgesi boş."
+		"nothingToExport": "Dışa aktarılacak bir şey yok — zaman çizelgesi boş.",
+		"audioLayersSkipped": "Video ses katmanları olmadan dışa aktarıldı — dışa aktarılan dosya miks için geri okunamadı",
+		"audioLayerMissingFile": "{{count}} ses katmanı atlandı: dosya okunamadı"
 	},
 	"inspector": {
 		"resetFocusPoint": "Odak noktasını sıfırla",
diff --git a/src/i18n/locales/vi/editor.json b/src/i18n/locales/vi/editor.json
index 17db6ec4b..08d5699f3 100644
--- a/src/i18n/locales/vi/editor.json
+++ b/src/i18n/locales/vi/editor.json
@@ -197,7 +197,9 @@
 		"failedToWriteFile": "Không thể ghi tệp",
 		"qualityUpscaleWarning": "Upscale",
 		"exportedVideoOf": "video đã xuất trong",
-		"nothingToExport": "Không có gì để xuất — dòng thời gian trống."
+		"nothingToExport": "Không có gì để xuất — dòng thời gian trống.",
+		"audioLayersSkipped": "Đã xuất video không có lớp âm thanh — không thể đọc lại tệp đã xuất để trộn",
+		"audioLayerMissingFile": "Đã bỏ qua {{count}} lớp âm thanh: không đọc được tệp"
 	},
 	"inspector": {
 		"resetFocusPoint": "Đặt lại điểm lấy nét",
diff --git a/src/i18n/locales/zh-CN/editor.json b/src/i18n/locales/zh-CN/editor.json
index de7e52b55..5254174e9 100644
--- a/src/i18n/locales/zh-CN/editor.json
+++ b/src/i18n/locales/zh-CN/editor.json
@@ -197,7 +197,9 @@
 		"failedToWriteFile": "写入文件失败",
 		"qualityUpscaleWarning": "放大",
 		"exportedVideoOf": "的视频已导出，用时",
-		"nothingToExport": "没有可导出的内容 — 时间轴为空。"
+		"nothingToExport": "没有可导出的内容 — 时间轴为空。",
+		"audioLayersSkipped": "视频已导出但未包含音频图层——无法重新读取导出文件进行混音",
+		"audioLayerMissingFile": "已跳过 {{count}} 个音频图层：无法读取文件"
 	},
 	"inspector": {
 		"resetFocusPoint": "重置焦点",
diff --git a/src/i18n/locales/zh-TW/editor.json b/src/i18n/locales/zh-TW/editor.json
index f567810a5..775342255 100644
--- a/src/i18n/locales/zh-TW/editor.json
+++ b/src/i18n/locales/zh-TW/editor.json
@@ -197,7 +197,9 @@
 		"failedToWriteFile": "寫入檔案失敗",
 		"qualityUpscaleWarning": "放大",
 		"exportedVideoOf": "的影片已匯出，耗時",
-		"nothingToExport": "沒有可匯出的內容 — 時間軸為空。"
+		"nothingToExport": "沒有可匯出的內容 — 時間軸為空。",
+		"audioLayersSkipped": "影片已匯出但未包含音訊圖層——無法重新讀取匯出的檔案進行混音",
+		"audioLayerMissingFile": "已略過 {{count}} 個音訊圖層：無法讀取檔案"
 	},
 	"inspector": {
 		"resetFocusPoint": "重設焦點",