Crate ffcine

Expand description

ffcine: GPU video finishing. Decode, grade (3D LUTs, tone and gamut mapping, crop/scale, user shaders) and encode, with frames kept in VRAM end to end.

The types here (Pipeline, Grade, Lut, ColorSpace, EncoderSettings) are backend-neutral; backend::Ffmpeg (feature ffmpeg) runs them on ffmpeg’s libav* and libplacebo/Vulkan.

use ffcine::{Backend, Grade, Lut, LutStage, LutType, Pipeline, backend};

let ff = backend::Ffmpeg::new()?;
println!("{}", ff.probe("in.mov".as_ref())?);
let grade = Grade {
    lut: Some(LutStage { lut: Lut::from_cube_file("grade.cube")?, kind: LutType::Normalized }),
    ..Grade::default()
};
Pipeline::new("in.mov", "out.mkv").grade(grade).run(&ff)?;

§Portable API

Use ffcine = { version = "0.4", default-features = false } for timeline editing, LUT parsing, and pipeline construction without native dependencies.

use ffcine::{Pipeline, Rational, timeline::Timeline};

let rate: Rational = "24000/1001".parse()?;
assert_eq!(rate.den, 1001);
let pipeline = Pipeline::new("input.mov", "output.mkv");
assert!(pipeline.stages.is_empty());
let timeline = Timeline::new("Example edit");
assert_eq!(Timeline::from_json(&timeline.to_json()?)?, timeline);

§Features and native dependencies

Feature	Default	Requires
`ffmpeg`	Yes	ffmpeg 9 development libraries; enables audio too
`placebo`	Yes	libplacebo >= 7.365 and Vulkan headers
`nvof`	Yes	`ffmpeg`; NVIDIA optical flow driver at runtime
`audio`	No (enabled by `ffmpeg`)	ffmpeg audio I/O and filters
`telemetry`	No	`nvof`; camera gyro parsing

docs.rs builds the portable API with default features disabled. To browse the GPU backend, use the repository’s Nix shell and run cargo doc --workspace --no-deps --open. The README lists hardware requirements and the supported native build environment.

