Inspect

Read-only media inspection. Use this skill when you need metadata without changing files.

When to use

• This skill — ffprobe metadata, duration, resolution, batch comparison tables, structured JSON for agent reasoning.
• audio / image / video-transformation — when you need to transform media (trim, transcode, resize). Run inspect first to confirm codecs and duration before destructive operations.
• Raw ffprobe — fine for one-off queries, but these scripts return consistent JSON the agent can parse reliably.

Gotchas

• Container vs stream duration — ffprobe format.duration is authoritative for most files; individual stream durations can differ when audio/video lengths don't match (bad mux, trailing silence). Prefer format.duration for edit boundaries.
• No video stream — audio-only files return empty resolution; resolution.py reports width/height as null, not an error.
• Variable frame rate (VFR) — avg_frame_rate in probe JSON may differ from r_frame_rate. For frame-accurate edits, inspect both before assuming CFR.
• Corrupt or partial files — moov atom not found means an incomplete MP4 (common with interrupted downloads). Re-download or remux; probing cannot recover metadata.
• Image "video" streams — some still formats appear as a single-frame video stream; duration may be N/A or 0.04 seconds.

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/describe.py --input "<path-to-media>"

<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 inspect.
3. Otherwise search standard install locations and confirm the script exists:

NAME=inspect
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/describe.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/describe.py" --input "<path-to-media>"

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, 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 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

Quick metadata check

uv run <skill_directory>/scripts/describe.py --input /path/to/clip.mp4

Example result:

{"ok": true, "op": "inspect.describe", "data": {"format": "mov,mp4,m4a,3gp,3g2,mj2", "duration": "12.500000", "size": "1048576", "video": {"codec": "h264", "width": 1920, "height": 1080}, "audio_codecs": ["aac"]}, "output_paths": []}

Full structured probe (for programmatic use)

uv run <skill_directory>/scripts/probe.py --input /path/to/clip.mp4

Returns complete ffprobe JSON in data — all streams, tags, bit rates.

Compare before/after a transcode

uv run <skill_directory>/scripts/compare.py --input-a original.mp4 --input-b transcoded.mp4

Check data.a vs data.b for duration drift, resolution change, or size reduction.

Batch inventory a folder

uv run <skill_directory>/scripts/batch_probe.py --paths clip1.mp4 clip2.mp4 clip3.wav

Use data.rows for a table. Rows with error indicate unreadable paths.

Answer a specific question (agent workflow)

uv run <skill_directory>/scripts/ask.py --input clip.mp4 --question "Does this file have an audio track?"

Returns full probe JSON plus your question — the agent reads data.probe.streams and answers.

Troubleshooting

Available scripts

Acceptance checks (agent must pass before delivery)

1. Contract: exit 0, ok: true.
2. Spot-check: duration/streams/codecs answer the user's question; use compare.py when verifying a transform result against its source.
3. On failure: re-probe or escalate; do not invent metadata.

Do not use for

• Modifying or transcoding media (use audio, image, or video-transformation)
• Downloading from URLs (use download)
• Generating captions from speech (use speech-captions)

Related skills

• install-media-tools — install ffprobe/ffmpeg
• audio, video-transformation, image — processing after inspection