damionrashford/media-os

---

Why use Media OS

Built for broadcast engineers, video automation developers, live producers, and AI media pipeline engineers who want Claude’s natural-language interface over the real toolchain — not yet another wrapper that fails on the third edge case.

• FFmpeg is unforgiving. One missing flag — -movflags +faststart, -sc_threshold 0, aac_adtstoasc, hvc1 vs hev1 — ships a broken file. Every skill front-loads the gotchas LLMs get wrong from training data alone, and mosafe lints commands before they run.
• Broadcast tools aren’t scriptable. NDI, DeckLink, Dolby Vision, HDR10+, OpenTimelineIO — production-grade but not designed for natural-language interfaces. Media OS provides scripted entry points for all of them, with the right metadata sidecar mux handled.
• AI media is a license minefield. Every Layer 9 AI skill ships a hard filter: only Apache-2 / MIT / BSD / GPL models. NC, research-only, and commercial-restricted models are explicitly documented-and-dropped.
• Routed dispatch is deterministic. The router skill auto-loads on any production intent and forces the four-step contract (read _shared.md, read mode file, compose, spawn). No opportunistic skill selection; no forgotten cross-cutting rules.

---

Install

Option A — Install the full plugin (recommended)

/plugin marketplace add damionrashford/media-os
/plugin install media-os@media-os

All 109 skills (96 tool + 13 workflow) plus the routing layer load under /media-os:. The router auto-triggers on intent. The bin/ CLIs (moprobe, moqc, mosafe) are added to your PATH. Hooks register on session start.

Option B — Copy a single skill

Every skill at skills// is a sealed self-contained folder — SKILL.md + optional scripts/ + references/, no cross-skill imports.

git clone https://github.com/damionrashford/media-os.git /tmp/media-os
cp -r /tmp/media-os/skills/ffmpeg-hdr-color   ~/.claude/skills/
cp -r /tmp/media-os/skills/obs-websocket      ~/.claude/skills/
cp -r /tmp/media-os/skills/hdr-dovi-tool      ~/.claude/skills/

Standalone skills load under /ffmpeg-hdr-color, /obs-websocket, etc. No plugin namespace, no marketplace dependency.

Requirements

---

Quick examples

The most-requested production tasks and the skill chain Media OS routes them to:

---

Routed modes

Media OS implements the modes pattern — a routed multi-agent dispatch system. The router skill auto-loads on any media production intent and forces a deterministic four-step contract.

How dispatch works

USER: "encode this master for HLS with VMAF ≥ 95"
        ↓
Router skill auto-loads on intent
        ↓
Dispatch contract (4 steps, every dispatch):
  1. Read modes/_shared.md from disk
  2. Read modes/streaming-distribution.md from disk
  3. Compose prompt = _shared + mode + user_ask
  4. Agent(subagent_type="delivery", prompt=composed, description="streaming-distribution")
        ↓
delivery specialist runs in isolated context:
  - probes input, derives bitrate ladder
  - mosafe-wraps every ffmpeg invocation
  - encodes tiers, runs moqc per tier
  - packages HLS / DASH, applies cbcs DRM
  - writes artifact to deterministic path
        ↓
${MEDIA_WORK_DIR}/modes/streaming-distribution/{date}_{slug}/

Mode files are read fresh from disk on every dispatch — never cached, never paraphrased. Cross-cutting rules (mosafe-wrap every ffmpeg call, license filter on AI models, deterministic output paths, idempotent re-runs) live in modes/_shared.md and apply to every specialist.

The 13 modes

Each mode declares its specialist, trigger phrases, required + optional inputs, output schema, and quality bar. Modes are the configurable surface — adding a task type is one new mode file plus one routing-table row.

⚠️ = approval-gated (operator confirms target spec before dispatch).

The 13 modes are 1:1 with the 13 portable workflow-* skills in skills/ — same domain coverage, two delivery surfaces. The modes layer is the orchestrated path (auto-route, dispatch contract, deterministic output paths); the workflow-* skills are the copy-a-folder portable path.

Chained dispatch

Multi-step intents run sequentially with artifact paths passed forward. The router knows about:

Observability

Every dispatch logs one JSON line to ${MEDIA_WORK_DIR}/modes/dispatch.log via the SubagentStop audit hook — timestamp, mode, specialist, duration, exit status, transcript path.

tail -F ${MEDIA_WORK_DIR}/modes/dispatch.log | jq

---

Specialists

7 domain agents with pre-loaded skill sets and tool restrictions. Spawn from any Claude conversation, or let the router dispatch them.

