Skip to content

cecil-ia-labs/cecilialabs-ffmpeg

v2.0.0MIT

Professional FFmpeg and FFprobe workflows with deterministic CLI, Skills, scripts, hardware acceleration, and declarative media pipelines.

GitHubOpen Website

Changelog

2.0.0 — 2026-09-21 — Agent-first scripts, Skills & release validation

Added

  • Agent-first scripts and Skills roadmap documenting the rejection of a public MCP reverse-proxy/network deployment and the planned v2 migration.
  • Project-level AGENTS.md with repository boundaries, validation rules, and the post-setup branch-and-pull-request workflow.
  • ffmpeg-onboarding Skill for execution-context and FFmpeg readiness checks.
  • ffmpeg-workflow Skill for request routing, preflight, and artifact verification.
  • Milestone 20 shared Skill-script runner with JSON request/result envelopes, context-aware regular-Chat guidance, cancellation, redaction, and safe-path checks.
  • Read-only environment readiness reporting for Node.js, npm, the toolkit, FFmpeg/FFprobe versions, capabilities, hardware metadata, and output-path writability.
  • Explicit global, local, and npm-exec onboarding installation plans with opt-in authorization and post-install checks.
  • Namespaced cecilia-ffmpeg pipeline validation, plan-printing, execution, and inline pipeline parsing for the next pipeline CLI contract.
  • Milestone 22 associated scripts for environment inspection and all six media domain Skills, backed by the shared JSON request/result runner.
  • Canonical intent-routing and JSON request examples covering onboarding, environment, video, audio, conversion, composition, streaming, diagnostics, and pipelines.
  • Skill script catalog verification, executable-bit checks, and per-Skill documentation links for the associated operational entry points.

Milestone 24 — Documentation and development-record cleanup

Added

  • docs/agent-workflows.md as the authoritative guide for execution context, Skill routing, associated scripts, CLI fallback, preflight, and verified artifacts.

Changed

  • README, installation, getting-started, CLI, pipeline, migration, and Skill catalog documentation now share one current execution flow.
  • verify:foundation is restored to the start of npm run validate and now verifies that its own gate remains wired.
  • Documentation verification covers the agent workflow guide and rejects the removed top-level pipeline action there.

Removed

  • Obsolete checked-in validation transcripts and duplicate legacy catalog records that were not current user or agent guidance.

Milestone 25 — v2.0 release validation

Added

  • A publication-quality v2 release gate that runs the full validation matrix, stable release contract, clean npm installation, package inspection, and real environment/media smoke flows.
  • Cross-platform release smoke coverage for FFmpeg/FFprobe readiness, media probing and trimming, the namespaced pipeline grammar, and the associated environment/video Skill scripts.

Changed

  • Synchronized package, plugin, lockfile, source, project identity, and stable contract metadata to 2.0.0.
  • Replaced the v1 release workflow with the v2 release-validation matrix and made publication depend on the complete v2 gate.
  • Strengthened release verification so removed MCP/runtime surfaces and contradictory migration artifacts fail before publication.

Removed

  • Milestone 23 removes the legacy stdio MCP runtime, npm dependency, binary, package export, plugin metadata, schemas, tests, docs, and validation gate.
  • Agent-facing execution is now proven through the associated Skill scripts, the canonical CLI, and the explicit npm-exec fallback.

Compatibility

  • The typed media domains, CLI, package API, Skills, and result contracts remain available; only the legacy alternate agent adapter surface is removed.
  • Historical release entries below remain an immutable record of prior v1 distribution surfaces and are not current execution instructions.

1.3.0 — 2026-09-20 — Milestone 18 — Pipeline & Preset System

Added

  • Declarative YAML pipeline v1 schema and loader.
  • Public cecilia-ffmpeg run <pipeline> command.
  • Sequential typed execution for trim, speed, resize, normalization, roadmap-compatible audio.normalize, and conversion steps.
  • Isolated temporary workspace for intermediate media with optional --keep-temp preservation.
  • Local reusable named presets with nested expansion, unknown-reference errors, and cycle detection.
  • Pipeline-level dry-run that validates schema, input, presets, step order, and final output contracts without fabricating intermediates.
  • Output codec/extension/final-step consistency validation.
  • Final FFprobe codec assertion against the produced artifact.
  • Protection against final-output/original-input path collisions.
  • Cross-command eager output preflight: local file destinations are checked before expensive media work; batch existing=error validates all planned outputs before workers start.
  • Deterministic preset safety limits: 32 nesting levels and 256 expanded concrete steps.
  • Public package API for loading, expanding, validating, and executing pipelines.
  • media_run_pipeline MCP tool, increasing the MCP catalog from 9 to 10 tools.
  • Dedicated ffmpeg-pipelines professional Skill and schema reference, increasing the bundled Skill catalog from 7 to 8.
  • Public pipeline/preset documentation and Getting Started examples.
  • verify:pipeline architecture/release gate and pipeline-specific unit/integration coverage.
  • Direct runtime dependency on js-yaml@^4.3.2.

