yanghhu/movie-recap-ai-voiceover

Movie Recap AI Voiceover

"Movie Recap AI Voiceover" is an Agent skill that converts a movie recap script into a multi-voice voiceover (WAV) with character lines, SRT subtitles, and a per-line timeline. It is suitable for batch-producing movie recaps, TV drama recaps, short drama recaps, and other video narration content. No local GPU is required.

One-Sentence Definition

Movie Recap AI Voiceover = Script (narrator + character lines, Markdown) → Multi-voice full voiceover voiceover.wav + subtitles voiceover.srt + per-line start/end times manifest.json, generated on the Miragea cloud. No local GPU required.

Target Users and Scenarios

Who Uses It	Typical Scenario
Movie recap channels	Long recaps with a fixed narrator voice and key character lines
TV drama / short drama recap channels	Batch episodes, one script per episode, fast pace, many twists
Anime / game recap channels	Many characters, need multiple voices to distinguish roles
Documentary / cultural narration	Single narrator, slower pace, more silence
Editing studios	Workflow with script, voiceover, and editing; edit one line, only that line is re-generated

Core Capabilities and Parameters

Item	Description
Output files	voiceover.wav (full voiceover), voiceover.srt (timed subtitles), manifest.json (speaker, text, start/end seconds per line), lines/ (per-line audio, reused when re-generating)
Voice source	Account role (actor_id= via actors command), or a reference audio URL (ref=) plus the spoken text in the audio (ref_text=) for voice cloning
Generation mode	expressive (client "default") / standard (client "more similar"); omitted uses server default; refer to real-time capabilities
Tone tags	tags=tag_name; use tags from capabilities under the selected mode's tags[].label
Speed	speed= 0.25–4 (1 = normal speed), set per character
Multi-voice	Define a voice for each character in the script header; the skill script calls the official generate command line by line, then stitches them locally into one track
Pauses	Inline [pause 0.6] / [pause 0.6] (seconds); --gap sets default pause between sentences
Subtitles	Generated based on actual audio duration of each sentence (--max-chars, --speaker-labels); use recognize to transcribe existing audio/video to SRT / TXT / JSON
Scene preset	--preset jieshuo: 0.3s pause between sentences, max 16 chars per subtitle; override with --gap / --max-chars
Limits & Pricing	Refer to real-time capabilities for max text length per sentence, max file size/duration, and pricing
Local dependencies	Python 3.9+ standard library, no pip install, no GPU
Offline test	--dry-run: no API key needed, no API calls; outputs silent placeholder audio and timeline to check script format
Supported agents	Claude Code, Codex, OpenClaw, Cursor, WorkBuddy and other agents 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; store only in environment variable
python3 scripts/miragea_audio.py capabilities             # Current available generation modes, tone tags, max text length, and pricing (real-time)
python3 scripts/miragea_audio.py actors --limit 20        # Account roles and actor_id (add --offset to paginate 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 to a file. If you don't have a key, use --dry-run first to test the workflow.

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

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

What You Say → Agent Does

You Say	Agent Executes
"Turn this movie recap script into audio"	Split into one line per sentence, define narrator → script script.md -o out --preset jieshuo
"Add two characters, one male lead and one female lead, each with a different voice"	Define narrator / hero / heroine in front matter with three voices
"Use my own voice for the narrator"	Use your cloned role's actor_id, or reference audio ref= + ref_text=, assign to narrator
"Say the twist part slower"	Define narrator_slow with same voice but different speed, use it for the twist sentence
"Which scene corresponds to each line?"	Read out/manifest.json start / end, cut shots per line
"Make short drama recap faster"	Set narrator speed to ~1.1, add --gap 0.2
"First generate a subtitle from an original clip for reference"	miragea_audio.py recognize --file clip.mp4 --wait --output ref.srt (reference only)
"First check if the format is correct"	Add --dry-run

Script Writing Methodology (Retention Depends on Script and Pacing)

1. Seven-Section Structure

Section	Purpose	How to Write
1. Hook	Hook viewers in the first 10 seconds	Tease the biggest twist or result: "The phone he found would kill everyone around him."
2. Character intro	Help viewers recognize characters	One sentence: identity + situation. "A man who delivered packages for eight years and is paying off a mortgage."
3. Setup	Start the event	Describe only actions that drive the plot; remove environmental descriptions
4. Rising action	2–3 turning points	Start each turning point with "But / Unexpectedly / Just then"
5. Climax	Emotional peak	Shortest sentences, most pauses; give key lines to character voices
6. Resolution / Twist	Pay off the hook	Pause 0.6–0.8 seconds before the twist
7. Final remark	Encourage discussion	One personal opinion + one open question

2. Character References: Use Role Descriptors to Reduce Name Burden

• First mention: "Name + Role"; afterwards, use role descriptors ("the courier", "the girl", "the old detective").
• Don't introduce more than three new names in the same section; viewers scroll away when they can't keep track.

