Struct CodecParameters 

#[non_exhaustive]
pub struct CodecParameters {

    pub codec_id: CodecId,
    pub media_type: MediaType,
    pub sample_rate: Option<u32>,
    pub channels: Option<u16>,
    pub sample_format: Option<SampleFormat>,
    pub channel_layout: Option<ChannelLayout>,
    pub width: Option<u32>,
    pub height: Option<u32>,
    pub pixel_format: Option<PixelFormat>,
    pub frame_rate: Option<Rational>,
    pub extradata: Vec<u8>,
    pub bit_rate: Option<u64>,
    pub options: CodecOptions,
    pub limits: DecoderLimits,
    pub device_index: Option<u32>,
    pub tag: Option<CodecTag>,
    pub language: Option<String>,
    pub color_signal: ColorSignal,
    pub layers: Vec<LayerInfo>,
}

Codec-level parameters shared between demuxer/muxer and en/decoder.

Marked #[non_exhaustive] — construction via struct-literal syntax is not supported. Use the audio / video constructors (or functional-update CodecParameters { ..base } syntax) so new fields can be added without another semver break.

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.

codec_id: CodecId

Registry identifier of the codec this stream is encoded with.

media_type: MediaType

Whether this stream is audio, video, subtitle, or data. Set by the constructor (audio, video, subtitle, data).

sample_rate: Option<u32>

Audio: sample rate in Hz. None for non-audio streams.

channels: Option<u16>

Audio: number of channels. See Self::resolved_channels for the layout-aware accessor.

sample_format: Option<SampleFormat>

Audio: sample format of the decoded output (or encoder input).

channel_layout: Option<ChannelLayout>

Speaker layout for the audio stream. This is the canonical answer to “what layout does this stream have?” — layout is a stream-level property and is intentionally not duplicated on individual AudioFrames.

Optional and additive alongside channels: a codec/container that only knows the count can leave this None and consumers will fall back to ChannelLayout::from_count via Self::resolved_layout. When both are set, they must agree on channel count.

width: Option<u32>

Video: coded frame width in pixels. None for non-video streams.

height: Option<u32>

Video: coded frame height in pixels. None for non-video streams.

pixel_format: Option<PixelFormat>

Video: pixel format of the decoded output (or encoder input).

frame_rate: Option<Rational>

Video: nominal frame rate in frames per second, as a rational (e.g. 30000/1001). None when unknown or variable.

extradata: Vec<u8>

Per-codec setup bytes (e.g., SPS/PPS, OpusHead). Format defined by codec.

bit_rate: Option<u64>

Nominal stream bit rate in bits per second, when the container or encoder declares one.

options: CodecOptions

Codec-specific tuning knobs (e.g. {"interlace": "true"} for PNG’s Adam7 encode, {"crf": "23"} for h264). Empty by default. The shape is declared by each codec’s options struct — see crate::options. Parsed once at encoder/decoder construction; the hot path never touches this.

limits: DecoderLimits

DoS-protection caps threaded into every decoder constructed from these parameters. See DecoderLimits for the semantics of each field. Defaults are conservative-but-finite (32 k × 32 k pixels, 1 GiB per arena, etc.) — every existing real-world stream decodes unchanged. Tighten via Self::with_limits when the caller wants to harden the pipeline against untrusted input.

device_index: Option<u32>

Optional 0-based device selector for hardware-accelerated codecs. None (the default) means “use the backend’s default device”; Some(n) requests device n from the backend’s crate::engine::HwDeviceInfo enumeration order.

Software codecs ignore this field. Hardware codecs read it as params.device_index.unwrap_or(0) to pick which physical engine to bind to. Indexing matches the order of devices reported by the codec entry’s engine_probe function.

tag: Option<CodecTag>

On-wire tag for this stream — the FourCC / WAVEFORMATEX wFormatTag / MP4 ObjectTypeIndication / Matroska CodecID string carried by the container. Set by the producer:

• Demuxers populate this from the stream’s container header at read-time so muxers re-emitting the same stream round-trip the original tag byte-for-byte (mpeg4video demuxed as DIVX re-muxes as DIVX, not as the codec crate’s first-declared XVID).
• Encoders populate this in crate::Encoder::output_params to tell muxers which wire tag to write — needed for multi-FourCC codecs whose configuration (pixel format / bit depth / alpha / chroma sampling) selects one of several valid FourCCs (e.g. MagicYUV’s 17 native v7 codes).

