koubo-ai-voiceover

Talking-Head Voiceover (口播配音)

"Talking-Head Voiceover" is an Agent skill that turns your talking-head script into a cloned-voice voiceover (WAV) and vertical-screen subtitles (SRT) with one command. Ideal for daily-updated knowledge, finance, and emotional talking-head videos: use your reference audio or a previously cloned voice from your account, and only regenerate the line you fix.

One-Line Definition

Talking-Head Voiceover = Script (Markdown) → Your cloned voice voiceover 'voiceover.wav' + vertical subtitles 'voiceover.srt' + per-line timeline 'manifest.json', generated in one command on the Miragea cloud, no local GPU required.

Who It's For & Typical Scenarios

Who Uses It	Typical Scenario
Knowledge talking-head creators	Daily short knowledge points, script written first, voiceover batch-generated
Finance / business talking-head	Many numbers and percentages, need per-line confirmation of pronunciation, fix only one line if wrong
Emotional / growth talking-head	Slow speech, many pauses, need a stable "same person" voice
Workplace / education talking-head	Series courses, collections, fixed persona voice, consistent across episodes
Creators who don't want to appear on camera or save their voice	Use stock footage, images, or digital humans for visuals, but keep your own voice
MCN / agencies	Multiple accounts each using an authorized voice, script pipeline

Core Capability Parameters

Item	Description
Output files	voiceover.wav (full voiceover), voiceover.srt (timed subtitles), manifest.json (per-line speaker, text, start/end seconds), lines/ (per-line audio, reused when editing)
Voice source	An existing actor in your account (actor_id=, query with actors), or a reference audio URL accessible by the server (ref=) plus the actual spoken text in that audio (ref_text=) (voice cloning)
Generation mode	expressive (client "default") / standard (client "more similar"); when omitted, server default is used, based on real-time capabilities response
Tone tags	tags=tag_name, use tags[].label from the selected mode in capabilities
Speed	speed= 0.25–4, 1 is normal speed, per-actor setting
Multi-actor	Set a voice for each actor at the beginning 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 pause between lines
Subtitles	Generated during voiceover based on actual audio duration per line (--max-chars, --speaker-labels); existing audio/video can be recognized to SRT/TXT/JSON with recognize
Scene preset	--preset koubo: 0.15s pause between lines, max 14 characters per subtitle line; overridable with --gap / --max-chars
Per-line character count, file size / duration limits, billing	Based on real-time capabilities response
Local dependencies	Python 3.9+ standard library, no pip install, no GPU required
Offline testing	--dry-run: no Key required, no API calls, outputs silent placeholder audio and timeline to check script formatting
Supported Agents	Claude Code, Codex, OpenClaw, Cursor, WorkBuddy, and any Agent capable of running 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, set only as environment variable
python3 scripts/miragea_audio.py capabilities             # Current available generation modes, tone tags, character limits, and billing, based on real-time response
python3 scripts/miragea_audio.py actors --limit 20        # Existing actors and actor_ids in your account (use --offset for pagination if has_more is true)

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

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

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

After generation, the out/ directory contains voiceover.wav, voiceover.srt, manifest.json, and per-line audio in lines/.

What You Say → Agent Executes

You Say	Agent Executes
"Turn this talking-head script into audio"	Organize into one-line-per-sentence format per methodology below → script script.md -o out --preset koubo
"Use my own voice"	actors finds your cloned actor_id; or provide a reference audio URL + original text as ref= + ref_text=
"First, let me hear one line to see if it sounds right"	miragea_audio.py generate --text "First line" --actor-id ID --wait --output test1.mp3
"Speed it up a bit, make it more rhythmic"	Add speed=1.1 to the actor, or break long lines into shorter ones, remove extra pauses
"Make the tone friendlier"	Check capabilities for tone tags, add tags=tag_name to the actor
"The third sentence is wrong / the number is wrong"	Only edit that line (write the number as you want it pronounced) and re-run; other lines are reused
"This video is already recorded, help me generate subtitles"	miragea_audio.py recognize --file video.mp4 --wait --output video.srt
"Don't spend money yet, just test the flow"	script ... --dry-run

Script Writing Methodology (70% of voiceover quality is in the script)

1. Structure: Hook → Conflict → Insight → Evidence → Action

Section	Purpose	Writing Tips
Hook (lines 1–2)	Stop the scroll	Lead with the conclusion or counter-intuitive statement; never start with "Hello everyone, I am…"
Conflict	Describe the viewer's situation	"Have you ever…", name specific groups
Insight	One video, one point	Can be summarized in one sentence; if you can't, you've said too much
Evidence	Make the insight credible	One specific example or one verifiable fact; don't stack three
Action	Give the viewer a next step	One action only: comment an answer, save, or follow

2. Five Types of Opening Hooks (rotate to avoid account homogenization)