---

Safety hooks

5 lifecycle hooks fire automatically. Four catch the FFmpeg mistakes that take a pipeline down; one audits every dispatch.

---

CLI toolbelt

Three commands added to your PATH on install. Use them from any shell, Makefile, or CI job.

# Compact media inspection
moprobe source.mov                                # one-line summary
moprobe --color source.mov                        # HDR / color pipeline summary
moprobe --json source.mov                         # full ffprobe JSON

# Quality gate (VMAF + SSIM + PSNR + loudness + freeze/black/silence)
moqc --ref source.mov --out encoded.mp4 --vmaf-min 95 --format json

# FFmpeg pre-flight lint (wrap every ffmpeg call in CI)
mosafe ffmpeg -i in.mov -c:v libx264 -crf 23 -b:v 5M out.mp4 || exit 1

All three exit non-zero on failure — drop them in CI directly. The plugin also runs an incoming-watch background monitor that polls INCOMING_MEDIA_DIR for new stable files and surfaces them to Claude with a suggested probe.

---

Skills catalog

96 tool-and-technique skills across 9 layers, plus 13 workflow- recipe skills* (the portable counterparts of the 13 routed modes).

Every skill is a sealed folder. Browse the full catalog at skills/.

License filter on AI skills

Every model shipped in a Layer 9 skill is Apache-2 / MIT / BSD / GPL. Restricted models — XTTS-v2, F5-TTS, CodeFormer, DAIN, SVD, Wav2Lip, SadTalker, Surya, FLUX-dev, Meta MusicGen, SDXL/SD3 base — are explicitly documented-and-dropped in each AI skill’s references/LICENSES.md. You don’t accidentally ship something you can’t monetize.

---

Configuration

userConfig fields (set at /plugin install time)

External tool requirements (per skill)

Install only what your workflows actually need. Every helper script is stdlib-only Python 3 (runs via uv run) and shells out to the real CLI.

---

Architecture

• Skills are sealed. One folder, one SKILL.md, optional scripts/ and references/. No cross-skill imports — copy a folder, get a working skill.
• SKILL.md bodies ≤ 500 lines. Deep reference material lives in references/.md and loads on demand via progressive disclosure.
• Helper scripts are stdlib Python 3. PEP 723 inline deps (uv run ready), --dry-run, --verbose, exact shell command printed to stderr before executing.
• Gotchas front-loaded. Every SKILL.md lists production traps LLMs get wrong from training data alone — wrong pixel format, missing -movflags +faststart, -sc_threshold 0 for HLS, aac_adtstoasc for TS→MP4, ASS &HAABBGGRR color order, zscale=t=linear→format=gbrpf32le sandwich for PQ ↔ HLG, fieldmatch → decimate IVTC order, repeat-headers=1 for streaming HEVC, hvc1 vs hev1 tags, cbcs for unified DRM.
• Modes are deterministic. Mode files are loaded fresh from disk on every dispatch. The router skill auto-loads on intent and forces the four-step contract (read _shared.md, read mode file, compose, spawn). No opportunistic skill selection.

→ Full contributor reference: CLAUDE.md. Modes pattern reference: github.com/damionrashford/modes.

---

Contributing & releases

Contributions welcome — see CONTRIBUTING.md.

• 🐛 Report a broken skill / hook / CLI
• 💡 Propose a new skill
• 🛤️ Propose a new workflow / mode
• 💬 Discussions

Author a new skill locally:

# Scaffold
uv run .claude/skills/skill-creator/scripts/scaffold.py \
  --name  \
  --output skills \
  --with-scripts --with-references \
  --description "What it does. Use when the user asks to X, Y, or Z."

# Validate (matches CI)
uv run .claude/skills/skill-creator/scripts/validate.py skills/

Exit codes: 0 clean · 2 warnings only (acceptable) · 1 spec violation (must fix). CI at .github/workflows/validate.yml runs the same checks plus modes-layer validation.

Releases: see CHANGELOG.md and GitHub releases. Current: v2.1.0. Third-party marketplaces do not auto-update — pull new versions with /plugin marketplace update media-os.

---

FAQ

---

License & related

MIT. FFmpeg itself is LGPL 2.1+ / GPL 2+ depending on build (ffmpeg.org/legal.html). Each companion tool and AI model carries its own license — see each skill’s references/.

• Media OS project site — marketing site, full docs, llms.txt for AI agents
• Claude Code documentation — the runtime
• Claude Code plugins spec
• Agent Skills specification
• Modes pattern — the dispatch architecture this plugin implements

---