aniflow

Define the pipeline once. Transform every frame. Rebuild the experience.

aniflow is a reproducible, resumable Rust orchestrator for frame-based video processing. The source package is 0.3.0 and exposes the music-video pipeline through a typed Rust library and versioned machine-readable CLI contract:

inspect → extract → ordered frame processors → validate → assemble
        → audio processors → subtitles → whole-video processors
        → master → delivery manifest

The engine owns temporal orchestration, checkpoints, validation, and run evidence. FFmpeg, Upscayl, Gemini Watermark Remover, and future processors retain ownership of their specialized media operations.

The package exposes a reusable Rust library behind a thin standalone CLI. See the architecture graph and v1 roadmap for the accepted boundaries and staged evolution.

Current source status (2026-10-28): main e1634df58fa32feda23021565b032a83c5a30d66 includes merged verified assembly PR #130, fixed recipe PR #131 and target-resolution PR #132, following the import/repair, Upscayl recovery and selected setup checkpoints. Standalone extraction draft PR #133 adds an accepted original frame index and PNG directory. The current stacked codex/35-source-music-video-recipe checkpoint adds one-command source entry: extract, prepare, optionally upscale, then assemble under one recipe root. The indexed entry remains available with its existing configuration and paired frame arguments. Existing v3 runs retain execution, acceptance and resume authority. #35, #107 and #111 remain open for their remaining scope and qualification.

These are authored implementations. Current-source tests/builds, lint/format/schema checks, native qualification and CI remain deferred under #64, including the known alignment cancellation/start-marker failure with unproven cause. Source package 0.3.0 remains unreleased.

Start with the current source and work order. #117 retains the complete open-work ledger. Dated receipts and roadmap snapshots describe their named revisions, not today's qualification. The first immutable release remains #10.

Try it with synthetic videos

The hands-on video demo generates two short, watchable landscape/portrait MP4s and matching local recipe configurations. Start with extraction and assembly, with repair and upscale disabled; no song, private video or neural model is needed. Generation requires Python 3.10+ and explicit local FFmpeg/ffprobe 8.0.1 executables. The guide separates generating/viewing clips, trying aniflow and running the automated tests. This demo checkpoint is authored; execution qualification remains deferred under #64.

Current capabilities

The following describes source behavior and its explicit support bounds. A successful plan, merged checkpoint or model-independent fixture does not qualify real media, native tools or a downstream release.

• Plan explicit music-video toolchain profiles with separate executable, version, codec, model and backend facts. New toolchain doctor / toolchain plan commands read local identities and caller-supplied evidence without launching tools or installing dependencies. The #38 checkpoints are authored and unqualified.

• Collect bounded FFmpeg/ffprobe diagnostic evidence with the separately invoked toolchain probe command. It retains exact query/process/capture evidence and parsed capabilities from explicitly pinned tools. The #101/#102 Linux/macOS implementation and synthetic tests are authored but unrun; hardware-device proof and optional tool probes remain follow-ups.

• Bind selected audio-inspection stages to an explicit toolchain preflight document with --toolchain-preflight. The immutable plan requires the same document on run/resume and rechecks pinned tools before source rebinding or cache access. This #103 adapter-specific gate and synthetic coverage remain unrun under #64.

• Prepare reviewable native audio registration documents with toolchain prepare-registration --configuration "request.json". Matching registration, manifest, settings and preflight documents are returned as inert JSON for explicit review and placement. No tool is launched or setup file written. This #104 checkpoint and its coverage remain unrun under #64.

• Prepare selected repair/Upscayl configurations with toolchain prepare-media --configuration "request.json". One explicit capability and local inventory produce a reviewable typed configuration or precise missing/incompatible/unverified diagnostics. Options stay in the selected profile; preparation reads no media and launches no tools.

The audio support matrix records all eight capability families, exact input profiles, uncertainty and unsupported outcomes. The integrated synthetic workflow and consumer guide connect their public evidence without claiming real-model accuracy or downstream release qualification.

The manual audio/video release-preparation runbook and exploratory spec capture the evolving finishing, optional creator-watermark, timestamp-evidence and destination-export workflow. #79 uses Akashic as the first pilot; #80–#83 track its gaps. Native inspection and sample statistics from #80 are authored, while execution qualification stays deferred under #64. The broader finishing/publication workflow remains exploratory.