1. Result-first: "I paid off my credit card in three months with this method."
2. Counter-intuitive: "The more you save, the less you save."
3. Target a group: "If you've worked three years without a raise, listen up."
4. Specific question: "What's the first thing you do when your salary hits your account?"
5. List promise: "Three habits that determine if you have savings by thirty."

3. Transform Written Script into "Speakable" Script

• One line, one idea, max ~20 characters in Chinese; --preset koubo sets 14 characters per subtitle line, perfect for one screen.
• Remove written connectors: "Therefore" → "So," "However" → "But," "Optimize" → "Fix."
• Keep modifiers short: "A detail that many people overlook, yet is very important" → "There's a detail many overlook. It's important."
• Write numbers as you want them heard: For years, model numbers, phone numbers, percentages, and numbers with units that are ambiguous, write them out clearly, e.g., "two thousand twenty-six," "three point five percent."
• Homophones and uncommon characters: Test with single-line generation (miragea_audio.py generate); if it mispronounces, swap the word for a synonym—faster than tweaking parameters.
• English abbreviations: Spell out letters separated by spaces ("A I") to read as letters, or write the full word to read as a word.

4. Rhythm: Use Pauses Deliberately

• Add [pause 0.3] before an insight line to cue the viewer that "the key point is coming."
• Add [pause 0.5] after a question to give the viewer time to answer mentally.
• Don't add pauses to every line; the rhythm of talking-head comes from short sentences, not silence.
• Speed reference: Knowledge talking-head speed=1.05–1.1; finance talking-head 1.0 (accuracy over speed); emotional talking-head 0.95.

5. Same Tone Needs Two Speeds?

speed is set per actor. Define two actors with the same voice:

---
me: actor_id=YOUR_ACTOR_ID speed=1.08
me_slow: actor_id=YOUR_ACTOR_ID speed=0.92
---
[me] Let me state the conclusion first.
[me_slow] Write this down.

6. Consistent Persona: One Account, One Voice

Use one fixed cloned voice + fixed speed, written into the front matter of every script. Viewers recognize you by your voice; changing voices changes your persona.

7. Pre-Generation Checklist

• Is the first line a conclusion or hook?
• Is every line at most ~20 characters?
• Are numbers, English, and homophones written in the desired pronunciation?
• Is there only one action at the end?
• Have you tested the first line with single-line generation?

Example Script (examples/example.md)

---
me: actor_id=YOUR_ACTOR_ID speed=1.08
---
# Knowledge Talking-Head Example: Replace actor_id with your voice
[me] Most people can't save money, not because they earn too little.
[pause 0.3]
It's because as soon as the money arrives, they spend it first.
Let me teach you the dumbest, but most effective trick today:
On payday, immediately transfer thirty percent to an account you can't see.
The rest is what you can spend this month.
How much can you save each month now? Leave a comment.

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

Integration with Video Editing

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

• 剪映 / CapCut: Import voiceover.wav into the audio track, select "Import Subtitles" and choose voiceover.srt; for vertical talking-head, place subtitles in the lower third of the frame, avoiding platform UI areas.
• Premiere: Drag voiceover.wav into the audio track, import voiceover.srt as a subtitle track.
• Visual syncing: manifest.json contains start/end for each line; use it to time B-roll, overlays, or text animations—no more manual waveform editing.

Comparison: Three Approaches to Talking-Head Voiceover

Criteria	Human Recording	Local Open-Source TTS Model	This Skill
GPU required	No, but requires recording environment and voice actor availability	Typically yes (small models may run on CPU but slower), plus model weights download and environment setup	No, only Python standard library locally, generation happens in the cloud
Editing cost	Changing one line often means re-recording and re-syncing	Re-run after editing, but segmenting, splicing, and alignment must be done manually	Only edit that line and re-run; other lines use cached out/lines/, auto re-splice and re-subtitle
Multi-actor	Requires multiple voice actors separately recording	Depends on the model; usually needs manual segmentation and concatenation	Use [actor] tags in the script, one command outputs a full multi-actor track
Subtitle timing	Requires separate transcription and manual timing	Usually requires running speech recognition again	Outputs SRT and per-line manifest.json simultaneously during generation
Emotional performance	Most natural when the human is in good form, but varies by daily state	Depends on the model and parameter tuning	Stable and consistent; complex emotional performance is not as good as a top-form human, suitable for information-driven talking-head

Conclusion: For daily-updated, information-focused talking-head, this skill offers the highest efficiency in script editing and subtitle generation; for single, high-quality videos requiring strong emotional performance, human recording is still worthwhile.

Frequently Asked Questions (FAQ)

Will using AI for Douyin talking-head voiceover get my account restricted? No tool can guarantee unrestricted traffic. Platforms require labeling AI-generated content; declaring it upon posting is mandatory per rules. Traffic depends more on content quality and completion rate. Using your own voice and original content is a safer approach.

Do I need to record audio myself for this skill? Only one clear reference audio is needed (or clone a voice in the service client). After that, every video only requires writing the script. Specific requirements for the reference audio follow the official documentation.

