Crate avio

Expand description

avio is a safe, high-level video-editing engine for Rust: assemble a Timeline of Clips, edit it through an Editor, and render it to a file.

The engine owns the editing model (timeline / clips / tracks, the model-to-scene derivation, and edit history) and speaks in ff-format value types (VideoCodec, AudioCodec, PixelFormat, Color, TextSpec, …) plus the ff-filter authoring types (FilterStep, BlendMode, AnimationTrack, …). The lower-level ff-* primitives (standalone decoders, encoders, pipelines, stream outputs, the GPU compositor) live in their own crates; depend on those directly when you need a primitive. See docs/adr/0004-avio-engine-not-facade.md.

§Feature flags

Feature	Default	Effect
`hwaccel`	yes	hardware-accelerated export (`ff-encode/hwaccel`)
`preview`	no	real-time `TimelinePlayer` + `Scene` types
`serde`	no	`serde` (de)serialization of the model
`gpu`	no	GPU compositing for preview and export (`wgpu`)
`gpl`	no	GPL-only codecs (x264 / x265)

The editing model, render, probe (open), and media analysis are always present.

§Quick start

Build a Timeline of Clips and render it with an EncoderConfig; the timeline_render example is a complete end-to-end flow.

use avio::{Clip, EncoderConfig, Timeline, VideoCodec, AudioCodec, BitrateMode};

let timeline: Timeline = /* build from clips */ Timeline::default();
timeline.render("output.mp4", EncoderConfig::builder()
    .video_codec(VideoCodec::H264)
    .audio_codec(AudioCodec::Aac)
    .bitrate_mode(BitrateMode::Crf(23))
    .build())?;

Edit through an Editor with Commands (undo/redo), inspect a source with open before importing it, and - with the preview feature - play a timeline in real time via TimelinePlayer.

§Projects using avio

avio-editor-demo is a non-linear video editor and the primary driver of this API: multi-track composition with per-clip colour correction and transitions, a real-time preview that matches the exported result, and scene / silence / loudness analysis.

Structs§

