magnus919_agent-skills/ffmpeg

FFmpeg Expert Skill

A practical FFmpeg skill for inspecting local media, planning reviewable video or podcast edits, rendering safely, and accepting outputs from evidence rather than command success alone.

Why Install This Skill

FFmpeg failures often happen at boundaries: the wrong stream is selected, a cut lands on an unexpected keyframe, a filter is absent from the installed build, timestamps drift, or a technically valid output fails in its real destination. Editorial work adds another risk: sparse frames, silence intervals, and imperfect transcripts can look more conclusive than they are.

This skill provides a repeatable intake-to-acceptance workflow. It separates technical measurements from editorial judgment, preserves originals, makes cuts reviewable in an edit decision list, and records what was actually checked.

What You Get

Core guidance

Path	Purpose
SKILL.md	Trigger boundaries, capability routing, evidence classes, and the core workflow
references/core-model-and-command-anatomy.md	Containers, streams, codecs, mapping, option scope, and timestamps
references/filters-and-transformations.md	Simple and complex filtergraphs, audio/video filters, and graph debugging
references/intermediate-workflows.md	Trimming, concat, metadata, subtitles, scripting, pipes, and streaming
references/advanced-operations-and-safety.md	Hardware, synchronization, reproducibility, and operational safety
references/command-cookbook.md	Short, assumption-labeled commands
references/learning-summary.md	Learning progression and consolidated mental model
references/source-inventory.md	Original primary/secondary source inventory and evidence boundaries
references/local-verification.md	Version- and host-specific FFmpeg 8.1.2 experiments

Media editing and evidence guidance

Path	Purpose
references/media-intake-and-manifest.md	Authorization, source identity, probe capture, output contracts, privacy, and preservation
references/video-inspection-and-visual-evidence.md	Bounded frame/clip sampling and defensible visual claims
references/editorial-video-editing.md	Transcript-assisted decisions, sequencing, treatments, and review gates
references/audio-and-podcast-editing.md	Mechanical edits, signal cleanup, editorial audio decisions, and listening checks
references/ffmpeg-edit-decision-lists.md	EDL semantics, validation, keyframe status, mapping, and command planning
references/media-verification-and-acceptance.md	Layered probe, decode, content, editorial, and downstream acceptance evidence
references/media-failure-modes.md	Diagnosis matrix, safe recovery, and stop rules
references/media-research-source-index.md	Claim-to-source map for official docs, standards, experiments, and heuristics

Copyable templates

Path	Purpose
templates/media-intake.json	Parseable source, stream, timing, contract, privacy, and assumption manifest
templates/edit-decision-list.json	Parseable source ranges, evidence, confidence, treatments, mapping, and verification
templates/video-inspection-report.md	Fixed-section technical and sampled-evidence report
templates/visual-review-packet.md	Timestamped review samples with attribution and coverage limits
templates/podcast-edit-plan.md	Mechanical, signal-processing, and editorial audio plan
templates/media-acceptance-report.md	Criterion-by-criterion evidence and release verdict
templates/research-experiment-record.md	Versioned, reproducible command experiment record

Existing automation and evals

Path	Purpose
scripts/ffmpeg-preflight	Tool status, inventory counts, and named filter/encoder/hwaccel checks
scripts/test_ffmpeg_preflight.py	Deterministic tests for the capability preflight
scripts/fixtures/ffmpeg-8.1.2-inventories.json	Small version-labeled parser fixture
scripts/media-intake	Read-only input inventory with bounded ffprobe metadata
scripts/extract-review-frames	Bounded timestamp frame extraction for human or vision review
scripts/render-edl	Validate an EDL and emit a non-executing FFmpeg command plan (review before multi-source rendering)
scripts/audio-inspect	Read-only audio metadata inspection with bounded probing
scripts/media-verify	Compare input/output probe documents against basic criteria
evals/evals.json	Output-quality cases for core FFmpeg, media evidence, video, podcast, EDL, safety, and acceptance behavior

Quick Start

Install FFmpeg with your platform package manager and inspect the source before choosing an edit:

ffmpeg -version
ffprobe -version
ffprobe -v error -show_format -show_streams -of json input.mp4

For a media editing task:

1. Copy templates/media-intake.json into a private task workspace and record the source and output contract.
2. Collect only the bounded frame, clip, transcript, or signal evidence needed for the decision.
3. Copy templates/edit-decision-list.json or templates/podcast-edit-plan.md and review consequential cuts.
4. Render to a new path with overwrite refusal while exploring.
5. Copy templates/media-acceptance-report.md, probe and review the result, then test the intended player, editor, service, or archive boundary.

Before using a version-sensitive recipe, inspect the local capability:

scripts/ffmpeg-preflight --filter scale --filter loudnorm --encoder libx264 --hwaccel videotoolbox

Named checks report each capability as present or absent. Exit code 1 means a required tool/probe failed; 2 means a requested capability is absent from a usable inventory. Add --json for machine-readable output.

Triggers

Load this skill for:

• Media intake, FFprobe manifests, stream/container/timestamp inspection, or output contracts
• Remuxing, transcoding, filtering, trimming, joining, extraction, subtitles, or synchronization
• Bounded review-frame or audio-evidence preparation from supplied/authorized local media
• Transcript-assisted video edits, reviewable EDLs, or deterministic render plans
• Podcast cutting, silence/noise analysis, loudness measurement, and audio cleanup
• Build capability checks, overwrite-safe batch work, output verification, or failure diagnosis

Use another capability first for online media/transcript acquisition, semantic image interpretation, HTML-authored HyperFrames composition, platform publishing/API work, DRM, or rights clearance.

Requirements

• ffmpeg and ffprobe on PATH for execution
• A shell with careful filename and filter-expression quoting
• A vision-capable or human reviewer for semantic claims about extracted images
• Listening playback for editorial audio acceptance
• Network access only for linked documentation or an explicitly requested network protocol
• Hardware acceleration only with the relevant device, drivers, compiled support, and a verified end-to-end path