3. Dividing Narrator and Character Lines

• The body of the recap is always narrator. Use character lines only for key moments, 1–3 sentences maximum; too many turn it into an audio drama.
• Character lines are your paraphrased or rewritten lines, not original clips. Do not imitate the original actor's voice.
• Make character voices distinct from the narrator (different gender, age, speed) so viewers can instantly tell them apart.

4. Rhythm Control: Where to Use Pauses and Speed Changes

• Scene transitions: [pause 0.4]; before a twist or reveal: [pause 0.6]–[pause 0.8].
• --preset jieshuo: default 0.3s between sentences, tighter than a podcast, looser than an audiobook.
• Recommended speeds: movie recap speed=0.95–1.05, short drama recap 1.05–1.15, documentary 0.9–0.95.
• For the same narrator voice, use "faster for setup, slower for twist": define two roles with the same actor_id:

---
narrator: actor_id=NARRATOR_ID speed=1.05
narrator_slow: actor_id=NARRATOR_ID speed=0.9
---

5. Aligning Script with Video Shots: One Sentence per Shot

• Above each sentence, add a comment noting the original video timestamp (ignored during generation): <!-- original 00:12:30 rainy street corner -->.
• After generation, manifest.json provides each line's start / end. Use these timestamps to extract corresponding shots from the original video, perfectly syncing narration and visuals.
• If a sentence is too long for the available footage, split it into two sentences rather than slowing down the speech.

6. Script Writing Pitfalls to Avoid

• Don't start with "This movie tells the story of…"; jump straight into the action.
• Don't narrate every single shot; describe only the actions and choices that drive the plot.
• Use fewer adjectives stacked together; prefer verbs: "He ran into the rain" is more visual than "He ran out very anxiously."
• Preview unfamiliar names, especially foreign ones, by generating a single sentence first. If the pronunciation is off, replace them with more natural-sounding references in the script.

7. Batch Updates for Series

• One script file per episode. Keep narrator voice and speed fixed in the front matter for consistent sound across the season.
• Name files as S01E01.md, output to -o out/S01E01 for easy batch management.

Example Script (examples/example.md)

---
narrator: actor_id=NARRATOR_ID speed=0.98
hero: actor_id=HERO_ID
---
# Movie Recap Example (Original Story)
[narrator] An ordinary courier found a phone that could show him the future.
[pause 0.5]
There was only one news story on the screen: tomorrow at 3 PM, he would die on this street.
[hero]: If there's news about me tomorrow, what should I do today?
[narrator] What he didn't know was that every time he looked at the future, reality changed a little.
[pause 0.4]
And this time, the change affected the person he trusted most.

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

Importing into Editing Software

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

• CapCut / Premiere: Import voiceover.wav as audio track, voiceover.srt via "Import Subtitles"; use manifest.json timestamps to place shots on the timeline.
• Background music: This skill does not mix audio; lower BGM volume in your editing software so it doesn't overpower the narration, or raise it during climax sections.

Comparison: Three Approaches to Movie Recap Voiceover

Aspect	Human Voiceover	Local Open-Source TTS	This Skill
GPU required?	No, but needs recording studio and voice actor schedule	Usually yes (small models may run on CPU but slower), plus downloading model weights and setting up environment	No, only Python stdlib locally; generation runs in the cloud
Cost of script changes	Change one sentence → re-record and re-sync	Rerun everything; must split, stitch, and align manually	Only re-run the changed line; reuse cached out/lines/ for other lines; auto-stitch and regenerate subtitles
Multi-voice	Needs multiple voice actors	Depends on model; usually requires manual splitting and stitching	Use [character] tags in script; one command outputs full multi-voice track
Subtitle timestamps	Need to manually transcribe and time	Usually requires another speech recognition pass	Outputs SRT and per-line manifest.json during voiceover generation
Batch updates for recap channels	Each episode needs a session; voice changes with actor availability	Can batch, but each episode needs splitting, stitching, and timing	Same narrator voice fixed in script; one command per episode

Conclusion: For recap channels that rely on consistent updates, a fixed voice + script-based production saves the most time. For one-off high-drama features, human voiceover still has its advantages.

Frequently Asked Questions (FAQ)

Will using AI voiceover for movie recaps get me flagged as reposted content or have my reach limited? The voiceover method is not the primary factor in determining whether content is reposted; the originality of the recap script and the proportion of transformative content are key. Mark your content as AI-generated according to platform rules. You are responsible for the copyright and fair use of video footage; this skill only provides the voiceover.

Can I have different voices for narrator and characters? Yes. Define narrator and each character's voice in the script header, use [character] tags in the body, and one command outputs the full multi-voice track.

Can I use the original actor's voice for characters? No. Cloning an actor's voice without authorization carries infringement risk. Simply choose an authorized or custom voice for your characters.