Architecture

Pipeline execution is an orchestration layer over existing typed domains:

YAML
  -> schema validation
  -> preset expansion
  -> output-contract validation
  -> typed domain steps
  -> shared FFmpeg/FFprobe runtime

The pipeline layer does not invoke child processes directly and does not route MCP through CLI adapters.

Compatibility

  • Existing single-operation CLI/API/MCP behavior remains unchanged.
  • Relative media paths resolve from the pipeline file directory.
  • Software encoding and existing hardware-selection defaults are preserved inside hardware-aware pipeline steps.
  • Pipeline dry-run performs planning/validation only; actual multi-step execution creates real intermediate media in an isolated workspace.

1.2.0 — 2026-09-20 — Milestone 17 — Advanced Hardware Acceleration

Added

  • Typed hardware encoder policy: software|auto|nvenc|qsv|vaapi|videotoolbox.
  • H.264 mappings for NVENC, Quick Sync, VAAPI, and VideoToolbox.
  • VP9 mappings for Quick Sync and VAAPI.
  • Runtime encoder usability probes in addition to FFmpeg compile-time capability discovery.
  • Platform-aware automatic backend preference ordering.
  • Deterministic software fallback with W_HARDWARE_SOFTWARE_FALLBACK.
  • Strict hardware-required mode through --hardware-strict.
  • VAAPI render-device discovery and explicit --hardware-device.
  • NVDEC/CUVID decoder-family capability metadata.
  • Hardware-aware conversion, batch conversion, image-to-video, and upscale/restore paths.
  • Hardware policy on MCP media_convert and media_restore.
  • verify:hardware, hardware unit tests, and FFmpeg-backed integration coverage.

Changed

  • Package/plugin/runtime release line advanced to 1.2.0.
  • Public docs now recommend global npm install -g @cecilialabs/ffmpeg once and use cecilia-ffmpeg ... thereafter.
  • Non-global usage now explicitly selects the CLI with npm exec --yes --package=@cecilialabs/ffmpeg -- cecilia-ffmpeg ....
  • All seven Skills now prefer a matching connected MCP tool, then the global CLI, then explicit npm-exec fallback, and finally native FFmpeg only for unsupported/explicit-native requests.
  • Plugin extension metadata/schema now covers both the MCP server and hardware policy.

Compatibility

  • Software encoding remains the default, so v1.0/v1.1 command behavior is preserved unless hardware is requested.
  • Hardware capability discovery does not by itself count as runtime usability; actual encodes probe the selected backend first.
  • NVDEC/CUVID is reported for discovery/diagnostics but is not silently injected into filter graphs in v1.2.

1.1.0 — 2026-09-20 — Milestone 16 — MCP Server

Added

  • Dedicated cecilia-ffmpeg-mcp stdio server binary.
  • Public @cecilialabs/ffmpeg/mcp package export.
  • Nine MCP media tools backed directly by existing typed domain functions.
  • Stable @modelcontextprotocol/server v2 integration using protocol-aware serveStdio().
  • Zod-derived JSON-native tool schemas, structured MCP results, and toolkit error mapping.
  • MCP request cancellation propagation into the existing media/runtime AbortSignal.
  • MCP unit/integration coverage and verify:mcp architecture gate.
  • Public MCP host configuration and development architecture documentation.

Architecture

The MCP layer is an adapter sibling to the CLI. It does not call CLI actions and does not execute FFmpeg/FFprobe directly; all process execution remains behind the existing core runtime boundary.

1.0.0 — 2026-09-20 — Milestone 15 — Stable CLI Release

