mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-17 06:26:31 +03:00
Magnus HedemarkandGitHub
f92cf52b25
Repairs public FFmpeg evidence references, adds named capability checks, and expands deterministic failure-path coverage. Closes #428.
48 lines
3.4 KiB
Markdown
48 lines
3.4 KiB
Markdown
# Learning FFmpeg Without Memorizing Recipes
|
|
|
|
FFmpeg is best understood as a graph of media transformations. An input URL is demuxed into streams, streams may be selected and either copied or decoded, decoded frames can pass through audio/video filters, encoders turn processed frames back into packets, and a muxer writes those packets to an output URL. `ffprobe` is the inspection tool that tells you what the container and streams actually contain.
|
|
|
|
## The practical mental model
|
|
|
|
- A **container** such as MP4, Matroska, MPEG-TS, or WAV packages one or more streams and their metadata.
|
|
- A **codec** describes the encoded elementary stream, such as H.264, AV1, AAC, Opus, or PCM.
|
|
- A **stream** is one typed track, usually video, audio, subtitles, data, or attachments.
|
|
- **Remuxing** changes the container while copying encoded streams. It is fast and avoids generation loss, but only works when the target container accepts those streams.
|
|
- **Transcoding** decodes and re-encodes. It enables filtering and format changes, but costs time and can reduce quality.
|
|
- **Mapping** makes stream selection explicit. Use it whenever multiple inputs, multiple tracks, or complex filters make automatic selection ambiguous.
|
|
- A **filtergraph** is a directed graph of named inputs, filters, and outputs. A labeled output from `-filter_complex` must be mapped explicitly.
|
|
|
|
## A reliable operating loop
|
|
|
|
1. Inspect: `ffprobe -v error -show_format -show_streams -of json input.mkv`.
|
|
2. Decide: remux, stream-copy, transcode, filter, or combine inputs.
|
|
3. Verify capabilities: `ffmpeg -formats`, `-codecs`, `-encoders`, `-filters`, and `-hwaccels`.
|
|
4. Build a minimal command with explicit stream selectors and output options.
|
|
5. Run without overwriting first, capture stderr, and probe the output.
|
|
6. Test playback and the intended downstream consumer. A successful exit code and valid container are not universal compatibility proof.
|
|
|
|
## Learning path
|
|
|
|
Start with inspection and the command line, then understand stream selection and copy/transcode. Add simple filters before learning labeled filtergraphs. Next learn seeking, timestamps, concat, metadata, subtitles, pipes, and shell loops. Only then move to streaming, hardware acceleration, and complex debugging.
|
|
|
|
## What local testing changed
|
|
|
|
The local macOS Homebrew FFmpeg 8.1.2 build successfully generated and probed an H.264/AAC MP4. A subsequent scale/fps/text-filter experiment failed because this build did not contain `drawtext`. That failure is part of the lesson: online recipes are not portable promises. Check the installed build and verify the final artifact.
|
|
|
|
## Implications
|
|
|
|
FFmpeg becomes predictable when commands are treated as typed pipelines rather than incantations. Most difficult failures occur at boundaries: stream selection, option scope, timestamps, filter availability, codec/container constraints, shell escaping, or hardware/software memory transfer. Make those boundaries explicit and debugging becomes a sequence of observable checks.
|
|
|
|
SOURCES (SKILL NAVIGATION)
|
|
references/core-model-and-command-anatomy.md
|
|
-> Detailed model of containers, streams, codecs, option scope, mapping, and copy/transcode.
|
|
|
|
references/filters-and-transformations.md
|
|
-> Filtergraph construction and audio/video transformation boundaries.
|
|
|
|
references/intermediate-workflows.md
|
|
-> Inspection, joining, metadata, scripting, and streaming workflows.
|
|
|
|
references/advanced-operations-and-safety.md
|
|
-> Hardware acceleration, timestamps, reproducibility, and diagnosis.
|