AVPact

Declarative, inspectable, and verifiable media transformations.

Status: 0.3 release. The complete local-file operation set is implemented and covered by unit, CLI, and generated-media integration tests.

AVPact compiles a small set of media intents into a deterministic execution plan. The plan records streams, codecs, filters, expected outputs, resource limits, and verification checks before any transformation starts.

avpact schema --brief --format json
avpact capabilities --format json
avpact inspect input.mp4 --format json
avpact plan recipe.json --out plan.json --format json
avpact apply plan.json --progress ndjson --format json
avpact receipt show rcpt_0123... --format json
avpact verify output.mp4 --against plan.json --format json

FFmpeg is powerful but its option space is difficult to predict safely. Agents should choose a typed media intent, not synthesize a fragile shell command from memory.

• Declarative recipes are the source of truth.
• Inspect and plan before compute-heavy mutation.
• No shell interpolation.
• Deterministic encoder and filter selection is visible in the plan.
• Progress is emitted as bounded NDJSON events.
• Output properties are verified after encoding.
• The compiled FFmpeg argv remains inspectable.

AVPact 0.1 supports inspection, clip, transcode, resize/fit/crop/pad/rotation, audio extraction, measured loudness normalization, compatible concatenation, thumbnails, contact sheets, and subtitle burn-in.

See CONCEPT.md for the product model and ROADMAP.md for release gates. Typed recipes, constraints, and unsupported cases are documented in docs/OPERATIONS.md.

Download a native archive from GitHub Releases, or install from a source checkout:

cargo install --path . --locked

See INSTALL.md for platform-specific, checksum- and provenance-verified native installation, updating, and removal.

FFmpeg and FFprobe must be available on PATH. Because codec/filter support varies by build, inspect it before automation:

avpact capabilities --format json

Generate completion scripts with avpact completions bash (also zsh, fish, power-shell, and elvish).

Rust 1.85 or newer, FFmpeg, and FFprobe are required.

cargo build --release
cargo test --all-targets

./target/release/avpact inspect input.mp4 --format json
./target/release/avpact plan examples/clip.recipe.json \
  --out plan.json --format json
./target/release/avpact apply plan.json \
  --progress ndjson --format json
./target/release/avpact verify clip.mp4 \
  --against plan.json --format json

Recipe-relative input and output paths resolve from the recipe file's directory. The example therefore expects input.mp4 in the repository root and publishes clip.mp4 there.

By default, apply stores its receipt under .avpact/receipts/ beside the plan. Run receipt show <receipt-id> --state-dir <plan-directory>/.avpact from another directory. Use --receipt-out <path> on apply when an explicit standalone receipt path is preferable. If receipt persistence fails after publication, AVPact retains the verified output, attempts a no-clobber recovery receipt beside it, and emits action: "do_not_retry_apply" with the relevant paths and output SHA-256. Follow the receipt recovery procedure.

New receipts use the avpact.receipt/v0.2 contract. Their full SHA-256 identifier binds the plan digest, backend identity and arguments, timings, warnings, verification report, and publication evidence. The reader retains exact v0.1 compatibility; see receipt integrity and its trust boundary.

The execution contract applies to every operation:

• explicit default/first stream selection and warnings for dropped streams;
• inspectable FFmpeg argument arrays with capability checks;
• pinned FFmpeg build/library and FFprobe versions between plan and apply;
• verified codec, dimensions, square-pixel aspect, known frame rate, channels, and exact stream layout;
• no overwrite of an existing output;
• input identity revalidation before apply;
• hard output, temporary-disk, and runtime budgets;
• destination-adjacent temporary output, verification, then no-clobber same-filesystem publication;
• no-clobber receipt recovery without deleting an already published path;
• bounded NDJSON progress on stderr and final JSON on stdout;
• Ctrl-C cancellation with backend process-tree cleanup.

Use avpact schema --document recipe --format json (or plan, inspection, progress, verification, receipt, capability, and error) to retrieve the full JSON Schema for a document.

AVPact's checked-in contract compatibility corpus freezes accepted v0.1 recipes, plans, and receipts plus the content-addressed v0.2 receipt. CI checks exact round trips, semantic validation, fixture digests, and fail-closed behavior for declared tampering cases.

The published adversarial safety corpus exercises 60 labeled input-identity, current-receipt, output-verification, input/output-alias, and existing-destination cases through production paths. The reproducible score is 60/60 detected with zero unintended destination changes and zero leaked temporary paths.

The versioned performance harness enforces contract, end-to-end plan, CLI process-tree memory, isolated backend memory, and temporary-file thresholds from 20 samples over project-generated synthetic media. It retains every raw sample and applies a noise-aware regression envelope against the checked-in Ubuntu 24.04 baseline.

CI tests Linux, macOS, Windows, and the declared Rust 1.85 MSRV. Tagged releases contain native archives, documentation, shell completions, SHA-256 checksums, CycloneDX SBOMs, and GitHub/Sigstore build provenance and SBOM attestations. See RELEASING.md and SECURITY.md.

Use GitHub Discussions for questions and workflow exploration, and the structured issue forms for reproducible bugs and feature proposals. See CONTRIBUTING.md, SUPPORT.md, GOVERNANCE.md, and the Code of Conduct before participating. Security-sensitive behavior must be reported privately.

Verified, opt-in usage is recorded in ADOPTERS.md.

MIT