Added

  • Stable v1.0.0 package/plugin/runtime version line.
  • Machine-readable stable release contract in specs/stable-release-contract.json.
  • verify:release for semantic version, package/plugin identity, CLI surface, Skills, migration coverage, and no-shell-runtime guarantees.
  • validate:release as the publication-quality superset of the regular validation chain.
  • Public npm publishConfig.access for the scoped package.
  • Stable release architecture and completion checklist.
  • Clean npm tarball installation verifier covering the generated executable and package import.
  • Cross-platform CLI/doctor smoke runner.
  • GitHub Actions v1 release matrix with full Linux validation plus macOS/Windows smoke coverage.

Release policy

Milestone 15 is a stabilization milestone. Public CLI/API changes require explicit compatibility review; new media capabilities are deferred unless they fix a v1 release blocker.

Pre-v1 hardening — Milestone 14.5 — CLI Installation & Release Workflow

Added

  • Interactive npm run setup:cli for contributor build/link setup.
  • link:cli and unlink:cli development commands.
  • Optional, separately consented ~/.bashrc PATH repair when the npm global bin is not already visible.
  • Repository-only scripts/publish-npm.sh release workflow.
  • verify:distribution structural gate.
  • Branded CLI help headline: Cecil-IA Labs · FFmpeg Media Toolkit.

Changed

  • prepack now builds dist/ before npm tarball generation.
  • npm run validate now includes the distribution workflow verifier.
  • Installation docs now distinguish public global install, npx usage, and local contributor linking.
  • Release documentation now formalizes clean-master parity, exact-tarball publication, npm verification, and post-publish Git tagging.

Safety

  • No postinstall hook modifies user shell configuration.
  • Local ~/.bashrc modification requires explicit consent and uses an idempotent managed block.
  • Actual publication is restricted to a clean master matching origin/master.
  • Release/setup scripts remain outside the npm package allowlist.

Validation

Before merge:

npm run validate
npm run setup:cli
./scripts/publish-npm.sh --dry-run --allow-non-master

0.9.9 — Milestone 14 — Documentation & Migration Guide

Added

  • Complete public documentation set for installation, getting started, CLI reference, video, image, audio, conversion, composition, streaming, diagnostics, batch processing, hardware acceleration status, and Bash migration.
  • Full canonical mapping for all 21 legacy Bash utilities.
  • verify:docs documentation coverage gate.
  • Semantic CLI icon catalog.
  • Friendly TTY icons for command help, operation summaries, warnings/errors, and FFmpeg progress.
  • Semantic progress cues for percent, frames, processing FPS, speed multiplier, and ETA.
  • Dedicated semantic UX tests.

Changed

  • Package/plugin version advanced to 0.9.9.
  • Skills updated to the canonical pre-v1 command taxonomy and expanded media capabilities.
  • Human TTY output uses stronger semantic color + icon cues.
  • --no-color now suppresses both ANSI styling and friendly semantic icons.
  • README now acts as the documentation entry point.

Compatibility

  • JSON output remains decoration-free and structurally unchanged.
  • Non-TTY progress remains plain text.
  • video restore, audio attach, and audio add-silence remain documented compatibility aliases.
  • Hardware acceleration documentation does not claim the future Milestone 17 automatic-selection behavior is already implemented.

Validation

Run locally before merge:

npm run validate

0.9.8 — Milestone 13.5 — Media Capability Expansion & CLI Polish

Added

  • First-class image convert and image extract commands.
  • JPEG/JPG source/target conversion support.
  • MP4 as a generic visual conversion target.
  • Audio conversion for WAV, MP3, AAC, M4A, FLAC, Opus, and Ogg through both file and batch engines.
  • Shared contain, cover, and stretch fit semantics with configurable background.
  • Canonical video upscale, video attach-audio, and video add-silence commands.
  • MP4/WebM output selection for applicable video and composition operations.
  • Native zoomin plus explicit custom zoomout transition.
  • Slideshow sequence mode with transitions, include/exclude patterns, and MP4/WebM/GIF/WebP outputs.
  • Brighter human TTY color palette.
  • verify:media-expansion, expanded unit/CLI/integration tests, and Milestone 13.5 documentation.

Compatibility

  • video restore remains available as a compatibility alias for the new canonical video upscale.
  • audio attach remains available alongside video attach-audio.
  • audio add-silence remains available alongside video add-silence.
  • Existing vertical-stack slideshow behavior remains the default style.
  • Existing distance continues to use FFmpeg's native transition; zoomout is not implemented as a dissolve alias.

