diff --git a/docs/remotion-music.md b/docs/remotion-music.md
new file mode 100644
index 0000000000..df3428c0fc
--- /dev/null
+++ b/docs/remotion-music.md
@@ -0,0 +1,74 @@
+# Documented music configuration in Remotion
+
+The templated `render` and direct `remotion_render` operations resolve music
+asset IDs using `asset_manifest`, stage local audio, and send a playable `src`
+to both CinematicRenderer and Explainer. Example:
+
+```json
+{
+  "audio": {
+    "music": {
+      "asset_id": "music-bed",
+      "volume": 0.25,
+      "fade_in_seconds": 1,
+      "fade_out_seconds": 2
+    }
+  }
+}
+```
+
+The manifest entry for `music-bed` must contain a non-empty `path`. Explicit
+asset IDs are authoritative: an unknown ID is an error, even if a `src` is also
+provided. Missing local files fail before launching the render CLI. Filesystem
+paths, file URIs, and paths relative to the active Remotion public directory
+are supported; HTTP(S)/data sources pass through to Remotion without a Python
+network fetch. This adapter does not validate remote availability.
+
+Legacy top-level `music` and direct `src`/`source`/`path` inputs remain supported.
+When both locations exist, `audio.music` wins. An explicit empty object or null
+canonical block disables legacy music. Snake-case fade keys override camelCase
+aliases. Volume must be finite and within 0–1; timing values must be finite and
+nonnegative. Zero volume means mute; zero fade means no fade. Omitted defaults
+remain composition-specific (music volume 0.15 for CinematicRenderer and 0.1 for
+Explainer; fades 2/3 seconds for both).
+
+Existing narration, captions, scenes and SFX payloads are preserved. This change
+does not add a segmented narration/SFX adapter or dynamic ducking. Existing
+supported narration tracks and pre-mixed SFX remain the way to supply those
+layers. The existing explicit `audio_path` still means an approved complete mix
+that replaces the rendered audio, including music. Include music in that mix
+when using `audio_path`.
+
+FFmpeg, HyperFrames, and hand-authored atelier routing are unchanged. In
+particular, music is not promoted to FFmpeg's replacement `audio_path` because
+that would discard existing audio and bypass volume/fades. The tool version is
+bumped so cached silent renders from the old version cannot be reused.
+
+## Offline verification
+
+Run the adapter contracts with:
+
+```bash
+python -m pytest -q tests/tools/test_video_compose_music.py
+```
+
+With the existing Node/Remotion dependencies and FFmpeg, run the production
+audio-expression tests and staged-input FFmpeg proof:
+
+```bash
+python -m pytest -q tests/tools/test_remotion_music_envelope.py
+```
+
+These execute the actual JSX audio expressions with supplied hook values, then
+measure a synthetic AAC export made using the staged WAV and those envelopes.
+They are not a full Remotion render. To verify the full browser path on a host
+that permits Chromium, opt into the six additional tests:
+
+```bash
+OPENMONTAGE_TEST_REMOTION=1 REMOTION_TEST_BROWSER=/path/to/chromium \
+  python -m pytest -q tests/tools/test_video_compose_music_render.py
+```
+
+No dependencies are automatically installed. The full-render tests set npm
+offline mode, use only synthetic local inputs, and inspect decoded output with
+FFmpeg. `OPENMONTAGE_MUSIC_EVIDENCE_DIR` optionally saves proof files and metrics.
diff --git a/remotion-composer/src/CinematicRenderer.tsx b/remotion-composer/src/CinematicRenderer.tsx
index 44d9cd0300..8eaf4ac1f1 100644
--- a/remotion-composer/src/CinematicRenderer.tsx
+++ b/remotion-composer/src/CinematicRenderer.tsx
@@ -402,8 +402,8 @@ export const Soundtrack: React.FC<{
   const frame = useCurrentFrame();
   const { durationInFrames, fps } = useVideoConfig();
 
-  const fadeInFrames = Math.max(1, Math.round(fadeInSeconds * fps));
-  const fadeOutFrames = Math.max(1, Math.round(fadeOutSeconds * fps));
+  const fadeInFrames = Math.max(0, Math.round(fadeInSeconds * fps));
+  const fadeOutFrames = Math.max(0, Math.round(fadeOutSeconds * fps));
   const trimBefore =
     trimBeforeSeconds !== undefined
       ? Math.round(trimBeforeSeconds * fps)
@@ -413,19 +413,25 @@ export const Soundtrack: React.FC<{
       ? Math.round(trimAfterSeconds * fps)
       : undefined;
 
-  const fadeIn = interpolate(frame, [0, fadeInFrames], [0, volume], {
-    extrapolateLeft: "clamp",
-    extrapolateRight: "clamp",
-  });
-  const fadeOut = interpolate(
-    frame,
-    [durationInFrames - fadeOutFrames, durationInFrames],
-    [volume, 0],
-    {
-      extrapolateLeft: "clamp",
-      extrapolateRight: "clamp",
-    },
-  );
+  const fadeIn =
+    fadeInFrames === 0
+      ? volume
+      : interpolate(frame, [0, fadeInFrames], [0, volume], {
+          extrapolateLeft: "clamp",
+          extrapolateRight: "clamp",
+        });
+  const fadeOut =
+    fadeOutFrames === 0
+      ? volume
+      : interpolate(
+          frame,
+          [durationInFrames - fadeOutFrames, durationInFrames],
+          [volume, 0],
+          {
+            extrapolateLeft: "clamp",
+            extrapolateRight: "clamp",
+          },
+        );
 
   return (
     <Audio
diff --git a/remotion-composer/src/Explainer.tsx b/remotion-composer/src/Explainer.tsx
index 19e823de57..fff7912dc4 100644
--- a/remotion-composer/src/Explainer.tsx
+++ b/remotion-composer/src/Explainer.tsx
@@ -915,17 +915,21 @@ export const Explainer: React.FC<ExplainerProps> = (props) => {
             const totalFrames = durationInFrames;
 
             // Fade in
-            const fadeIn = interpolate(f, [0, fadeInDur], [0, baseVol], {
-              extrapolateLeft: "clamp",
-              extrapolateRight: "clamp",
-            });
+            const fadeIn = fadeInDur === 0
+              ? baseVol
+              : interpolate(f, [0, fadeInDur], [0, baseVol], {
+                  extrapolateLeft: "clamp",
+                  extrapolateRight: "clamp",
+                });
             // Fade out
-            const fadeOut = interpolate(
-              f,
-              [totalFrames - fadeOutDur, totalFrames],
-              [baseVol, 0],
-              { extrapolateLeft: "clamp", extrapolateRight: "clamp" }
-            );
+            const fadeOut = fadeOutDur === 0
+              ? baseVol
+              : interpolate(
+                  f,
+                  [totalFrames - fadeOutDur, totalFrames],
+                  [baseVol, 0],
+                  { extrapolateLeft: "clamp", extrapolateRight: "clamp" }
+                );
             return Math.min(fadeIn, fadeOut);
           }}
         />
diff --git a/tests/tools/remotion_music_envelope.cjs b/tests/tools/remotion_music_envelope.cjs
new file mode 100644
index 0000000000..af602bd0cd
--- /dev/null
+++ b/tests/tools/remotion_music_envelope.cjs
@@ -0,0 +1,74 @@
+// Execute the actual production JSX audio expressions, without launching a browser.
+// Hook values are supplied by the harness; interpolate and React are real packages.
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+const {createRequire} = require('node:module');
+const composer = path.resolve(__dirname, '../../remotion-composer');
+const localRequire = createRequire(path.join(composer, 'package.json'));
+const ts = localRequire('typescript');
+const React = localRequire('react');
+const {interpolate} = localRequire('remotion');
+
+function source(name) {
+  const filename = path.join(composer, 'src', name);
+  return ts.createSourceFile(filename, fs.readFileSync(filename, 'utf8'),
+    ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+}
+
+function find(tree, predicate) {
+  let match;
+  function walk(node) {
+    if (!match && predicate(node)) match = node;
+    ts.forEachChild(node, walk);
+  }
+  walk(tree);
+  if (!match) throw new Error('Production audio expression was not found');
+  return match;
+}
+
+function evaluate(text, globals) {
+  const js = ts.transpileModule(text, {
+    compilerOptions: {jsx: ts.JsxEmit.React, target: ts.ScriptTarget.ES2020},
+    reportDiagnostics: true,
+  });
+  const errors = (js.diagnostics || []).filter(d => d.category === ts.DiagnosticCategory.Error);
+  if (errors.length) throw new Error(ts.formatDiagnosticsWithColorAndContext(errors, {
+    getCanonicalFileName: f => f, getCurrentDirectory: () => composer, getNewLine: () => '\n',
+  }));
+  return vm.runInNewContext(js.outputText, globals);
+}
+
+const input = JSON.parse(fs.readFileSync(0, 'utf8'));
+const state = {frame: 0};
+const globals = {
+  React, interpolate, Audio: 'Audio', resolveAsset: src => src,
+  useCurrentFrame: () => state.frame,
+  useVideoConfig: () => ({fps: input.fps, durationInFrames: input.frames}),
+};
+let renderAudio;
+if (input.family === 'documentary-montage') {
+  const tree = source('CinematicRenderer.tsx');
+  const soundtrack = find(tree, n => ts.isVariableDeclaration(n) && n.name.getText(tree) === 'Soundtrack');
+  globals.Soundtrack = evaluate(`(${soundtrack.initializer.getText(tree)})`, globals);
+  const musicElement = find(tree, n => ts.isJsxSelfClosingElement(n)
+    && n.tagName.getText(tree) === 'Soundtrack' && n.getText(tree).includes('music.src'));
+  globals.music = input.music;
+  renderAudio = () => globals.Soundtrack(evaluate(`(${musicElement.getText(tree)})`, globals).props);
+} else {
+  const tree = source('Explainer.tsx');
+  const musicElement = find(tree, n => ts.isJsxSelfClosingElement(n)
+    && n.tagName.getText(tree) === 'Audio' && n.getText(tree).includes('audio.music.src'));
+  Object.assign(globals, {audio: {music: input.music}, fps: input.fps, durationInFrames: input.frames});
+  renderAudio = () => evaluate(`(${musicElement.getText(tree)})`, globals);
+}
+const volumes = [];
+let element;
+for (state.frame = 0; state.frame < input.frames; state.frame++) {
+  element = renderAudio();
+  const volume = typeof element.props.volume === 'function'
+    ? element.props.volume(state.frame) : element.props.volume;
+  if (!Number.isFinite(volume)) throw new Error(`Invalid volume at frame ${state.frame}`);
+  volumes.push(volume);
+}
+process.stdout.write(JSON.stringify({src: element.props.src, volumes}));
diff --git a/tests/tools/test_remotion_music_envelope.py b/tests/tools/test_remotion_music_envelope.py
new file mode 100644
index 0000000000..f89cb4e12d
--- /dev/null
+++ b/tests/tools/test_remotion_music_envelope.py
@@ -0,0 +1,163 @@
+"""Execute production audio curves and a staged-input FFmpeg proof, offline.
+
+The FFmpeg proof exercises the Python adapter/staging and actual JSX envelopes.
+It is NOT a full Remotion video render; that separate opt-in suite needs a
+working browser. It must never be reported as end-to-end Remotion evidence.
+"""
+
+import array
+import json
+import math
+import os
+import shutil
+import subprocess
+import wave
+from pathlib import Path
+
+import pytest
+
+from tools.video.video_compose import VideoCompose
+
+
+ROOT = Path(__file__).resolve().parents[2]
+HELPER = Path(__file__).with_name("remotion_music_envelope.cjs")
+NODE_READY = shutil.which("node") and (ROOT / "remotion-composer/node_modules/typescript").is_dir()
+pytestmark = pytest.mark.skipif(not NODE_READY, reason="existing Node/Remotion packages required; no auto-install")
+
+
+def envelope(family, music):
+    process = subprocess.run(
+        ["node", str(HELPER)], input=json.dumps({"family": family, "music": music, "fps": 30, "frames": 120}),
+        text=True, capture_output=True, timeout=30,
+    )
+    assert process.returncode == 0, process.stderr
+    return json.loads(process.stdout)
+
+
+@pytest.mark.parametrize("family", ["documentary-montage", "explainer-data"])
+@pytest.mark.parametrize("volume,fade_in,fade_out", [(0.5, 1, 1), (0.25, 0, 0), (0, 0, 0), (1, 0, 1), (1, 1, 0), (0.4, 4, 4)])
+def test_actual_renderer_volume_and_fade_expressions(family, volume, fade_in, fade_out):
+    values = envelope(family, {"src": "bed.wav", "volume": volume,
+                              "fadeInSeconds": fade_in, "fadeOutSeconds": fade_out})["volumes"]
+    assert all(math.isfinite(v) and 0 <= v <= volume for v in values)
+    assert values[0] == (0 if fade_in else volume)
+    assert values[15] == pytest.approx(volume * min(1, 0.5 / fade_in if fade_in else 1,
+                                                 3.5 / fade_out if fade_out else 1))
+    assert values[60] == pytest.approx(volume * min(1, 2 / fade_in if fade_in else 1,
+                                                 2 / fade_out if fade_out else 1))
+    assert values[105] == pytest.approx(volume * min(1, 3.5 / fade_in if fade_in else 1,
+                                                  0.5 / fade_out if fade_out else 1))
+
+
+@pytest.mark.parametrize("family,default", [("documentary-montage", 0.15), ("explainer-data", 0.1)])
+def test_actual_renderer_defaults_stay_unchanged(family, default):
+    values = envelope(family, {"src": "bed.wav", "fadeInSeconds": 0, "fadeOutSeconds": 0})["volumes"]
+    assert values == [default] * 120
+
+
+def tone(path, frequencies):
+    samples = array.array("h", (
+        round(32767 * sum(0.1 * math.sin(2 * math.pi * f * i / 48000) for f in frequencies))
+        for i in range(4 * 48000)
+    ))
+    with wave.open(str(path), "wb") as output:
+        output.setnchannels(1)
+        output.setsampwidth(2)
+        output.setframerate(48000)
+        output.writeframes(samples.tobytes())
+
+
+def frequency_amplitude(samples, frequency, start, end):
+    values = samples[round(start * 48000):round(end * 48000)]
+    step = 2 * math.pi * frequency / 48000
+    real = sum(v * math.cos(step * i) for i, v in enumerate(values))
+    imaginary = sum(v * math.sin(step * i) for i, v in enumerate(values))
+    return 2 * math.hypot(real, imaginary) / len(values)
+
+
+@pytest.mark.skipif(not shutil.which("ffmpeg") or not shutil.which("ffprobe"), reason="local FFmpeg required")
+@pytest.mark.parametrize("family", ["documentary-montage", "explainer-data"])
+def test_ffmpeg_proof_uses_staged_source_and_production_envelope(tmp_path, monkeypatch, family):
+    monkeypatch.setenv("OPENMONTAGE_ASSET_CACHE", "0")
+    monkeypatch.setattr(VideoCompose, "_remotion_available", lambda self: True)
+    music_path = tmp_path / "music.wav"
+    tone(music_path, [880])
+    output = tmp_path / "adapter-only.mp4"
+    proof = tmp_path / f"ffmpeg-staged-{family}.mp4"
+    captured = {}
+
+    def capture(self, command, **kwargs):
+        # Substitute only the CLI for inspection; never pretend this is a render.
+        props_path = Path(next(x.split("=", 1)[1] for x in command if x.startswith("--props=")))
+        public_dir = Path(next(x.split("=", 1)[1] for x in command if x.startswith("--public-dir=")))
+        props = json.loads(props_path.read_text())
+        music = props["music"] if family == "documentary-montage" else props["audio"]["music"]
+        captured["music"] = music
+        shutil.copy2(public_dir / music["src"], tmp_path / "staged.wav")
+        output.write_bytes(b"stub: not video")
+
+    monkeypatch.setattr(VideoCompose, "run_command", capture)
+    config = {"asset_id": "bed", "volume": 0.5, "fade_in_seconds": 1, "fade_out_seconds": 1}
+    result = VideoCompose()._remotion_render({
+        "output_path": str(output),
+        "edit_decisions": {"renderer_family": family, "audio": {"music": config},
+                           "cuts": [{"id": "t", "type": "text_card", "text": "Audio test",
+                                     "source": "", "in_seconds": 0, "out_seconds": 4}]},
+        "asset_manifest": {"assets": [{"id": "bed", "path": str(music_path)}]},
+    })
+    assert result.success, result.error
+    assert result.data["staged_media_count"] == 1
+    curve = envelope(family, captured["music"])["volumes"]
+    with wave.open(str(tmp_path / "staged.wav"), "rb") as source:
+        music_samples = array.array("h")
+        music_samples.frombytes(source.readframes(source.getnframes()))
+    # Sample the actual JSX envelope at each video frame. The extra frequencies
+    # are synthetic stand-ins for an existing narration/SFX mix, not speech.
+    mixed = array.array("h", (
+        round(value * curve[min(i // 1600, 119)]
+              + 32767 * 0.06 * math.sin(2 * math.pi * 220 * i / 48000)
+              + 32767 * 0.06 * math.sin(2 * math.pi * 440 * i / 48000))
+        for i, value in enumerate(music_samples)
+    ))
+    with wave.open(str(tmp_path / "mix.wav"), "wb") as dest:
+        dest.setnchannels(1)
+        dest.setsampwidth(2)
+        dest.setframerate(48000)
+        dest.writeframes(mixed.tobytes())
+    subprocess.run(["ffmpeg", "-v", "error", "-y", "-f", "lavfi", "-i",
+                    "testsrc2=duration=4:size=640x360:rate=30", "-i", str(tmp_path / "mix.wav"),
+                    "-c:v", "libx264", "-pix_fmt", "yuv420p", "-c:a", "aac",
+                    "-b:a", "192k", "-shortest", "-movflags", "+faststart", str(proof)],
+                   check=True, capture_output=True, timeout=30)
+    probe = json.loads(subprocess.check_output(["ffprobe", "-v", "error", "-show_streams",
+                                               "-show_format", "-of", "json", str(proof)]))
+    assert any(s["codec_name"] == "aac" for s in probe["streams"])
+    assert abs(float(probe["format"]["duration"]) - 4) < 0.1
+    raw = subprocess.check_output(["ffmpeg", "-v", "error", "-i", str(proof), "-vn",
+                                   "-ac", "1", "-ar", "48000", "-f", "f32le", "-"])
+    decoded = array.array("f")
+    decoded.frombytes(raw)
+    levels = {"early": frequency_amplitude(decoded, 880, 0.05, 0.25),
+              "middle": frequency_amplitude(decoded, 880, 1.5, 2.5),
+              "late": frequency_amplitude(decoded, 880, 3.75, 3.95)}
+    assert levels["middle"] == pytest.approx(0.05, rel=0.1)
+    assert 0.03 < levels["early"] / levels["middle"] < 0.3
+    assert 0.03 < levels["late"] / levels["middle"] < 0.3
+    other = {str(f): frequency_amplitude(decoded, f, 1.5, 2.5) for f in (220, 440)}
+    assert all(v == pytest.approx(0.06, rel=0.1) for v in other.values())
+    volume_run = subprocess.run(["ffmpeg", "-hide_banner", "-i", str(proof), "-af",
+                                 "volumedetect", "-f", "null", "-"], capture_output=True, text=True, timeout=30)
+    assert volume_run.returncode == 0
+    evidence = os.environ.get("OPENMONTAGE_MUSIC_EVIDENCE_DIR")
+    if evidence:
+        destination = Path(evidence)
+        destination.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(proof, destination / proof.name)
+        metrics = {"test_type": "FFmpeg proof from staged source + production JSX envelope; NOT a Remotion render",
+                   "family": family, "music_frequency_hz": 880, "music_amplitudes": levels,
+                   "other_tone_amplitudes": other, "duration_seconds": probe["format"]["duration"],
+                   "volume_detect": [line for line in volume_run.stderr.splitlines() if "_volume:" in line]}
+        (destination / f"{proof.stem}.json").write_text(json.dumps(metrics, indent=2))
+        subprocess.run(["ffmpeg", "-v", "error", "-y", "-ss", "2", "-i", str(proof),
+                        "-frames:v", "1", str(destination / f"{proof.stem}.png")],
+                       check=True, capture_output=True, timeout=30)
diff --git a/tests/tools/test_video_compose_music.py b/tests/tools/test_video_compose_music.py
new file mode 100644
index 0000000000..77dd9349e9
--- /dev/null
+++ b/tests/tools/test_video_compose_music.py
@@ -0,0 +1,260 @@
+"""Offline contracts for documented Remotion music (issue #937).
+
+CLI execution is stubbed here; real decoded-audio tests live in
+test_video_compose_music_render.py. No provider discovery or API calls.
+"""
+
+import copy
+import json
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from tools.video.video_compose import VideoCompose
+
+
+@pytest.fixture
+def capture_render(monkeypatch):
+    captured = {}
+    monkeypatch.setenv("OPENMONTAGE_ASSET_CACHE", "0")
+    monkeypatch.setattr(VideoCompose, "_remotion_available", lambda self: True)
+    monkeypatch.setattr("tools.video.video_compose.shutil.which", lambda name: name)
+    monkeypatch.setattr(VideoCompose, "_run_final_review", lambda *a, **kw: {"status": "pass"})
+
+    def run(self, command, **kwargs):
+        captured["command"] = command
+        props_path = Path(next(a.split("=", 1)[1] for a in command if a.startswith("--props=")))
+        captured["props"] = json.loads(props_path.read_text())
+        public_arg = next((a for a in command if a.startswith("--public-dir=")), None)
+        if public_arg:
+            public_dir = Path(public_arg.split("=", 1)[1])
+            captured["public_dir"] = public_dir
+            captured["files"] = {p.name: p.read_bytes() for p in public_dir.rglob("*") if p.is_file()}
+        Path(command[5]).write_bytes(b"mock render, not audiovisual evidence")
+
+    monkeypatch.setattr(VideoCompose, "run_command", run)
+    return captured
+
+
+def render_inputs(tmp_path, music, *, legacy=False, family="documentary-montage"):
+    clip = tmp_path / "clip.mp4"
+    clip.write_bytes(b"video")
+    ed = {
+        "renderer_family": family,
+        "render_runtime": "remotion",
+        "cuts": [{"id": "clip", "source": "clip", "in_seconds": 0, "out_seconds": 4}],
+    }
+    if legacy:
+        ed["music"] = music
+    else:
+        ed["audio"] = {"music": music}
+    return {
+        "operation": "render",
+        "output_path": str(tmp_path / "output.mp4"),
+        "edit_decisions": ed,
+        "asset_manifest": {"assets": [{"id": "clip", "path": str(clip)}]},
+    }
+
+
+@pytest.mark.parametrize("legacy", [False, True])
+@pytest.mark.parametrize("family", ["documentary-montage", "explainer-data"])
+def test_music_asset_reaches_both_compositions_and_stages_once(tmp_path, capture_render, legacy, family):
+    bed = tmp_path / "bed with space.wav"
+    bed.write_bytes(b"music")
+    config = {"asset_id": "bed", "volume": 0.35, "fade_in_seconds": 1, "fade_out_seconds": 2}
+    inputs = render_inputs(tmp_path, config, legacy=legacy, family=family)
+    inputs["asset_manifest"]["assets"].append({"id": "bed", "path": str(bed)})
+    original = copy.deepcopy(inputs)
+    result = VideoCompose().execute(inputs)
+    assert result.success, result.error
+    props = capture_render["props"]
+    assert props["music"] == props["audio"]["music"]
+    assert props["music"]["volume"] == 0.35
+    assert props["music"]["fadeInSeconds"] == 1
+    assert props["music"]["fadeOutSeconds"] == 2
+    assert capture_render["files"][props["music"]["src"]] == b"music"
+    assert result.data["staged_media_count"] == 2
+    assert inputs == original
+    assert bed.read_bytes() == b"music"
+    assert not capture_render["public_dir"].exists()
+
+
+@pytest.mark.parametrize("source_key", ["src", "source", "path"])
+@pytest.mark.parametrize("as_uri", [False, True])
+def test_direct_operation_resolves_source_aliases_and_file_uris(tmp_path, capture_render, source_key, as_uri):
+    music = tmp_path / "music with spaces.wav"
+    music.write_bytes(b"audio")
+    inputs = render_inputs(tmp_path, {source_key: music.as_uri() if as_uri else str(music)})
+    inputs["operation"] = "remotion_render"
+    inputs["edit_decisions"]["cuts"][0]["source"] = inputs["asset_manifest"]["assets"][0]["path"]
+    result = VideoCompose().execute(inputs)
+    assert result.success, result.error
+    assert capture_render["files"][capture_render["props"]["music"]["src"]] == b"audio"
+
+
+def test_direct_operation_resolves_manifest_id(tmp_path, capture_render):
+    music = tmp_path / "music.wav"
+    music.write_bytes(b"audio")
+    inputs = render_inputs(tmp_path, {"asset_id": "bed"})
+    inputs["operation"] = "remotion_render"
+    inputs["asset_manifest"]["assets"].append({"id": "bed", "path": str(music)})
+    result = VideoCompose().execute(inputs)
+    assert result.success, result.error
+    assert capture_render["files"][capture_render["props"]["music"]["src"]] == b"audio"
+
+
+@pytest.mark.parametrize("music", [{"asset_id": "absent"}, {"src": "absent.wav"}, {"path": "absent.wav"}])
+def test_missing_music_fails_before_cli(tmp_path, capture_render, music):
+    result = VideoCompose().execute(render_inputs(tmp_path, music))
+    assert not result.success
+    assert "Music" in result.error and ("not found" in result.error)
+    assert "command" not in capture_render
+    assert not (tmp_path / "output.mp4").exists()
+    assert not list(tmp_path.glob(".remotion-public-*"))
+
+
+@pytest.mark.parametrize("path", [None, "", 12])
+def test_manifest_without_valid_path_is_an_error(path):
+    resolved, error = VideoCompose._resolve_music({"audio": {"music": {"asset_id": "bed"}}}, {"bed": {"path": path}})
+    assert resolved is None
+    assert "no valid path" in error
+
+
+def test_unknown_asset_id_cannot_fall_back_to_filename_or_src(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "bed").write_bytes(b"unregistered")
+    resolved, error = VideoCompose._resolve_music({"music": {"asset_id": "bed", "src": "bed"}}, {})
+    assert resolved is None
+    assert "not found in asset_manifest" in error
+
+
+@pytest.mark.parametrize("kind", ["missing", "directory", "missing_file_uri"])
+def test_manifest_path_must_be_a_file(tmp_path, capture_render, kind):
+    path = tmp_path / "bed.wav"
+    if kind == "directory":
+        path.mkdir()
+    source = path.as_uri() if kind == "missing_file_uri" else str(path)
+    inputs = render_inputs(tmp_path, {"asset_id": "bed"})
+    inputs["asset_manifest"]["assets"].append({"id": "bed", "path": source})
+    result = VideoCompose().execute(inputs)
+    assert not result.success and "Music file not found" in result.error
+    assert "command" not in capture_render
+
+
+@pytest.mark.parametrize("value", [0, 0.25, 1])
+def test_valid_volume_including_explicit_mute(value):
+    result, error = VideoCompose._resolve_music({"music": {"src": "bed.wav", "volume": value}}, {})
+    assert error is None and result["volume"] == value
+
+
+@pytest.mark.parametrize("value", [-0.1, 1.1, float("nan"), float("inf"), "quiet", None, True])
+def test_invalid_volume_is_rejected(value):
+    result, error = VideoCompose._resolve_music({"music": {"src": "bed.wav", "volume": value}}, {})
+    assert result is None and "volume" in error
+
+
+@pytest.mark.parametrize("field", ["fade_in_seconds", "fade_out_seconds", "fadeInSeconds", "fadeOutSeconds"])
+@pytest.mark.parametrize("value", [-1, float("nan"), "one", None])
+def test_invalid_fades_are_rejected(field, value):
+    result, error = VideoCompose._resolve_music({"music": {"src": "bed.wav", field: value}}, {})
+    assert result is None and field in error
+
+
+def test_zero_fades_snake_precedence_and_existing_options():
+    config = {"src": "bed.wav", "fade_in_seconds": 0, "fadeInSeconds": 99,
+              "fade_out_seconds": 0, "fadeOutSeconds": 99, "volume": 0,
+              "offsetSeconds": 2, "loop": True, "ducking": False, "custom": "keep"}
+    result, error = VideoCompose._resolve_music({"music": config}, {})
+    assert error is None
+    assert result["fadeInSeconds"] == result["fadeOutSeconds"] == result["volume"] == 0
+    assert result["loop"] is True and result["offsetSeconds"] == 2
+    assert result["ducking"] is False and result["custom"] == "keep"
+    assert config["fadeInSeconds"] == 99
+
+
+def test_omitted_settings_keep_renderer_defaults():
+    result, error = VideoCompose._resolve_music({"music": {"src": "bed.wav"}}, {})
+    assert error is None
+    assert "volume" not in result and "fadeInSeconds" not in result and "fadeOutSeconds" not in result
+
+
+@pytest.mark.parametrize("canonical", [{"src": "canonical.wav"}, {}, None])
+def test_canonical_block_overrides_legacy_even_when_empty(canonical):
+    result, error = VideoCompose._resolve_music({"audio": {"music": canonical}, "music": {"src": "legacy.wav"}}, {})
+    assert error is None
+    assert result == (canonical or None)
+
+
+@pytest.mark.parametrize("music", ["bad", [], 0, False, {"volume": 0.2}, {"asset_id": ""}])
+def test_malformed_configuration_does_not_silently_disappear(music):
+    result, error = VideoCompose._resolve_music({"music": music}, {})
+    assert result is None and error
+
+
+def test_existing_public_relative_music_remains_playable(tmp_path, capture_render):
+    public = tmp_path / "public"
+    (public / "audio").mkdir(parents=True)
+    (public / "audio" / "bed.wav").write_bytes(b"pre-staged")
+    inputs = render_inputs(tmp_path, {"src": "audio/bed.wav"})
+    inputs["public_dir"] = str(public)
+    result = VideoCompose().execute(inputs)
+    assert result.success, result.error
+    assert capture_render["props"]["music"]["src"] == "audio/bed.wav"
+    assert (public / "audio" / "bed.wav").read_bytes() == b"pre-staged"
+
+
+@pytest.mark.parametrize("source", ["https://example.invalid/bed.mp3", "data:audio/wav;base64,AAAA"])
+def test_remote_sources_are_forwarded_without_python_fetch(tmp_path, capture_render, source):
+    result = VideoCompose().execute(render_inputs(tmp_path, {"src": source}))
+    assert result.success, result.error
+    assert capture_render["props"]["music"]["src"] == source
+
+
+def test_preserves_narration_sound_effects_captions_and_video(tmp_path, capture_render):
+    files = {}
+    for name in ("music", "narration", "sfx"):
+        files[name] = tmp_path / f"{name}.wav"
+        files[name].write_bytes(name.encode())
+    inputs = render_inputs(tmp_path, {"src": str(files["music"])})
+    ed = inputs["edit_decisions"]
+    ed["audio"]["narration"] = {"src": str(files["narration"]), "volume": 0.8}
+    ed["audio"]["sfx"] = [{"src": str(files["sfx"]), "start_seconds": 1}]
+    ed["soundtrack"] = {"src": str(files["narration"]), "volume": 0.8}
+    ed["captions"] = {"words": [{"word": "Keep", "startMs": 0, "endMs": 500}]}
+    ed["subtitles"] = {"caption_props": {"fontSize": 40}}
+    original = copy.deepcopy(inputs)
+    result = VideoCompose().execute(inputs)
+    assert result.success, result.error
+    props = capture_render["props"]
+    for field in (props["audio"]["narration"], props["soundtrack"]):
+        assert capture_render["files"][field["src"]] == b"narration"
+        assert field["volume"] == 0.8
+    assert capture_render["files"][props["audio"]["sfx"][0]["src"]] == b"sfx"
+    assert props["captions"] == ed["captions"]
+    assert props["captionProps"] == {"fontSize": 40}
+    assert props["scenes"][0]["durationSeconds"] == 4
+    assert result.data["staged_media_count"] == 4
+    assert inputs == original
+
+
+def test_render_failure_cleans_music_and_keeps_original(tmp_path, capture_render, monkeypatch):
+    music = tmp_path / "music.wav"
+    music.write_bytes(b"keep")
+
+    def fail(*args, **kwargs):
+        raise subprocess.CalledProcessError(1, "remotion", stderr="synthetic failure")
+
+    monkeypatch.setattr(VideoCompose, "run_command", fail)
+    result = VideoCompose().execute(render_inputs(tmp_path, {"src": str(music)}))
+    assert not result.success and "synthetic failure" in result.error
+    assert music.read_bytes() == b"keep"
+    assert not list(tmp_path.glob(".remotion-public-*"))
+    assert not (tmp_path / ".remotion_props.json").exists()
+
+
+def test_cache_does_not_reuse_old_silent_render():
+    current, previous = VideoCompose(), VideoCompose()
+    previous.version = "0.1.0"
+    inputs = {"operation": "render", "edit_decisions": {"audio": {"music": {"asset_id": "bed"}}}}
+    assert current.cache_key(inputs) != previous.cache_key(inputs)
diff --git a/tests/tools/test_video_compose_music_render.py b/tests/tools/test_video_compose_music_render.py
new file mode 100644
index 0000000000..5e54c0ee06
--- /dev/null
+++ b/tests/tools/test_video_compose_music_render.py
@@ -0,0 +1,160 @@
+"""Opt-in, entirely local Remotion + FFmpeg integration tests.
+
+Run with OPENMONTAGE_TEST_REMOTION=1 and REMOTION_TEST_BROWSER set to an
+already installed Chromium executable. Uses the existing node_modules only;
+npm offline mode prevents dependency downloads. Synthetic WAVs are free.
+"""
+
+import array
+import json
+import math
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from lib.media_profiles import ALL_PROFILES, AspectRatio, MediaProfile
+from tools.video.video_compose import VideoCompose
+
+
+pytestmark = pytest.mark.skipif(
+    os.environ.get("OPENMONTAGE_TEST_REMOTION") != "1",
+    reason="opt-in local render: set OPENMONTAGE_TEST_REMOTION=1",
+)
+
+
+def run(command):
+    return subprocess.run(command, check=True, capture_output=True, timeout=60)
+
+
+def decode(path):
+    raw = run(["ffmpeg", "-v", "error", "-i", str(path), "-vn", "-ac", "1",
+               "-ar", "48000", "-f", "f32le", "-"]).stdout
+    samples = array.array("f")
+    samples.frombytes(raw)
+    return samples
+
+
+def amplitude(samples, frequency, start, end):
+    window = samples[round(start * 48000):round(end * 48000)]
+    step = 2 * math.pi * frequency / 48000
+    real = sum(value * math.cos(step * i) for i, value in enumerate(window))
+    imag = sum(value * math.sin(step * i) for i, value in enumerate(window))
+    return 2 * math.hypot(real, imag) / len(window)
+
+
+@pytest.fixture(scope="module")
+def sources(tmp_path_factory):
+    root = tmp_path_factory.mktemp("music-render")
+    run(["ffmpeg", "-v", "error", "-y", "-f", "lavfi", "-i",
+         "testsrc2=duration=4:size=640x360:rate=30", "-an", "-c:v", "libx264",
+         "-pix_fmt", "yuv420p", str(root / "clip.mp4")])
+    run(["ffmpeg", "-v", "error", "-y", "-f", "lavfi", "-i",
+         "sine=frequency=880:duration=4:sample_rate=48000", str(root / "music.wav")])
+    # Separate frequencies stand in for narration and already-mixed SFX.
+    run(["ffmpeg", "-v", "error", "-y", "-f", "lavfi", "-i",
+         "sine=frequency=220:duration=4:sample_rate=48000", "-f", "lavfi", "-i",
+         "sine=frequency=440:duration=4:sample_rate=48000", "-filter_complex",
+         "amix=inputs=2:normalize=0", str(root / "narration-sfx.wav")])
+    return root
+
+
+@pytest.fixture
+def local_renderer(monkeypatch):
+    browser = os.environ.get("REMOTION_TEST_BROWSER")
+    assert browser and Path(browser).is_file(), "Set REMOTION_TEST_BROWSER to installed Chromium"
+    assert VideoCompose()._remotion_available(), "Existing Remotion node_modules are required"
+    assert shutil.which("ffmpeg") and shutil.which("ffprobe")
+    monkeypatch.setenv("NPM_CONFIG_OFFLINE", "true")
+    monkeypatch.setenv("OPENMONTAGE_ASSET_CACHE", "0")
+    monkeypatch.setitem(ALL_PROFILES, "music-test", MediaProfile(
+        name="music-test", width=640, height=360,
+        aspect_ratio=AspectRatio.LANDSCAPE_16_9, fps=30,
+        codec="libx264", audio_codec="aac", crf=23,
+    ))
+    return browser
+
+
+@pytest.mark.parametrize("family", ["documentary-montage", "explainer-data"])
+@pytest.mark.parametrize("volume,fade,other_audio", [(0.5, 1, True), (0.25, 0, False), (0, 0, False)])
+def test_decoded_music_gain_fades_mute_and_existing_audio(
+    tmp_path, sources, local_renderer, family, volume, fade, other_audio,
+):
+    name = f"{family}-volume-{volume}-fade-{fade}"
+    output = tmp_path / f"{name}.mp4"
+    music = {"asset_id": "bed", "volume": volume,
+             "fade_in_seconds": fade, "fade_out_seconds": fade}
+    ed = {
+        "version": "1.0", "render_runtime": "remotion", "renderer_family": family,
+        "total_duration_seconds": 4,
+        "cuts": [{"id": "c1", "source": "clip", "in_seconds": 0, "out_seconds": 4,
+                  "transition_in": "cut", "transition_out": "cut"}],
+        "audio": {"music": music},
+    }
+    if family == "explainer-data":
+        # Exercise the documented legacy location on the actual Explainer path.
+        ed["music"] = ed["audio"].pop("music")
+    if other_audio:
+        voice = {"src": str(sources / "narration-sfx.wav"), "volume": 0.6,
+                 "fadeInSeconds": 0, "fadeOutSeconds": 0}
+        if family == "documentary-montage":
+            ed["soundtrack"] = voice
+            ed["captions"] = {"words": [{"word": "AUDIO CHECK", "startMs": 0, "endMs": 4000}], "fontSize": 24}
+        else:
+            ed["audio"]["narration"] = voice
+            ed["captions"] = [{"word": "AUDIO CHECK", "startMs": 0, "endMs": 4000}]
+            ed["captionStyle"] = {"fontSize": 24}
+    manifest = {"assets": [{"id": "clip", "path": str(sources / "clip.mp4")},
+                           {"id": "bed", "path": str(sources / "music.wav")}]}
+    result = VideoCompose().execute({
+        "operation": "render", "edit_decisions": ed, "asset_manifest": manifest,
+        "output_path": str(output), "profile": "music-test",
+        "remotion_browser_executable": local_renderer, "remotion_concurrency": 1,
+        "remotion_timeout_ms": 60000,
+    })
+    assert result.success, result.error
+    assert result.data["staged_media_count"] == (3 if other_audio else 2)
+    probe = json.loads(run(["ffprobe", "-v", "error", "-show_streams", "-show_format",
+                            "-of", "json", str(output)]).stdout)
+    assert any(s["codec_name"] == "aac" for s in probe["streams"])
+    video = next(s for s in probe["streams"] if s["codec_type"] == "video")
+    assert video["width"] == 640 and video["height"] == 360
+    assert abs(float(probe["format"]["duration"]) - 4) < 0.1
+    samples = decode(output)
+    reference = amplitude(decode(sources / "music.wav"), 880, 1.5, 2.5)
+    levels = {"early": amplitude(samples, 880, 0.05, 0.25),
+              "middle": amplitude(samples, 880, 1.5, 2.5),
+              "late": amplitude(samples, 880, 3.75, 3.95)}
+    metrics = {"name": name, "music_amplitude": levels, "reference_amplitude": reference,
+               "expected_volume": volume, "duration": probe["format"]["duration"],
+               "codec": "aac", "final_review": result.data["final_review"],
+               "other_audio_amplitude": {str(f): amplitude(samples, f, 1.5, 2.5) for f in (220, 440)}}
+    evidence = os.environ.get("OPENMONTAGE_MUSIC_EVIDENCE_DIR")
+    if evidence:
+        destination = Path(evidence)
+        destination.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(output, destination / output.name)
+        (destination / f"{name}.json").write_text(json.dumps(metrics, indent=2))
+        if other_audio:
+            run(["ffmpeg", "-v", "error", "-y", "-ss", "2", "-i", str(output),
+                 "-frames:v", "1", str(destination / f"{name}.png")])
+    if volume:
+        assert levels["middle"] / reference == pytest.approx(volume, rel=0.2)
+        if fade:
+            assert 0.03 < levels["early"] / levels["middle"] < 0.4
+            assert 0.03 < levels["late"] / levels["middle"] < 0.4
+        else:
+            assert levels["early"] / levels["middle"] == pytest.approx(1, rel=0.2)
+            assert levels["late"] / levels["middle"] == pytest.approx(1, rel=0.2)
+    else:
+        assert max(abs(s) for s in samples) < 0.0001
+    if other_audio:
+        for frequency in (220, 440):
+            assert amplitude(samples, frequency, 1.5, 2.5) > 0.03
+    first = run(["ffmpeg", "-v", "error", "-ss", "0.5", "-i", str(output),
+                 "-frames:v", "1", "-f", "md5", "-"]).stdout
+    last = run(["ffmpeg", "-v", "error", "-ss", "3.5", "-i", str(output),
+                "-frames:v", "1", "-f", "md5", "-"]).stdout
+    assert first != last, "moving source video became frozen"
diff --git a/tools/video/video_compose.py b/tools/video/video_compose.py
index d5066e3c2a..e3bb4512aa 100644
--- a/tools/video/video_compose.py
+++ b/tools/video/video_compose.py
@@ -34,6 +34,7 @@
 import json
 import hashlib
 import logging
+import math
 import secrets
 import shutil
 import subprocess
@@ -57,7 +58,7 @@
 
 class VideoCompose(BaseTool):
     name = "video_compose"
-    version = "0.1.0"
+    version = "0.1.1"
     tier = ToolTier.CORE
     capability = "video_post"
     provider = "ffmpeg"
@@ -104,7 +105,7 @@ class VideoCompose(BaseTool):
                 "type": "object",
                 "description": (
                     "Full asset_manifest artifact (required for render). "
-                    "Used to resolve asset IDs in cuts[].source to file paths."
+                    "Resolves cuts[].source and Remotion music asset IDs to file paths."
                 ),
             },
             "proposal_packet": {
@@ -855,6 +856,73 @@ def _cuts_to_cinematic_scenes(cuts: list[dict[str, Any]]) -> list[dict[str, Any]
 
         return scenes
 
+    @staticmethod
+    def _resolve_music(
+        edit_decisions: dict[str, Any],
+        asset_lookup: dict[str, Any],
+    ) -> tuple[dict[str, Any] | None, str | None]:
+        """Adapt documented music to Remotion without changing other audio layers.
+
+        Canonical audio.music takes precedence over legacy top-level music,
+        including an explicit empty/null canonical block. Renderer-specific
+        defaults are retained when volume or fades are omitted.
+        """
+        audio = edit_decisions.get("audio")
+        music = (
+            audio["music"]
+            if isinstance(audio, dict) and "music" in audio
+            else edit_decisions.get("music")
+        )
+        if music is None or music == {}:
+            return None, None
+        if not isinstance(music, dict):
+            return None, "Music configuration must be an object."
+
+        asset_id = music.get("asset_id")
+        if "asset_id" in music:
+            if not isinstance(asset_id, str) or not asset_id.strip():
+                return None, "Music asset_id must be a non-empty string."
+            if asset_id not in asset_lookup:
+                return None, f"Music asset_id {asset_id!r} not found in asset_manifest."
+            source = asset_lookup[asset_id].get("path")
+            if not isinstance(source, str) or not source.strip():
+                return None, f"Music asset_id {asset_id!r} has no valid path in asset_manifest."
+        else:
+            source = music.get("src") or music.get("source") or music.get("path")
+            if not isinstance(source, str) or not source.strip():
+                return None, "Music requires an asset_id or a playable src/source/path."
+
+        resolved = dict(music, src=source)
+        # Keep unknown music options intact. Remove source aliases so staging
+        # cannot copy a stale alias in addition to the selected track.
+        resolved.pop("source", None)
+        resolved.pop("path", None)
+        numeric_fields = (
+            ("volume", "volume"),
+            ("fade_in_seconds", "fadeInSeconds"),
+            ("fade_out_seconds", "fadeOutSeconds"),
+            ("offset_seconds", "offsetSeconds"),
+            ("trim_before_seconds", "trimBeforeSeconds"),
+            ("trim_after_seconds", "trimAfterSeconds"),
+        )
+        for canonical, renderer_key in numeric_fields:
+            key = canonical if canonical in music else renderer_key
+            if key not in music:
+                continue
+            value = music[key]
+            if (
+                isinstance(value, bool)
+                or not isinstance(value, (int, float))
+                or not math.isfinite(value)
+                or value < 0
+                or (canonical == "volume" and value > 1)
+            ):
+                return None, f"Music {key} must be a finite number in " + (
+                    "[0, 1]." if canonical == "volume" else "[0, infinity)."
+                )
+            resolved[renderer_key] = value
+        return resolved, None
+
     @staticmethod
     def _file_uri_to_raw_path(uri: str) -> str:
         """Convert a ``file:`` URI to a raw filesystem path string.
@@ -1715,6 +1783,7 @@ def _render(self, inputs: dict[str, Any]) -> ToolResult:
         if self._needs_remotion(resolved_cuts):
             remotion_inputs: dict[str, Any] = {
                 "edit_decisions": dict(edit_decisions, cuts=resolved_cuts),
+                "asset_manifest": asset_manifest,
                 "output_path": str(output_path),
             }
             if profile:
@@ -2040,6 +2109,21 @@ def _remotion_render(self, inputs: dict[str, Any]) -> ToolResult:
         # Deep-copy props so we don't mutate the original
         props = json.loads(json.dumps(composition_data))
 
+        manifest = inputs.get("asset_manifest") or {}
+        music, music_error = self._resolve_music(
+            props, {asset["id"]: asset for asset in manifest.get("assets", [])}
+        )
+        if music_error:
+            return ToolResult(success=False, error=music_error)
+        if music is not None:
+            # CinematicRenderer reads top-level music; Explainer reads audio.music.
+            props["music"] = music
+            props["audio"] = dict(props.get("audio") or {}, music=music)
+        else:
+            props.pop("music", None)
+            if isinstance(props.get("audio"), dict):
+                props["audio"].pop("music", None)
+
         # Build a custom themeConfig from the playbook's actual colors.
         # This ensures every video gets a unique visual identity derived
         # from its production decisions — not picked from a preset menu.
@@ -2102,6 +2186,16 @@ def _remotion_render(self, inputs: dict[str, Any]) -> ToolResult:
         staged_count = 0
         profile_name = inputs.get("profile")
         try:
+            if music is not None and not music["src"].startswith(("http://", "https://", "data:")):
+                source = music["src"]
+                if source.lower().startswith("file://"):
+                    source = self._file_uri_to_raw_path(source)
+                local_path = Path(source).expanduser()
+                public_root = public_dir if requested_public_dir else composer_dir / "public"
+                if local_path.is_file():
+                    music["src"] = str(local_path.resolve())
+                elif local_path.is_absolute() or not (public_root / source).is_file():
+                    raise ValueError(f"Music file not found: {source}")
             staged_count = self._stage_remotion_media(props, public_dir)
             if not staged_count and cleanup_public_dir:
                 public_dir = None