framefinery-api
framefinery-api contains the reusable media primitives behind FrameFinery.
It is intentionally codec-agnostic: codec crates and applications can share
frame buffers, pixel-format handling, pipeline traits, and small reusable
filters without depending on AV2, VVC, or the ff command-line frontend.
API Surface
The crate is organized around a simple media pipeline:
Source -> Filter -> Encoder -> Sink
Important public types:
FrameInfo,Frame,FrameRef,PixelFormat,SampleBitDepth, andChromaSamplingdescribe raw frames and validated buffer sizes.CodecId,VideoEncoderConfig,RawVideoFrameSource,VideoEncoderSession, andEncodedVideoChunkdefine the molten v0 video encoder API contract.DecodedPictureBuffer,DpbEntry, andPictureIdprovide codec-neutral reference-picture storage helpers without imposing codec reference-list policy.Source,Filter,Encoder, andSinkare small traits for pipeline stages.run_frame_filter_pipelineandrun_frame_encode_pipelineconnect stages and report frame/packet counts.IdentityFilteris the no-op transform filter.PatternSourceandPatternKindgenerate deterministic raw-video test frames.FILTERSandfilter_manifestexpose the reusable filter catalog used by theffCLI.FilterStageSpec,FilterPipelineSpec,FilterPipelineBuilder,build_source_filter,build_raw_video_source_filter,generate_source_filter_stream, andbuild_filter_transformlet frontends pass filter specs through the core registry without knowing concrete filter implementation types.generate_source_filter_streamis a short-fixture helper that collects all requested frames; streaming callers should prefer the raw source builders.FrameSourceRawVideoAdapter,FilteredRawVideoFrameSource, andRawVideoFrameSourceReadAdapterbridge owned-frame filters, raw-frame callbacks, and legacy byte-reader encoders without buffering whole streams.FilterSpecManifestdescribes each filter's accepted spec forms, parameters, examples, and notes.
Filters
Filter manifests live in this crate so library users and the CLI discover the same compiled stages:
use ;
let filter = filter_manifest.expect;
assert_eq!;
assert_eq!;
Filter spec metadata is structured so applications can render their own help pages without copying CLI strings:
use filter_spec_manifest;
let spec = filter_spec_manifest.expect;
assert_eq!;
PatternSource is modeled as a source filter because it creates frames instead
of transforming an input stream:
use ;
let info = new?;
let mut source = new?;
let frame = source.pull?.expect;
assert_eq!;
# Ok::
Current pattern output supports planar YUV and gray formats from 8 through 16
bits, plus gbrp8 and rgb24. The accepted pattern names are black,
checker, gradient, and color_blocks; blocks is accepted as a short alias
for color_blocks.
crop extracts rectangular regions. Subsampled planar formats require crop
coordinates and dimensions aligned to chroma samples. scale resizes frames
with deterministic nearest-neighbor sampling. Both transforms keep the input
pixel format and update frame geometry before encoder construction.
Features
The default product-filters feature enables the executable filter catalog for
direct framefinery-api users:
filter-patternfilter-identityfilter-cropfilter-scaleall-filters
Applications that want a smaller compiled surface can disable default features
and enable individual filter implementations. all-filters is kept as a
compatibility alias for the complete filter catalog:
= {
version = "0.0.3",
= false,
= ["filter-identity"]
}
Disabled filters are not listed in FILTERS. Concrete implementation types and
helpers, such as IdentityFilter and PatternSource, are compiled only when
their matching filter-* feature is enabled.
v0 Video API
The first encoder API contract is documented in
../../docs/api-v0.md. It is intentionally molten: the
contract is useful enough for the CLI, Rust API, and future WASM work to share a
direction, but it can still change before 0.1.0.
Long-stream adapters should prefer RawVideoFrameSource: the caller fills one
frame buffer on demand and the encoder consumes frames without requiring the
whole raw stream to be resident in memory or requiring a total frame count up
front. VideoEncoderConfig::frame_limit is an optional caller/source bound,
not an encoder requirement. Frame remains the owned post-filter and
reconstruction type; FrameRef is the borrowed validated view.
When filters are used before a source-driven encoder, prefer
FilteredRawVideoFrameSource over collecting the filtered stream into a
Vec<u8>. It owns at most the current input frame and queued filter outputs,
which keeps long generated or captured streams usable for native and future
WASM integrations.
Errors
Public fallible APIs return framefinery_api::Result<T>, an alias for
Result<T, MediaError>. Buffer sizes and frame dimensions are validated before
frame construction or pattern generation.
Encoder-facing API boundaries use structured MediaError variants for common
failures such as unsupported codecs, unsupported pixel formats, unknown or
invalid settings, short raw-frame reads, encode-after-flush, and frame-limit
violations. Experimental codec internals may still surface string messages
until the failure mode is stable enough to expose directly.