Video Transformation

ffmpeg-based video operations: editorial cuts, transcoding, scaling, muxing, and derivative exports. Outputs land in the workspace root .mediaskills/generated/ unless you pass --output. Override base path with $MEDIASKILLS_DATA_DIR.

When to use

• This skill — trim, concat, transcode, scale, proxy, frame/audio extraction, GIF, replace audio, and similar ffmpeg transformations.
• inspect — read metadata first (duration, codecs) before choosing trim boundaries or transcode settings.
• timecode — frame-accurate timecode math when working in HH:MM:SS:FF or HH:MM:SS;FF instead of seconds.
• audio — normalize or process audio before replace_audio.py.
• subtitles — mux soft subtitles without burning; use this skill when the container needs re-wrapping.

Choosing an operation

Transcoding and editorial trims share the same toolchain — probe first, then pick copy vs re-encode based on whether you need frame-accurate cuts or a new codec.

Gotchas

• Stream copy vs re-encode — trim.py and trim_multi.py try -c copy first (fast, lossless cuts on keyframes). If that fails, they fall back to H.264/AAC re-encode. Cuts may snap to nearest keyframe when copying.
• Concat codec mismatch — concat.py also tries copy first; mixed codecs/resolutions trigger a re-encode fallback.
• Replace audio length — -shortest ends when the shorter of video or audio ends. Trim or pad audio first if lengths must match exactly.
• GIF size — to_gif.py caps width at 480px and 10 fps; long clips produce large files. Trim first for previews.
• Transcode codec strings — pass codec and bitrate separately (--codec libx264 --bitrate 1M). The script normalizes common agent mistakes like h264@1M.
• Transcode vs replace audio — transcode.py re-encodes streams from a single input. Use replace_audio.py when audio comes from a separate file.

Running scripts

This skill's scripts live in scripts/ alongside this file. Before running any script, resolve its absolute path from this skill's own directory — do not assume the shell cwd is the skill folder, the repo root, or the workspace. Stay in the workspace (so media paths resolve) and pass the absolute script path to uv run:

uv run <skill_directory>/scripts/trim.py --input "<path-to-media>" --start 5 --end 12.5

<skill_directory> is a placeholder. Never pass those angle brackets to the shell — the command will fail. Replace it with a real absolute directory before invoking uv run.

How to get that directory (do this yourself; do not ask the user first; do not skip the skill):

1. If your tools showed a filesystem path when loading this SKILL.md, strip SKILL.md and use that folder.
2. If you already ran another mediaskills script (for example .../audio/scripts/extract.py), this skill is a sibling of that folder: same parent, directory name video-transformation.
3. Otherwise search standard install locations and confirm the script exists:

NAME=video-transformation
for d in \
  "$HOME/.agents/skills/$NAME" \
  "$HOME/.cursor/skills/$NAME" \
  "$HOME/.codex/skills/$NAME" \
  "$HOME/.claude/skills/$NAME" \
  "$PWD/.agents/skills/$NAME" \
  "$PWD/.cursor/skills/$NAME" \
  "$PWD/skills/$NAME"
do
  if [ -f "$d/SKILL.md" ] && [ -e "$d/scripts/trim.py" ]; then
    SKILL_DIR=$(cd "$d" && pwd)
    break
  fi
done
[ -n "$SKILL_DIR" ] || { echo "mediaskills: $NAME not found" >&2; exit 1; }
uv run "$SKILL_DIR/scripts/trim.py" --input "<path-to-media>" --start 5 --end 12.5

Prefer absolute paths for --input / --output when cwd is uncertain.

Missing binaries vs permissions

Before running any script, treat these two failures differently:

• If a required binary (uv, ffmpeg, ffprobe) reports No such file or directory or command not found: this is a missing or unreachable binary, not a permissions issue. Escalating sandbox permissions will not fix it. Run command -v uv, command -v ffmpeg, and command -v ffprobe to see whether they resolve at all. If not, install or re-link them (install-media-tools doctor/install) rather than retrying with wider permissions.
• Only escalate sandbox permissions if the error is explicitly a permission denial (e.g. Operation not permitted, Permission denied).

Recipes

Trim a section

uv run <skill_directory>/scripts/trim.py --input /path/to/clip.mp4 --start 5 --end 12.5

Use output_path from the JSON result for the next step.

Cut several segments then join

1. trim_multi.py with segments → returns segment_paths (real files like clip_segment_0.mp4).
2. concat.py --paths with those exact paths from step 1. Never invent filenames.
3. Report the concat output_path from the result.

uv run <skill_directory>/scripts/trim_multi.py --input clip.mp4 --segment 0:3 --segment 5:8
uv run <skill_directory>/scripts/concat.py --paths .mediaskills/generated/clip_segment_0.mp4 .mediaskills/generated/clip_segment_1.mp4

Transcode for delivery

uv run <skill_directory>/scripts/transcode.py --input master.mov --codec libx264 --bitrate 5M --output deliverable.mp4

Replace audio track

When video and audio live in different files (e.g. after audio normalization):

uv run <skill_directory>/scripts/replace_audio.py --input video.mp4 --audio normalized.wav --copy-video

Do not use transcode.py for external audio — it only re-encodes a single file's streams.

Trim then transcode

1. trim.py → note output_path.
2. transcode.py --input <trim output> --codec libx264 --bitrate 2M.

Low-res proxy for review

uv run <skill_directory>/scripts/proxy.py --input master.mp4

640px wide, ultrafast x264, CRF 28.

Troubleshooting

Available scripts

Acceptance checks (agent must pass before delivery)

1. Contract: exit 0, ok: true, every output_paths entry exists and is non-empty.
2. Probe: inspect.describe / compare on each media output — duration, codec, resolution, and streams match the request.
3. Spot-check: open or sample the deliverable (trim window correct, scale dimensions, audio present after mux).
4. On failure: fix flags and retry; do not present unprobed transforms as done.

Do not use for

• Read-only metadata (use inspect)
• Audio-only pipelines (use audio)
• Caption/subtitle authoring (use speech-captions / subtitles)

Related skills

• inspect — probe before transforming
• timecode — timecode conversions
• audio — process audio before muxing
• subtitles — soft-subtitle mux workflows
• install-media-tools — install ffmpeg