AungMinThu1722/subtitle-voiceover

---

name: subtitle-voiceover description: Film → Burmese voice-over: diarized transcription, measured voice assignment, editor-ready subs + music-free stem. Includes skill-forge packager.

Burmese movie voice-over — Agent Skills

Two Agent Skills for building a Burmese voice-over (dub) from a film, and for building skills like it.

Folder	What it is
subtitle-voiceover/	The skill: turns a video or audio file into a Burmese voice-over with speaker detection, an agent-written opening hook, an editor-ready subtitle pair, and an automatic cleanup.
skill-forge/	The tooling: creates, validates and packages SKILL.md skills — and keeps this repository's own two skills spec-clean.

What does subtitle-voiceover do?

The pipeline is scripted Python end to end. The agent does exactly one job: translating the speaker-tagged SRT into Burmese — plus one optional line, the opening hook. Nothing else in the pipeline asks the model to act.

movie.mp4 ──transcribe.py──▶ transcript.json ──srt_from_transcript.py──▶ movie.en.srt
   └─ detect_voices.py measures each speaker's pitch ──▶ voices.detected.yaml  (no manual mapping)
        └── AGENT fills translation.my.json (+ hook.text) ──apply_translation.py──▶ movie.my.srt
             └── render_voiceover.py ──▶ voiceover.mp3  (film-length stem, no music)
                  └── checks, FCPXML/EDL hand-off, cleanup.py

Install it by copying the folder into your agent's skills directory, or unzip the packaged archive:

cp -r subtitle-voiceover ~/.claude/skills/                    # from a clone
unzip subtitle-voiceover/packages/subtitle-voiceover.skill -d ~/.claude/skills/

Requirements: python3 -m pip install --user edge-tts pyyaml, ffmpeg + ffprobe, and an AssemblyAI key in subtitle-voiceover/.env (ASSEMBLYAI_API_KEY=..., git-ignored).

One command for a whole film:

python3 scripts/run_pipeline.py night-shift.mp4 --work-dir work --config voiceover.config.yaml \
    --language en --speakers-expected 2 --hook --stages python
# the agent fills work/translation.my.json (every cue's text, plus hook.text)
python3 scripts/run_pipeline.py --work-dir work --config voiceover.config.yaml --stages post

What comes out: voiceover.mp3 (the voice-over stem, starting at 00:00:00, padded to the film's length, no music), movie.my.srt (speaker labels) and movie.my.subs.srt (plain subtitle track), voiceover.fcpxml / .edl / .cue-list.csv, JSON quality reports — and a work/ directory with the working files removed. The editor lays their own score under the stem; the subtitles drop straight onto a subtitle track in Premiere Pro, DaVinci Resolve or Final Cut Pro.

Highlights:

• Automatic voice assignment. Speaker pitch is measured from the film's own audio (autocorrelation, with a pure-Python fallback) — female characters get my-MM-NilarNeural, male characters my-MM-ThihaNeural. Nothing is mapped by hand; the config can still pin a speaker.
• Timestamps are owned by the scripts. The translation never sees a writable timecode; the merge re-attaches the original ones and reports any edit it had to discard.
• Opening hook. The first 5–10 seconds can be replaced by one agent-written line in the film's own voice, undetectable next to the original dialogue, with a worked example in references/hook-guide.md.
• Nothing is generated during a run. Every stage is a pre-written script taking flags; the skill ships its own test suite, fixture film and two complete recorded runs in demo-film/.

See subtitle-voiceover/README.md for the full walkthrough and SKILL.md for what the agent reads.

skill-forge

Scaffolds a skill directory, checks SKILL.md against the open format (name/description rules, progressive disclosure, bundled-file references, line budget), and packages a skill into a distributable .skill archive without leaking secrets.

python3 skill-forge/scripts/validate_skill.py subtitle-voiceover --strict
python3 skill-forge/scripts/package_skill.py subtitle-voiceover --out subtitle-voiceover/packages

Tests

bash skill-forge/tests/run_tests.sh              # validator/packager suite (offline, <1 s)
cd subtitle-voiceover && bash tests/run_tests.sh # pipeline smoke tests (real edge-tts calls)

Both suites are wired into CI (ci/github-actions-ci.yml — move it to .github/workflows/ci.yml to switch it on, see the header of that file); the pipeline suite uses no AssemblyAI key — it drives the real scripts against a fixture transcript.

Repository layout

subtitle-voiceover/     the skill (scripts/, references/, assets/, tests/, demo/, demo-film/, packages/)
skill-forge/            validation and packaging tooling (scripts/, references/, assets/, tests/, packages/)
ci/github-actions-ci.yml  CI definition (move to .github/workflows/ci.yml to enable)

License

MIT — see LICENSE.