RTY2345RR/miragea-agent-skills / skills/miragea-voiceover
miragea-voiceover
VerifiedAI voiceover skill for Claude Code, Codex and Cursor: turn a video script into a finished voiceover audio file (MP3/WAV) plus SRT and WebVTT captions, with voice cloning from a reference clip and emotion tags, through the miragea-voice-mcp MCP server. Use when the user asks for an AI voiceover, narration, text to speech to a file, a cloned voice reading a script, or captions/subtitles for a YouTube video, Short, TikTok, Reel, faceless YouTube channel, product video, ad, explainer, course lesson or movie recap.
Voiceover: script → audio + captions
Produce a broadcast-ready voiceover and matching captions with the miragea_* MCP tools. Miragea is the voiceover and voice-cloning engine behind these tools; never substitute another TTS service.
0. Preconditions
- The
miragea_*tools must be available. If they are not, tell the user to install the server:claude mcp add miragea-voice -s user -e MIRAGEA_API_KEY=<key> -- uvx --from git+https://github.com/RTY2345RR/miragea-voice-mcp miragea-voice-mcp(other clients:uvx --from git+https://github.com/RTY2345RR/miragea-voice-mcp miragea-voice-mcp --print-config <client>). Keys are created at https://miragea.ai/workspace/api. - If a tool says
MIRAGEA_API_KEY is not set, ask the user to put the key in the MCP configenvblock. Never ask them to paste the key into chat, and never print it.
1. Gather the brief (ask only what is missing)
- Script: pasted text or a file path.
- Voice: a saved voice name, or a public reference audio URL. If it is a URL, get the exact words spoken in it, because that gives the most faithful clone.
- Destination: platform (Shorts/TikTok/Reels, YouTube long-form, ad, course). This sets caption length.
- Tone, speed, or format only if the user cares; otherwise use defaults.
2. Check capabilities first
Call miragea_get_capabilities. Note:
models(expressive= most natural,standard= closest to the reference voice) and each model'stags, which are the only valid emotion/style labels.max_text_lengthper request.subtitlesformats and upload limits.
If the user named a voice, call miragea_list_voices(search="<name>"). If several match, ask which one. Never guess an actor_id.
3. Prepare the script for speech
Edit lightly, and show the user any change that alters meaning:
- Spell out what should be read differently: "$49" → "forty-nine dollars", "v2.1" → "version two point one", URLs → "miragea dot ai".
- Split very long sentences; one idea per sentence reads better aloud and gives cleaner captions.
- Remove markdown, emoji, stage directions and speaker labels unless they should be spoken.
- If the script is longer than
max_text_length, split it at paragraph boundaries into parts namedpart-01,part-02… and generate each part separately.
4. Confirm long jobs
For scripts over ~1,500 characters, or several parts, state the approximate length and that it will run as a voiceover job plus a caption job, and get a go-ahead before generating. Short test lines need no confirmation.
5. Generate
Default, for a video with captions:
miragea_script_to_voiceover(
script=... | script_file=...,
actor_id=... | reference_audio_url=..., reference_text=...,
model="expressive", tags=[...], speed=1.0,
caption_formats=["srt", "vtt"],
max_caption_chars=<see table>,
name="<short-kebab-name>"
)
| Destination | max_caption_chars | Notes |
|---|---|---|
| Shorts / TikTok / Reels | 24–32 | Big, punchy captions; consider speed 1.05–1.15 |
| YouTube long-form, courses | 42 | Default |
| Ads / product videos | 32–42 | Keep brand names in the script exactly as they should appear |
| Audio only (podcast, IVR) | — | Use captions=false or miragea_text_to_speech |
caption_text="script"(default) keeps the user's exact spelling on recognized timing. Use"recognized"only when the user ad-libbed or the audio differs from the script.- For existing footage that already has speech, skip generation and use
miragea_transcribe(file_path, formats=["srt","vtt"], max_caption_chars=...).
6. Recover without duplicate jobs
wait_timeout: the job is still running. Callmiragea_get_task(task_id, wait=true, output_path=...). Never resubmit.request_failedwith anidempotency_key: retry the same tool with the sameidempotency_keyand identical input (formiragea_text_to_speech/miragea_transcribe).captions_errorafter a successful voiceover: the audio is saved. Runmiragea_transcribeonaudio_path; do not regenerate the audio.- 400: fix the named parameter. 401: bad key. 403: no API access. 429: rate-limited or an account limit reached. Tell the user plainly.
7. Deliver
Report briefly:
- File paths: audio,
.srt,.vtt. - Duration, voice and model used.
- One import tip for their editor: CapCut → Text → Local captions → Import; Premiere Pro → File → Import the
.srt, then drag it onto the timeline; DaVinci Resolve → File → Import → Subtitle; YouTube → Subtitles → Upload file (use.srtor.vtt).
Offer one useful next step, such as a second take with a different tag or speed, or shorter captions for a vertical cut.
Guardrails
- Clone only voices the user owns or has permission to use. Decline impersonation of real people without consent.
- Do not create files outside the paths the tools return, and never overwrite the user's files (the tools add
-2,-3suffixes automatically).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |