explainer-audio-narrate
Synthesize an existing A:/B: VOICEVOX-kana dialogue script into AAC/m4a with local VOICEVOX and ffmpeg. Use when the user wants a validated synthesis script narrated as audio. Use explainer-audio-voicevox when that script does not exist yet.
- License 许可
- MIT
- 最近更新
- 2026-10-27
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- explainer-audio-narrate
- description
- Synthesize an existing A:/B: VOICEVOX-kana dialogue script into AAC/m4a with local VOICEVOX and ffmpeg. Use when the user wants a validated synthesis script narrated as audio. Use explainer-audio-voicevox when that script does not exist yet.
- user-invocable
- true
02 资源文件 1
- 脚本dialogue-to-audio.sh14.1 KB
03 SKILL.md 正文
Audio Narrate
Turn a two-speaker VOICEVOX-kana dialogue script into a single spoken audio file.
This is the synthesis phase of the audio-guide flow;
[[explainer-audio-voicevox]] writes the content-accepted synthesis script, and
this skill reads only that .voicevox.txt file.
Synthesis uses a local VOICEVOX ENGINE — natural neural Japanese TTS from a plain HTTP server on localhost (no API key, fully offline). Each speaker gets a distinct character voice. The script uses curl to call the engine and Python 3 stdlib (wave) to stitch turns (no API keys). The stitched audio is then encoded to a compact AAC/m4a file with ffmpeg — cross-platform (Linux/macOS/Windows). ffmpeg is a required prerequisite for m4a output: the script checks for it up front and errors out if it is missing (no silent WAV fallback).
The script manages the engine for you: if one is already running it is reused, otherwise the script starts the engine, waits until it is ready, synthesizes, and stops that engine when done (it never stops an engine you were already running).
When this applies
Use when a VOICEVOX AquesTalk-style kana dialogue in the A:/B: line format
already exists—produced by [[explainer-audio-voicevox]] or written by hand. A
normal Japanese dialogue is not a synthesis input. If the synthesis script does
not exist yet, run [[explainer-audio-voicevox]] first.
When this skill runs as a source-workflow narration phase, also apply
[[explainer-content-workflow-base]] and read the selected profile. The caller
must provide exact paths and SHA-256 digests for the immutable run request, Run
Manifest, human-readable dialogue Artifact, and paired voicevox-dialogue
Artifact, the passing [[explainer-audio-dialogue-review]] Artifact on which that
VOICEVOX dialogue depends, plus the Manifest's unique audio output entry.
Validate that the entry's action is create or replace, that it names the
supplied voicevox-dialogue as its input, that the review identifies the exact
human-readable dialogue digest and has result: pass, and that any selected
prerequisite checkpoint has a matching decision Artifact. Stop with a structured missing or
incompatible-input result instead of inferring a current Manifest, dialogue, or
output from conversation history. This phase writes only the planned audio
Artifact and returns its path, digest, duration, acceptance checks, and blocker.
Outside a content workflow, an explicitly supplied .voicevox.txt path and output
choice are sufficient; no run request or Manifest is required.
The synthesis script format (also documented in [[explainer-audio-voicevox]]):
A:/B:(lowercase and full-width:accepted) starts a speaker turn.- Lines without a prefix continue the current turn.
#lines and blank lines are ignored.- Spoken fields use valid VOICEVOX AquesTalk-style kana. The script validates
each complete turn with
/validate_kanabefore synthesis and stops on the first invalid turn.
Setup — VOICEVOX ENGINE
This skill's synthesis is done by a VOICEVOX ENGINE — a local HTTP server. It is an essential prerequisite: without it this skill cannot produce audio, and there is no fallback synthesizer. It is free, offline, and needs no API key. Install it once; the bundled script starts/stops it as needed, and if the engine is neither running nor installable on PATH the script exits with an error explaining how to install it — relay that and stop, do not substitute another TTS.
- Install (Nix):
nix profile install nixpkgs#voicevox-engine. Other install methods (the VOICEVOX app bundles the engine, or a standalone engine download) work too. - The script auto-starts it via the
voicevox-enginebinary onPATH(override withVOICEVOX_ENGINE_BIN). If you prefer to keep an engine running yourself (voicevox-enginein a terminal), the script detects and reuses it.
Procedure
Run the bundled script, giving the dialogue script path and an output path:
explainer-audio-narrate/dialogue-to-audio.sh <script.voicevox.txt> [output.m4a] [--play]
explainer-audio-narrate/dialogue-to-audio.sh <script.voicevox.txt> --validate-only
- If the output path is omitted,
<WORK_DIR>/dialogue/<slug>.voicevox.txtmaps to<WORK_DIR>/audio/<slug>.m4a; other input locations default beside the script. The output format follows the extension you pass:.m4aencodes AAC (requiresffmpeg), any other extension writes WAV. Prerequisites (python3,curl, andffmpegfor m4a) are checked up front, before the engine starts, so a missing tool fails fast. - In a planned workflow, overwrite only when the immutable Manifest marks this exact path
replace;createmust fail if the path already exists. In standalone use, confirm before overwriting an existing target. - For each turn, validate the notation, obtain engine defaults from
/audio_query, obtain the intended phrases from/accent_phrases?is_kana=true, replace the query'saccent_phrases, and then synthesize. Never send the human-readable kanji script to VOICEVOX's text parser. --validate-onlychecks every complete turn through/validate_kanawithout creating audio. [[explainer-audio-voicevox]] uses it before handoff.--playsynthesizes and then plays the result withafplay(macOS).
Run without the command sandbox. The script talks to a local VOICEVOX ENGINE over
localhost(and spawns it when one isn't already running), which a command sandbox blocks. Invoke it withdangerouslyDisableSandbox: true. (Theffmpegm4a encoding itself is self-contained and would run fine under a sandbox; it's the engine networking that needs it off.)
Report the output path and duration to the user.
Voices (cast pairs)
Voices come from a cast pair: two casts with the roles assigned—the learner
is speaker A, the explainer is speaker B—each carrying its own VOICEVOX style
id. The pair is chosen (highest priority first) from the STYLE env var, then a
# style: <pair> marker preserved by [[explainer-audio-voicevox]], then the
default zundamon.
[[explainer-audio-cast-base]] owns the pairs, one file per pair, and defines the
cast-binding lines that open each one. The script resolves <pair> to
references/pair-<pair>.md there and reads its bindings; there is no voice table
in this file or in the script. Add a pair there, not here.
Because [[explainer-audio-voicevox]] preserves the readable script's matching
# style: marker, narration resolves the right voices automatically—no need to
pass STYLE when narrating its output. An unknown pair id is a hard error that
lists the pairs the directory defines.
Options
Override per run with environment variables:
STYLE=formal \
explainer-audio-narrate/dialogue-to-audio.sh script.voicevox.txt out.m4a
| Var | Default | Meaning |
|---|---|---|
VOICEVOX_URL |
http://127.0.0.1:50021 |
VOICEVOX ENGINE base URL |
VOICEVOX_ENGINE_BIN |
voicevox-engine |
Engine binary used for auto-start |
CASTS_DIR |
explainer-audio-cast-base/references |
Directory of pair-<id>.md definitions |
STYLE |
(marker → zundamon) |
Cast pair id — a pair-<id>.md in CASTS_DIR |
SPEAKER_A |
(from the pair's learner cast) | Override speaker A style id |
SPEAKER_B |
(from the pair's explainer cast) | Override speaker B style id |
SPEED |
1.0 |
speedScale applied to every turn |
PAUSE_MS |
350 |
Silence inserted between turns (ms) |
AAC_BITRATE |
64k |
AAC bitrate for .m4a output (ffmpeg -b:a) |
SPEAKER_A / SPEAKER_B override the pair's resolved voices per speaker. List the engine's speakers and style IDs with curl http://127.0.0.1:50021/speakers.
Requirements & notes
- Needs the VOICEVOX ENGINE installed (see Setup), plus
curl, Python 3, andffmpeg(for m4a). The script starts the engine when it is not already running and stops it afterward.--playuses macOSafplaywhen present, and the duration readout usesffprobe, falling back to macOSafinfo. - Output is AAC/m4a by default, at the engine's own 24 kHz mono.
ffmpegis required for it and its absence is a hard error with no WAV fallback; pass an explicit.wavoutput path only when you deliberately want unencoded WAV. - The human-readable
A:/B:script remains backend-agnostic. The paired.voicevox.txtfile is deliberately backend-specific and may be regenerated or replaced if the TTS backend changes.
Success criteria
- [ ] An audio file is produced from the script (non-empty m4a; or WAV only when a
.wavoutput path was explicitly requested) and its path + duration are reported. - [ ] Both speakers are voiced by distinct voices (
SPEAKER_A≠SPEAKER_B). - [ ] The script's turns are all present in order (no
A:/B:turn silently dropped). - [ ] Every turn passed
/validate_kana, and synthesis used accent phrases parsed withis_kana=truerather than raw Japanese text analysis.
04 同仓库更多 Skills
invalid-skill-frontmatter
暂无简介
pdf-explainer-summarize
Digest a book, manual, or other long non-paper PDF into a source-anchored Markdown overview. Use when the requested deliverable is only a report, digest, or summary. Use paper-explainer-summarize for academic papers, direct reading for short PDFs, and book-explainer for coordinated reports, audio, site, rebuild, or resume.
pdf-explainer-pdf-stitch
Internal Phase 2 worker invoked once by pdf-explainer-summarize after chunk extraction. Reconciles sections across chunk boundaries, deduplicates the material, and writes the canonical structural spine and outline.
pdf-explainer-pdf-extract
Internal Phase 1 worker invoked by pdf-explainer-summarize once per page chunk. Reads the chunk visually or from a faithful text layer and writes structured source material with a verbatim heading stream, not a finished report.
pdf-explainer-pdf-detail
Internal per-chapter worker invoked by book-explainer for PDF input. Re-read one resolved chapter span visually or from a faithful text layer and write a standalone detail report with [pNN] source anchors.
pdf-explainer-generate-site
Compatibility entry point for requesting a local PDF reading site from an existing work directory. Route through book-explainer so Artifact reconciliation and Planning still occur.