• Produce offline vocal/accompaniment candidates with the typed Demucs PCM WAV profile, explicit prepared model assets, audio integrity/duration evidence, and Pipeline v3 checkpoints.
• Inspect classic RIFF PCM16, packed PCM24 and finite float32 without quantizing the source. Explicit native signal settings retain original peak/RMS/crest and silence/clipping regions; native loudness and true peak remain unavailable. The #80 implementation and synthetic coverage are authored; all qualification is unrun under #64.
• Inspect bounded audio and measure its signal properties while preserving declared stem lineage to an original mix; see technical inspection and signal analysis for the supported profiles.
• Produce bounded tempo, beat and key estimates with an explicitly installed local analyzer, retained disagreements and unavailable calibrated confidence.
• Convert lyrics and timed-text subsets with exact supplied timing, explicit conversion losses and retained provenance, without a model.
• Produce observed offline transcripts with an explicitly pinned local tool/model profile and honest timing/confidence gaps.
• Propose offline reviewed-lyrics alignment with preserved authored text/review evidence, explicit partial matches and candidate timing that still requires review.
• Extract probabilistic MIDI candidates with an explicitly pinned local Basic Pitch model, source-relative note evidence and a declared Standard MIDI File export subset; generated notes do not replace authored MIDI.
• Inspect source streams, decoded frame intervals and packet timestamps with bounded ffprobe observations. Preserve exact rational clocks and input-global stream identities; see temporal correctness.
• Process contiguous zero-origin CFR on the observed grid. Automatically select only a unique moving-video and optional audio stream; otherwise require explicit selection and acknowledgement of every discarded stream. Inspect well-formed unsupported inputs while refusing VFR, unsupported offsets or contradictory clocks before processing.
• Extract predictably named lossless PNG frames and 24-bit PCM audio.
• Extract a supported source video into an accepted original frame index and complete RGB PNG set with video extract-frames. Read-only planning leaves geometry and frame count pending; native execution observes the selected source conversion and verifies every output frame. Its accepted outputs can then enter the fixed recipe without a hand-authored index.
• Chain any number of ordered per-frame processors.
• Use first-class upscayl_ncnn and gemini_watermark_remover adapters.
• Add generic restoration, denoise, color, stylization, or custom commands.
• Use native directory batching for Upscayl and Gemini Watermark Remover.
• Resume generic per-frame processors by skipping valid frame outputs.
• Validate frame count, ordering, file integrity, and uniform dimensions.
• Run ordered audio and whole-video external processor chains.
• Restore processed or original audio as 320 kbps AAC on the compatibility path.
• Assemble an existing original-clock PNG index or an Upscayl spatial index through two ordinary Pipeline v3 stages with video assemble-frames. The assembly guide covers the FFV1 MP4 master, H.264 MP4 delivery, original AAC packet verification, plan/run/resume/status, and the explicit manual handoff from repair or upscale output.
• Burn ASS/SRT subtitles or mux a subtitle track.
• Snapshot configuration and subtitle inputs into each run.
• Record stage state, logs, media metadata, checksums, and delivery metadata.
• Preserve compact per-frame Gemini removal decisions as JSON Lines metadata.
• Embed diagnostics, inspection, planning, execution, resume, and status through a deliberately small crate-root Rust API.
• Emit versioned JSON results and typed application failures for machine-mode CLI operations. Argument-parser errors occur before the application envelope; current machine application failures use stderr.
• Coordinate the fixed music-video recipe from a source video or existing indexed PNGs through explicit repair/upscale choices into assembly. The source configuration adds an extraction child in the same root; geometry and target decisions wait for accepted extraction. Each enabled step uses its existing v3 run, and downstream exact plans await accepted input.
• Select an opt-in target-resolution rule in the fixed recipe. Explicit geometry, exact/minimum target policy and force intent determine whether to execute existing Upscayl work or pass accepted frames unchanged; a bypass does not require the neural executable or model files.
• Publish provider-native v1 manifest, effective-configuration, and compatibility-fingerprint contracts for temporal extension authors and independent consumers.
• Publish a coherent runnable provider-conformance bundle for frame, audio, whole-video, and evidence-producing artifact-validator stages, with an honest support matrix and authoring guide.
• Resolve explicitly registered local providers through deterministic replacement, primary, and fallback policy with exact provider locks.
• Parse strict Pipeline v3 intent and resolve it through the read-only plan_v3 file facade, lower-level resolve_pipeline_v3 library API, or plan-v3 CLI into a canonical, self-validating plan with exact provider locks and resolution attempts.
• Execute that exact Pipeline v3 plan through separate run_v3, resume_v3, and status_v3 library APIs or the matching run-v3, resume-v3, and status-v3 CLI commands without changing Pipeline v2 behavior.
• Resume Pipeline v3 stages from immutable, content-aware checkpoints and an append-only run-manifest history only after inputs, dependency outputs, validations, and freshly resolved exact provider locks still match.
• Invoke Pipeline v3 providers through the closed aniflow.provider-invocation/v1 direct-argument contract and accept outputs only after provider-runtime checks, mandatory artifact integrity, and explicitly selected validation gates pass.
• Retain component, stage, candidate-master and delivery acceptance records for Pipeline v3 status and resume. The #33 implementation and synthetic coverage are authored; test/check execution remains deferred under #64.
• Execute resolved providers with cancellation, wall-clock and capture bounds, process-tree termination, redacted diagnostics, strict artifact limits, and output validation independent from exit status.
• Adapt every pipeline v2 frame, batch, audio, and whole-video processor to the same provider runtime, with one lock per stage and one execution report per invocation.
• Split videos into explicit sub-30-second segments with either keyframe-aligned stream copy or frame-accurate H.264/AAC transcoding.
• Resume a verified segment prefix and reconstruct it through an immutable, checksummed manifest with duration validation.
• Preserve the disabled-by-default renderflow handoff only on the pipeline v2 compatibility path; pipeline v3 configuration rejects it.

