Skip to content

RTY2345RR/miragea-agent-skills / skills/miragea-voiceover

miragea-voiceover

Verified

AI 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.

FileKindSize
SKILL.mdskill md5.7 KB
---
name: miragea-voiceover
description: "AI 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."
license: MIT
metadata:
  version: "0.1.0"
  requires: "miragea-voice-mcp MCP server (uvx --from git+https://github.com/RTY2345RR/miragea-voice-mcp miragea-voice-mcp) and a MIRAGEA_API_KEY"
  keywords: "ai voiceover skill, claude code voiceover, text to speech skill, srt subtitles, voice cloning"
---

# 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 config `env` block. 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's `tags`, which are the only valid emotion/style labels.
- `max_text_length` per request.
- `subtitles` formats 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 named `part-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. Call `miragea_get_task(task_id, wait=true, output_path=...)`. **Never resubmit.**
- `request_failed` with an `idempotency_key`: retry the same tool with the same `idempotency_key` and identical input (for `miragea_text_to_speech` / `miragea_transcribe`).
- `captions_error` after a successful voiceover: the audio is saved. Run `miragea_transcribe` on `audio_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 `.srt` or `.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`, `-3` suffixes automatically).
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 323kUpdated Claude CodeCodexVerifiedInstall