Skip to main content
Agent skill

Storyboard Av Mix

Muxes per-shot storyboard video with Chinese and English voice-over by retiming video to match VO duration (setpts), writing Video-Chinese/ and Video-English/ (matched by shot id 01, 02, …). Use when the user wants storyboard A/V mix, storyboard A/V mix, VO dubbing mix, video retime to audio, Video-Chinese, Video-English, bilingual VO on cut video, or batch mux Video/ + Chinese/ + English/.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Storyboard Av Mix when an AI agent needs a reusable SKILL.md workflow for this job: Muxes per-shot storyboard video with Chinese and English voice-over by retiming video to match VO duration (setpts), writing Video-Chinese/ and Video-English/ (matched by shot id 01, 02, …). Use when the user wants storyboard A/V mix, storyboard A/V mix, VO dubbing mix, video retime to audio, Video-Chinese, Video-English, bilingual VO on cut video, or batch mux Video/ + Chinese/ + English/.

When not to use it

Skip Storyboard Av Mix when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/storyboard-av-mix
# Save SKILL.md to ~/.claude/skills/storyboard-av-mix/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/storyboard-av-mix/SKILL.md. For a shared project, commit the folder at .claude/skills/storyboard-av-mix/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Storyboard Av Mix skill for this task: Use Storyboard Av Mix when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

70/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
61/100
Source signals
70/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Storyboard AV Mix

Take a work directory with **per-shot** video and bilingual VO. For each shot, **retime the video to the full VO duration** (audio master), drop original video audio, mux, and write language-specific folders.

| Input | Path | |-------|------| | Shot video | `<root>/Video/<shot-id>.*` | | Chinese VO | `<root>/Chinese/<shot-id>.*` | | English VO | `<root>/English/<shot-id>.*` |

| Output | Path | |--------|------| | Chinese mux | `<root>/Video-Chinese/<shot-id>.<video-ext>` | | English mux | `<root>/Video-English/<shot-id>.<video-ext>` |

## Rules

When this skill applies, read and follow [skill-dependency-manager](../skill-dependency-manager.md) — run scripts as documented, install missing tools into `.dependency/`.

1. **VO timing is immutable.** Never stretch, shrink, pad, trim, or `atempo` the voice-over. Duration of the VO file is the master clock. 2. **Video serves audio.** Only change video duration (FFmpeg `setpts`) so it equals that shot’s VO length, then mux. 3. Drop all audio from the source video; replace with the VO track. Prefer `-c:a copy`; if the container cannot hold the VO codec (e.g. WAV→MP4), encode AAC **without** changing length. 4. **Do not downgrade video.** `setpts` requires a re-encode, but match the source: codec family (H.265 Main10 when source is 10-bit HEVC), `pix_fmt`, bitrate, color tags, and HDR side data (mastering display / MaxCLL). Copy container + video-stream metadata from the source clip. 5. Match shots by **filename stem** (`01.mp4` ↔ `01.wav`). 6. Batch only via `.ai/storyboard-av-mix/mix.py` — do not hand-write FFmpeg mux/retime commands. 7. Never overwrite inputs under `Video/`, `Chinese/`, or `English/`.

## Quick Start

From project root:

```bash .dependency/python/python .ai/storyboard-av-mix/mix.py path/to/<root> ```

Single language:

```bash .dependency/python/python .ai/storyboard-av-mix/mix.py path/to/<root> --lang chinese ```

Per shot / language the script:

1. Probes VO duration (source of truth) and video duration 2. Applies `setpts=PTS*(vo_dur/video_dur)` — stretch or compress **video only** (plus short freeze-tail so video ≥ VO) 3. Muxes with `-shortest` so **container duration == VO duration** 4. Writes `<root>/Video-Chinese|` or `Video-English/` / `<shot-id>.<same-ext>`

## Layout

``` <root>/ Video/ 01.mp4 02.mp4 Chinese/ 01.wav 02.wav English/ 01.wav 02.wav Video-Chinese/ # written by this skill 01.mp4 02.mp4 Video-English/ 01.mp4 02.mp4 ```

Typical `<root>` is a [storyboard-tts](../storyboard-tts/SKILL.md) audio dir that also has a sibling or nested `Video/` of cut clips — confirm the folder that contains `Video/`, `Chinese/`, and `English/`.

## Common Flags

| Flag | Notes | |------|--------| | `root` | Work dir with `Video/`, `Chinese/`, `English/` | | `--lang` | `both` (default), `chinese`, `english` |

Existing outputs are overwritten. Missing VO for a language → skip that job with a warning. Missing video → skip shot.

## Agent Notes

1. Audio first: if durations disagree, change **video**, never VO. 2. Prefer one `mix.py` run for the whole board. 3. Re-encode must preserve source quality tags (Main10 / HDR / bitrate) — never force 8-bit H.264. 4. Chat summary: `<root>`, jobs done / skipped, paths to `Video-Chinese/` and `Video-English/`. 5. Upstream VO usually from [storyboard-tts](../storyboard-tts/SKILL.md); this skill does not synthesize speech. 6. Missing Python/FFmpeg → populate `.dependency/` per skill-dependency-manager, retry same command.

## Tests

From repo root:

```bash .dependency/python/python .ai/storyboard-av-mix/test_mix.py ```

## Related

- [storyboard-tts](../storyboard-tts/SKILL.md) — bilingual VO under `Chinese/` / `English/` - [storyboard](../storyboard/SKILL.md) — source markdown

Manual CLI examples: [cli/storyboard-av-mix.md](../../../cli/storyboard-av-mix.md)

Intended uses

  • Use Storyboard Av Mix when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.