fix(v0.13.1): restore v2 showreel audio

session: codex-2026-04-24-v0131-audio

What: Add two TTS narration assets and audio tracks to the v2 showreel, resolve relative composition audio paths to file URLs during source compile, and add a BDD regression for preview/export audio.

Why: The desktop preview had visuals but no sound because the showcase JSON contained only visual component tracks, so both preview and export correctly produced silent output. Resolving project-relative audio at compile time keeps JSON portable while giving the preview and export muxer the same concrete audio source.

Co-Authored-By: Claude Opus 4.7

Author: claude

crates/nf-project/src/lib.rs

@@ -7,7 +7,7 @@ use directories::BaseDirs;
 use once_cell::sync::Lazy;
 use regex::Regex;
 use serde::{Deserialize, Serialize};
-use serde_json::{Value, json};
+use serde_json::{json, Value};
 use thiserror::Error;
 
 static SLUG_RE: Lazy<Result<Regex, regex::Error>> =
@@ -79,7 +79,7 @@ pub trait Storage {
     fn load_project(&self, slug: &str) -> Result<Project, ProjectError>;
     fn save_project(&self, project: &Project) -> Result<(), ProjectError>;
     fn load_episode(&self, project_slug: &str, episode_slug: &str)
-    -> Result<Episode, ProjectError>;
+        -> Result<Episode, ProjectError>;
     fn save_episode(&self, project_slug: &str, episode: &Episode) -> Result<(), ProjectError>;
 }
 
@@ -297,7 +297,9 @@ pub fn compile_composition_source(
     let tracks = object
         .get("tracks")
         .and_then(Value::as_array)
-        .ok_or_else(|| ProjectError::ValidationFailed("composition.tracks must be an array".to_string()))?;
+        .ok_or_else(|| {
+            ProjectError::ValidationFailed("composition.tracks must be an array".to_string())
+        })?;
 
     let mut warnings = Vec::new();
     let mut source_tracks = Vec::new();
@@ -349,7 +351,8 @@ pub fn compile_composition_source(
                     components.insert(component_id.to_string(), Value::String(src));
                 }
                 params.insert("component".to_string(), json!(component_id));
-                let mut component_params = track.get("params").cloned().unwrap_or_else(|| json!({}));
+                let mut component_params =
+                    track.get("params").cloned().unwrap_or_else(|| json!({}));
                 if let (Some(target), Some(style)) = (
                     component_params.as_object_mut(),
                     track.get("style").and_then(Value::as_object),
@@ -365,19 +368,25 @@ pub fn compile_composition_source(
                     "style".to_string(),
                     track.get("style").cloned().unwrap_or_else(|| json!({})),
                 );
-                params.insert("track".to_string(), json!({
-                    "id": track_id,
-                    "z": track.get("z").and_then(Value::as_i64).unwrap_or(index as i64),
-                    "kind": kind
-                }));
+                params.insert(
+                    "track".to_string(),
+                    json!({
+                        "id": track_id,
+                        "z": track.get("z").and_then(Value::as_i64).unwrap_or(index as i64),
+                        "kind": kind
+                    }),
+                );
                 has_visual = true;
             }
             "audio" => {
                 let Some(src) = track.get("src").and_then(Value::as_str) else {
                     warnings.push(format!("ignored audio track '{track_id}' without src"));
                     continue;
                 };
-                params.insert("src".to_string(), json!(src));
+                params.insert(
+                    "src".to_string(),
+                    json!(composition_audio_src(storage.root(), project_slug, src)),
+                );
                 copy_number_param(track, &mut params, "from_ms");
                 copy_number_param(track, &mut params, "to_ms");
                 copy_number_param(track, &mut params, "volume");
@@ -806,6 +815,31 @@ fn audio_params(object: &serde_json::Map<String, Value>) -> Option<serde_json::M
     Some(params)
 }
 
+fn composition_audio_src(root: &Path, project_slug: &str, src: &str) -> String {
+    if src.starts_with("file://") || src.starts_with("data:") {
+        return src.to_string();
+    }
+    let path = if Path::new(src).is_absolute() {
+        PathBuf::from(src)
+    } else {
+        root.join(project_slug).join(src)
+    };
+    file_url(&path)
+}
+
+fn file_url(path: &Path) -> String {
+    let mut encoded = String::new();
+    for byte in path.to_string_lossy().as_bytes() {
+        match *byte {
+            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' | b'/' => {
+                encoded.push(char::from(*byte))
+            }
+            other => encoded.push_str(&format!("%{other:02X}")),
+        }
+    }
+    format!("file://{encoded}")
+}
+
 fn copy_string_param(
     source: &serde_json::Map<String, Value>,
     target: &mut serde_json::Map<String, Value>,
@@ -994,7 +1028,11 @@ fn track_time_ms(
         .and_then(|value| value.get("end"))
         .or_else(|| track.get("end"))
         .unwrap_or(&end_default);
-    let start = time_value_ms(Some(start_value), anchors, &format!("track '{track_id}' start"))?;
+    let start = time_value_ms(
+        Some(start_value),
+        anchors,
+        &format!("track '{track_id}' start"),
+    )?;
     let end = time_value_ms(Some(end_value), anchors, &format!("track '{track_id}' end"))?;
     Ok((start.min(duration_ms), end.min(duration_ms)))
 }
@@ -1073,7 +1111,10 @@ fn load_theme_css(root: &Path, project_slug: &str, theme_id: &str) -> Result<Str
         let path = theme_dir.join(file);
         if path.exists() {
             let raw = fs::read_to_string(&path).map_err(|err| {
-                ProjectError::StorageFailed(format!("theme CSS read failed: {}: {err}", path.display()))
+                ProjectError::StorageFailed(format!(
+                    "theme CSS read failed: {}: {err}",
+                    path.display()
+                ))
             })?;
             css.push_str(&raw);
             css.push('\n');
@@ -1117,8 +1158,8 @@ fn copy_number_param(
 #[cfg(test)]
 mod tests {
     use super::{
-        Episode, JsonStorage, Project, Registry, RegistryProject, Storage,
-        compile_composition_source,
+        compile_composition_source, Episode, JsonStorage, Project, Registry, RegistryProject,
+        Storage,
     };
 
     #[test]
@@ -1250,29 +1291,40 @@ mod tests {
                 "component": "html.hero-title",
                 "time": { "start": "in", "end": "out" },
                 "params": { "title": "Hello" }
+            }, {
+                "id": "voice",
+                "kind": "audio",
+                "time": { "start": "in", "end": "out" },
+                "src": "audio/demo.mp3",
+                "volume": 0.8
             }]
         });
 
         let compiled = compile_composition_source(&storage, "demo", &composition)?;
 
         assert_eq!(compiled.source["duration"], 4000);
         assert_eq!(compiled.source["tracks"][0]["kind"], "component");
+        assert_eq!(compiled.source["tracks"][1]["kind"], "audio");
+        assert!(compiled.source["tracks"][1]["clips"][0]["params"]["src"]
+            .as_str()
+            .unwrap_or_default()
+            .starts_with("file://"));
+        assert!(compiled.source["tracks"][1]["clips"][0]["params"]["src"]
+            .as_str()
+            .unwrap_or_default()
+            .ends_with("/demo/audio/demo.mp3"));
         assert_eq!(
             compiled.source["tracks"][0]["clips"][0]["params"]["component"],
             "html.hero-title"
         );
-        assert!(
-            compiled.source["components"]["html.hero-title"]
-                .as_str()
-                .unwrap_or_default()
-                .contains("update")
-        );
-        assert!(
-            compiled.source["theme"]["css"]
-                .as_str()
-                .unwrap_or_default()
-                .contains("--accent")
-        );
+        assert!(compiled.source["components"]["html.hero-title"]
+            .as_str()
+            .unwrap_or_default()
+            .contains("update"));
+        assert!(compiled.source["theme"]["css"]
+            .as_str()
+            .unwrap_or_default()
+            .contains("--accent"));
         cleanup(storage.root())?;
         Ok(())
     }

