What Passtape does

Passtape is a media engine, not a timeline editor or a command-line wrapper. Your application describes media as a graph of sources, operations, parameters, and outputs. A runtime then prepares that graph for a concrete request and executes the prepared work.

The graph is reusable. It does not contain decoder objects, output paths, Metal textures, or codec sessions. Those belong to the runtime and output target.

Passtape currently has a complete macOS backend. Its platform-neutral graph and runtime contracts are designed for additional native backends.

Build a graph

Create the runtime, register the file with its source provider, and use the returned descriptor to add the source to a graph.

use passtape::{H264Mov, MediaGraph, RequestedVideoOutput, new_runtime};

let mut runtime = new_runtime()?;
let source_info = runtime.sources_mut().add_file("input", input_path)?;

let mut graph = MediaGraph::builder("transcode");
let source = graph.add_video_source(
    "input",
    source_info.full_range(),
    source_info.descriptor(),
)?;

Names such as input and transcode are stable identities. They make graph validation, caching, diagnostics, and graph updates predictable.

Add operations

Operations are explicit nodes with typed inputs, outputs, and parameters. Built-in operations use named option structures, so the wiring remains readable as the library grows.

use passtape::ops::video_blur_gaussian;

let radius = graph.add_scalar_parameter("blur-radius", 12.0)?;
let blurred = graph.add_operation(video_blur_gaussian::Options {
    id: "soften",
    active_range: source_info.full_range(),
    input: source,
    radius,
})?;
let output = graph.add_video_output("output", blurred)?;

Parameters can be constant or keyframed. An operation may also expose several named outputs—for example, an image and a mask—without executing unused ports.

Prepare and export

An output target turns a logical graph output into a concrete request. Preparation validates the complete path and compiles fixed execution programs before any frame is rendered.

let requested = RequestedVideoOutput::new(
    output.node_id(),
    H264Mov::new(output_path),
);

let plan = runtime.prepare(
    graph.build(),
    &requested.execution_request(),
)?;

runtime.start_video_output(plan, requested)?.run()?;

H264Mov is a convenient macOS preset. Configurable video, audio, and combined media-file targets are available when the codec, container, dimensions, cadence, or quality must be explicit.

Playback and interactive frames

Playback and export use the same graph and preparation model. An interactive request asks a prepared plan for a frame at a specific media time rather than running the entire output range.

Applications that receive rapid, replaceable requests—such as a playhead being scrubbed—can use the latest-request scheduler. It discards obsolete queued work while preserving the currently executing request and the runtime’s bounded caches.

For concurrent audio and video playback, use the concurrent runtime. It owns native audio and video state on dedicated workers and presents a thread-safe interface to the application.

Output policy

The request controls delivery details such as output dimensions, cadence, destination, and preparation policy. These do not become graph operations because they describe how a logical result is delivered, not how media is transformed inside the graph.

GPU-surface output preserves backend-native storage. CPU-buffer output explicitly materializes packed pixels for consumers such as thumbnails or pixel inspection. A preparation policy can require, prefer, or merely allow hardware decoding and zero-copy surface import.

Where to go next

• Learn how the facade selects its system runtime and output targets.
• Run common graphs through the command-line interface.
• Produce graph parameters with tracking and stabilization.
• Read how Passtape works for the data flow from graph construction through preparation, native execution, and output.

Passtape is a library for defining media transformation graphs and running them with the system media backend.

use passtape::{MediaGraph, new_runtime};

let mut runtime = new_runtime()?;
let mut graph = MediaGraph::builder("transcode");
// Add sources, operations, and outputs to the graph.

The facade selects its video and audio backends at build time. Platform-neutral graph, planning, and custom-runtime APIs are re-exported from passtape-engine. Platform crates remain available when an application needs native surfaces, errors, or backend-specific configuration.

On macOS, the facade exposes VideoFile for H.264, HEVC, and ProRes, AudioFile for AAC, Apple Lossless, or PCM, and MediaFile for video and/or audio outputs. H264Mov and H264AacMov are convenience presets. These are output targets driven by the generic runtime’s prepared output sessions. The corresponding VideoFileSpecification, AudioFileSpecification, and MediaFileSpecification types describe preparation without choosing a destination path; at(path) binds one when execution begins.

Continue with the Passtape docs or read how Passtape works.

passtape-cli is a command-line entry point for running Passtape media graphs.

