agentleFS
yyert123yyert123/miragea-skills/screen-recording-voiceover/SKILL.md

screen-recording-voiceover

Skill0 starsChanged 2 days agoMITView on GitHub

Turn a silent screen recording (product demo, tutorial, walkthrough, bug repro) into a narrated video in one command. Finds the steps in the recording, helps write one line per step, voices each line with a saved or cloned voice, starts every line exactly at its step, speeds up or freezes frames automatically when a line runs long ("freeze-sync"), mixes optional ducked music, normalizes loudness and writes SRT/VTT captions (optionally burned in). Use when the user wants to add AI voiceover or narration to a screen recording, demo or tutorial video, sync a script to on-screen actions, or narrate a Screen Studio / Loom / OBS / QuickTime export. English-first; voice by Miragea.

  • Reads credentials

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Check MIRAGEA_API_KEY is set (never print it).

    line 25
  2. Distinctive:

    Check the timing without spending anything:

    line 38
  3. Distinctive:

    If it still does not fit, the video holds the last frame of that step until the sentence ends, then continues.

    line 70

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Screen recording voiceover

The slow part of narrating a screen recording is not the voice, it is the sync: lining each sentence up with the click it describes, and fixing the places where the sentence is longer than the action. This skill does both automatically and never lets narration drift or overlap.

When to use

  • "Add a voiceover to this demo / tutorial / screen recording."
  • "I recorded my screen silently, narrate it" or "I don't want to use my own voice / accent."
  • "Make the narration match what happens on screen."

Steps

  1. Check MIRAGEA_API_KEY is set (never print it). Voice: ask once for the user's Miragea voice id, or a public URL of a clip of their voice plus its exact words. Suggest export MIRAGEA_VOICE_ID=... so it is never asked again. Only clone a voice the user owns or has permission to use.
  2. Find the steps and create a script template:

    python3 scripts/scenes.py demo.mp4      # -> demo.frames/*.jpg, demo.frames/steps.json, demo.script.txt
  3. Look at the frames in demo.frames/ (you can read images) and write one clear sentence per step into demo.script.txt after each timestamp, replacing the # step comment. Stay within the ~N words hint so the line fits before the next step. Merge, move or delete steps freely. If the user gave their own script, put its sentences at the matching timestamps instead.
  4. Check the timing without spending anything:

    python3 scripts/voiceover.py demo.mp4 demo.script.txt --dry-run

    Shorten any line marked will freeze if the user wants zero frozen frames.

  5. Render:

    python3 scripts/voiceover.py demo.mp4 demo.script.txt --voice VOICE_ID            # captions as files
    python3 scripts/voiceover.py demo.mp4 demo.script.txt --burn --music bed.mp3      # burned captions + ducked music
  6. Give the user the paths from the printed JSON: video (narrated MP4), voice_track (WAV for their editor), srt/vtt. Mention frozen_seconds if it is above zero.
  7. To change a line, edit the script and run step 5 again: unchanged lines come from the cache for free.

Script format

[00:00] Welcome to Acme. Here is the dashboard you see after signing in.
[00:04] Click New Project, type a name, and choose the team that should own it.
[01:02.5] That's it. Your project is ready.

Accepted timestamps: [mm:ss], [h:mm:ss], mm:ss.s, 12.5s. Lines starting with # are comments.

How the sync works

  • Each line starts exactly at its timestamp; 0.25 s of breathing room is kept before the next step.
  • A line longer than its slot is sped up, at most --max-speed (default 1.15x, still natural).
  • If it still does not fit, the video holds the last frame of that step until the sentence ends, then continues. Later lines shift by the same amount, so sync is never lost.
  • Captions are timed from the actual spoken length of each line (2 lines x 42 characters max).
  • Loudness is normalized to about -16 LUFS (YouTube/web standard). Music, if given, is ducked under speech.

Options

FlagDefaultWhat it does
--voice ID / --ref-url URL --ref-text TEXTenvSaved Miragea voice, or clone from a public clip (exact text = cheaper 1x rate)
--modelexpressiveor standard
--max-speed1.15Max speed-up before freezing frames
--burnoffBurn captions into the video
--music FILEnoneBackground music, looped and auto-ducked
--keep-audiooffKeep the recording's own sound, quietly, under the voice
--dry-runShow the slot plan with an estimated speaking rate; no API calls
-o FILEVIDEO.voiceover.mp4Output path; the original is never modified

Cost and limits

Speech is billed per character by Miragea (1x with a saved voice or exact reference text; live rates at GET https://miragea.ai/v1/capabilities). A 3-minute demo is usually 2,000-3,000 characters. Each line must be under 2,000 characters. Reference clips must be public URLs until Miragea's upload endpoint ships.

Troubleshooting

  • no timestamp / not after the previous line -> fix the script line named in the error.
  • no voice chosen -> pass --voice or set MIRAGEA_VOICE_ID.
  • 401 key wrong, 402 top up at miragea.ai, 429 wait and re-run (cached lines are not re-billed).
  • Too many or too few steps from scenes.py -> --threshold 0.02 (more) / 0.08 (fewer), --min-gap.

See examples/ for a real script, the plan JSON and the captions it produced.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.