examples/v2-showcase/audio/showreel-narration-2.mp3

@@ -140,6 +140,28 @@
       "params": {
         "steps": ["JSON", "DOM", "SVG", "Canvas", "Edit", "Export"]
       }
+    },
+    {
+      "id": "voice-intro",
+      "kind": "audio",
+      "time": { "start": "intro", "end": "data" },
+      "src": "audio/showreel-narration.mp3",
+      "volume": 1,
+      "tts": {
+        "voice": "en-US-AriaNeural",
+        "text": "NextFrame V2 showreel. One JSON controls live HTML components, SVG, canvas, editor changes, and final video export."
+      }
+    },
+    {
+      "id": "voice-outro",
+      "kind": "audio",
+      "time": { "start": "data", "end": "out" },
+      "src": "audio/showreel-narration-2.mp3",
+      "volume": 1,
+      "tts": {
+        "voice": "en-US-AriaNeural",
+        "text": "The second half keeps the same JSON timeline alive. You can move tracks in the editor, save the composition, and export the exact same result."
+      }
     }
   ]
 }

examples/v2-showcase/audio/showreel-narration.mp3

@@ -0,0 +1,20 @@
+import { tracks } from "./mock.js";
+
+const root = document.querySelector("#demo");
+
+root.innerHTML = `
+  <section class="stage">
+    <div class="preview">
+      <div class="wave">${Array.from({ length: 24 }, (_, index) => `<i style="--i:${index}"></i>`).join("")}</div>
+    </div>
+    <div class="timeline">
+      ${tracks.map((track) => `
+        <div class="track" aria-label="${track.label}">
+          <div class="clip" style="--left:${track.left};--width:${track.width}"></div>
+        </div>
+      `).join("")}
+    </div>
+    <div class="toast">本轮完成：预览有旁白，导出 MP4 有 AAC 音轨。</div>
+    <div class="progress" aria-hidden="true"></div>
+  </section>
+`;

