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>,
}

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

media_type: MediaType

sample_rate: Option<u32>

channels: Option<u16>

sample_format: Option<SampleFormat>

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>

height: Option<u32>

pixel_format: Option<PixelFormat>

frame_rate: Option<Rational>

extradata: Vec<u8>

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

bit_rate: Option<u64>

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.

Implementations

impl CodecParameters

pub fn audio(codec_id: CodecId) -> Self

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

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"));

Trait Implementations

impl Clone for CodecParameters

fn clone(&self) -> CodecParameters

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.