FFmpeg Media Toolkit

Release status: 2.0.0 — release validation complete on the milestone branch; publication follows merge and final registry checks.

FFmpeg Media Toolkit is a TypeScript package, CLI, and Skills-based plugin for deterministic FFmpeg/FFprobe workflows. It keeps media operations typed, preflighted, transactional, and verifiable on the hosts that can execute them.

Architecture

The supported execution path is:

user request
    ↓
execution-context check
    ↓
behavioral Skill
    ↓
domain Skill and associated script
    ↓
cecilia-ffmpeg / typed media runtime
    ↓
FFprobe preflight → FFmpeg execution → artifact verification
    ↓
structured result or guided recovery

The canonical CLI and the JSON-in/JSON-out Skill scripts use the same typed domain functions and core process boundary. A host that cannot execute local files receives a reproducible plan; it is never told that media was processed without an observed, verified result.

Identity and requirements

• Plugin: cecilialabs-ffmpeg
• npm package: @cecilialabs/ffmpeg
• CLI: cecilia-ffmpeg
• Node.js: >=22
• FFmpeg/FFprobe: 6.1 or newer
• License: MIT

FFmpeg builds differ in their codecs, filters, and hardware backends. Use the toolkit's environment checks for the capability needed by the workflow instead of treating an installed binary as proof that every encoder is usable.

Documentation

These are the authoritative user and agent guides:

• Getting started — first check and first pipeline.
• Installation — global, local, and package-runner setup.
• Agent workflows — context, routing, scripts, CLI fallback, and result verification.
• CLI reference — commands, options, and output behavior.
• Declarative pipelines — YAML, presets, dry-runs, and intermediate files.
• Migration from Bash — semantic mapping for the 21 historical scripts.
• Skill request examples — copy/paste JSON requests.

Domain guides cover video, image, audio, conversion, composition, streaming, diagnostics and repair, batch processing, hardware acceleration, and platform support.

The documentation index and development notes provide the complete map.

Install and run

Recommended public installation:

npm install -g @cecilialabs/ffmpeg
cecilia-ffmpeg doctor

Without a global installation, name the executable explicitly:

npm exec --yes --package=@cecilialabs/ffmpeg -- cecilia-ffmpeg doctor

For a development checkout:

npm install
npm run setup:cli
cecilia-ffmpeg --help

setup:cli builds and links the checkout. It asks before changing shell configuration and never installs system FFmpeg packages. See Installation for the complete flow.

Execution surface order

Use the highest-level surface available for the requested action:

associated Skill script
        ↓ unavailable or unsupported action
global cecilia-ffmpeg
        ↓ unavailable
npm exec --yes --package=@cecilialabs/ffmpeg -- cecilia-ffmpeg ...
        ↓ toolkit capability is insufficient or native syntax is requested
native FFmpeg / FFprobe

Operational scripts accept one JSON request on stdin and emit one structured result envelope on stdout. The request context controls whether the operation may inspect files, execute scripts, install dependencies, or write media.

CLI at a glance

The stable grammar includes:

cecilia-ffmpeg doctor
cecilia-ffmpeg probe <input>
cecilia-ffmpeg environment <check|install|version|capabilities>
cecilia-ffmpeg video <action> ...
cecilia-ffmpeg audio <action> ...
cecilia-ffmpeg image <action> ...
cecilia-ffmpeg convert <file|batch> ...
cecilia-ffmpeg compose <concat|transition|slideshow> ...
cecilia-ffmpeg diagnose <input>
cecilia-ffmpeg repair <timestamps|normalize> <input>
cecilia-ffmpeg stream <camera|file> ...
cecilia-ffmpeg pipeline <file> <validate|print|run>

The complete command surface and global options are in the CLI reference. Pipeline execution is namespaced under pipeline; there is no separate top-level pipeline command.

Safe media behavior

File-producing operations share these rules:

• FFprobe input inspection when stream properties affect correctness;
• destination and input/output collision checks before expensive work;
• no implicit overwrite;
• sibling temporary files and transactional finalization;
• structured warnings and error codes;
• FFprobe verification of the final artifact.

Use --dry-run to inspect a plan without running a mutating FFmpeg operation. A dry-run or planned response is not a completed artifact. Use --json when a caller needs one machine-readable result document on stdout; human progress and diagnostics stay on stderr.

Pipelines

cecilia-ffmpeg pipeline pipeline.yaml validate
cecilia-ffmpeg pipeline pipeline.yaml print
cecilia-ffmpeg pipeline pipeline.yaml run --dry-run
cecilia-ffmpeg pipeline pipeline.yaml run

Pipeline files validate against the v1 schema, expand local presets, resolve relative paths from the pipeline file, preflight the final output, and execute typed domain steps in order. Intermediate files are isolated and removed unless --keep-temp is explicit. See Declarative pipelines.

Skills

The plugin ships ten Skills:

ffmpeg-onboarding       environment and installation readiness
ffmpeg-workflow         natural-language routing and verified outcomes
ffmpeg-environment      versions, capabilities, and media inspection
ffmpeg-video-editing    trim, speed, image-to-video, and resize
ffmpeg-audio            tracks, silence, and telephony
ffmpeg-conversion       single-file and batch conversion
ffmpeg-composition      concat, transitions, and slideshows
ffmpeg-streaming        camera capture and network delivery
ffmpeg-diagnostics      diagnosis and observation-driven repair
ffmpeg-pipelines        YAML pipelines and reusable presets

See the Skill catalog for the activation boundaries, associated scripts, references, and request examples. The agent workflow guide explains how these Skills cooperate across regular Chat, Work, Codex, IDE, and terminal contexts.

Package and plugin distribution

The npm package contains the compiled CLI and library, Skills, documentation, schemas, plugin metadata, and branding assets. Repository-only test, setup, validation, and release helpers are not shipped in the tarball.

Check the package and manifest with:

npm run verify:plugin
npm run build
npm run verify:package

Development validation

Install dependencies before running the repository checks:

npm install

The milestone gate is:

npm run validate

The publication-quality v2 gate is:

npm run validate:release

It adds the v2 release contract, clean npm tarball installation, package inspection, and real environment/media/CLI/Skill smoke flows. A passing local gate is evidence for this checkout only; it does not publish the package.

It starts with verify:foundation, which protects package identity, strict TypeScript configuration, global CLI options, required repository files, and the single process-execution boundary. It then runs the runtime, CLI, Skill, documentation, distribution, typecheck, lint, test, build, and package gates.

Useful focused checks are:

npm run verify:foundation
npm run verify:docs
npm run verify:agent-workflows
npm run verify:skills
npm run verify:skill-scripts
npm run check
npm test

Current runtime capability checks and media fixtures are host-dependent. A passing static or TypeScript check does not, by itself, prove that a particular codec, hardware device, or media artifact works on another host.

Project history and roadmap

The roadmap records the agent-first migration and the remaining release gate. The changelog separates current guidance from historical release notes. Development notes retain durable architecture, compatibility, and migration decisions; generated validation transcripts are not treated as current execution instructions.