None is the default — sensible for in-memory streams that haven’t been bound to a container yet. Muxers that need a wire tag and find None here will fall back to whatever container-specific synthesis they support (e.g. AVI’s PCM wFormatTag synthesis from sample_format, or the extradata[0..4] printable-FourCC hint for legacy callers) and otherwise return Error::Unsupported.

language: Option<String>

BCP-47 / ISO 639 language tag ("en", "jpn", …) when the container labels the stream’s language. None means “unspecified” — not “neutral”.

Demuxers populate this from the container’s per-track language element (MKV Language / LanguageBCP47, MP4 mdhd ISO 639-2 code, Ogg LANGUAGE= comment, …). Muxers re-emit it on the matching container element so a round-trip preserves the caller-visible tag byte-for-byte. No validation is performed here — the value is whatever string the producer supplied.

color_signal: ColorSignal

Video: the stream’s colour-signal description — sample range plus the H.273 colour primaries / transfer characteristics / matrix coefficients. See crate::signal for the semantics.

Defaults to ColorSignal::unspecified (every field open). Set by the producer: a demuxer from the container’s colour record (an ISOBMFF colr box, a Matroska Colour element, …), a decoder from the bitstream’s own signalling when the container had none, an encoder in output_params() to tell the muxer what to write. Consumers (colour converters, renderers, muxers) read it through resolved_color_range and the fields directly; a per-frame VideoFrame::color_signal record, when present, refines this stream-level value.

Not compared by matches_core: like extradata, it is descriptive metadata that a lossless copy may legitimately rewrite.

layers: Vec<LayerInfo>

Video: description of the stream’s layers for multi-layer / multi-view content (scalable or multi-view coding, auxiliary alpha / depth layers). Empty — the default — for single-layer streams and for producers that do not describe the structure. See crate::layer for the semantics and VideoFrame::layer for the per-frame identity that pairs with it.

Implementations

impl CodecParameters

pub fn audio(codec_id: CodecId) -> Self

Construct audio codec parameters with every optional field unset. Chain builder methods (channels, channel_layout, …) or assign fields directly to fill in the format.

pub fn matches_core(&self, other: &CodecParameters) -> bool

True when self and other have the same codec_id and core format parameters (sample_rate/channels/sample_format for audio, width/height/pixel_format for video). Extradata and bitrate differences are tolerated — many containers rewrite extradata losslessly during a copy operation. channel_layout is compared only via the channel count (through Self::resolved_layout) so a stream that surfaces an explicit layout still matches a count-only stream of the same width.

pub fn video(codec_id: CodecId) -> Self

Construct video codec parameters with every optional field unset. Assign width / height / pixel_format (or use the builder methods) to fill in the format.

pub fn subtitle(codec_id: CodecId) -> Self

Construct subtitle codec parameters. No format-specific fields are populated — subtitle codecs typically only carry an opaque extradata blob (the format’s header / style block) and the codec id.

pub fn data(codec_id: CodecId) -> Self

Construct generic data-stream codec parameters (timed metadata, chapters, etc.). Like Self::subtitle, no format-specific fields are populated.

pub fn channels(self, n: u16) -> Self

Builder method: set the channel count.

Pairs with Self::channel_layout for the layout. The two are kept as independent fields so a codec that only knows one or the other can populate just the field it has; Self::resolved_layout derives a layout from whatever is set.

pub fn channel_layout(self, layout: ChannelLayout) -> Self

Builder method: set the channel layout. Mirrors Self::channels; setting one does not auto-fill the other — use Self::resolved_layout / Self::resolved_channels at read time to bridge the two.

pub fn resolved_layout(&self) -> Option<ChannelLayout>

Best-effort layout: prefers an explicit Self::channel_layout when set, otherwise infers one from Self::channels via ChannelLayout::from_count. Returns None only when neither field is populated (e.g. video / data streams, or audio params surfaced before the codec has been opened).

This is the canonical call-site for resolving a stream’s channel layout — frames do not carry layout, so audio consumers (downmix, device routing, channel-aware filters) should read it from the stream’s CodecParameters once and pass it down with the frame.