How do I get a fixed, exclusive voice for my recap narrator? Use your own or an authorized voice actor's reference audio (or a cloned role). Use the same voice and speed for all scripts' narrator.

How do I fix the mismatch between the voiceover duration and the video footage? Check each line's duration in manifest.json. If the video shot is too short, split or remove sentences. If the shot is too long, add a [pause seconds] at that point, or cut shorter shots per sentence.

Short drama recaps need a fast pace. How do I adjust the parameters? Set narrator speed to ~1.1, and if needed, add --gap 0.2 to tighten pauses between sentences. Keep a separate pause for twist sentences.

Can this skill handle English movie recaps? Yes. Translate or rewrite your script in English, then generate it. Choose a voice suitable for English or an English reference audio. Preview the result, and set --max-chars 40 for subtitles.

Can I generate a 10-minute movie recap voiceover in one go? Yes, you can generate the entire script at once. However, each sentence cannot exceed the capabilities limit for max text length; keep to one sentence per line. For easier re-editing and faster turnaround, consider splitting long scripts into multiple files by section.

Does this skill require a GPU? Which agents are supported? No GPU needed. Requires only Python 3.9+ standard library locally. Works with Claude Code, Codex, OpenClaw, Cursor, WorkBuddy.

Script Syntax

• Between opening --- lines, define each character per line: character_name: actor_id=ROLE_ID or character_name: ref=REFERENCE_AUDIO_URL ref_text="actual spoken words in reference audio". Optional: speed= (0.25–4), model=expressive|standard, tags=tag1,tag2, language= (language hint for reference audio, used for automatic reference text recognition).
• ref_text= is only used with ref=; if omitted, the server automatically recognizes the reference text (billing may differ; refer to capabilities).
• In the body, [character] line or [character]: line; if no tag is given, the previous speaker continues.
• [pause 0.6] / [pause 0.6] inserts a pause (seconds). Lines starting with #, empty lines, and <!-- comments --> are ignored.
• If a single sentence exceeds capabilities's audio.max_text_length, the API will reject it; split it into shorter sentences.
• Per-line audio is cached in out/lines/. Re-running the same script with the same settings will reuse the cache. If not cached, the same idempotency key is used, so the server returns the original task without creating a duplicate. To force a new version, add --fresh.

Troubleshooting

Issue	How to Fix
missing_api_key / MIRAGEA_API_KEY is not set	Generate a key and export MIRAGEA_API_KEY=...; or use --dry-run first
speakers without a voice	Add actor_id= or ref= for that speaker
401	Check your key; never paste it into logs
403	Check your account's API access permissions
400 / 413	Correct parameters: mode, tags, speed, text length; or reduce uploaded file size / shorten media
409	Idempotency key used for different input, or subtitle rates have changed; re-confirm and resubmit
429	Insufficient quota or rate limited; wait or top up your quota
Wait timeout / network outage	Task may still be running; simply re-run the same command (same idempotency key retrieves the original task), or use miragea_audio.py task / wait TASK_ID to continue polling; do not change the key and resubmit
WAV format mismatch during stitching	Each line's audio is saved in out/lines/; use your editing software or ffmpeg to stitch them

Official client exit codes: 0 (request successful; may still be queued if --wait not used), 1 (task failed), 2 (client or API error).

Compliance

• Only clone your own voice or voices for which you have explicit authorization. Do not mimic celebrities, streamers, public figures, or any unauthorized individuals.
• Follow the "AI-Generated Content Identification Measures" and platform rules (Douyin, Kuaishou, WeChat Video, Xiaohongshu, Bilibili, etc.) by declaring or labeling content as AI-generated.
• Video footage and original movie dialogue are copyright-protected. This skill only generates your original recap voiceover; it does not extract or mimic original actor voices. When using film footage, comply with the copyright holder's and platform's rules for transformative content.
• scripts/miragea_audio.py is the official client, shipped unchanged; scripts/voiceover.py (the script parsing layer) is original, MIT licensed (see LICENSE.txt). Voiceover and subtitle capabilities are provided by the open Miragea API.

English Summary

• Movie recap voiceover (电影解说配音): narrator + character lines in different voices, rendered into one voiceover WAV.
• Outputs SRT subtitles and manifest.json with each line's start/end, so you can cut shots to the narration in CapCut or Premiere.
• Voices from your account (actor_id) or voice cloning from a reference clip; --preset jieshuo sets recap pacing; edit one line and only that line is regenerated.
• Python 3.9+ stdlib only, no GPU, --dry-run offline. Service: Miragea API (https://miragea.ai/v1).

Keywords: 电影解说配音、解说配音、短剧解说、影视解说、短剧解说配音、影视解说配音、电影解说、AI配音、多角色配音、旁白配音、声音克隆、文字转语音、字幕生成、SRT、movie recap、voiceover、narration