AnimationTrack: A sorted collection of keyframes with interpolated value_at(t) lookup.
AudioFrame: A decoded audio frame.
AudioStreamInfo: Information about an audio stream within a media file.
AudioStreamInfoBuilder: Builder for constructing AudioStreamInfo.
BlackFrameDetector: Detects black intervals in a video file and returns their start timestamps.
BpmResult: Result of BPM (beats-per-minute) detection over an audio stream.
ChapterInfo: Information about a chapter within a media file.
ChapterInfoBuilder: Builder for constructing ChapterInfo.
Clip: A single media clip on a timeline.
ClipEffect: One typed effect in a Clip’s ordered effect list.
ClipId: Stable identity of a Clip within a Timeline.
Color: An 8-bit-per-channel RGBA color value.
ContainerInfo: Container-level metadata extracted from AVFormatContext.
ContainerInfoBuilder: Builder for ContainerInfo.
DrawTextOptions: Options for the drawtext filter.
Editor: A stateful editing session: an undo/redo history of Timeline versions.
EffectDescriptor: A host-facing description of an effect kind and its editable parameters, returned by EffectKind::descriptor. Lets a UI render a parameter panel generically, without hard-coding each EffectKind variant.
EffectId: Stable identity of a ClipEffect within a Clip.
EncoderConfig: Codec and quality configuration for the pipeline output.
EncoderConfigBuilder: Consuming builder for EncoderConfig.
FrameHistogram: Per-channel color histogram for a single video frame.
GpuCompositor: Composites derived layers on the GPU, returning None (CPU fallback) on unsupported content or any GPU error.
GpuLayerPlan: One layer of a GpuScenePlan: the transform / blend / opacity the ff_render::Compositor needs, plus the per-layer effect nodes to run before compositing. The transform is stored as scalars (evaluated at the frame time); Br3/Br4 build the ff_render::LayerTransform from them.
GpuPreviewCompositor: Preview adapter over GpuCompositor: composites the runner’s layers on the GPU, falling back to None (the runner’s CPU path) on unsupported content or a GPU error.
GpuScenePlan: A whole frame’s GPU compositing plan: the output canvas and the z-ordered layers.
GroupId: Stable identity of a clip group within a Timeline.
Hdr10Metadata: HDR10 static metadata (MaxCLL + MaxFALL + mastering display).
Histogram: 256-bin luminance and per-channel RGB histogram.
HistogramExtractor: Extracts per-channel color histograms at configurable frame intervals.
Keyframe: A single keyframe in an animation track.
KeyframeEnumerator: Enumerates the timestamps of all keyframes in a video stream.
Marker: A labelled point on the timeline.
MarkerId: Stable identity of a Marker within a Timeline.
MasteringDisplay: Mastering display colour volume (SMPTE ST 2086).
MediaInfo: Information about a media file.
MediaInfoBuilder: Builder for constructing MediaInfo.
NetworkOptions: Shared network configuration for network-backed decoders and live outputs.
ParamDescriptor: A host-facing description of one effect parameter (see EffectDescriptor).
PlayerHandle: Shared, cloneable handle to a running PlayerRunner.
Progress: Progress information delivered to the caller on each processed frame.
Rational: A rational number represented as a fraction (numerator / denominator).
RealtimeLayer: One layer in a RealtimeComposer, composited bottom-up in Vec order (index 0 is the base; later layers blend on top).
RealtimeLayerDescriptor: The dimension-independent part of a RealtimeLayer: every field except width / height / pixel_format, which are only known once a frame has been decoded.
Rgb: An RGB colour value used by the three-way colour corrector.
RgbParade: Per-channel waveform monitor data (RGB parade).
RgbaFrame: A decoded video frame as contiguous RGBA bytes.
RgbaSink: Reference FrameSink implementation that stores the latest frame in a shared Arc<Mutex<Option<RgbaFrame>>>.
Scene: A whole timeline’s worth of playback work, described without the editing model.
SceneAudioPlacement: One audio-only clip placed on the timeline.
SceneAudioTrack: One dedicated audio-only track (A1, A2, …).
SceneDetector: Detects scene changes in a video file and returns their timestamps.
ScenePlacement: One video clip placed on the timeline.
SceneRunner: Exclusive owner of the timeline decode pipeline.
SceneVideoTrack: One video track: an ordered list of clip placements along the timeline. The track’s index in Scene::video_tracks is its compositing order (0 = base).
ScopeAnalyzer: Scope analysis utilities for decoded video frames.
SilenceDetector: Detects silent intervals in an audio file and returns their time ranges.
SilenceRange: A detected silent interval in an audio stream.
SubtitleEvent: A single subtitle event (cue).
SubtitleStreamInfo: Information about a subtitle stream within a media file.
SubtitleStreamInfoBuilder: Builder for constructing SubtitleStreamInfo.
SubtitleTrack: A parsed subtitle track containing ordered events.
TextSpec: A text/title layer: the string, its placement, and its styling.
TextStyle: Visual styling for a text layer.
Timeline: An ordered layout of Clip instances across video and audio tracks.
TimelineBuilder: Builder for Timeline.
TimelinePlayer: Thin builder for a (SceneRunner, PlayerHandle) pair backed by a Timeline.
Timestamp: A timestamp representing a point in time within a media stream.
Track: An ordered list of Clips and its editorial state.
TrackAutomation: Typed, per-property track-level automation.
TrackId: Stable identity of a Track within a Timeline.
VideoEffectRenderer: Reusable single-frame renderer for a Clip’s video effect chain.
VideoFrame: A decoded video frame.
VideoStreamInfo: Information about a video stream within a media file.
VideoStreamInfoBuilder: Builder for constructing VideoStreamInfo.
WaveformAnalyzer: Computes peak and RMS amplitude per time interval for an audio file.
WaveformSample: A single waveform measurement over a configurable time interval.

Enums§