Requirements

Base runtime:

brew install ffmpeg rust

Cargo.toml declares Rust 1.85 as the minimum compiler. The current source still requires the deferred MSRV and supported-host qualification pass.

Optional processors:

• upscayl-bin for the upscayl_ncnn adapter.
• gwr for the gemini_watermark_remover adapter.

Install Gemini Watermark Remover and its image codec:

pnpm add --global @pilio/gemini-watermark-remover sharp

Upscayl NCNN currently requires a source build or a compatible binary plus its model files. Its upstream README includes Apple Silicon CMake and MoltenVK instructions. The executable is named upscayl-bin.

If either tool is already cloned instead of installed on PATH, set command to its absolute executable path. For Gemini Watermark Remover, that may be the executable bin/gwr.mjs; for Upscayl, it is the built upscayl-bin. Pipeline v2 retains bare command names for compatibility: aniflow resolves such a name once from the caller's PATH, converts it to an absolute path, and then registers that exact executable. The provider registry itself never performs implicit discovery.

Quick start

cargo build --release

./target/release/aniflow doctor

./target/release/aniflow inspect "/path/to/video.mp4"

./target/release/aniflow plan \
  --input "/path/to/video.mp4" \
  --pipeline "pipelines/passthrough.yml"

./target/release/aniflow run \
  --input "/path/to/video.mp4" \
  --pipeline "pipelines/passthrough.yml"

These plan and run commands use the Pipeline v2 compatibility path. To resolve Pipeline v3 intent without launching providers or creating a run workspace, supply every input, provider-registration locator, host observation, and authority grant explicitly:

./target/release/aniflow plan-v3 \
  --pipeline "pipeline-v3.yml" \
  --input "source-video=/path/to/video.mp4" \
  --provider-registration "providers/upscale.registration.json" \
  --host-cpu-threads "8" \
  --host-memory-mib "16384" \
  --host-storage-mib "65536" \
  --host-gpu-available \
  --allow-side-effect "filesystem-read" \
  --allow-side-effect "filesystem-write" \
  --allow-side-effect "subprocess" \
  --allow-side-effect "gpu" \
  --offline

Each --input is an authored artifact ID and local path in ID=PATH form. Each registration document uses aniflow.provider-registration/v1 and names a manifest, effective configuration, executable, implementation ID, and observed components. Locator paths are resolved relative to that document and never enter plan identity. Repeat both flags when the pipeline needs more inputs or provider candidates.