Changed

  • Package/plugin version advanced to 0.9.8.
  • Generic conversion now models video, image, and audio formats.
  • Composition normalization uses the shared fit engine.
  • Milestone 14 documentation target moved to v0.9.9 after the pre-v1 capability expansion.

Validation

Run locally before merge:

npm run validate

0.9.7 — Milestone 13 — UX, Progress & Agent-Friendly Output

Added

  • Async-scoped FFmpeg progress observer used by CLI actions.
  • Automatic -progress pipe:1 -nostats instrumentation for observable FFmpeg operations.
  • Structured progress fields for frame count, processing FPS, speed multiplier, processed time, percentage, ETA, and completion state.
  • Duration estimation from explicit output ranges, FFprobe preflight metadata, trim offsets, speed factors, and multi-input composition timelines.
  • TTY single-line progress rendering and coarse non-TTY progress checkpoints.
  • --no-progress global CLI option.
  • Structured progress summaries in the JSON result envelope.
  • Human errors now include stable toolkit error codes.
  • Restrained TTY color for human stdout, warnings, and errors with --no-color, NO_COLOR, and FORCE_COLOR support.
  • Milestone 13 unit/integration tests, verify:ux, documentation, and checklist.

Changed

  • Package/plugin version advanced to 0.9.7.
  • npm run validate now includes verify:ux.
  • Output-envelope JSON Schema and public contracts now include optional progress summaries.
  • Batch conversion progress respects the global --no-progress setting.

Agent contract

  • --json keeps human progress off stdout and emits one result envelope.
  • Machine consumers can read typed progress fields instead of scraping FFmpeg terminal statistics.
  • Unbounded live streams omit percentage/ETA rather than fabricating a duration.
  • GitHub Actions remain deferred until alpha completion.

Validation

Run locally before merge:

npm run validate

0.9.5 — Milestone 12 — Test Suite & Media Fixtures

Added

  • Reproducible FFmpeg fixture generator and Git-ignored generated fixture directory.
  • Checked-in fixture manifest describing expected codecs, streams, dimensions, frame rates, timebases, pixel formats, sample rates, and channels.
  • Fixture coverage for H.264, HEVC, VP9, GIF, static WebP, animated WebP, PNG, JPEG, MP3, AAC, PCM WAV, G.711 μ-law, CFR/VFR, missing streams, multiple timebases, resolutions, and pixel formats.
  • FFprobe-backed fixture verification including VFR timestamp-delta checks.
  • Explicit legacy migration map for all 21 Bash scripts.
  • One equivalent integration regression case for every migrated Bash script.
  • verify:test-suite, verify:fixtures, fixtures:generate, and fixtures:clean scripts.
  • Milestone 12 test/fixture documentation and checklist.

Changed

  • Package/plugin version advanced to 0.9.5.
  • npm run validate now verifies test topology and the complete media fixture matrix before TypeScript/lint/Vitest/build/package gates.
  • Project identity version advanced to 0.9.5; test-only fixture contracts remain outside the distribution package.

Regression guarantees

  • Media tests verify FFprobe properties rather than treating output existence as success.
  • Legacy GIF→WebM is asserted as real VP9 WebM.
  • Legacy gsm-ulaw naming is guarded by an explicit G.711 μ-law versus GSM assertion.
  • WebP→PNG regression uses a static WebP decode fixture; animated WebP remains separately guarded through RIFF animation chunks because FFmpeg 7.1.x has incomplete animated-WebP decode support.
  • Legacy “WebSocket” capture is guarded as an HTTP MPEG-TS relay plan.
  • GitHub Actions remain deferred until alpha completion.

Validation

Run locally before merge:

npm run validate

0.9.0 — Milestone 11 — Plugin Packaging & Assets

Added

  • Final portable plugin.json metadata for Agent Plugins 1.0.0.
  • Cecil-IA Labs extension namespace for branding, documentation, skill catalog, and npm identity metadata.
  • Original self-contained light/dark plugin icons, horizontal logo, and two SVG documentation-preview assets.
  • specs/plugin-extension.schema.json documenting the Cecil-IA Labs extension payload.
  • scripts/verify-plugin.mjs for manifest, containment, skill catalog, and asset validation.
  • scripts/verify-package.mjs for npm pack --dry-run --json --ignore-scripts tarball inspection.
  • test/plugin/plugin-package.test.ts and Milestone 11 packaging documentation/checklist.

