Media OS para Claude Code
damionrashford/media-os
Processamento de mídia em linguagem natural com roteamento inteligente de especialistas
Ver no GitHubSistema completo de produção audiovisual multi-agent com 96 skills, 13 modos roteados e 7 agentes especializados. Cobre FFmpeg, OBS, NDI, DeckLink, Dolby Vision e HDR10+, abstraindo a complexidade de flags e metadados de broadcast profissional.
Instalação
npx convez-ai damionrashford/media-os1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Encoding automático para múltiplos formatos (HLS, DASH, ProRes)
- Masterização de conteúdo HDR e Dolby Vision em pipeline
- Automação de feeds NDI e captura DeckLink com PTZ
- Validação e linting de comandos FFmpeg antes de execução
- Integração de IA em workflows de pós-produção broadcast
Veredito

Skill maduro e bem arquitetado para engenheiros de broadcast que precisam de interface em linguagem natural sobre ferramentas profissionais reais. A abstração de gotchas de FFmpeg e suporte a padrões broadcast (HDR, Dolby, NDI) é genuinamente útil, mas exige familiaridade técnica com pipelines de mídia para extrair máximo valor.
README
A tradução para o português deste README ainda está na fila.
Media OS for Claude Code
Routed multi-agent media production for Claude Code. Say what you want — encode this for HLS, master Dolby Vision profile 8.4, set up an NDI feed with a PTZ camera — the router spawns the right specialist with the right tools and the right flags.
96 skills · 13 routed modes · 7 specialist agents · 5 lifecycle hooks · 3 PATH CLIs. MIT licensed. v2.1.0.
🌐 damionrashford.github.io/media-os — marketing site & docs
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,hvc1vshev1— ships a broken file. Every skill front-loads the gotchas LLMs get wrong from training data alone, andmosafelints 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/<name>/ 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
| Requirement | Version | Notes |
|---|---|---|
| Claude Code | ≥ 2.1.60 | Plugin system support |
| Python | ≥ 3.10 | All helper scripts are stdlib-only, run via uv run |
| FFmpeg | Recent full build | brew install ffmpeg · apt install ffmpeg · winget install Gyan.FFmpeg |
| Per-skill CLIs | varies | See Configuration — install only what you use |
Quick examples
The most-requested production tasks and the skill chain Media OS routes them to:
| You say... | Mode dispatched | Skills invoked |
|---|---|---|
| "encode this for HLS, VMAF ≥ 95" | streaming-distribution | ffmpeg-streaming → ffmpeg-quality → media-shaka → ffmpeg-captions |
| "master Dolby Vision profile 8.4 for HLS" | hdr-mastering → streaming-distribution | ffmpeg-hdr-color → hdr-dovi-tool → hdr-hdr10plus-tool → ffmpeg-mxf-imf |
| "upscale + interpolate + denoise" | ai-enhancement | media-upscale → media-interpolate → media-denoise-ai → ffmpeg-transcode |
| "set up NDI feed from OBS with PTZ on cam-2" | live-production | obs-websocket → ndi-tools → ptz-onvif → media-midi → media-dmx |
| "podcast: TTS → mix → normalize → captions" | podcast-pipeline | media-tts-ai → ffmpeg-audio-filter → media-ffmpeg-normalize → ffmpeg-captions |
| "VFX ACES conform (EXR → master)" | vfx-pipeline | vfx-oiio → vfx-openexr → ffmpeg-ocio-colorpro → ffmpeg-transcode |
| "Premiere ↔ Resolve round-trip" | editorial-interchange | otio-convert → ffmpeg-probe → media-mediainfo → ffmpeg-transcode |
| "QC + deliver IMF for Netflix" | analysis-quality → broadcast-delivery | moqc → ffmpeg-mxf-imf → media-shaka |
| "lipsync + face animation" | ai-enhancement | media-lipsync → media-tts-ai → ffmpeg-transcode |
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.
| Mode | Specialist | Domain |
|---|---|---|
live-production | live | OBS + NDI + DeckLink + PTZ + RTMP/SRT/RIST/WHIP |
streaming-distribution | delivery | HLS / DASH / CMAF / LL-HLS + cbcs DRM + CDN upload |
broadcast-delivery ⚠️ | delivery | DPP AS-11 · Netflix IMF · ProRes · MXF OP1a (approval-gated) |
editorial-interchange | architect | Premiere ↔ Resolve ↔ Avid ↔ FCP via FCPXML / AAF / EDL / OTIO |
ai-enhancement | architect | Upscale, interpolate, denoise, matte, depth, lipsync |
ai-generation | architect | Image / video / TTS / music gen (license-filtered) |
podcast-pipeline | architect | Record / script / re-master → EBU R128 + captions |
vfx-pipeline | architect | EXR / DPX / USD through ACES + OCIO to ProRes 4444 / J2K IMF |
hdr-mastering | hdr | HDR10, HDR10+, Dolby Vision profiles 5 / 7 / 8.4, HLG, SDR tone-map |
vod-post-production | encoder | H.264 / H.265 / AV1 / ProRes / DNxHR with VMAF gate |
analysis-quality | qc | VMAF + SSIM + PSNR + loudness + freeze / black / silence |
audio-production | architect | PipeWire / JACK / Core Audio / WASAPI routing, mix, repair, MIDI/OSC |
acquisition-archive | probe | Probe-batch, ingest-card, tether-capture, archive-verify |
⚠️ = 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:
| You say... | Chain |
|---|---|
| "encode + deliver this master for HLS" | vod-post-production → streaming-distribution |
| "upscale + interpolate + deliver" | ai-enhancement → vod-post-production → streaming-distribution |
| "HDR master + broadcast deliver" | hdr-mastering → broadcast-delivery |
| "QC + deliver" | analysis-quality → (if pass) → broadcast-delivery |
| "VFX → HDR master" | vfx-pipeline → hdr-mastering |
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.
| Agent | Color | Specialization |
|---|---|---|
architect | 🔵 blue | Plans end-to-end pipelines before any command runs |
probe | 🟢 green | Forensic file inspection — color, HDR side-data, GOP, captions, timecode |
qc | 🟦 teal | Automated quality gate — VMAF + SSIM + PSNR + loudness + freeze/black/silence |
hdr | 🟣 purple | HDR10, HDR10+, Dolby Vision, PQ ↔ HLG, ACES, OpenColorIO |
encoder | 🟠 orange | Rate control, pixel format, container flags, hardware acceleration |
live | 🔴 red | OBS + RTMP/SRT/RIST/WHIP + NDI + DeckLink + PTZ |
delivery | 🟡 yellow | HLS/DASH packaging + cbcs DRM + CDN upload + IMF/MXF |
Safety hooks
5 lifecycle hooks fire automatically. Four catch the FFmpeg mistakes that take a pipeline down; one audits every dispatch.
| Event | What it does |
|---|---|
SessionStart | Probes installed CLIs + FFmpeg build flags (libvmaf, libzimg, libvidstab, librist, libplacebo, hwaccel) and surfaces gaps before Claude recommends anything it can't run |
UserPromptSubmit | When you name a media path, auto-probes it and drops the summary (codec, color, HDR side-data, duration, GOP) into context |
PreToolUse(Bash) | Flags in-place overwrites · missing -movflags +faststart · missing -sc_threshold 0 on HLS · missing aac_adtstoasc on TS→MP4 · conflicting -crf + -b:v |
PostToolUse(Bash) | Re-ffprobes every FFmpeg output; catches zero-duration / truncated files before they ship |
SubagentStop | Logs every routed dispatch (mode, specialist, duration, exit status) to ${MEDIA_WORK_DIR}/modes/dispatch.log |
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).
| # | Layer | Count | Coverage |
|---|---|---|---|
| 1 | FFmpeg complete | 37 | transcode, streaming, filters, HDR, codecs, protocols, broadcast MXF/IMF, DRM, 360°, VapourSynth |
| 2 | Professional companion tools | 17 | yt-dlp, MKVToolNix, Shaka Packager, GPAC, MediaInfo, ImageMagick, ExifTool, SoX, HandBrake, whisper.cpp, Demucs, PySceneDetect, ffmpeg-normalize, MoviePy, alass, cloud upload, GNU parallel |
| 3 | OBS Studio | 4 | obs-websocket v5, profile authoring, C++ plugin SDK, Python/Lua scripting |
| 4 | Streaming frameworks | 2 | GStreamer pipelines, MediaMTX all-protocol server |
| 5 | Broadcast IP + editorial + HDR dynamic | 6 | NDI, OpenTimelineIO, dovi_tool, hdr10plus_tool, Blackmagic DeckLink SDI, gphoto2 DSLR tether |
| 6 | Control protocols + system audio | 9 | MIDI 1.0 + 2.0 UMP, OSC, DMX512/Art-Net/sACN via OLA, VISCA + ONVIF PTZ, PipeWire/JACK/Core Audio/WASAPI |
| 7 | VFX stack | 3 | Pixar USD, OpenEXR, OpenImageIO |
| 8 | Computer vision + WebRTC | 6 | OpenCV, MediaPipe Tasks, W3C WebRTC spec, Pion (Go), mediasoup (Node SFU), LiveKit (Go SFU) |
| 9 | 2026 open-source AI media | 12 | Real-ESRGAN · SwinIR · HAT · RIFE · FILM · BiRefNet · rembg · RVM · Kokoro · OpenVoice · Piper · StyleTTS2 · Riffusion · ComfyUI · FLUX-schnell · Kolors · LTX-Video · CogVideoX · LivePortrait · LatentSync · Depth-Anything · MiDaS · PaddleOCR · DeepFilterNet · CLIP · SigLIP |
| W | Workflow recipe skills | 13 | 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)
| Field | Purpose | Default |
|---|---|---|
MEDIA_WORK_DIR | Scratch directory for intermediate renders | /tmp/media-os |
DEFAULT_ENCODE_PRESET | x264 / x265 default preset | medium |
DEFAULT_VMAF_TARGET | QC gate threshold | 93 |
OBS_WEBSOCKET_URL / _PASSWORD | OBS control endpoint + auth | ws://localhost:4455 |
HUGGINGFACE_TOKEN | AI skill model access | empty |
SHAKA_KEY_SERVER_URL | DRM key server for Shaka Packager | empty |
CLOUDFLARE_STREAM_TOKEN · MUX_TOKEN_ID/SECRET · BUNNY_CDN_TOKEN | CDN upload credentials | empty |
INCOMING_MEDIA_DIR | Watcher target | empty (disabled) |
LIVE_STREAM_URL | Stream-health monitor target | empty (disabled) |
RENDER_QUEUE_URL / _DIR | Render farm monitor | empty (disabled) |
SAFETY_REQUIRE_CONFIRM_OVERWRITE | Toggle pre-FFmpeg overwrite guard | true |
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.
| Skill family | External tool | Required build flags |
|---|---|---|
ffmpeg-* (most) | ffmpeg, ffprobe, ffplay | A full-featured build |
ffmpeg-stabilize | ffmpeg | --enable-libvidstab |
ffmpeg-quality | ffmpeg | --enable-libvmaf |
ffmpeg-hdr-color | ffmpeg | --enable-libzimg |
ffmpeg-rist-zmq | ffmpeg | --enable-librist |
ffmpeg-ocio-colorpro | ffmpeg + OpenColorIO | OCIO link |
ffmpeg-* (GPU tonemap) | ffmpeg + libplacebo | --enable-libplacebo |
media-ytdlp | yt-dlp | — |
media-whisper | whisper.cpp / faster-whisper | — |
media-demucs | demucs | — |
media-mkvtoolnix | mkvmerge / mkvextract / mkvpropedit | — |
media-gpac | MP4Box | — |
media-shaka | packager (Shaka) | — |
media-handbrake | HandBrakeCLI | — |
media-imagemagick | magick (ImageMagick 7+) | — |
media-exiftool | exiftool | — |
media-mediainfo | mediainfo | — |
media-sox | sox | — |
media-scenedetect | scenedetect | — |
media-subtitle-sync | alass / ffsubsync | — |
media-ffmpeg-normalize | ffmpeg-normalize | — |
media-moviepy | moviepy | — |
media-batch | parallel (GNU parallel) | — |
media-cloud-upload | curl / aws / rclone per provider | — |
| Skill | External tool |
|---|---|
hdr-dovi-tool | dovi_tool |
hdr-hdr10plus-tool | hdr10plus_tool |
ndi-tools | NDI Tools runtime (Vizrt / NewTek) |
decklink-tools | Blackmagic Desktop Video driver |
gphoto2-tether | gphoto2 (libgphoto2) |
media-dmx | ola / olad daemon |
otio-convert | opentimelineio |
ptz-onvif / ptz-visca | onvif-zeep / VISCA over serial-or-IP |
media-midi | python-rtmidi |
media-osc | python-osc |
| Skill | External tool |
|---|---|
vfx-usd | usdpython + usdview |
vfx-oiio | oiiotool, iinfo, iconvert |
vfx-openexr | OpenEXR CLI + libOpenEXR |
Layer 9 AI skills require Python + a model runtime (PyTorch or similar). Each AI skill's references/ documents exact model install paths and GPU requirements. Most benefit significantly from a CUDA / Metal / ROCm-capable GPU. All models are Apache-2 / MIT / BSD / GPL.
Architecture
- Skills are sealed. One folder, one
SKILL.md, optionalscripts/andreferences/. No cross-skill imports — copy a folder, get a working skill. - SKILL.md bodies ≤ 500 lines. Deep reference material lives in
references/<topic>.mdand loads on demand via progressive disclosure. - Helper scripts are stdlib Python 3. PEP 723 inline deps (
uv runready),--dry-run,--verbose, exact shell command printed to stderr before executing. - Gotchas front-loaded. Every
SKILL.mdlists production traps LLMs get wrong from training data alone — wrong pixel format, missing-movflags +faststart,-sc_threshold 0for HLS,aac_adtstoascfor TS→MP4, ASS&HAABBGGRRcolor order,zscale=t=linear→format=gbrpf32lesandwich for PQ ↔ HLG,fieldmatch → decimateIVTC order,repeat-headers=1for streaming HEVC,hvc1vshev1tags,cbcsfor 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 <new-skill> \
--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/<new-skill>
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
No. Media OS is MIT-licensed. You pay for the Claude model you use (Anthropic billing) and any paid external tools — most are free (FFmpeg, OBS, GStreamer, MediaMTX); some are paid (Blackmagic DeckLink hardware, NDI HX2 licensing, DRM key servers for Shaka). Each skill's references/ lists licensing.
No. Claude auto-loads only what each task needs, and every skill folder is sealed. Copy a single folder into ~/.claude/skills/ to use one standalone, or install the full plugin for batteries-included mode.
Five hooks run automatically. SessionStart probes installed CLIs and FFmpeg build flags. UserPromptSubmit auto-probes any media path you mention. PreToolUse blocks common FFmpeg foot-guns (in-place overwrites, missing -movflags +faststart, missing -sc_threshold 0 on HLS, missing aac_adtstoasc on TS→MP4 remux, conflicting -crf + bitrate). PostToolUse re-ffprobes every output for zero-duration / truncation. SubagentStop logs every routed dispatch to dispatch.log.
Same domain coverage, two delivery surfaces. Modes are the orchestrated path — the router skill auto-loads on intent, reads modes/_shared.md + the matched mode file, composes a prompt, spawns the specialist, and the artifact lands at a deterministic path. workflow-* skills are the copy-a-folder portable path — sealed self-contained capability declarations you can cp -r into another project without the router. Use modes when you want orchestrated dispatch; use the workflow-* skills when you want one folder you can move.
Every Layer 9 AI skill passes a strict OSI-open and commercial-safe filter (Apache-2, MIT, BSD, GPL only). Restrictive 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.
Media OS does not replace FFmpeg — it gives Claude the right vocabulary, flag combinations, and pre-flight checks for FFmpeg, OBS, GStreamer, MediaMTX, NDI, DeckLink, Dolby Vision, and 50+ other media tools. You still run the real tools; Media OS makes sure the agent calls them with the right arguments, validates the output, and catches the gotchas LLMs get wrong from training alone.
Yes for most skills — FFmpeg, OBS, GStreamer, NDI, DeckLink, MIDI, OSC, DMX all run locally. Internet is required for AI model downloads (first run only, cached after), cloud upload skills, DRM key server skills, and yt-dlp.
macOS (Apple Silicon + Intel), Linux (x86_64 + ARM), Windows (x86_64). Some skills are platform-conditional — audio-coreaudio is macOS-only, audio-wasapi is Windows-only, audio-pipewire and audio-jack are Linux-primary. Each SKILL.md documents platform support.
Yes. Scaffold via the vendored .claude/skills/skill-creator, validate with validate.py, ship a PR. See CONTRIBUTING.md and CLAUDE.md. Every skill is a sealed folder — copy a folder, get a working skill.
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
⭐ If Media OS ships you a working pipeline, leave a star.
Built by Damion Rashford · LinkedIn