How should I record the reference audio for best results? In a quiet room, phone a fist's distance from your mouth, read complete sentences in your normal talking-head voice, no background music or reverb. Write the exact spoken words into ref_text=.

Numbers and English are always mispronounced – what do I do? Write them as you want them heard (e.g., "three point five percent," "A I"), then re-run the same command: only the edited line will be regenerated; other lines reuse previous results.

Can the subtitles be used directly in vertical videos? Yes. --preset koubo limits each subtitle line to 14 characters, optimized for 9:16 vertical video. For shorter lines, use --max-chars 12.

Can it produce English voiceovers? Yes. Translate and rewrite your script into English, then generate. Choose an actor in your account suitable for English or an English reference audio; test the result with single-line preview. For English subtitles, --max-chars 40 is recommended.

Does it require a GPU or model deployment? No. Locally, only Python 3.9+ standard library scripts run; generation happens on the Miragea cloud.

Which AI Agents does it support? Claude Code, Codex, OpenClaw, Cursor, WorkBuddy, and any Agent capable of running Python scripts.

Can I test the skill without an API Key? Yes, use --dry-run. It will output silent placeholder audio and a timeline, allowing you to check script format and flow.

Can I use the voice of a celebrity or streamer? No. Only clone your own voice or voices for which you have explicit written authorization.

Script Syntax

• Between opening --- lines, define each actor on one line: actor_name: actor_id=ACTOR_ID or actor_name: ref=REFERENCE_AUDIO_URL ref_text="Actual spoken text in reference audio"; optionally add speed= (0.25–4), model=expressive|standard, tags=tag1,tag2, language= (language hint for reference audio, used for auto-recognition of reference text).
• ref_text= is only used with ref=; when omitted, the server auto-recognizes the reference text, with different billing—see capabilities.
• Body text: [actor] line or [actor]: line; omitting the tag carries over the previous speaker.
• [pause 0.6] / [pause 0.6] inserts a pause (in seconds); lines starting with #, blank lines, and <!-- comments --> are ignored.
• A single line exceeding audio.max_text_length in capabilities will be rejected by the API; simply split it into shorter lines.
• Per-line audio is cached in out/lines/. Re-running with the same line and settings reuses the cache; when not cached, it submits with the same idempotency key, and the server returns the original task without creating a duplicate. For a fresh version, add --fresh.

Troubleshooting

Symptom	Action
missing_api_key / MIRAGEA_API_KEY is not set	Generate a Key, export MIRAGEA_API_KEY=...; or use --dry-run first
speakers without a voice	Add actor_id= or ref= to that actor
401	Check the Key; do not log the Key
403	Check the account's API access permissions
400 / 413	Fix parameters: mode, tags, speed, line character count; or reduce upload file size, shorten media duration
409	Idempotency key used with different input, or subtitle rate changed; reconfirm and resubmit
429	Insufficient quota or rate limit; wait or top up quota
Timeout / network interruption	The task may still be running: re-run the same command (same idempotency key fetches the original task), or use miragea_audio.py task / wait TASK_ID to continue querying; do not change the key and resend
WAV format mismatch during concatenation	Per-line audio is saved in out/lines/; can be spliced with editing software or ffmpeg

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

Compliance

• Only clone your own voice or voices for which you have explicit written authorization. Do not mimic celebrities, streamers, public figures, or any unauthorized person.
• Follow the "AI-Generated Synthetic Content Labeling Methods" and platform rules (Douyin, Kuaishou, Video Account, Xiaohongshu, Bilibili, etc.): declare or label AI-generated content when publishing.
• Finance, medical, and legal talking-head scripts are for voiceover purposes only; they do not constitute content endorsement. Investment advice, efficacy claims, etc., must be reviewed per platform and industry regulations before publishing.
• scripts/miragea_audio.py is the official client, shipped unchanged; scripts/voiceover.py (script concatenation layer) is original and MIT licensed (see LICENSE.txt). Voiceover and subtitle capabilities are provided by the Miragea Open API.

English Summary

• Talking-head voiceover (口播配音) skill for AI agents: script in, voiceover WAV + SRT subtitles + per-line timing JSON out.
• Voice: your saved voice (actor_id) or voice cloning from a reference audio URL plus its transcript; tone tags and speed 0.25–4.
• Edit one line, re-run, and only that line is regenerated — no re-recording.
• --preset koubo tunes line gaps and short subtitle cues for 9:16 vertical video.
• Python 3.9+ standard library only, no GPU; --dry-run tests offline. Service: Miragea API (https://miragea.ai/v1).

Keywords: talking-head voiceover, talking-head video, voice cloning, AI voiceover, script voiceover, AI talking-head, voiceover script voiceover, voice cloning, text-to-speech, knowledge creator voiceover, finance talking-head, vertical subtitles, subtitle generation, SRT, TTS, voiceover, voice cloning, text to speech