From b437da69633194175931ca29bcd73963cc893b6e Mon Sep 17 00:00:00 2001 From: miga-heygen Date: Wed, 16 Sep 2026 13:25:05 +0000 Subject: [PATCH] fix(skills): bake a short edge fade into every faceless-explainer voice clip MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per-frame voice clips are butt-joined back-to-back with zero gap by the cumulative-start layout (adjacent clips touch exactly, by construction), but were mounted with no fade at all — a hard cut at both edges of every line, producing audible word-jumps and abrupt cuts at scene seams. applyVoiceEdgeFade() bakes an ~11ms in/out fade into each voice file before it's mounted, the same way ensureBgmCovers() already bakes BGM's own loop-fade — same ffprobe-then-ffmpeg shape, same extension/codec discipline (explicit PCM output so a .wav-named file is actually WAV). Each edge is capped to half the clip's own duration so a very short clip still fades smoothly instead of going silent for its whole length. Degrades to the untouched clip (with an anomaly note) when ffmpeg/ ffprobe are unavailable, matching ensureBgmCovers()'s own degrade path. Cost: one extra ffprobe + ffmpeg subprocess pair per voice clip, each a fast audio-only pass over a few seconds of speech — negligible next to the render pipeline's own screenshot/encode time. Co-Authored-By: Miguel Ángel --- skills-manifest.json | 2 +- .../scripts/assemble-index.mjs | 57 +++++++- .../scripts/assemble-index.test.mjs | 126 ++++++++++++++++++ 3 files changed, 183 insertions(+), 2 deletions(-) diff --git a/skills-manifest.json b/skills-manifest.json index e411541e93..8b2d4462a9 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -6,7 +6,7 @@ "files": 142 }, "faceless-explainer": { - "hash": "7ff529b85f588ffc", + "hash": "49d84ce2eede2b2e", "files": 24 }, "figma": { diff --git a/skills/faceless-explainer/scripts/assemble-index.mjs b/skills/faceless-explainer/scripts/assemble-index.mjs index 93cefa23a6..d37c393c52 100644 --- a/skills/faceless-explainer/scripts/assemble-index.mjs +++ b/skills/faceless-explainer/scripts/assemble-index.mjs @@ -123,6 +123,54 @@ function ensureBgmCovers(relPath, hyperframesDir, total) { return { looped: true, rel: relOut, from: dur }; } +// Voice clips are butt-joined back-to-back with zero gap by the cumulative-start +// layout below (see "cumulative starts" comment) — by construction, with no edge +// fade at all, so consecutive lines cut/word-jump at the join. Bake a short in/out +// fade into each voice file itself, the same way ensureBgmCovers() bakes BGM's +// loop-fade, into a sibling *.faded.wav; mounting still just points +// data-start/duration at the same slot, only the audio content changes. Needs +// ffprobe+ffmpeg (present in the render env); degrades to the original file + an +// anomaly note when they're absent, matching ensureBgmCovers()'s degrade path. +const VOICE_FADE_SECONDS = 0.011; +function applyVoiceEdgeFade(relPath, hyperframesDir) { + const abs = join(hyperframesDir, relPath); + const probe = spawnSync( + "ffprobe", + ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", "--", abs], + { encoding: "utf8" }, + ); + if (probe.status !== 0) return { faded: false, reason: "ffprobe unavailable" }; + const dur = parseFloat(String(probe.stdout || "").trim()); + if (!Number.isFinite(dur) || dur <= 0) return { faded: false, reason: "unreadable duration" }; + // Each edge gets at most half the clip (dur is already confirmed > 0 above, + // so this is always > 0 too), so a clip shorter than 2 fade windows fades + // smoothly in and out instead of being silent for its entire length. + const fade = Math.min(VOICE_FADE_SECONDS, dur / 2); + // Always emit .wav via an explicit PCM codec, matching ensureBgmCovers()'s own + // extension/codec discipline just above — the contract's voice files are + // "assets/voice/NN.wav", so the output must actually be WAV, not smuggle a + // different container in a .wav-named file. + const relOut = relPath.replace(/\.([^./]+)$/, ".faded.wav"); + const absOut = join(hyperframesDir, relOut); + const fadeOutStart = Math.max(0, dur - fade); + const ff = spawnSync( + "ffmpeg", + [ + "-y", + "-i", + abs, + "-af", + `afade=t=in:st=0:d=${fade},afade=t=out:st=${fadeOutStart}:d=${fade}`, + "-c:a", + "pcm_s16le", + absOut, + ], + { encoding: "utf8" }, + ); + if (ff.status !== 0 || !existsSync(absOut)) return { faded: false, reason: "ffmpeg unavailable" }; + return { faded: true, rel: relOut }; +} + const hyperframesDir = resolve(flag("hyperframes", ".")); const storyboardPath = resolve(flag("storyboard", join(hyperframesDir, "STORYBOARD.md"))); const audioMetaPath = resolve(flag("audio-meta", join(hyperframesDir, "audio_meta.json"))); @@ -394,10 +442,17 @@ for (const m of mounted) { const v = m.frame.number != null ? voiceByFrame.get(m.frame.number) : undefined; if (v?.path) { if (existsSync(join(hyperframesDir, v.path))) { + let voiceSrc = v.path; + const fade = applyVoiceEdgeFade(v.path, hyperframesDir); + if (fade.faded) { + voiceSrc = fade.rel; + } else { + anomalies.push(`${m.compId}: voice edge fade skipped (${fade.reason}) — using raw clip`); + } body.push( ` 0, `expected an RMS level dB reading in ffmpeg stderr:\n${r.stderr}`); + const value = matches.at(-1)[1]; + return value === "-inf" ? -Infinity : parseFloat(value); +} + +test("voice clips get a short edge fade baked in, not a hard cut", { skip: !HAS_FFMPEG }, () => { + const { dir, r } = assembleWith({ + audioMeta: { bgm: null, voices: [{ frame: 1, path: "assets/voice/01.wav" }], sfx: [] }, + beforeAssemble: (projectDir) => { + mkdirSync(join(projectDir, "assets", "voice"), { recursive: true }); + // A constant-amplitude tone spanning the full 3s frame duration: with no + // fade, the start/end windows measure the same RMS level as the middle. + const gen = spawnSync( + "ffmpeg", + [ + "-y", + "-f", + "lavfi", + "-i", + "sine=frequency=440:duration=3", + join(projectDir, "assets", "voice", "01.wav"), + ], + { encoding: "utf8" }, + ); + assert.equal(gen.status, 0, gen.stderr); + }, + }); + + assert.equal(r.status, 0, r.stderr); + const html = readFileSync(join(dir, "index.html"), "utf8"); + const voiceEl = html.match(/id="el-[^"]*-voice"[\s\S]*?src="([^"]+)"/); + assert.ok(voiceEl, "expected a voice