AlphaMode: Alpha modes.
AnalysisError: Errors that can occur during media analysis (scene / silence / BPM / histogram / keyframe / black-frame / waveform).
Anchor: Where a text layer is anchored within its canvas.
AnimatedValue: A value that is either constant or animated over time.
AudioCodec: Audio codec identifier.
AudioProperty: An audio-track property that a TrackAutomation can animate.
BitrateMode: Bitrate control mode for video encoding.
BlendMode: Specifies how two video layers are combined during compositing.
ChannelLayout: Audio channel layout representing the speaker configuration.
ClipProperty: A per-clip property that Command::SetClipProperty can set.
ClipSource: The origin of a clip’s frames.
ColorPrimaries: Color primaries defining the color gamut (the range of colors that can be represented).
ColorRange: Color range defining the valid range of color values.
ColorSpace: Color space (matrix coefficients) for YUV to RGB conversion.
ColorTransfer: Color transfer characteristic (opto-electronic transfer function).
Command: A single, value-based edit to a Timeline. Apply it with apply.
CompositeOp: Porter-Duff compositing operator for combining two video layers.
DecodeError: Errors that can occur during decoding operations.
Easing: Easing function applied to a keyframe interval.
EditError: An edit that could not be applied to a Timeline.
EffectDomain: Which of a clip’s media streams an EffectKind applies to (#1712).
EffectKind: A typed effect that a clip can carry. #[non_exhaustive]: more kinds are added over time, so external matchers must include a _ arm.
EncodeError: Encoding error type.
EqBand: A single band for the parametric equalizer.
ErrorSeverity: Severity class of a media error: whether the failing operation can be retried without rebuilding the component that raised it.
FilterError: Errors that can occur during filter graph construction and processing.
FilterStep: A single step in a filter chain.
FitMode: How a clip’s source frame is framed against the project canvas.
FormatError: Error type for format-related operations.
FrameError: Error type for frame operations.
GpuEffect: A per-layer effect the GPU path can apply, mapped from a FilterStep. #[non_exhaustive]: more kinds are added as node coverage grows.
GpuFallback: Why a frame cannot composite on the GPU and falls back to the CPU compositor. #[non_exhaustive]: more reasons appear as coverage changes.
GpuMapping: The result of mapping a frame: a GPU plan, or a whole-frame CPU fallback.
GpuTransition: The ff-render transition node an XfadeTransition renders as.
HwAccel: Hardware acceleration backend for filter graph operations.
Pacing: How SceneRunner::run paces frame delivery.
Param: One parameter of an EffectKind: a constant value or a keyframe track.
ParamValue: The type, editable metadata, and current value of an effect parameter. The variant tells a host which editor to render (slider / checkbox / number field / colour picker / file picker / curve editor).
PitchAlgo: Backend algorithm for the PitchShift and TimeStretch steps.
PixelFormat: Pixel format for video frames.
PreviewError: Errors that can occur during preview and proxy operations.
ProbeError: Error type for media probing operations.
SampleFormat: Audio sample format for audio frames.
ScaleAlgorithm: Resampling algorithm for the scale filter.
SceneSource: The video source backing a ScenePlacement: a decoded media file, or a generated (solid-colour / text) source rendered without a file — the preview counterpart of the engine’s ClipSource. Generated sources are produced by ff-filter’s SolidSource / TextSource (the same color / drawtext filters the export path uses), so preview matches export.
SubtitleCodec: Subtitle codec identifier.
SubtitleError: Error type for subtitle parsing operations.
TimelineError: Errors from building or rendering the editing model.
TimelineIssue: A single problem found by Timeline::validate.
ToneMap: Tone-mapping algorithm for HDR-to-SDR conversion.
TrackKind: Which track list a TrackId refers to.
VideoCodec: Video codec identifier.
VideoProperty: A video-layer property that a TrackAutomation can animate.
XfadeTransition: Transition type for the xfade cross-dissolve filter.
YadifMode: Deinterlacing mode for the yadif filter.

Traits§

FrameSink: A sink that receives decoded video frames as contiguous RGBA bytes.
GpuLayerSource: A derived layer the GPU mapping can read. Implemented for the export VideoLayer, the preview RealtimeLayerDescriptor, the runner’s realized RealtimeLayer, and &T for any of them (so a &[&RealtimeLayer] maps like a &[RealtimeLayer]), keeping the mapping one shared implementation.
IoSink: A byte sink FFmpeg can mux into.
IoSource: A byte source FFmpeg can demux from.
MediaError: Shared classification for the ff-* crate error types.
PreviewCompositor: An external compositor the preview runner can use in place of its built-in CPU compositor. Implemented by avio over ff-render; see the module docs.

Functions§

apply: Applies command to timeline, returning a new Timeline.
map_scene: Maps a derived layer set (bottom to top) at frame time t to a GpuMapping.
map_transition: The GPU node for kind, or None when it has no equivalent and must stay on the CPU path.
open: Opens a media file and extracts its metadata.

Crate avio

Crate avio Copy item path

§Feature flags

§Quick start

§Projects using avio

Structs§

Enums§

Traits§

Functions§

Crate avio