Execute the same resolved intent by changing only the command and, optionally, choosing the parent directory for the new isolated run:

./target/release/aniflow run-v3 \
  --pipeline "pipeline-v3.yml" \
  --input "source-video=/path/to/video.mp4" \
  --provider-registration "providers/upscale.registration.json" \
  --host-cpu-threads "8" \
  --host-memory-mib "16384" \
  --host-storage-mib "65536" \
  --host-gpu-available \
  --allow-side-effect "filesystem-read" \
  --allow-side-effect "filesystem-write" \
  --allow-side-effect "subprocess" \
  --allow-side-effect "gpu" \
  --offline \
  --output-directory ".aniflow/runs"

run-v3 performs the same read-only resolution first, preflights the bounded execution subset, then creates a workspace and executes the exact plan. Every expected output declares its artifact ID, exact path and file or directory kind. Ports declared one retain the v1 invocation/report contract. Explicit nonempty sets on one_or_more or many ports use the v2 contracts; every planned member must pass integrity and any configured provider validation before stage acceptance. Optional, unbound or empty output sets, unsupported validation contracts, lifecycle-observer stages, and providers requesting publish authority fail before workspace creation or provider launch. See Authoring a temporal provider for the process ABI, support matrix, least-authority rules, and runnable reference profiles.

Human output is the default. Every command also exposes the same application result through the machine contract:

./target/release/aniflow plan \
  --input "/path/to/video.mp4" \
  --pipeline "pipelines/passthrough.yml" \
  --output "json"

plan-v3 accepts the same --output json mode. On success, its envelope result is an aniflow.pipeline-plan/v1 document. On failure, the result retains an aniflow.pipeline-planning-failure/v1 diagnostic, including the affected stage and deterministic provider-resolution attempts when applicable.

run-v3 and resume-v3 return an aniflow.pipeline-run-outcome/v1 result with the run directory, immutable plan digest, newest manifest locator, validated outputs, and executed/reused stage IDs. status-v3 returns the newest validated aniflow.pipeline-run/v1 manifest. If run or resume fails after durable execution starts, the error envelope instead retains an aniflow.pipeline-run-recovery/v1 result with the run directory and, when the newest manifest can be fully validated, its exact locator. Failures before workspace startup omit result as before.

Successful envelopes are written to standard output, failure envelopes to standard error, and the exit code identifies the typed failure category. See the public contract and compatibility policy.

Pipeline v2's final output and delivery manifest appear beneath one timestamped run:

.aniflow/runs/<timestamp>-<pipeline>/
├── providers/<stage>/provider-lock.json
├── providers/<stage>/reports/<invocation>.json
├── output/master.mp4
└── delivery/manifest.json

Resume or inspect a run:

./target/release/aniflow resume \
  ".aniflow/runs/20260726T220000Z-gemini-clean-upscale"

./target/release/aniflow status \
  ".aniflow/runs/20260726T220000Z-gemini-clean-upscale"

Pipeline v3 uses a separate workspace and commands. Resume must receive the same explicit input and registration authority needed to re-observe source content and re-resolve every selected provider lock; it never searches PATH or chooses a fallback after execution has begun:

./target/release/aniflow resume-v3 \
  ".aniflow/runs/20260915T220000000000Z-upscale" \
  --input "source-video=/path/to/video.mp4" \
  --provider-registration "providers/upscale.registration.json"

./target/release/aniflow status-v3 \
  ".aniflow/runs/20260915T220000000000Z-upscale"

status-v3 opens the existing workspace and validates its complete, hash-linked run-manifest history without creating or repairing anything.

Rust library

Add aniflow to another Rust project's dependencies while the public preview is developed from main:

[dependencies]
aniflow = { git = "https://github.com/egohygiene/aniflow", branch = "main" }

The crate-root facade returns application data without parsing CLI arguments or printing human output:

use aniflow::{Result, RunRequest};

fn process_video() -> Result<()> {
    let plan = aniflow::plan("source.mp4", "pipelines/passthrough.yml")?;
    println!("{} stages", plan.stages.len());

    let outcome = aniflow::run(RunRequest::new(
        "source.mp4",
        "pipelines/passthrough.yml",
    ))?;
    let status = aniflow::status(&outcome.run_directory)?;
    println!("{} completed stages", status.stages.len());
    Ok(())
}

