mediaskills

# Agent routing guide

Start here when choosing a mediaskills skill. Install with:

```bash
npx skills add timelapsetech/mediaskills@v0.1.5 --skill <name>
```

Machine-readable catalog: [`skills/index.json`](skills/index.json). Regenerate with `python scripts/list_ops.py --write`.

## Decision tree

```
Need metadata only (no file changes)?
  └─ inspect

Need to change video (cut, transcode, resize, mux, GIF, frame grab)?
  └─ video-transformation

Need audio-only edits?
  └─ audio  (mux back to video → video-transformation replace_audio.py)

Need SMPTE timecode math (DF/NDF, fps conversion)?
  └─ timecode

Need captions from speech?
  └─ speech-captions → captions-compliance / subtitles

Need subtitle file ops (SRT/VTT shift, burn-in)?
  └─ subtitles

Need broadcast caption compliance (SCC, SMPTE-TT, validation)?
  └─ captions-compliance

Need shot boundaries or midpoint frames?
  └─ shots

Need program segmentation (blacks, silence, acts)?
  └─ program-master

Need exhaustive frame-accurate burned-in dialogue / forced narrative?
  └─ forced-narrative-exact

Need on-screen text / vision analysis workflow?
  └─ vision-analysis  (agent analyzes frames; scripts merge JSON)

Need to download from URL?
  └─ download

Missing ffmpeg / tools?
  └─ install-media-tools  (doctor.sh first)
```

## Running skill scripts

Skills may live under a git checkout (`skills/<name>/`), `$HOME/.agents/skills/<name>/`, `$HOME/.cursor/skills/<name>/`, or a project `.agents/skills/<name>/`. Always invoke scripts by a **real absolute path** to the directory that contains that skill's `SKILL.md`. Do **not** `cd` into the skill folder (media `--input` paths are usually workspace-relative) and do **not** run `scripts/foo.py` against the current working directory.

`<skill_directory>` in recipes is a placeholder. **Never send that token to the shell** (`uv run <skill_directory>/scripts/transcribe.py` will fail). Expand it first.

```bash
# After SKILL_DIR is a real path, e.g. /home/me/.agents/skills/speech-captions
uv run "$SKILL_DIR/scripts/transcribe.py" --input "<workspace-or-absolute-media>"
bash "$INSTALL_MEDIA_TOOLS_DIR/scripts/doctor.sh"
```

Resolve `SKILL_DIR` in this order — search yourself; do not ask the user; do not invent a fallback pipeline:

1. Path reported when this `SKILL.md` was loaded (strip `/SKILL.md`).
2. Sibling of a skill you already ran: if `.../skills/audio/scripts/extract.py` worked, then speech-captions is `.../skills/speech-captions`.
3. Probe standard locations (`$HOME/.agents/skills/<name>`, `$HOME/.cursor/skills/<name>`, `$PWD/skills/<name>`, …) until `SKILL.md` and the target script exist.
4. If you can run `install-media-tools` `locate-skill.sh --skill <name>`, use `data.skill_directory` from its JSON.

Companion files (`profiles/*.json`, references) need the same absolute prefix.

## Missing binaries vs permissions

Treat these two failures differently. Escalating sandbox permissions does **not** install tools.

- If `uv`, `ffmpeg`, `ffprobe`, or another required binary reports `No such file or directory` or `command not found`: it is missing or not on PATH. Run `command -v <tool>`. If it does not resolve, use `install-media-tools` doctor/install (or tell the user to install/re-link) — do not retry with wider permissions.
- Only request sandbox permission escalation when the error is an explicit denial (`Operation not permitted`, `Permission denied`).

## Always do first

1. `bash <install-media-tools_skill_directory>/scripts/doctor.sh` — confirm binaries
2. `inspect` probe/describe — confirm duration, codecs, streams before destructive ops
3. Read the target skill's **Do not use for** and **Acceptance checks** sections in `SKILL.md`

## Always verify before deliver

After every skill step — and again before presenting results to the user — pass these gates. Do not claim complete, compliant, or exact output until they pass.

1. **Contract** — exit code `0`, stdout JSON has `ok: true`, and every path in `output_paths` exists and is non-empty.
2. **Probe transforms** — for media outputs, re-run `inspect` `describe` / `compare` and assert duration, codec, resolution, and stream presence match the request.
3. **Skill gate** — when the skill ships `validate_*`, `doctor`, or QC artifacts, run them and require fail-closed success (`passed: true`, `publication_ready: true`, or zero blocking errors). See each skill's **Acceptance checks**.
4. **Spot-check** — sample content appropriate to the skill (first/last cues, PDF pages, midpoint frames, report row coverage). Structural JSON success is not enough for OCR, ASR, or segment labeling.
5. **On failure** — fix or escalate; never present partial or unvalidated bundles as delivery.

Optional helper for path/duration gates (mediaskills git checkout): `python <mediaskills_repo>/scripts/verify_output.py --from-json <envelope.json> …` (see script `--help`).

## Chaining outputs

Scripts return JSON on stdout. Pass paths from `data.output_path` or `output_paths[]` to the next step **only after** the verify checklist for that step passes.

| From | Field | To |
| --- | --- | --- |
| any transform | `output_paths[0]` | next `--input` (after re-`inspect`) |
| timecode | `data.seconds_realtime` | `video-transformation` `--start` / `--end` |
| speech-captions | SRT path | `captions-compliance` validate/format |
| vision-analysis | `manifest_path` | agent frame analysis → `merge_analysis.py` → **`validate_analysis.py` (required before reports)** |
| program-master | labeled manifest / report bundle | require QC `passed: true` → `forced-narrative-exact` pass scoping |
| forced-narrative-exact | refined JSON / report paths | `validate_report` → deliver md/json/csv/srt |

## Op ID namespaces

| Prefix | Skill |
| --- | --- |
| `inspect.*` | inspect |
| `audio.*` | audio |
| `video.*` | video-transformation |
| `image.*` | image |
| `timecode.*` | timecode |
| `speech_captions.*` | speech-captions |
| `caption.*` | captions-compliance |
| `subtitles.*` | subtitles |
| `download.*` | download |
| `shots.*` | shots |
| `program_master.*` | program-master |
| `forced_narrative_exact.*` | forced-narrative-exact |
| `vision.*` | vision-analysis |
| `install-media-tools.*` | install-media-tools (bash) |

Full list: `python scripts/list_ops.py` or [`docs/OP_NAMESPACES.md`](docs/OP_NAMESPACES.md).

## Workflows

End-to-end recipes: [`docs/workflows/`](docs/workflows/).

## Contract

JSON shape, exit codes, env vars: [`docs/SCRIPT_CONTRACT.md`](docs/SCRIPT_CONTRACT.md).

Common errors: [`docs/ERRORS.md`](docs/ERRORS.md).