Changed

  • Package/plugin version advanced to 0.9.0.
  • npm package files allowlist now explicitly includes docs/ and CHANGELOG.md.
  • npm run validate now runs static plugin verification before compile/test gates and tarball verification after build.
  • README, roadmap, project identity, and asset documentation updated for distributable plugin packaging.

Standards

  • The closed Agent Plugins 1.0.0 manifest schema is respected; skills remain in the standard fixed skills/ discovery directory.
  • Branding/documentation metadata is placed under extensions.com.cecilialabs.ffmpeg instead of non-standard top-level fields.
  • GitHub Actions remain deferred until alpha completion.

Validation

Run locally before merge:

npm run validate

0.8.0 — Milestone 10 — Professional-Level Skills

Added

  • Seven professional agent skills: environment, video editing, audio, conversion, composition, streaming, and diagnostics.
  • Portable YAML front matter with precise activation descriptions for every skill.
  • Explicit “do not use” boundaries to reduce cross-domain activation ambiguity.
  • Required-input, preflight, toolkit-command, validation, recovery, safety, and deterministic-behavior sections in every skill.
  • One substantive domain reference document under each skill's references/ directory.
  • scripts/verify-skills.mjs and test/skills/skills.test.ts.
  • Milestone 10 architecture documentation and completion checklist.

Changed

  • Package/plugin version advanced to 0.8.0.
  • npm run validate now includes verify:skills.
  • skills/README.md now documents the installed professional skill set.

Policy

  • Implemented operations prefer @cecilialabs/ffmpeg over arbitrary FFmpeg shell construction.
  • Native FFmpeg is a fallback for unsupported capabilities or explicit native-command requests.
  • GitHub Actions remain deferred until the alpha version is complete.

Validation

Run locally before merge:

npm run check
npm run lint
npm test
npm run build
npm run validate

0.7.0 — Milestone 9 — Streaming & Capture

Added

  • Real stream camera and stream file <input> commands.
  • Typed streaming domain separating source/capture, encoding, container, transport, and destination.
  • Direct HTTP/HTTPS, RTMP/RTMPS, RTSP, SRT, UDP, and TCP planning.
  • URL-scheme/transport compatibility validation and protocol-specific muxer defaults.
  • V4L2, AVFoundation, and DirectShow camera input formats.
  • Low-latency H.264 default plus MPEG-1 video support for legacy JSMpeg-style receivers.
  • AAC, stream-copy, and audio-drop policies.
  • FFprobe preflight for file sources and -re real-time pacing by default.
  • Dry-run planning that does not open camera devices or network destinations.
  • Milestone 9 unit, CLI, and dry-run integration tests.
  • verify:streaming and streaming report JSON Schema.
  • Milestone 9 architecture and legacy migration documentation.

Changed

  • Package/plugin version advanced to 0.7.0.
  • Streaming commands are no longer placeholders.
  • npm run validate now includes the Milestone 9 streaming verifier.
  • The legacy stream-to-websocket.sh behavior is represented accurately as HTTP MPEG-TS output.

Policy

  • Direct WebSocket output is intentionally rejected. WebSocket/browser delivery must use an explicit relay rather than treating HTTP as WebSocket.
  • GitHub Actions remain deferred until the alpha version is complete.

Validation

  • Unit and integration test sources are included.
  • Dry-run integration tests are designed to require FFmpeg/FFprobe but no live network receiver or camera.
  • Final npm run validate is delegated to the configured local Codex Environment before merge.

0.6.0 — Milestone 8 — Diagnostics & Repair

Added

  • Real diagnose, repair timestamps, and repair normalize commands.
  • Typed diagnostic issue/severity model and structured diagnostic report schema.
  • FFprobe structural checks for streams, frame rates, time bases, SAR, pixel format, and WebM codec compatibility.
  • Read-only FFmpeg decode scan with parsing for decode errors, corrupt packets, non-monotonic DTS, PTS/DTS failures, timestamp discontinuities, stream-mapping errors, and filter-graph errors.
  • Optional --log analysis for pre-existing FFmpeg stderr logs.
  • Optional deep freezedetect analysis.
  • Timestamp repair remux and reencode modes.
  • Full video/audio normalization with aspect-preserving scale/pad, square-pixel SAR, CFR, pixel format, AVTB/PTS reset, async audio resampling, and channel-layout normalization.
  • Post-repair FFprobe and diagnostic validation.
  • Milestone 8 unit/integration/CLI test sources and verify:diagnostics.
  • ChatGPT Desktop / Codex Local Environment setup documentation plus codex:setup and codex:cleanup scripts.

