Struct CodecInfo 

#[non_exhaustive]
pub struct CodecInfo {
    pub id: CodecId,
    pub capabilities: CodecCapabilities,
    pub decoder_factory: Option<DecoderFactory>,
    pub encoder_factory: Option<EncoderFactory>,
    pub probe: Option<ProbeFn>,
    pub tags: Vec<CodecTag>,
    pub payload_magics: Vec<Vec<u8>>,
    pub encoder_options_schema: Option<&'static [OptionField]>,
    pub decoder_options_schema: Option<&'static [OptionField]>,
    pub engine_id: Option<&'static str>,
    pub engine_probe: Option<EngineProbeFn>,
}

A single registration: capabilities, decoder/encoder factories, optional probe, and the container tags this codec claims.

Codec crates build one of these per codec id inside their register(reg) function and hand it to CodecRegistry::register. The struct is #[non_exhaustive] so additional fields can be added without breaking existing codec crates — construction is only possible through CodecInfo::new plus the builder methods below.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

id: CodecId

Canonical codec identifier this entry registers.

capabilities: CodecCapabilities

Capability description (media kind, feature flags, priority).

decoder_factory: Option<DecoderFactory>

Factory producing a fresh decoder instance, if decode is supported.

encoder_factory: Option<EncoderFactory>

Factory producing a fresh encoder instance, if encode is supported.

probe: Option<ProbeFn>

Probe function that returns a confidence in 0.0..=1.0 for a given ProbeContext. None means “confidence 1.0 for every claimed tag” — the correct default for codecs whose tag claims are unambiguous.

tags: Vec<CodecTag>

Tags this codec is willing to be looked up under. One codec may claim many tags (an AAC decoder covers several WaveFormat ids, a FourCC, an MP4 OTI, and a Matroska CodecID string at once).

payload_magics: Vec<Vec<u8>>

Payload magic prefixes this codec answers to (\x01vorbis, OpusHead, …). Some carriage formats have no codec tag — the codec is announced by a magic byte prefix on the payload itself (an Ogg logical stream’s first packet is the canonical case; raw elementary streams are another). Such claims are prefix-matched by CodecRegistry::resolve_payload_magic_ref instead of living in the exact-match CodecTag index. Attached with Self::payload_magic / Self::payload_magics. Empty prefixes are ignored at registration time (a zero-length prefix would match every stream while carrying no evidence).

encoder_options_schema: Option<&'static [OptionField]>

Schema of the encoder’s recognised option keys (CodecParameters::options). Attached with Self::encoder_options. Used for validation / oxideav list / pipeline JSON checks.

decoder_options_schema: Option<&'static [OptionField]>

Schema of the decoder’s recognised option keys.

engine_id: Option<&'static str>

HW backend identifier, e.g. "nvidia", "vaapi", "vdpau", "vulkan-video", "videotoolbox". Set by HW siblings on every CodecInfo they register; SW codecs leave this None. Consumers (e.g. the CLI’s info command) use it to group codec entries by backend and to dedupe probe calls — multiple CodecInfo entries with the same engine_id typically share an engine_probe function, and consumers should call the probe at most once per engine_id per pass. Attached via Self::with_engine_id.

engine_probe: Option<EngineProbeFn>

Optional engine probe function. When Some, calling it returns one crate::engine::HwDeviceInfo entry per device the backend sees. Phase-2 HW siblings populate this on every CodecInfo they register; Phase-3 consumers (CLI) call it on demand. Attached via Self::with_engine_probe.

Implementations

impl CodecInfo

pub fn new(id: CodecId) -> Self

Start a new registration for id with empty capabilities, no factories, no probe, and no tags. Chain the builder methods below to fill it in, then hand the result to CodecRegistry::register.

pub fn capabilities(self, caps: CodecCapabilities) -> Self

Replace the capability description. The default built by Self::new is a placeholder (audio-flavoured, no flags); every real registration should call this.

pub fn decoder(self, factory: DecoderFactory) -> Self

Builder: attach the decoder factory.

pub fn encoder(self, factory: EncoderFactory) -> Self

Builder: attach the encoder factory.

pub fn probe(self, probe: ProbeFn) -> Self

Builder: attach a confidence probe (see CodecInfo::probe).

pub fn tag(self, tag: CodecTag) -> Self

Claim a single container tag for this codec. Equivalent to .tags([tag]) but avoids the array ceremony for single-tag claims.

pub fn tags(self, tags: impl IntoIterator<Item = CodecTag>) -> Self

Claim a set of container tags for this codec. Takes any iterable (arrays, Vec, Option, …) so the common case of a codec with 3-6 tags reads as one clean block.

pub fn payload_magic(self, magic: impl Into<Vec<u8>>) -> Self

Claim one payload magic prefix for this codec (see Self::payload_magics). Chain repeatedly for codecs that answer to more than one magic:

let info = CodecInfo::new(CodecId::new("vorbis")).payload_magic(b"\x01vorbis");

pub fn payload_magics<I>(self, magics: I) -> Self

where I: IntoIterator, I::Item: Into<Vec<u8>>,

Claim a set of payload magic prefixes for this codec — the iterable companion to Self::payload_magic, mirroring the Self::tag / Self::tags pair.

pub fn encoder_options<T: CodecOptionsStruct>(self) -> Self

Declare the options struct this codec’s encoder factory expects. Attaches T::SCHEMA so the registry can enumerate recognised option keys (for oxideav list, pipeline JSON validation, etc.). The factory itself still has to call crate::parse_options::<T>() against CodecParameters::options at init time.

pub fn decoder_options<T: CodecOptionsStruct>(self) -> Self

Declare the options struct this codec’s decoder factory expects. See Self::encoder_options for the encoder counterpart.

pub fn with_engine_id(self, engine_id: &'static str) -> Self

Tag this codec as belonging to a HW backend identified by engine_id. Should match the engine_id of every other CodecInfo registered by the same backend, and the corresponding engine_id field used by the CLI for grouping. SW codecs leave this unset.

pub fn with_engine_probe(self, probe: EngineProbeFn) -> Self

Attach a probe function. Consumers call it to enumerate the engines (devices) this backend can dispatch to. Probes are expected to be idempotent and side-effect free; consumers may call them more than once per process and should dedupe by Self::engine_id.