Use run_with_progress or resume_with_progress when an embedding application needs lifecycle observations. Use run_with_progress_and_cancellation or resume_with_progress_and_cancellation to supply a shared CancellationToken that is forwarded to processor invocations. The public API is intentionally small and pre-1.0; ErrorCategory, MachineEnvelope, and command result types provide the 0.3.x integration boundary.

Temporal provider authors and registries can use ProviderManifest, ProviderConfiguration, CompatibilityFingerprint, ProviderRegistry, and the versioned provider lock/event/report types through the crate root. Local executables must be registered explicitly and are launched only after exact resolution and authority checks. See the temporal provider contract and provider authoring guide.

Pipeline v3 integrators use plan_v3 for the same file-based boundary as the CLI, or PipelineV3Configuration and resolve_pipeline_v3 with a prebuilt registry. The planner remains deliberately read-only: it hashes explicit inputs, validates the authored stage graph and artifact bindings, and resolves only explicitly supplied provider registrations.

Execution is a separate boundary. Construct PipelineV3RunRequest from an already validated PipelineV3Plan, immutable input bindings, and an explicit ProviderRegistry, then call run_v3. Construct PipelineV3ResumeRequest from the run directory plus fresh input bindings and registry authority, then call resume_v3. status_v3 is read-only. The executor re-resolves each selected registration and requires complete ProviderLock equality before mutation or launch. Operational logs and telemetry may observe a caller, but they never become canonical plan, provider-lock, checkpoint, fingerprint, or artifact identity.

flow should consume the library facade when running in-process and the v1 machine envelope when a process boundary is required. See the dedicated flow integration guide.

The independent consumer example exercises every supported application operation without importing the CLI parser:

cargo run --example library -- inspect "/path/to/video.mp4"
cargo run --example library -- plan \
  "/path/to/video.mp4" \
  "pipelines/passthrough.yml"

Short-segment workflows

Exact timing and stream selection are described in the temporal correctness guide. New segment records use v2; source frame intervals and stream indices are authoritative, with typed refusal for unsupported VFR, offsets and unacknowledged streams. The #32 implementation is authored with validation intentionally deferred to #64.

Plan before writing media:

aniflow segment plan \
  --input "source.mp4" \
  --output-directory ".aniflow/segments/demo" \
  --segment-duration-ms 10000 \
  --mode stream-copy

Run and later resume the same isolated workspace:

aniflow segment run \
  --input "source.mp4" \
  --output-directory ".aniflow/segments/demo" \
  --segment-duration-ms 10000 \
  --mode transcode-h264-aac

aniflow segment resume \
  --run-directory ".aniflow/segments/demo"

Reconstruct only after the complete manifest and all segment checksums verify:

aniflow segment reconstruct \
  --run-directory ".aniflow/segments/demo" \
  --output-file "reconstructed.mp4"

See Short-segment workflows for timing semantics, recovery behavior, public Rust APIs, and flow/renderflow ownership boundaries.

First real Gemini music-video pass

The ready-made pipeline removes the small visible Gemini mark before upscaling. That order avoids enlarging the watermark before removal.

First, edit the pipeline if your Upscayl models are not resolved from the current working directory:

model_path: /absolute/path/to/upscayl-ncnn/models

Then verify every enabled dependency:

./target/release/aniflow doctor \
  --pipeline "pipelines/gemini-clean-upscale.example.yml"

Plan and run:

./target/release/aniflow plan \
  --input "/path/to/music-video.mp4" \
  --pipeline "pipelines/gemini-clean-upscale.example.yml"

./target/release/aniflow run \
  --input "/path/to/music-video.mp4" \
  --pipeline "pipelines/gemini-clean-upscale.example.yml"

Upscayl and Gemini Watermark Remover run in their native directory modes, so each tool loads once for the complete stage. Upscayl controls its internal GPU and worker behavior through its own options.

Use watermark removal only for media you created or are authorized to modify. The adapter targets Gemini's visible overlay; it does not remove invisible provenance systems such as SynthID.

Processor model

Frame processors

Frame processors are ordered. Every processor reads the complete output directory of the previous processor and writes a new immutable stage directory:

frames/source
  → frames/stages/01-remove-gemini-watermark
  → frames/stages/02-upscale

Built-in adapter kinds:

Kind	Command	Purpose
gemini_watermark_remover	gwr	Native directory batch; reverse-alpha removal of supported Gemini visible marks
upscayl_ncnn	upscayl-bin	Native directory batch; NCNN/Real-ESRGAN frame upscaling
external	configured	Concurrent per-frame restoration, denoise, grading, stylization, or custom logic

Frame import and selective repair

The read-only frame-selection preview accepts an existing exact frame index and explicit inclusive ranges before repair:

aniflow video frame-selection-plan \
  --frame-index "frames/index.json" \
  --range "1:299" \
  --range "600:898"

It reports exact positions, rational time spans and selected/unselected counts without needing RIFE tools or configuration. This #36 source checkpoint checks index declarations only. The separate import command observes actual source and PNG bytes and fully decodes immutable snapshots.

Selective repair combines import and repair in one ordinary Pipeline v3 run. An explicit direct-image processor handles only the chosen ranges; every unselected PNG remains byte-identical. The output retains the complete filename/index/time mapping and records selected versus actually changed frames. A changed file is not proof that a visual defect was fixed. This initial generic repair profile starts a fresh run and refuses resume; unobserved model/environment dependencies cannot justify result reuse.

The generic profile keeps its pinned tool and literal argv interface. The separate named allenk profile pins a current or legacy visible-overlay profile, observes its executable version, and reuses compatible whole import/repair stages after fresh dependency checks. Interrupted repair retries every selected frame; partial frame files are not checkpoints. Embedded profile assets are bound through the executable; shared-library/host qualification remains unobserved. GWR integration, clip-only processing, detection review and external manifest migration retain separate scope. Execution checks remain deferred to #64.

The selected media setup guide derives the named repair or Upscayl configuration from reviewed local inventory. Save its returned configuration explicitly, then pass it to the existing video command. Setup currently prepares the per-frame Upscayl policy; bounded chunks remain an explicit recovery configuration choice. Setup readiness does not replace fresh planning and execution checks.

Recoverable frame upscaling

The Upscayl recovery profile supports per-frame processing and explicit bounded native chunks with immutable checkpoints. Per-frame mode admits up to 1,024 frames; chunk mode admits longer workspaces within its frame, chunk, plan and storage bounds. For 5,602 frames, 64-frame chunks need 88 chunk checkpoints plus a collector. An interrupted run reuses compatible completed chunks and retries the entire unfinished chunk once. Exact binary/model pins, source bytes, timing, chunk boundaries and settings govern reuse; existing files alone are never enough.

Native model scale and requested output scale are separate settings. The output keeps original source timing and records scaled geometry in an explicit spatial index. Existing legacy native directory batches remain available. Historical output adoption, full failure coverage and actual Apple Silicon/NCNN qualification remain open under #37; execution checks stay deferred to #64.

Source-video entry

Use video extract-frames to prepare an original indexed PNG workspace from a supported source video. One ordinary v3 stage produces extracted_frames, extracted_index and extraction_evidence. Plan/run/resume use explicit FFmpeg/ffprobe pins, source-stream selection and finite resource bounds. Planning launches no probe; source support, geometry and frame count remain pending until execution.

Pass the accepted frame-directory and index paths to video music-video. This is a separate extraction checkpoint followed by the existing recipe, with unchanged source preservation, whole-stage recovery and downstream acceptance. The extraction guide explains the observed RGB conversion and the distinction from mathematically lossless YUV round trips or native qualification.

Verified video assembly

Use video assemble-frames after selecting the complete repaired or upscaled frame directory and its matching index. It keeps the original source geometry and clock evidence separate from upscaled output geometry. An explicit FFmpeg/ffprobe 8.0.1 configuration produces two ordered stages: assemble_master, then encode_delivery. When audio is selected, both outputs include the original AAC packets; no new audio encode is requested. Master acceptance checks decoded RGB pixels and exact timing, while audio packet payloads, integer timestamps, codec extradata and priming are compared at both stages.