Changed

  • Package/plugin version advanced to 0.6.0.
  • Diagnostics and repair commands are no longer placeholders.
  • npm run validate now includes the Milestone 8 diagnostics verifier.

Validated

  • Strict TypeScript compilation of the diagnostics dependency graph with exactOptionalPropertyTypes and noUncheckedIndexedAccess.
  • Real FFmpeg/FFprobe diagnose, normalization, timestamp-repair, reprobe, and deep-freeze smoke runs.
  • Normalized CFR output reports avg_frame_rate=30/1 and r_frame_rate=30/1 in the validation fixture.
  • Full npm-based validation remains delegated to a connected local environment because registry access timed out in the assembly sandbox.

0.5.0 — Milestone 7 — Composition & Filter Graph Engine

Added

  • Real compose concat, compose transition, and compose slideshow commands.
  • Reusable FilterGraphBuilder and composition normalization layer.
  • N-input normalized concat with optional FFmpeg xfade transitions and cumulative offsets.
  • Audio concat and acrossfade handling with auto, preserve, and drop policies.
  • Portable built-in xfade transition catalog replacing the legacy hard dependency on gltransition.
  • Vertical-stack slideshow migration with deterministic image discovery and no shell eval.
  • Composition report schema, CLI/unit/integration test sources, verify:composition, and Milestone 7 documentation.

Fixed

  • Milestone 6 CLI tuning boundary for exactOptionalPropertyTypes: true using a dedicated TuningInput and conditional property emission.
  • Node globals for verifier scripts in ESLint configuration.
  • Unused imports in audio/attach.ts, video/trim.ts, and verify-foundation.mjs.
  • Unnecessary quote escapes in verify-conversion.mjs.
  • ANSI escape stripping implementation so no-control-regex can remain enabled.
  • FFmpeg 7.x xfade compatibility by applying setpts=PTS-STARTPTS before fps; applying it after fps can clear CFR metadata and produce current rate of 1/0 is invalid.

Validated

  • Strict TypeScript compilation of the composition domain.
  • Real FFmpeg 7.1.5 transition, fade concat, plain concat, and vertical-stack slideshow smoke tests using mismatched input resolution/FPS.
  • Outputs were reprobed with FFprobe and retained expected video/audio streams.

0.4.0 — Milestone 6 — Media Conversion & Batch Engine

Added

  • Real convert file <input> and convert batch <directory> commands.
  • Typed src/conversion/ domain with format inference, profile construction, file conversion, glob matching, and generic batch scheduling.
  • Initial conversion matrix: MP4→WebM, MP4→GIF, MP4→animated WebP, WebM→GIF, WebP→PNG, and GIF→WebM.
  • Generic batch traversal with optional recursion, include/exclude globs, deterministic ordering, configurable parallelism, fail-fast/continue-on-error modes, output directories, hierarchy preservation, existing-output strategies, progress events, summaries, and JSON reports.
  • Preflight output-collision detection for flattened or otherwise colliding batch destinations.
  • Inline GIF palette generation and paletteuse pipeline.
  • Animated WebP generation through FFmpeg directly, removing the legacy webpmux dependency.
  • Batch and single-conversion JSON schemas.
  • Milestone 6 unit, CLI, discovery, and real-media integration-test sources.
  • Dependency-free verify:conversion verifier and Milestone 6 architecture/migration/validation documentation.

Changed

  • Package/plugin version advanced to 0.4.0.
  • Conversion commands are no longer placeholders.
  • The legacy convert-all-gif-in-folder-to-webm.sh intent is corrected: the toolkit now performs real GIF→WebM conversion instead of producing another GIF.
  • MP4→WebM uses VP9 and preserves audio as Opus when present.
  • GIF and animated-WebP conversion drop audio explicitly and emit structured warnings.
  • WebP→PNG explicitly exports the first frame.
  • Dry-run conversion performs read-only FFprobe inspection so stream-dependent plans remain accurate while FFmpeg transformation is not executed.