This crate is a facade: each part lives in its own crate (docs/design.md#crates) and is re-exported here under the module names it always had.

Re-exports§

pub use ffcine_assembly as assembly;
pub use ffcine_audio as audio;
pub use ffcine_breakdown as breakdown;
pub use ffcine_comp as comp;
pub use ffcine_delivery as delivery;
pub use ffcine_filters as filters;
pub use ffcine_hooks as hooks;
pub use ffcine_import as import;
pub use ffcine_ingest as ingest;
pub use ffcine_reframe as reframe;
pub use ffcine_stabilize as stabilize;
pub use ffcine_text as text;
pub use ffcine_timeline as timeline;
pub use ffcine_triage as triage;

Modules§

anim: Param tracks (docs/compositing.md#param-tracks): one type for every numeric, vector and colour parameter, a constant, keyframes with easing, or an expression.
backend: Backends. Only ffmpeg (libav* I/O) + libplacebo (Vulkan processing) exists today.
bake: The LUT baker: a camera LUT, a grade LUT and the look (LookParams) evaluated over a lattice into one 3D LUT, with no ffmpeg in the loop. The result goes on the source as one pl_custom_lut (or out as a .cube for other tools), in the order the GPU pass runs them: camera LUT, grade LUT, look.
blend: Blend modes for crate::Layers (ffcine.comp.blend/1 mode, Resolve’s composite modes): the W3C compositing formulas (Photoshop’s where W3C has none), as a CPU reference and as the GLSL the backend’s composite pass runs. Both work on encoded RGB in 0..1 (the output’s transfer), the backdrop opaque: out = (1 − a) · b + a · B(b, s) with a the layer’s alpha times its opacity.
camera: Camera input profiles: which colour-in a source needs, picked from the probe, and the camera LUTs (log -> Rec.709) that go with them.
color: Colour space description, independent of ffmpeg’s and libplacebo’s enums.
encode: Encoder settings, backend-neutral (names follow ffmpeg’s encoder options).
extra: A grade’s raw ffmpeg filters (extra, after the grade) as GPU hooks: the colour filters the prototype’s edits use, parsed from ffmpeg’s filter syntax (name=k=v:k=v, positional arguments, comma-separated chains) and run as PREOUTPUT hooks in chain order, so nothing falls back to the CPU.
geom: Plane geometry for per-frame warps: 3x3 homogeneous matrices in pixel coordinates.
grade: The grade: everything libplacebo does to a frame between decode and encode.
layer: Picture layers composited over a pipeline’s graded frames in the same GPU pass: split-screen panels, picture-in-picture, stickers and logos, the incoming side of a transition.
lut: 3D LUTs (.cube), parsed on the CPU and uploaded by the backend.
overlay: Overlays composited onto the output in the grade pass (text cards, captions), backend-neutral.
pipeline: A pipeline: one input, a chain of GPU stages, one encoded output.
probe: What a media file contains, as reported by a backend (ffcine_render::Backend).
profile: Delivery render profiles: the encoder and output size for a kind of copy (DeliveryProfile).
shaders: libplacebo user shaders (mpv .hook format) generated by ffcine.

Structs§

Bake: What to bake, applied in this order.
ColorMapTuning: Tuning for libplacebo’s tone and gamut mapping (pl_color_map_params). The defaults are the prototype’s (libavfilter libplacebo with its defaults).
ColorOverride: Overrides for the source’s colour tags (the prototype’s setparams before the grade).
ColorSpace: A complete colour description, as tagged on a stream or requested for an output.
Crop: A rectangle in pixels: a source crop in input pixels, or a placement in output pixels.
Deband: libplacebo’s debanding on the source planes (pl_deband_params).
Denoise: A denoise stage: temporal, then spatial on its result. Either may be off.
Dither: Dithering to the output bit depth.
EncoderSettings: How to encode the graded video.
Grade: One libplacebo render pass: colour conversion (incl. tone and gamut mapping), crop/scale, LUT and user shaders, ending in output.
Grain
HdrMetadata: Static HDR metadata written with an HDR deliverable: the SMPTE ST 2086 mastering display and the CTA-861.3 content light levels (HEVC SEI, and mdcv / clli in MP4 and MOV).
Hook: An inline mpv .hook shader and the values of its //!PARAMs.
Image: An RGBA image, 8 bits per channel, not premultiplied, row-major.
Layer: One layer over output frames from..to.
Lut: A 3D LUT: size^3 RGB entries, red varying fastest (.cube order).
LutStage: A LUT and how to apply it.
Mask: An 8-bit coverage mask, row-major, width * height bytes.
MediaInfo
Overlay: A mask drawn over output frames from..to (pipeline frame indices, 0 = the first frame output), fading in over the first fade_in frames and out over the last fade_out.
OverlayPart: One placement of an overlay’s mask.
ParamTrack: One //!PARAM’s value per output frame: frame i uses values[i], the last one holds past the end.
Pipeline: Decode input, run stages in order, encode with encoder into output.
Rational: An exact ratio (frame rates, time bases).
RunStats: What a Pipeline::run did.
Scaling: Scaling behaviour. The default matches swscale (lanczos, gamma light, no sigmoid) so GPU and CPU geometry agree.
Size: Output size in pixels.
Spatial: Spatial NLM part.
Temporal: Temporal (motion-compensated) part.
Warp: A per-frame warp in the grade pass (the GPU stabilizer’s output): for output frame i, transforms[i] maps output pixels to source pixels, in source pixel coordinates before the crop (the last one repeats past the end). Applied at libplacebo’s MAIN stage with a Catmull-Rom bicubic, black outside the source; the grade’s crop is folded into it.

Enums§

BlendMode: How a layer combines with the picture under it.
Codec: Video encoder.
Decode: Hardware decode API. Both drive the same video decoder; Vulkan hands frames straight to the renderer, CUDA (NVDEC) needs a copy into Vulkan memory per frame.
DeliveryProfile: A delivery profile.
Device: Which GPU to run on.
DitherMethod: Dither algorithm for the output quantization.
Error: Errors from ffcine and its backends.
GamutMapping: How out-of-gamut colours are brought into the target gamut.
LayerSource: Where a layer’s pictures come from.
LutType: What colour space a LUT’s input/output live in (libplacebo’s lut_type).
PixelFormat: Pixel format handed to the encoder.
RateControl: Rate control.
Scaler: Resampling filter.
Stage: One processing step. Frames stay on the GPU between stages.
ToneMapping: HDR -> SDR tone curve.

Traits§

Backend: An implementation of ffcine’s operations. The library’s types don’t depend on any backend; the ffmpeg + libplacebo one is crate::backend::Ffmpeg (feature ffmpeg).

Type Aliases§

Result

Crate ffcine

Crate ffcine Copy item path

§Portable API

§Features and native dependencies

Re-exports§

Modules§

Structs§

Enums§

Traits§

Type Aliases§

Crate ffcine