pub fn resolved_channels(&self) -> Option<u16>

Best-effort channel count: prefers an explicit Self::channels when set, otherwise reads the count off Self::channel_layout. Returns None only when neither field is populated.

pub fn limits(&self) -> &DecoderLimits

Read-only access to the DoS-protection caps for any decoder constructed from these parameters. See DecoderLimits.

pub fn with_limits(self, limits: DecoderLimits) -> Self

Builder method: replace the DecoderLimits for these parameters. Use to tighten caps before passing parameters into make_decoder (e.g. when processing untrusted uploads on a shared server).

let limits = DecoderLimits::default()
    .with_max_pixels_per_frame(4096 * 4096)
    .with_max_arenas_in_flight(2);
let p = CodecParameters::video(CodecId::new("h263")).with_limits(limits);
assert_eq!(p.limits().max_pixels_per_frame, 4096 * 4096);

pub fn with_device_index(self, index: u32) -> Self

Bind subsequent decoder/encoder construction to a specific device. index matches the position in the engine_probe device list.

Software codecs ignore this field. Hardware codecs read it as params.device_index.unwrap_or(0) to pick which physical engine to bind to.

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

Builder method: set the on-wire tag.

Demuxers call this from their stream-format parser so muxers re-emitting the stream preserve the original FourCC / wFormatTag byte-for-byte. Encoders call this in output_params() to announce which wire tag they’re producing.

let p = CodecParameters::video(CodecId::new("magicyuv"))
    .with_tag(CodecTag::fourcc(b"M8RG"));
assert_eq!(p.tag, Some(CodecTag::fourcc(b"M8RG")));

pub fn with_language(self, language: impl Into<String>) -> Self

Builder method: set the per-stream language tag. Accepts any string — BCP-47 short codes ("en"), ISO 639-2/T three-letter codes ("jpn"), or container-native values are all passed through verbatim. No validation is performed; the muxer writes whatever the caller hands in.

let p = CodecParameters::audio(CodecId::new("aac")).with_language("jpn");
assert_eq!(p.language.as_deref(), Some("jpn"));

pub fn with_color_signal(self, signal: ColorSignal) -> Self

Builder method: set the stream’s color_signal.

// A 10-bit full-range BT.2020 PQ stream, as a container's colour
// record describes it (primaries 9, transfer 16, matrix 9).
let mut p = CodecParameters::video(CodecId::new("h265"))
    .with_color_signal(ColorSignal::from_code_points(9, 16, 9, true));
p.pixel_format = Some(PixelFormat::Yuv420P10Le);
assert_eq!(p.resolved_color_range(), ColorRange::Full);

pub fn with_color_range(self, range: ColorRange) -> Self

Builder method: set only the sample range of the stream’s color_signal, leaving the H.273 triple as it was. For producers that know the range (an alpha plane is full range; a container flag said so) but nothing else.

pub fn resolved_color_range(&self) -> ColorRange

The stream’s effective sample range: the explicit color_signal range when specified, otherwise the range implied by the pixel_format label (PixelFormat::implied_color_range — Full for the YuvJ* formats), otherwise ColorRange::Unspecified. Converters apply their own policy to Unspecified (H.273 suggests limited for video imagery).

pub fn with_layers(self, layers: Vec<LayerInfo>) -> Self

Builder method: replace the stream’s layers description.

// A stereo pair: base layer = left view, layer 1 = right view
// predicted from the base.
let p = CodecParameters::video(CodecId::new("h265")).with_layers(vec![
    LayerInfo::new(0).with_view_id(0),
    LayerInfo::new(1).with_view_id(1).with_depends_on([0u16]),
]);
assert_eq!(p.layers.len(), 2);
assert_eq!(p.layer(1).and_then(|l| l.view_id), Some(1));
assert!(p.is_multi_layer());

pub fn layer(&self, layer_id: u16) -> Option<&LayerInfo>

The description of layer layer_id, when layers lists it.

pub fn is_multi_layer(&self) -> bool

true when layers describes more than one layer. Single-layer streams (and streams whose structure is not described) report false.

Trait Implementations

impl Clone for CodecParameters

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CodecParameters

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.