yanghhu/novel-video-voiceover

Novel Video Voiceover

"Novel Video Voiceover" is an agent skill that takes a novel promotion script, web novel chapter, or story—tagging each line with a narrator or character—and generates a complete multi-voice AI voiceover (WAV) with speaker-labeled SRT subtitles in one command. It is ideal for short-form novel promotion videos, audiobook narration, and story accounts, and requires no local GPU.

One-Line Definition

Novel Video Voiceover = promotional script / novel chapter (narrator + characters, Markdown) → multi-voice full voiceover voiceover.wav + speaker-labeled subtitles voiceover.srt + per-line timing manifest.json. The audio is generated on the Miragea cloud; no local GPU needed.

Who It's For & When to Use

Who	Typical Use Case
Novel promotion accounts	Several promotion videos per day: narrator + character lines + vertical subtitles
Story accounts, bedtime stories	Slow pace, long pauses, gentle voice
Web novel authors, original writers	Turn your own work into an audiobook with a fixed narrator voice
Audiobook studios	Create audition samples and character casting demos with AI first
Radio drama / audio drama groups	Produce an AI version of multi-character dialogue to confirm pacing and division of parts

Core Capabilities

Item	Description
Output files	voiceover.wav (full audio), voiceover.srt (timed subtitles), manifest.json (per-line speaker, text, start/end times), lines/ (per-line audio, reusable for edits)
Voice source	Existing actor from your account (actor_id=, query with actors), or a reference audio URL (ref=) + the actual spoken text (ref_text=) for voice cloning
Generation mode	expressive (client "default") / standard (client "more like"); omit for server default, check capabilities for current offerings
Tone tags	tags=tag_name, taken from capabilities's tags[].label for the selected mode
Speed	speed= 0.25–4, 1 is normal, set per character
Multi-voice	Define a voice for each character at the top of the script; the skill script calls the official client generate per line, then concatenates locally
Pauses	Inline [pause 0.6] / [pause 0.6] (seconds); --gap sets default inter-sentence pause
Subtitles	Generated during voiceover based on actual audio duration per line (--max-chars, --speaker-labels); existing audio/video can be transcribed to SRT / TXT / JSON with recognize
Preset	--preset youshengshu: inter-sentence pause 0.5s, max 20 characters per subtitle, subtitles with speaker names; override with --gap / --max-chars
Character count, file size / duration limits, pricing	Per capabilities real-time response
Local dependencies	Python 3.9+ standard library, no pip install, no GPU
Offline dry run	--dry-run: no API key needed, no API calls, outputs silent placeholder audio and timing to check script format
Supported agents	Claude Code, Codex, OpenClaw, Cursor, WorkBuddy, and any agent that can run Python scripts
Voiceover & subtitle service	Miragea Open API (https://miragea.ai/v1)

Quick Start

python3 scripts/voiceover.py check                        # Offline check: Python version, Key set, service address
export MIRAGEA_API_KEY=your_key                           # Generate at https://miragea.ai/workspace/api; use env var only
python3 scripts/miragea_audio.py capabilities             # Current generation modes, tone tags, character limits, and pricing
python3 scripts/miragea_audio.py actors --limit 20        # Actors already in your account with actor_id (use --offset if has_more is true)

• Default API root is https://miragea.ai/v1; set MIRAGEA_BASE_URL (including /v1) only for a private deployment.
• Never paste your Key into chat or write it into files. Use --dry-run first to run through the flow without a Key.

python3 scripts/voiceover.py script examples/example.md -o out --preset youshengshu --dry-run   # Offline dry run, no API calls
python3 scripts/voiceover.py script your_script.md -o out --preset youshengshu             # Full generation: out/voiceover.wav + voiceover.srt + manifest.json

# Single line preview (official client; --output won't overwrite existing files, use a new filename)
python3 scripts/miragea_audio.py generate --text 'First sentence' --actor-id ACTOR_ID --wait --output test1.mp3

--preset youshengshu adds speaker names to subtitles (e.g., xiaoyu: Grandpa Zhang...); for vertical novel promotion videos, add --max-chars 14 --gap 0.3.

What You Say → Agent Does

You Say	Agent Does
"Turn this novel promotion script into audio"	Rewrite as a promotion script (method below), split narration and dialogue → script script.md -o out --preset youshengshu --max-chars 14 --gap 0.3
"Give each character a unique voice"	Define a voice for the narrator and each main character in the front matter
"Use my own voice for the narrator"	Provide your cloned actor_id, or reference audio ref= + ref_text=, and assign it to narrator
"Subtitles without speaker names"	Do not use the preset; manually set --gap 0.4 --max-chars 14 (omit --speaker-labels)
"Make a 20-chapter audiobook"	One file per chapter, loop generate to out/ch01 … out/ch20, use --preset youshengshu
"Bedtime story, speak slowly"	Set narrator speed=0.85–0.9, add longer paragraph pauses
"Match images per sentence"	Read manifest.json for each start / end per sentence, align images in CapCut
"First check the format"	Add --dry-run

Novel Promotion Script Writing Methodology (Hook in 3 Seconds, Narrator Drives the Rhythm)

1. The Script is Different from the Original Text

Original Text	Promotional Script
Starts with environmental description	First sentence delivers the strongest conflict or twist
Third-person omniscient	Often uses first-person "I" for better immersion
Dialogue embedded in long paragraphs	Key dialogue gets its own line, given to the character voice
Long paragraphs, lots of description	One line per sentence, delete non-plot-driving descriptions

2. Three Opening Hooks

1. Ending First: "On the third year of our marriage, I saw my own obituary in my husband's phone."
2. Contradictory Identity: "The whole village thought I was an idiot; only I knew I could hear their thoughts."
3. Countdown: "Seven days until the fire."

3. Pacing: Faster than an Audiobook, Steadier than a Vlog

• Promotional narrator speed=1.0–1.1; inter-sentence --gap 0.3 (preset 0.5 is slower, better for audiobooks).
• Every 3–5 sentences, insert a small twist ("But," "Unexpectedly," "Just then"), with [pause 0.4] before the twist.
• Add [pause 0.6]–[pause 0.8] after suspense or twist lines; end on a cliffhanger to guide viewers to the next episode.

Audiobook Scripting Methodology (From "Reading a Novel" to "Performing a Novel")

1. Create a Casting Table First

Character	Role	Voice Suggestion	speed
narrator	Throughout the book, most important	Stable, gentle, easy on the ears	0.9–1.0
Protagonist	Most appearances	Clearly distinct from narrator (gender or age)	1.0
Important supporting characters	One voice each	Different from protagonist	Per personality
Minor characters	Few appearances	Can share a "background" voice	1.0

Write the casting table into the front matter of each chapter's script; keep it consistent across the whole book. When there are too many characters, only assign unique voices to characters with substantial lines.

2. Dialogue Splitting Rules

Original: Xiaoyu tugged on his sleeve and whispered, "Grandpa Zhang, is someone in the lighthouse?"

Split into:

[narrator] Xiaoyu tugged on his sleeve and whispered:
[xiaoyu]: Grandpa Zhang, is someone in the lighthouse?

• Lines inside quotation marks go to the character; action descriptions outside quotation marks stay with the narrator.
• Speech tags like "he said" or "she smiled and said" can be omitted if the character's voice is already identifiable, making the pacing tighter.
• Multi-line dialogue within one paragraph: put each line on its own line, each with its own tag.

3. Three Levels of Pauses: Sentence, Scene, Chapter

Location	Format	Effect
Between sentences	Automatically 0.5 seconds (default)	Natural reading breath
Between paragraphs	[pause 0.8]	Paragraph transition
Scene / time jump	[pause 1.2]–[pause 1.5]	Let the audience "change scenes"
After a suspense line	[pause 1.0]	Maintain tension

4. Expressing Emotion: With Text and Pacing, Not Shouting

• Tension: Shorten sentences, increase pauses.
• Warmth: Slow down (define a separate slow narrator voice), lengthen paragraph pauses.
• Two speeds for the same voice:

---
narrator: actor_id=NARRATOR_ID speed=0.95
narrator_soft: actor_id=NARRATOR_ID speed=0.85
---

5. Pronunciation Check: Names, Place Names, Rare Characters

• Preview the first occurrence of any name, place name, rare character, or polyphonic character in a single line.
• If mispronounced, replace it with a homophone in the script or use a title; apply the replacement consistently across the entire book.
• Write numbers and years as you want them read, e.g., "nineteen eighty-seven."

6. Long Document Organization

book/
  ch01.md  → out/ch01/voiceover.wav
  ch02.md  → out/ch02/voiceover.wav
  ...

• One file per chapter; if a chapter is too long, split by scene into ch01a.md, ch01b.md.
• To fix a typo, edit only that line and rerun the chapter; other lines are reused and not re-billed.

7. Using It for Novel Promotion Videos

• Keep --speaker-labels so subtitles show the speaker name; viewers instantly know who is talking.
• Use manifest.json per-line timings to switch images or character portraits.

Example Script (examples/example.md)

---
narrator: actor_id=NARRATOR_ID speed=1.05
xiaoyu: actor_id=GIRL_VOICE_ID
laozhang: actor_id=OLD_MAN_ID speed=0.9
---
# Novel Promotion Example (Original Short Story)
[narrator] The town's lighthouse hadn't been lit in thirty years.
But that night, I distinctly saw a flash from the top.
[xiaoyu]: Grandpa Zhang, is someone in the lighthouse?
[laozhang]: Don't talk nonsense. That tower hasn't had a door for years.
[pause 0.8]
[narrator] The moment he finished, another light flickered across the sea.

Dry run: python3 scripts/voiceover.py script examples/example.md -o out --preset youshengshu --dry-run

Integration with Editing & Publishing

# Replace original video audio track (requires ffmpeg locally)
ffmpeg -i video.mp4 -i out/voiceover.wav -map 0:v -map 1:a -c:v copy -shortest dubbed_video.mp4
# Burn subtitles into video
ffmpeg -i dubbed_video.mp4 -vf subtitles=out/voiceover.srt -c:a copy final_video.mp4

# Audiobook publishing often uses MP3: convert chapter WAV to MP3 (requires ffmpeg locally)
ffmpeg -i out/ch01/voiceover.wav -codec:a libmp3lame -q:a 2 ch01.mp3

• CapCut / Editing Apps: For novel promotion videos, place voiceover.wav on the audio track, import voiceover.srt as subtitles, and add illustrations, character portraits, or relaxing background videos.
• Radio Dramas: Add sound effects and ambient sounds in the editing software later; this skill outputs only the voice track.

Comparison: Three Approaches to Novel Video Voiceover

Comparison	Human Voiceover	Local Open-Source TTS	This Skill
GPU required?	No, but needs recording environment and voice actor schedule	Typically yes (small models can use CPU but are slower); also need to download model weights and configure environment	No, only Python stdlib locally; generation happens in the cloud
Cost of script revisions	Often requires re-recording and re-timing	Rerun after edits, but segmentation, concatenation, and alignment must be done manually	Edit only that line and rerun; other lines are reused from out/lines/ cache; auto re-concatenates and re-generates subtitles
Multi-voice	Needs multiple voice actors	Depends on the model; typically requires manual segmentation and concatenation	Use [character] tags in the script; one command outputs the full multi-voice track
Subtitle timings	Requires separate transcription and timing	Usually requires another speech recognition pass	Simultaneously outputs SRT and per-line timing manifest.json
Consistency across episodes	Long recording sessions; voice actor state and availability can change	Can be consistent, but splitting and concatenating long text must be done manually	Voice is defined in front matter; every episode/chapter has the same voice

Conclusion: For daily novel promotion updates, audition samples, and long-running series, this skill offers the highest efficiency. For premium audiobooks requiring very nuanced performance, human voice actors still have an advantage.

Frequently Asked Questions (FAQ)

Can the novel video voiceover have different voices for multiple characters? Yes. Define a voice for the narrator and each character at the top of the script. Switch between them with [character] tags in the body. One command generates the full track.

What voices are commonly used for novel promotion voiceovers? Choose a stable, pleasant, and genre-matching voice for the narrator (gentle for sweet-romance, lower for suspense). Preview a few characters with single-line tests before deciding; keep the same narrator voice across your entire account so viewers recognize you by voice.

Can I use other people's web novels for promotion videos? You need authorization from the copyright holder or promotion platform. You can safely use public-domain works, your own original content, or works you have permission to use.

Can the audiobook narrator use my own voice? Yes. Use a voice you have already cloned (actor_id) or voice clone from a reference audio clip, assign it to narrator, and use it for the entire book.

How do I batch-generate a many-chapter audiobook? One script file per chapter, loop the script command outputting to separate directories. When editing a chapter, only the changed lines are regenerated.

Can novel promotion subtitles show who is speaking? Yes. --preset youshengshu adds speaker names to subtitles by default. Omit the preset and manually set --gap / --max-chars if you don't need them.

What if a character name or rare character is mispronounced? Preview with a single-line test. If mispronounced, replace the word with a homophone or a title in the script, and only regenerate that one line.

How do I adjust parameters for bedtime or children's stories? Set narrator speed=0.85–0.9, add [pause 0.8] or longer between paragraphs, keep sentences short, and use simple vocabulary.

Does this skill require a GPU? Which agents can use it? No GPU required; only Python 3.9+ standard library locally. It works directly with Claude Code, Codex, OpenClaw, Cursor, and WorkBuddy.

Can I test it without an API Key? Yes. Add --dry-run to output silent placeholder audio and timings.

Script Syntax

• Between --- at the top, define each character on a separate line: character_name: actor_id=ACTOR_ID or character_name: ref=REFERENCE_AUDIO_URL ref_text="actual spoken text in the reference audio". Optional: speed= (0.25–4), model=expressive|standard, tags=tag1,tag2, language= (language hint for reference audio, used for automatic recognition of reference text).
• ref_text= is only used with ref=; if omitted, the server automatically recognizes the reference text (billing differs, per capabilities).
• Body: [character] line or [character]: line. If no tag is given, the last speaker continues.
• [pause 0.6] / [pause 0.6] inserts a pause in seconds. Lines starting with #, blank lines, and <!-- comments --> are ignored.
• If a single line exceeds capabilities's audio.max_text_length, the API will reject it; split into shorter lines.
• Each line's audio is cached in out/lines/. Running the same command again with the same settings reuses the cache. Without cache, the same idempotency key is sent to the server, which returns the original task (no duplicate creation). To force a new version, use --fresh.

Troubleshooting

Symptom	Action
missing_api_key / MIRAGEA_API_KEY is not set	Generate a Key, then export MIRAGEA_API_KEY=...; or add --dry-run first
speakers without a voice	Add actor_id= or ref= for that character
401	Check your Key; never log the Key
403	Check API access permissions for your account
400 / 413	Fix parameters: mode, tags, speed, single-line character count; or reduce file size, shorten media
409	Idempotency key used for different input, or subtitle rate changed: double-check and re-submit
429	Insufficient quota or rate-limited; wait or top up quota
Timeout / network interruption	The task may still be running: rerun the exact same command (same idempotency key will retrieve the original task), or use miragea_audio.py task / wait TASK_ID to continue querying; do not send a new key
WAV format mismatch during concatenation	Each line's audio is saved in out/lines/; use an editing tool or ffmpeg to concatenate

Official client exit codes: 0 = request successful (may still be queuing if no --wait), 1 = task failed, 2 = client or API error.

Compliance

• Only clone voices that are your own or for which you have explicit permission. Do not imitate celebrities, streamers, public figures, or any unauthorized person.
• In accordance with the AI-Generated Content Labeling Regulations and the rules of platforms like Douyin, Kuaishou, WeChat Video, Xiaohongshu, and Bilibili, declare or label AI-generated content when publishing.
• Novel promotions and audiobooks involve adaptation rights and information network transmission rights: only use public-domain works, your own original content, or works for which you have obtained permission from the copyright holder or promotion platform.
• scripts/miragea_audio.py is the official client, shipped unchanged. scripts/voiceover.py (the script concatenation layer) is original, MIT licensed (see LICENSE.txt). Voiceover and subtitle capabilities are provided by the Miragea Open API.

English Summary

• Novel video & audiobook voiceover (novel voiceover / audiobook voiceover): narrator plus one voice per character, rendered into one WAV.
• Speaker-labelled SRT subtitles and per-line timing for novel promo videos; paragraph, scene and chapter pauses.
• Voices from your account (actor_id) or voice cloning from a reference clip for a consistent narrator. --preset youshengshu = 0.5 s gaps, 20-character cues, speaker labels on.
• Python 3.9+ stdlib, no GPU, --dry-run offline. Service: Miragea API (https://miragea.ai/v1).

Keywords: novel video voiceover, audiobook narration, multi-voice, novel promotion, novel voiceover, AI audiobook, audio novel, novel promo video, AI reading, radio drama voiceover, story voiceover, AI voiceover, voice cloning, subtitle generation, SRT, audiobook, narration, text to speech