Validated

  • All six conversion routes completed successfully with real FFmpeg/FFprobe in the assembly environment.
  • A recursive two-file batch completed with parallelism=2, hierarchy preservation, and zero failures.
  • A second run with existing=skip skipped both pre-existing outputs without invoking conversion.
  • Production and test TypeScript trees passed strict compilation using temporary interface-only dependency shims because npm registry access timed out in the assembly environment.

0.3.0 — Milestone 5 — Audio Processing

Added

  • Real audio attach, audio silence, audio add-silence, audio detect-silence, audio remove-silence, and audio telephony commands.
  • Dedicated src/audio/ domain with typed operation reports and runtime options.
  • Structured SilenceInterval parsing from FFmpeg silencedetect output.
  • Configurable silenceremove pipeline with threshold, minimum-duration, and retained-silence controls.
  • Safe silent-track generation with explicit channel-layout semantics.
  • Audio attachment replace/append modes with default padding and container-aware AAC/Opus selection.
  • Telephony profiles for G.711 μ-law, G.711 A-law, GSM, and PCM with explicit codec/container compatibility.
  • Raw μ-law, A-law, GSM, and signed-16-bit PCM muxer support.
  • Shared media I/O module for readable-file checks, output derivation, overwrite protection, and transactional staging across video and audio.
  • Milestone 5 unit, CLI, and real-media integration-test sources.
  • verify:audio smoke verifier and Milestone 5 architecture/migration/validation documentation.

Changed

  • Package/plugin version advanced to 0.3.0.
  • Audio commands are no longer placeholders.
  • audio add-silence refuses to replace existing audio unless --replace-existing is explicit.
  • audio remove-silence is deliberately audio-only in v0.3.0 to prevent implicit A/V desynchronization.
  • The old convert-audio-to-gsm-ulaw.sh behavior is split into semantically correct G.711 μ-law and GSM profiles.
  • Milestone 4 verifier now accepts later semantic versions instead of requiring exactly 0.2.0.

Validated

  • Real silence generation, audio attachment, silent-track insertion, silence detection, silence removal, G.711 μ-law transcoding, and GSM transcoding completed successfully in the assembly environment.
  • silencedetect identified two known silence intervals in a deterministic fixture.
  • silenceremove reduced a 2.1-second fixture to approximately 0.989 seconds.
  • G.711 μ-law probed as pcm_mulaw at 8000 Hz mono; GSM probed separately as codec gsm.
  • Production source and test source passed strict TypeScript compilation using temporary dependency interface shims because npm registry access timed out in the assembly environment.

0.2.0 — Milestone 4 — Video Editing Operations

Added

  • Real video trim-start, video trim-end, and video trim commands.
  • auto, copy, and accurate trim modes with keyframe warning for stream-copy cuts.
  • Real video speed with synchronized audio tempo chaining and explicit audio-drop mode.
  • Real video from-image with duration, resolution, FPS and pixel-format controls.
  • Real video restore with explicit resolution plus balanced/aggressive restoration profiles.
  • Container-aware H.264/AAC and VP9/Opus encoding profiles.
  • Sibling temporary-output transaction with overwrite protection and final FFprobe validation.
  • Milestone 4 CLI-local options and action registry entries.
  • Unit, CLI and real-media integration tests for video operations.
  • Milestone 4 architecture, validation and Bash migration documentation.

Changed

  • Package/plugin version advanced to 0.2.0.
  • Video commands are no longer placeholders.
  • auto trim currently resolves to accurate re-encoding for deterministic cut semantics.
  • Legacy HD/FHD naming is replaced by explicit WIDTHxHEIGHT resolution.
  • Dry-run for video transforms may perform read-only FFprobe inspection but never executes the mutating FFmpeg transform.

Validated

  • Real trim-start, trim-end, trim-range, speed, still-image clip and restore transformations completed successfully in the assembly environment.
  • Final outputs were normalized with FFprobe and validated for duration, streams and dimensions.
  • Paths containing spaces were exercised by real transformations.
  • Production source passed strict TypeScript compilation using dependency interface shims because npm registry access timed out in the assembly environment.