examples/v2-showcase/compositions/showreel-24s.json

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>V2 Editor Authoring · Preview And Export Audio</title>
+  <link rel="stylesheet" href="./style.css">
+</head>
+<body>
+  <main id="demo" class="app" aria-label="preview and export audio demo"></main>
+  <script type="module" src="./animation.js"></script>
+</body>
+</html>

spec/bdd/v2-editor-authoring/demos/preview-and-export-audio/animation.js

@@ -0,0 +1,5 @@
+export const tracks = [
+  { label: "html/canvas/svg", left: "0%", width: "100%" },
+  { label: "voice-intro", left: "0%", width: "48%" },
+  { label: "voice-outro", left: "48%", width: "52%" },
+];

spec/bdd/v2-editor-authoring/demos/preview-and-export-audio/index.html

@@ -0,0 +1,104 @@
+@import "../../../../design/tokens.css";
+
+html,
+body {
+  margin: 0;
+  min-height: 100%;
+  background: #07080d;
+  color: #f6f7fb;
+  font: 14px/1.45 Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+.app {
+  min-height: 100vh;
+  display: grid;
+  place-items: center;
+}
+
+.stage {
+  width: min(980px, calc(100vw - 48px));
+}
+
+.preview {
+  aspect-ratio: 16 / 9;
+  border: 1px solid rgba(255,255,255,0.16);
+  background: radial-gradient(circle at 30% 28%, rgba(98,245,210,0.2), transparent 32%), #090b10;
+  position: relative;
+  overflow: hidden;
+}
+
+.wave {
+  position: absolute;
+  left: 8%;
+  right: 8%;
+  bottom: 14%;
+  height: 74px;
+  display: grid;
+  grid-template-columns: repeat(24, 1fr);
+  gap: 8px;
+  align-items: end;
+}
+
+.wave i {
+  display: block;
+  background: #62f5d2;
+  height: 18px;
+  animation: pulse 1.2s ease-in-out infinite;
+  animation-delay: calc(var(--i) * -46ms);
+}
+
+.timeline {
+  margin-top: 18px;
+  display: grid;
+  gap: 8px;
+}
+
+.track {
+  height: 34px;
+  border: 1px solid rgba(255,255,255,0.14);
+  background: rgba(255,255,255,0.05);
+  position: relative;
+}
+
+.clip {
+  position: absolute;
+  top: 5px;
+  bottom: 5px;
+  left: var(--left);
+  width: var(--width);
+  background: rgba(98,245,210,0.32);
+  border: 1px solid #62f5d2;
+}
+
+.toast {
+  margin-top: 18px;
+  height: 36px;
+  color: #c8ff5d;
+}
+
+.progress {
+  margin-top: 10px;
+  height: 4px;
+  background: rgba(255,255,255,0.14);
+  overflow: hidden;
+}
+
+.progress::before {
+  content: "";
+  display: block;
+  height: 100%;
+  width: 100%;
+  background: #c8ff5d;
+  transform-origin: left;
+  animation: run 10s linear infinite;
+}
+
+@keyframes pulse {
+  0%, 100% { height: 18px; opacity: 0.45; }
+  50% { height: 74px; opacity: 1; }
+}
+
+@keyframes run {
+  from { transform: scaleX(0); }
+  to { transform: scaleX(1); }
+}

spec/bdd/v2-editor-authoring/demos/preview-and-export-audio/mock.js

@@ -8,10 +8,11 @@
     "edit-params",
     "drag-position",
     "edit-timing",
-    "export-after-save"
+    "export-after-save",
+    "preview-and-export-audio"
   ],
   "completion": {
-    "total": 5,
+    "total": 6,
     "done": 0
   }
 }

spec/bdd/v2-editor-authoring/demos/preview-and-export-audio/style.css

@@ -3,7 +3,7 @@
   "title": "保存后的修改用于最终导出视频",
   "given": "用户已修改 final-title.title 并点击保存，桌面端显示 saved 状态。",
   "when": "用户点击导出按钮并等待进度完成。",
-  "then": "导出完成后出现打开按钮，MP4 抽帧能看到修改后的标题，导出源 track_count 仍是 10。",
+  "then": "导出完成后出现打开按钮，MP4 抽帧能看到修改后的标题，导出源 track_count 仍包含 10 条视觉轨和 2 条音频轨。",
   "human_actions": ["edit final-title title", "click save", "click export", "watch progress", "click open output"],
   "ai_tools": [
     {