passtape-cli audio input.wav output.m4a
passtape-cli audio input.wav output.flac --codec flac
passtape-cli audio input.wav output.caf --codec opus
passtape-cli audio input.wav output.m4a --target-lufs -14 --max-true-peak-dbtp -1
passtape-cli audio-mix first.wav second.wav output.m4a
passtape-cli transcode input.mov output.mov
passtape-cli transcode input.mov output.mp4 --codec hevc
passtape-cli video input.mov output.mov
passtape-cli video input.mov output.mp4 --codec hevc
passtape-cli video input.mov output.mov --codec hevc-main10
passtape-cli video input.mov output.mov --codec prores-4444
passtape-cli sequence a.mov b.mov c.mov --output edit.mov
passtape-cli alpha-over background.mov foreground.mov output.mov
passtape-cli mix first.mov second.mov output.mov --amount 0.5
passtape-cli resize input.mov output.mov --width 1280 --height 720
passtape-cli blur input.mov output.mov --radius 12
passtape-cli transform input.mov output.mov --translation-x 100 --scale-y -1 --rotation 15

audio builds an audio source-to-output graph. --codec selects AAC, Apple Lossless, FLAC, Opus, or PCM; the output extension selects a compatible M4A, CAF, WAV, AIFF, FLAC, MOV, or MP4 container. --target-lufs enables a complete analysis pass and rebuilds the graph with media.audio.normalize. --max-true-peak-dbtp sets the reconstructed PCM peak ceiling before encoding; the default is -1. Lossy codecs can introduce new peaks, so this option does not promise the decoded AAC or Opus result remains below that ceiling. audio-mix sums two matching audio streams through media.audio.mix and writes their shared duration to an AAC .m4a file. transcode builds video and audio source-to-output branches and prepares both in one request. Its output extension selects MOV or MP4, --codec selects H.264, HEVC Main/Main 10/alpha, or a ProRes 422/4444 profile, and audio is encoded as AAC. video builds only a video source-to-output graph. Its output extension selects MOV or MP4, and --codec selects the video codec. ProRes requires MOV, and ProRes 4444 preserves alpha. alpha-over places a foreground with transparency over a background. sequence opens each input independently and routes the complete videos end-to-end without adding a processing pass at hard cuts. mix builds a two-source graph with media.video.mix; --amount 0 selects the first input and --amount 1 selects the second. resize uses a video-only graph and requests fixed dimensions from the output target. blur applies media.video.blur.gaussian with a radius from zero to 64 pixels. transform applies translation, independent axis scale, and clockwise rotation. Each command prepares its graph with the generic Passtape runtime.

The passtape facade selects the system implementation at build time, so the commands do not construct or import a platform backend directly.

The commands run on macOS. Video operation commands produce video without audio; audio and audio-mix produce standalone audio files. Two-input video operations require matching dimensions and color metadata and use the inputs’ shared duration. Alpha-over preserves the foreground’s BGRA alpha channel. Audio mix inputs must have matching sample rates and channel counts. The CLI never overwrites an existing output file.

Offline geometric tracking for Passtape. On macOS, the crate uses Apple Vision to track object bounds, projected quadrilaterals, or global camera motion. Callers provide ordered frame times and an indexed frame loader, allowing each CVPixelBuffer to be decoded and released as Vision advances instead of retaining the full range.

The crate does not decode media or mutate a Passtape graph. Bounds results convert into synchronized translation, scale, and rotation parameter curves accepted by Passtape’s power-window operation. Quadrilateral results convert into four synchronized point curves accepted by the corner-pin operation. Camera-motion results are immutable measurements consumed by passtape-stabilization or another correction solver.

Run the optimized Apple Vision throughput matrix with:

cargo bench -p passtape-tracking --bench vision_tracking

The matrix covers bounds and quadrilateral tracking, fast and accurate quality, forward and bidirectional traversal, 360p through 1080p, and short and longer frame ranges. Fixture allocation happens before measurement.

Platform-independent camera-motion smoothing for Passtape. It converts an immutable passtape-tracking motion track into ordinary transform keyframes; rendering remains the responsibility of the existing graph operations.

Attach the returned translation and rotation curves to the matching video_transform_2d parameters. Attach the returned uniform scale curve to both scale_x and scale_y, with a centered anchor and zero crop parameters.