This source checkpoint admits only its strict original-clock CFR/SDR subset; unsupported offsets, long audio/video tails and derived RIFE clocks are refused. It neither proves the imported PNGs were extracted from the declared video nor reconstructs earlier processing history. Planning and accepted run evidence remain separate. The assembly guide retains the individual-command workflow; the fixed recipe coordinates those existing child runs from already indexed frames. It does not add extraction, arbitrary recipe stages or review/approval automation. Qualification stays under #64.

Audio and video processors

Audio and whole-video processors use one safe external-command contract. The command runs directly, without a shell:

Placeholder	Meaning
{input}	Absolute input artifact
{output}	Absolute output artifact the command must create
{run_dir}	Run workspace

The typed RIFE frame-interpolation profile authors same-duration 2x interpolation through Pipeline v3's existing provider ABI. It accepts an explicitly indexed RGB8/SDR frame directory, invokes serial frame pairs with 1:1:1 workers, and preserves exact rational timing in a derived output index. CPU is the default device; GPU selection is explicit. Automatic Apple Silicon settings use the conservative padded-1080p ceiling. Larger presets require declared memory headroom and remain serial. Resource estimates are uncalibrated admission policy, not enforced RAM/VRAM quotas.

aniflow video interpolation-plan \
  --configuration "/path/to/rife-configuration.json" \
  --frame-index "/path/to/source-frame-index.json" \
  --output json

Planning reads only those documents. Disabled configurations do not launch tools or load models. The #114 implementation and synthetic coverage are authored but unrun under #64; MP4 assembly, broader rates, automatic shot detection, fine-grained resume and native Apple Silicon qualification remain under #110. The provider produces frames and evidence, and leaves audio for the subsequent qualified assembly stage.

Every enabled pipeline v2 processor is normalized into a typed local provider, resolved before expensive media work, and executed with direct arguments. The runtime confines output to a fresh invocation directory, enforces configured bounds, and validates the declared artifact before aniflow performs its processor-specific checks and promotes it into the stage. Exit code zero alone never completes a processor stage.

All frame, audio, and video processor entries accept the same optional limits object:

Field	Default
timeout_seconds	21600
termination_grace_milliseconds	2000
maximum_stdout_bytes	67108864
maximum_stderr_bytes	67108864
maximum_artifact_files	1000000
maximum_artifact_bytes	1099511627776

The provider lock binds the adapter configuration and executable digest. When upscayl_ncnn.model_path is explicit, it also binds the selected .param and .bin model files. Execution reports retain termination, bounded redacted captures, lifecycle events, artifact observations, and the terminal outcome.

Pipeline packs

• pipelines/passthrough.yml: FFmpeg-only timing and reconstruction proof.
• pipelines/anime-upscale.example.yml: first-class Upscayl NCNN adapter.
• pipelines/gemini-clean-upscale.example.yml: watermark removal followed by Upscayl.
• pipelines/lyrics.example.yml: prepared ASS subtitle burn.

See Pipeline schemas for Pipeline v3 planning and every Pipeline v2 compatibility field.

Validation

The normal local gate is listed below for the later qualification session. It has not been run for this documentation reconciliation or the deferred implementation checkpoints. Follow the active #64 instruction before executing it; the list itself is not passing evidence.

cargo fmt --all -- --check
cargo check --all-targets --locked
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets
cargo test --doc
python3 scripts/check-contracts.py
./scripts/check-product-names.sh
./scripts/test-product-names.sh
cargo package --locked
./scripts/smoke-test.sh

The authored CI configuration repeats the locked check, all-target tests and doc tests on the declared Rust 1.85 baseline. This does not establish a current successful run.

The synthetic smoke test generates a two-second video with audio, processes it through both the complete FFmpeg path and a hermetic external-frame provider, inspects the master, and verifies retained provider lock/report evidence. The focused provider suite exercises the coherent reference bundle directly:

cargo test --test provider_conformance --locked

Suite boundary

aniflow owns time-based processing, master validation and its run evidence. Creative approval, native qualification and release publication remain separate decisions. renderflow owns its independent transform and derivative domain. flow owns cross-tool selection, sequencing, compatibility, and suite-level provenance.

aniflow does not directly depend on renderflow, optiflow, or flow in the target architecture. They may consume its released library or CLI externally.

Pipeline v2 still contains an optional, disabled-by-default renderflow handoff:

