Install media tools

Bootstrap the system binaries other mediaskills depend on. These scripts run in plain bash so they work before uv is installed.

When to use

• First setup — run doctor.sh on a new machine or CI runner before using inspect, audio, video-transformation, etc.
• Missing binary errors — when another skill returns ffmpeg not found or exit code 2.
• Path debugging — use which.sh to confirm which binary the agent shell resolves.
• Not for Python deps — other skills use uv run with PEP 723 inline deps; this skill only installs OS-level tools.

Output paths (all skills)

Script outputs always land under the workspace root .mediaskills/ — never inside .agents/skills/<skill>/:

Paths resolve from the repo root even when you cd into a skill folder. Override with $MEDIASKILLS_DATA_DIR for a custom base directory.

Toolchain overview

doctor.sh checks for ffmpeg, ffprobe, convert (ImageMagick CLI), exiftool, tesseract, yt-dlp, and uv. ImageMagick installs as convert on most platforms — there is no standalone imagemagick binary.

Gotchas

• ImageMagick vs GraphicsMagick — mediaskills expect ImageMagick (convert or magick). Do not substitute GraphicsMagick.
• Debian/Ubuntu convert conflicts — some minimal images ship without ImageMagick; the package name is imagemagick, binary is convert.
• Tesseract language packs — default install is English only. For other OCR languages: brew install tesseract-lang (macOS) or apt install tesseract-ocr-<lang> (Debian).
• ffmpeg builds vary — Homebrew and distro packages include most codecs; static builds from third parties may lack libx264. Prefer official package managers for dev/CI.
• yt-dlp updates frequently — brew upgrade yt-dlp or pip install -U yt-dlp if downloads fail due to site changes.
• uv is optional for bash scripts — only needed to run Python skills (uv run <skill_directory>/scripts/...).

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 (skills/install-media-tools/... is only valid inside this git checkout). Stay in the workspace and pass the absolute script path to bash:

bash <skill_directory>/scripts/doctor.sh

<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 bash.

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

NAME=install-media-tools
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/doctor.sh" ]; then
    SKILL_DIR=$(cd "$d" && pwd)
    break
  fi
done
[ -n "$SKILL_DIR" ] || { echo "mediaskills: $NAME not found" >&2; exit 1; }
bash "$SKILL_DIR/scripts/doctor.sh"

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 (bash, python3) 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 bash and command -v python3 to see whether they resolve at all. If not, tell the user to install those shells/tools rather than retrying with wider permissions. This skill's bash scripts do not need uv. Use doctor.sh to see which media binaries are missing; do not treat command not found as a sandbox problem.
• Only escalate sandbox permissions if the error is explicitly a permission denial (e.g. Operation not permitted, Permission denied).

Recipes

Check what's installed

bash <skill_directory>/scripts/doctor.sh

Example (partial install):

{"ok": true, "op": "install-media-tools.doctor", "data": {"healthy": false, "installed": ["ffmpeg", "ffprobe"], "missing": ["convert", "exiftool", "tesseract", "yt-dlp", "uv"], "platform": "darwin"}, "output_paths": []}

When healthy is false, run install or install missing packages manually.

Install via script (macOS or Debian/Ubuntu)

bash <skill_directory>/scripts/install.sh

• macOS — uses Homebrew: brew install ffmpeg imagemagick exiftool tesseract yt-dlp uv
• Debian/Ubuntu — uses apt-get (may prompt for sudo): ffmpeg imagemagick libimage-exiftool-perl tesseract-ocr, then installs yt-dlp and uv via official install scripts when missing

Re-run doctor.sh after install to confirm.

Locate another skill directory

bash <skill_directory>/scripts/locate-skill.sh --skill speech-captions

Use data.skill_directory from the JSON (a real absolute path) with uv run. Do not pass the <skill_directory> placeholder through to the shell.

List detected tools only

bash <skill_directory>/scripts/detect-tools.sh

Resolve a binary path

bash <skill_directory>/scripts/which.sh --tool ffmpeg
# or
bash <skill_directory>/scripts/which.sh --args '{"tool": "ffmpeg"}'

Manual install (by platform)

macOS (Homebrew)

brew install ffmpeg imagemagick exiftool tesseract yt-dlp uv

Optional OCR languages: brew install tesseract-lang

Debian / Ubuntu

sudo apt-get update
sudo apt-get install -y ffmpeg imagemagick libimage-exiftool-perl tesseract-ocr
# yt-dlp (pick one)
sudo apt-get install -y yt-dlp          # if available in your release
# or: sudo curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp && sudo chmod a+rx /usr/local/bin/yt-dlp
# uv
curl -LsSf https://astral.sh/uv/install.sh | sh

Fedora / RHEL

sudo dnf install -y ffmpeg ImageMagick perl-Image-ExifTool tesseract
pip install yt-dlp   # or use COPR / static binary
curl -LsSf https://astral.sh/uv/install.sh | sh

Verify versions

ffmpeg -version | head -1
convert -version | head -1    # or: magick -version
exiftool -ver
tesseract --version | head -1
yt-dlp --version
uv --version

Troubleshooting

Available scripts

Acceptance checks (agent must pass before delivery)

1. Contract: exit 0, ok: true from doctor.sh / install.sh JSON.
2. Skill gate: re-run doctor.sh after install; required tools for the next skill are listed in installed (not missing).
3. On failure: install missing tools or escalate; do not start media skills while core binaries are missing.

Do not use for

• Media processing itself (install tools, then use other skills)
• Windows auto-install (manual ffmpeg/uv install on Windows)

Related skills

• inspect — first skill to try after doctor passes ffmpeg/ffprobe
• download — requires yt-dlp
• image, speech-captions, vision-analysis — require additional tools from this skill