0.1.0-alpha.3 — Milestone 3 consolidated fixes

  • Fixed ffmpeg -filters parsing for FFmpeg 8.x distributions whose filter capability column uses two characters (TS, .., .S, T.).
  • Preserved compatibility with FFmpeg releases that expose the older three-character filter flags (TSC, ...).
  • Kept ANSI stripping and stdout/stderr capability-table collection from the first Milestone 3 hotfix.
  • Fixed TypeScript/Node Buffer generic inference in TailCapture by explicitly typing the backing buffer as Buffer (Buffer<ArrayBufferLike> under current Node typings).
  • Added a regression fixture based on Ubuntu FFmpeg 8.0.1 output.

All notable changes to FFmpeg Media Toolkit will be documented here.

0.1.0-alpha.3 — 2026-09-18

Added

  • Real doctor CLI command and environment health report.
  • Real environment version and environment capabilities commands.
  • Typed parsers for FFmpeg codecs, encoders, decoders, filters and hardware acceleration methods.
  • Conservative hardware backend summaries for NVENC, VAAPI, QSV, VideoToolbox, CUDA, Vulkan and OpenCL.
  • Minimum FFmpeg compatibility evaluation against the Milestone 0 >= 6.1 policy.
  • Canonical FFprobe JSON media inspection and normalization.
  • Typed MediaInfo, video/audio/auxiliary stream normalization and tighter discriminated stream contracts.
  • Input existence/readability checks for probe operations.
  • specs/media-info.schema.json.
  • Milestone-aware CLI action registry so implemented leaves coexist with future placeholders.
  • Explicit string typing for result-envelope request IDs, allowing deterministic non-UUID IDs in tests and library callers.
  • Dependency-free verify:inspection smoke verifier.
  • ADR 0003 selecting FFprobe JSON as the canonical media inspection interface.
  • Milestone 3 unit/integration test sources.

Changed

  • doctor, probe, environment version, and environment capabilities are no longer placeholders.
  • Probe JSON capture is explicitly bounded at 16 MiB and truncation fails safely.
  • Capability table capture is bounded at 8 MiB per FFmpeg process.
  • environment install is now an explicit reserved-policy response rather than a misleading Milestone 3 placeholder.

Validated

  • FFmpeg 7.1.5-0+deb13u1 and FFprobe 7.1.5-0+deb13u1 were inspected successfully in the assembly environment.
  • Capability parsing found 520 codecs, 225 encoders, 537 decoders and 555 filters in that environment.
  • Hardware method enumeration reported vdpau, cuda, vaapi, qsv, drm, opencl, and vulkan.
  • A generated MP4 fixture containing MPEG-4 video plus AAC audio was probed and normalized successfully.
  • New production source passes strict TypeScript compilation in the assembly environment using dependency interface shims.

0.1.0-alpha.2 — 2026-09-18

Added

  • Shared FFmpeg/FFprobe process runtime.
  • Deterministic binary resolution with explicit, environment, and PATH lookup.
  • Native spawn execution boundary with shell: false.
  • Bounded stdout/stderr capture with truncation metadata.
  • Structured CommandExecution results.
  • Typed runtime error definitions and exit-code mapping.
  • AbortSignal cancellation and process-signal bridge.
  • Temporary workspace manager with traversal protection.
  • Incremental FFmpeg -progress parser.
  • Result-envelope builders for stable JSON output.
  • Binary version parsing foundation for Milestone 3.
  • Milestone 2 unit/integration test sources and runtime verifier.
  • ADR 0002 documenting the native process runtime boundary.

Changed

  • Removed the provisional execa runtime dependency in favor of native Node.js spawn.
  • Extended the execution JSON schema with execution/truncation/signal metadata.
  • Exported core runtime APIs from the package root.

Validated

  • Core runtime passes strict TypeScript compilation.
  • Real ffmpeg -version and ffprobe -version execution passed in the assembly environment.
  • Cancellation, dry-run, progress parsing, result envelopes, and temporary-workspace behavior passed smoke validation.

0.1.0-alpha.1 — 2026-09-18

Added

  • Portable plugin.json manifest.
  • ESM TypeScript project foundation with strict compiler settings.
  • Commander-based hierarchical CLI skeleton.
  • Stable global flags from Milestone 0.
  • Zod validation for global CLI options.
  • Placeholder command registration for the full frozen command grammar.
  • Vitest smoke/unit test foundation.
  • ESLint flat configuration and Prettier formatting configuration.
  • npm bin mapping for cecilia-ffmpeg.
  • MIT license and ADR documenting the licensing decision.

Preserved

  • Milestone 0 architecture/specification artifacts.
  • Legacy Bash migration corpus for later domain milestones.