renderflow:
  enabled: false
  command: renderflow
  arguments:
    - run
    - --input
    - "{input}"
    - --output-directory
    - "{output}"

This is a deprecated compatibility seam rather than the future integration contract. Pipeline v3 configuration, planning, execution, and resume reject cross-holon renderflow selection. flow receives validated artifacts and aniflow run evidence through the versioned public boundary and sequences renderflow independently when suite policy requires it.

Known constraints

• Frame reconstruction uses exact observed rational intervals for contiguous zero-origin CFR. Informational average-rate fields do not choose timing; unsupported VFR, offsets and clock contradictions are explicit refusals.
• Processing selects one moving-video and optional audio stream by input-global index. A unique candidate may be selected automatically; ambiguity and any unacknowledged discarded stream are refused. Existing runs without the exact temporal record require a new run rather than a silent state upgrade.
• The frame interchange format is PNG.
• Checkpoint reuse and opt-in owned cross-run caches require complete compatible output sets and current acceptance; see cache reuse.
• The compatibility path decodes audio to PCM and encodes AAC. The explicit #35 assembly profile requires admitted original AAC and compares its copied packet evidence in both MP4 outputs; it does not transcode unsupported audio.
• Continuity validation checks sequence, file integrity, and dimensions; visual flicker and motion-consistency analysis are future stages.
• Pipeline v2 processor executables are content-hashed and locked per stage; FFmpeg, FFprobe, and the deprecated renderflow handoff remain on their legacy dependency paths.
• Pipeline v2 completion markers retain their compatibility behavior and do not carry Pipeline v3 checkpoint proofs.
• Pipeline v3 supports ordered stages, explicit nonempty output sets on one, one_or_more and many ports, and layered provider-backed acceptance. Optional/unbound/empty output ports and arbitrary DAG execution remain unsupported. The #69 artifact-set implementation and its synthetic coverage are authored; execution qualification remains deferred under #64.
• Provider-specific configuration.values validation remains the embedding application's responsibility; aniflow checks the exact schema identity and effective-value digest but does not interpret arbitrary schema keywords.
• Historical reference-provider conformance evidence covers its recorded Linux source and requires Python 3.10+ plus a Unix-compatible executable boundary. It does not qualify this current source or another platform.
• Pipeline v3 resume invalidates incompatible affected and downstream stages within the immutable plan; it does not replan, silently replace provider authority, or reuse evidence from another run.
• The compatibility-fingerprint contract is public, but Pipeline v3 does not automatically persist one; run-local checkpoints bind the exact plan, lock, invocation, report, observed artifacts, and built-in validation evidence.
• Public run progress remains stage-level and provisional; provider execution reports retain versioned invocation lifecycle events, and stable command results and error categories remain available in 0.3.x.
• RIFE currently produces indexed 2x RGB8/SDR frames. Final-video assembly, derived-clock/audio acceptance, broader rates and native resource/device qualification remain #110 work. Estimates do not enforce RAM/VRAM quotas.
• Toolchain preparation covers native-v2 audio registration and selected allenk/Upscayl configuration mapping. It returns inert documents; other typed mappings, complete environment identity, model discovery, optional tool/device probes and qualification remain #38 work.

License

MIT

Pipeline v3 cache reuse

Opt into verified cross-run stage reuse with --cache-policy, or request targeted reruns with --rerun-stage. Read-only cache inspection and explicit invalidation/ pruning share the public library. See cache reuse and operations. The #34 implementation and synthetic coverage are authored; qualification is deferred under #64. This is not a release-support claim.

Synthetic adversarial corpus

The #24 corpus supplies deterministic synthetic recipes, exact expected byte inventories, public-contract consumers and links to existing provider/recovery/validation/cache coverage. Use task corpus:check for read-only drift detection and explicit corpus tasks for generation or later qualification. The catalog is authored evidence; tests and native execution remain deferred under #64. No generated media payloads are committed.

Release convention

Cargo is the sole product version authority. The release guide covers explicit preparation, the proposed Linux/macOS binary matrix, signed candidate evidence, manual immutable Relay publication and rollback. The #10 workflow and synthetic tests are authored; qualification is deferred under #64 and Egolint #29 remains a release gate. No GitHub binary release, crates.io or Homebrew delivery is claimed by this implementation.