moq_audio/encode/

encoder.rs

//! Audio encoder front end.
//!
//! [`Encoder`] dispatches over the closed [`Codec`] set. Opus wraps libopus
//! 1.3.1 via [`unsafe_libopus`], while PCM serializes interleaved `f32` samples
//! directly.

use std::str::FromStr;
use std::time::Duration;

use bytes::Bytes;
use unsafe_libopus::{
	OPUS_APPLICATION_AUDIO, OPUS_GET_BITRATE_REQUEST, OPUS_GET_LOOKAHEAD_REQUEST, OPUS_OK, OPUS_RESET_STATE,
	OPUS_SET_BITRATE_REQUEST, OPUS_SET_DTX_REQUEST, OPUS_SET_INBAND_FEC_REQUEST, OpusEncoder, opus_encode_float,
	opus_encoder_create, opus_encoder_ctl_impl, opus_encoder_destroy, varargs,
};

use super::Encoded;
use crate::opus;
use crate::pcm;
use crate::{Error, Format};

/// libopus packet size ceiling per RFC 6716 §3.4.
const MAX_PACKET_BYTES: usize = 4_000;

/// Output audio codec. `#[non_exhaustive]` so new codecs can be added without
/// breaking external `match`es.
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
pub enum Codec {
	/// Opus (RFC 6716), and the default.
	#[default]
	Opus,
	/// Uncompressed interleaved little-endian IEEE-754 binary32 PCM.
	Pcm,
}

impl Codec {
	/// Canonical lowercase identifier, matching the WebCodecs / RFC catalog
	/// string. Used as the wire/FFI codec name everywhere.
	pub fn as_str(self) -> &'static str {
		match self {
			Self::Opus => "opus",
			Self::Pcm => "pcm",
		}
	}
}

impl std::fmt::Display for Codec {
	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
		f.write_str(self.as_str())
	}
}

impl FromStr for Codec {
	type Err = Error;

	fn from_str(s: &str) -> Result<Self, Self::Err> {
		match s {
			"opus" => Ok(Self::Opus),
			"pcm" => Ok(Self::Pcm),
			other => Err(Error::Unsupported(format!("unknown codec: {other}"))),
		}
	}
}

/// The PCM layout of the buffers handed to [`Encoder::encode`] /
/// [`Producer::write`](super::Producer::write).
///
/// The encoder's counterpart to a video encoder's width / height: it describes
/// the input, not the output. `publish_capture` fills it in from the capture
/// source, so only a bring-your-own-PCM caller builds one.
#[derive(Clone, Debug)]
pub struct Input {
	/// How samples are packed in each buffer.
	pub format: Format,
	/// Samples per second per channel. Resampled to the codec rate if they differ.
	pub sample_rate: u32,
	/// Channels per frame.
	pub channels: u32,
}

impl Default for Input {
	fn default() -> Self {
		Self {
			format: Format::F32,
			sample_rate: 48_000,
			channels: 2,
		}
	}
}

/// Encoder configuration: the input PCM layout plus the codec knobs.
///
/// The bring-your-own-PCM counterpart to [`Options`](super::Options), which
/// `publish_capture` uses when the layout comes from the capture source instead
/// of the caller.
///
/// `#[non_exhaustive]`: build via [`Config::new`] and set the optional fields,
/// so future knobs don't break callers.
#[derive(Clone, Debug)]
#[non_exhaustive]
pub struct Config {
	/// The PCM layout fed to the encoder.
	pub input: Input,
	/// Output codec. Defaults to [`Codec::Opus`].
	pub codec: Codec,
	/// Sample rate the codec runs at. `None` snaps [`Input::sample_rate`] up to
	/// the nearest rate the codec supports, resampling if that moved it.
	pub sample_rate: Option<u32>,
	/// Channel count the codec runs at. `None` matches [`Input::channels`];
	/// anything else is rejected, since remapping isn't implemented.
	pub channels: Option<u32>,
	/// Bitrate in bits per second. `None` lets Opus pick. PCM requires `None`
	/// because its bitrate is fixed by the sample rate and channel count.
	///
	/// Rates too low for Opus to code anything at the chosen
	/// [`frame_duration`](Self::frame_duration) are rejected: below its floor
	/// libopus emits empty frames whatever the input, which carry no audio and
	/// are indistinguishable from silence. The floor is 1200 bps at the default
	/// 20 ms, rises for shorter frames (9600 bps at 2.5 ms), and is 2400 bps for
	/// frames of 10 ms and longer.
	pub bitrate: Option<u32>,
	/// Enable Opus in-band forward error correction.
	pub fec: bool,
	/// Enable Opus discontinuous transmission during silence.
	pub dtx: bool,
	/// Encoded frame duration. Opus accepts 2.5 / 5 / 10 / 20 / 40 / 60 ms.
	/// PCM accepts any duration containing a whole number of samples.
	pub frame_duration: Duration,
}

impl Config {
	/// A config encoding `input` with the default codec settings.
	pub fn new(input: Input) -> Self {
		Self {
			input,
			codec: Codec::default(),
			sample_rate: None,
			channels: None,
			bitrate: None,
			fec: false,
			dtx: false,
			frame_duration: Duration::from_millis(20),
		}
	}
}

/// Audio encoder over the PCM layout declared in [`Config::input`].
///
/// Build one with [`Encoder::new`], feed full PCM frames via
/// [`encode`](Self::encode), then pass the trailing partial frame to
/// [`finish`](Self::finish). Publish every packet either call returns and apply
/// the terminal [`Finish::discard_padding`] when the container supports it.
pub struct Encoder {
	backend: Backend,
	config: Config,
	/// Resolved codec sample rate (from `config.sample_rate`, else the input rate
	/// snapped up to a supported one).
	codec_rate: u32,
	/// Resolved codec channel count (currently always the input's).
	codec_channels: u32,
	/// Current libopus target bitrate.
	bitrate: u64,
	/// Encoder lookahead expressed in the OpusHead 48 kHz timebase.
	pre_skip: u16,
	/// Encoder lookahead in codec-rate frames.
	lookahead: usize,
	frame_size: usize,
	/// Whether input has reached the codec, since a fresh encoder owes no drain.
	started: bool,
}

enum Backend {
	Opus(Opus),
	Pcm,
}

struct Opus {
	inner: *mut OpusEncoder,
	scratch: Vec<u8>,
}

// SAFETY: OpusEncoder is heap-allocated state owned exclusively by this
// struct; libopus encoder methods take a single &mut, so a unique owner is
// allowed to move it across threads.
unsafe impl Send for Opus {}

/// Packets emitted by [`Encoder::finish`] and the decoded padding at their end.
pub struct Finish {
	packets: Vec<Encoded>,
	discard_padding: usize,
}

impl Finish {
	/// Encoded packets in decode order.
	pub fn packets(&self) -> &[Encoded] {
		&self.packets
	}

	/// Decoded frames per channel to discard from the end of the final packet.
	pub fn discard_padding(&self) -> usize {
		self.discard_padding
	}

	/// Consume the result and return its encoded packets.
	pub fn into_packets(self) -> Vec<Encoded> {
		self.packets
	}
}

impl Encoder {
	/// Open an encoder for `config`.
	pub fn new(config: &Config) -> Result<Self, Error> {
		match config.codec {
			Codec::Opus => Self::new_opus(config.clone()),
			Codec::Pcm => Self::new_pcm(config.clone()),
		}
	}

	fn new_opus(config: Config) -> Result<Self, Error> {
		let codec_rate = config
			.sample_rate
			.unwrap_or_else(|| opus::pick_rate(config.input.sample_rate));
		opus::validate_rate(codec_rate)?;

		let codec_channels = config.channels.unwrap_or(config.input.channels);
		if codec_channels != config.input.channels {
			return Err(Error::Unsupported(format!(
				"channel remapping not implemented (input {}ch, output {codec_channels}ch)",
				config.input.channels
			)));
		}
		let channels = opus::validate_channels(codec_channels)?;

		let frame_size = opus::frame_size(codec_rate, config.frame_duration)?;

		let mut err = 0i32;
		// SAFETY: out-pointer `err` is valid; inner is checked for null below.
		let inner = unsafe { opus_encoder_create(codec_rate as i32, channels, OPUS_APPLICATION_AUDIO, &mut err) };
		if err != OPUS_OK || inner.is_null() {
			return Err(opus::error(err, "opus_encoder_create"));
		}

		let configured = Self::configure_opus(inner, &config, codec_rate, codec_channels, frame_size);
		let (bitrate, lookahead, pre_skip) = match configured {
			Ok(configured) => configured,
			Err(err) => {
				// SAFETY: `inner` was created above and not yet handed out.
				unsafe { opus_encoder_destroy(inner) };
				return Err(err);
			}
		};

		Ok(Self {
			backend: Backend::Opus(Opus {
				inner,
				scratch: vec![0u8; MAX_PACKET_BYTES],
			}),
			config,
			codec_rate,
			codec_channels,
			bitrate,
			pre_skip,
			lookahead,
			frame_size,
			started: false,
		})
	}

	fn new_pcm(config: Config) -> Result<Self, Error> {
		if config.bitrate.is_some() {
			return Err(Error::Unsupported(
				"pcm bitrate is fixed; leave Config::bitrate unset".into(),
			));
		}

		let codec_rate = config.sample_rate.unwrap_or(config.input.sample_rate);
		if codec_rate == 0 {
			return Err(Error::Unsupported("pcm sample rate must be greater than zero".into()));
		}

		let codec_channels = config.channels.unwrap_or(config.input.channels);
		if codec_channels == 0 {
			return Err(Error::Unsupported("pcm channel count must be greater than zero".into()));
		}
		if codec_channels != config.input.channels {
			return Err(Error::Unsupported(format!(
				"channel remapping not implemented (input {}ch, output {codec_channels}ch)",
				config.input.channels
			)));
		}

		let frame_size = pcm::frame_size(codec_rate, config.frame_duration)?;
		pcm::frame_bytes(frame_size, codec_channels)?;
		let bitrate = pcm::bitrate(codec_rate, codec_channels)?;
		Ok(Self {
			backend: Backend::Pcm,
			config,
			codec_rate,
			codec_channels,
			bitrate,
			pre_skip: 0,
			lookahead: 0,
			frame_size,
			started: false,
		})
	}

	fn configure_opus(
		inner: *mut OpusEncoder,
		config: &Config,
		codec_rate: u32,
		codec_channels: u32,
		frame_size: usize,
	) -> Result<(u64, usize, u16), Error> {
		if let Some(bitrate) = config.bitrate {
			Self::set_opus_bitrate(inner, codec_channels, bitrate as u64, codec_rate, frame_size)?;
		}
		Self::set_opus_ctl(
			inner,
			OPUS_SET_INBAND_FEC_REQUEST,
			i32::from(config.fec),
			"OPUS_SET_INBAND_FEC",
		)?;
		Self::set_opus_ctl(inner, OPUS_SET_DTX_REQUEST, i32::from(config.dtx), "OPUS_SET_DTX")?;

		let bitrate = Self::get_opus_ctl(inner, OPUS_GET_BITRATE_REQUEST, "OPUS_GET_BITRATE")?;
		let bitrate = u64::try_from(bitrate)
			.map_err(|_| Error::Unsupported(format!("Opus reported negative bitrate {bitrate}")))?;
		let lookahead = Self::get_opus_ctl(inner, OPUS_GET_LOOKAHEAD_REQUEST, "OPUS_GET_LOOKAHEAD")?;
		let lookahead = u64::try_from(lookahead)
			.map_err(|_| Error::Unsupported(format!("Opus reported negative lookahead {lookahead}")))?;
		let pre_skip = u16::try_from((lookahead * 48_000) / codec_rate as u64)
			.map_err(|_| Error::Unsupported(format!("Opus lookahead {lookahead} does not fit in OpusHead")))?;
		let lookahead = usize::try_from(lookahead)
			.map_err(|_| Error::Unsupported(format!("Opus lookahead {lookahead} does not fit in memory")))?;

		Ok((bitrate, lookahead, pre_skip))
	}

	fn set_opus_bitrate(
		inner: *mut OpusEncoder,
		channels: u32,
		bitrate: u64,
		codec_rate: u32,
		frame_size: usize,
	) -> Result<(), Error> {
		let max = 300_000 * channels as u64;
		// Below the floor libopus codes nothing at all, so the stream carries no
		// audio and every packet is framed like discontinuous transmission.
		let min = opus::bitrate_floor(codec_rate, frame_size).max(500);
		if !(min..=max).contains(&bitrate) {
			return Err(Error::Unsupported(format!(
				"Opus bitrate must be between {min} and {max} bits per second for {channels} channel(s) at {frame_size} samples, got {bitrate}"
			)));
		}
		Self::set_opus_ctl(inner, OPUS_SET_BITRATE_REQUEST, bitrate as i32, "OPUS_SET_BITRATE")
	}

	fn set_opus_ctl(inner: *mut OpusEncoder, request: i32, value: i32, name: &'static str) -> Result<(), Error> {
		// SAFETY: `inner` owns a live encoder and each request here expects one i32.
		let rc = unsafe { opus_encoder_ctl_impl(inner, request, varargs![value]) };
		if rc != OPUS_OK {
			return Err(opus::error(rc, name));
		}
		Ok(())
	}

	fn get_opus_ctl(inner: *mut OpusEncoder, request: i32, name: &'static str) -> Result<i32, Error> {
		let mut value = 0;
		// SAFETY: `inner` owns a live encoder and each request here expects one
		// valid mutable i32 output.
		let rc = unsafe { opus_encoder_ctl_impl(inner, request, varargs![&mut value]) };
		if rc != OPUS_OK {
			return Err(opus::error(rc, name));
		}
		Ok(value)
	}

	/// The encoder config, including the latest accepted runtime bitrate.
	pub fn config(&self) -> &Config {
		&self.config
	}

	/// The codec this encoder emits. A [`Producer`](super::Producer) must be
	/// built for the same codec to publish its packets.
	pub fn codec(&self) -> Codec {
		self.config.codec
	}

	/// Sample rate the codec actually runs at, which is
	/// [`Config::sample_rate`] resolved.
	pub fn codec_rate(&self) -> u32 {
		self.codec_rate
	}

	/// Channel count the codec actually runs at, which is
	/// [`Config::channels`] resolved.
	pub fn codec_channels(&self) -> u32 {
		self.codec_channels
	}

	/// Number of samples per channel the codec consumes per call to
	/// [`encode`](Self::encode).
	pub fn frame_size(&self) -> usize {
		self.frame_size
	}

	/// Current target bitrate in bits per second.
	pub fn bitrate(&self) -> u64 {
		self.bitrate
	}

	/// Retune the live Opus encoder to `bitrate` bits per second.
	pub fn set_bitrate(&mut self, bitrate: u64) -> Result<(), Error> {
		let Backend::Opus(opus) = &mut self.backend else {
			return Err(Error::Unsupported("pcm bitrate is fixed".into()));
		};
		if bitrate != self.bitrate {
			Self::set_opus_bitrate(
				opus.inner,
				self.codec_channels,
				bitrate,
				self.codec_rate,
				self.frame_size,
			)?;
			self.bitrate = bitrate;
			self.config.bitrate = Some(bitrate as u32);
		}
		Ok(())
	}

	/// Drop all codec history so a later epoch cannot emit audio from this one.
	pub(super) fn reset(&mut self) {
		if let Backend::Opus(opus) = &mut self.backend {
			// SAFETY: `inner` owns a live encoder and OPUS_RESET_STATE takes no arguments.
			let rc = unsafe { opus_encoder_ctl_impl(opus.inner, OPUS_RESET_STATE, varargs![]) };
			debug_assert_eq!(rc, OPUS_OK, "OPUS_RESET_STATE failed with {rc}");
		}
		self.started = false;
	}

	/// Whether this epoch has submitted audio to the codec.
	pub(super) fn started(&self) -> bool {
		self.started
	}

	/// Encode one frame of interleaved `f32` PCM at [`codec_rate`](Self::codec_rate).
	///
	/// `pcm.len()` must equal `frame_size() * codec_channels()`. The
	/// [`Producer`](super::Producer) handles format conversion and resampling
	/// before calling this; for direct use, the caller does the same.
	pub fn encode(&mut self, pcm: &[f32]) -> Result<Encoded, Error> {
		let expected = self.frame_size * self.codec_channels as usize;
		if pcm.len() != expected {
			return Err(Error::Misaligned {
				got: std::mem::size_of_val(pcm),
				expected: expected * std::mem::size_of::<f32>(),
			});
		}
		let encoded = match &mut self.backend {
			Backend::Opus(opus) => {
				// SAFETY: `inner` owns a live OpusEncoder; pcm and scratch slices
				// are bounded by the lengths we pass.
				let n = unsafe {
					opus_encode_float(
						opus.inner,
						pcm.as_ptr(),
						self.frame_size as i32,
						opus.scratch.as_mut_ptr(),
						opus.scratch.len() as i32,
					)
				};
				if n < 0 {
					return Err(crate::opus::error(n, "opus_encode_float"));
				}
				let payload = Bytes::copy_from_slice(&opus.scratch[..n as usize]);
				// The same rule the decoder applies, so both sides agree by reading the
				// packet rather than by two mechanisms kept in step. `Config::bitrate`
				// refuses the rates where a bare TOC would mean something else, which
				// is what makes reading the packet enough here.
				let activity = crate::opus::activity(&payload, false);
				Encoded { payload, activity }
			}
			Backend::Pcm => {
				let mut payload = Vec::with_capacity(std::mem::size_of_val(pcm));
				for sample in pcm {
					payload.extend_from_slice(&sample.to_le_bytes());
				}
				Encoded::new(payload.into())
			}
		};
		self.started = true;
		Ok(encoded)
	}

	/// Finish encoding, zero-padding `pcm` as the final partial frame and
	/// returning every packet needed to drain codec lookahead.
	///
	/// `pcm` is interleaved at [`codec_rate`](Self::codec_rate), may be empty,
	/// and must contain at most one frame. Silence added here only drains
	/// audio already supplied; [`Finish::discard_padding`] reports how much of
	/// the decoded tail is artificial and must not count as source duration.
	/// Consuming the encoder prevents encoding across the artificial terminal
	/// padding.
	pub fn finish(mut self, pcm: &[f32]) -> Result<Finish, Error> {
		let channels = self.codec_channels as usize;
		let frame_samples = self.frame_size * channels;
		if pcm.len() > frame_samples || !pcm.len().is_multiple_of(channels) {
			return Err(Error::Misaligned {
				got: std::mem::size_of_val(pcm),
				expected: if pcm.len() > frame_samples {
					frame_samples * std::mem::size_of::<f32>()
				} else {
					pcm.len().next_multiple_of(channels) * std::mem::size_of::<f32>()
				},
			});
		}

		let source_frames = pcm.len() / channels;
		let mut packets = Vec::new();
		let padding = if pcm.is_empty() {
			0
		} else {
			let mut frame = Vec::with_capacity(frame_samples);
			frame.extend_from_slice(pcm);
			frame.resize(frame_samples, 0.0);
			let padding = (frame_samples - pcm.len()) / channels;
			packets.push(self.encode(&frame)?);
			padding
		};

		if !self.started {
			return Ok(Finish {
				packets,
				discard_padding: 0,
			});
		}

		let drain = self.lookahead.saturating_sub(padding);
		let silence = vec![0.0; frame_samples];
		for _ in 0..drain.div_ceil(self.frame_size) {
			packets.push(self.encode(&silence)?);
		}

		let discard_padding = packets
			.len()
			.saturating_mul(self.frame_size)
			.saturating_sub(self.lookahead)
			.saturating_sub(source_frames);

		Ok(Finish {
			packets,
			discard_padding,
		})
	}

	/// hang catalog entry describing this encoder's output stream.
	pub fn catalog(&self) -> hang::catalog::AudioConfig {
		match self.config.codec {
			Codec::Opus => {
				// `codec_channels` is validated to mono/stereo at encoder construction,
				// so the OpusHead (channel mapping family 0) always encodes.
				let head = moq_mux::codec::opus::Config::new(self.codec_rate, self.codec_channels)
					.with_pre_skip(self.pre_skip)
					.encode()
					.expect("opus encoder channels validated to mono/stereo");

				let mut config = hang::catalog::AudioConfig::new(
					hang::catalog::AudioCodec::Opus,
					self.codec_rate,
					self.codec_channels,
				);
				config.bitrate = self.config.bitrate.map(u64::from);
				config.description = Some(head);
				config.container = hang::catalog::Container::Legacy;
				config
			}
			Codec::Pcm => {
				let mut config = hang::catalog::AudioConfig::new(
					hang::catalog::AudioCodec::Pcm,
					self.codec_rate,
					self.codec_channels,
				);
				config.bitrate = Some(
					pcm::bitrate(self.codec_rate, self.codec_channels)
						.expect("pcm encoder bitrate validated at construction"),
				);
				config.container = hang::catalog::Container::Legacy;
				config
			}
		}
	}
}

impl Drop for Opus {
	fn drop(&mut self) {
		// SAFETY: `inner` is a live OpusEncoder that nothing else aliases.
		unsafe { opus_encoder_destroy(self.inner) };
	}
}

#[cfg(test)]
mod tests {
	use super::*;
	use crate::Activity;
	use crate::decode::Decoder;

	fn sine(freq: f32, sample_rate: u32, channels: u32, frames: usize) -> Vec<f32> {
		let mut out = Vec::with_capacity(frames * channels as usize);
		for i in 0..frames {
			let t = i as f32 / sample_rate as f32;
			let v = (2.0 * std::f32::consts::PI * freq * t).sin() * 0.5;
			for _ in 0..channels {
				out.push(v);
			}
		}
		out
	}

	fn stereo_48k() -> Input {
		Input {
			format: Format::F32,
			sample_rate: 48_000,
			channels: 2,
		}
	}

	fn opus_inner(encoder: &Encoder) -> *mut OpusEncoder {
		let Backend::Opus(opus) = &encoder.backend else {
			panic!("expected Opus encoder");
		};
		opus.inner
	}

	#[test]
	fn opus_encode_then_decode_keeps_signal_close() {
		let mut enc = Encoder::new(&Config {
			bitrate: Some(96_000),
			..Config::new(stereo_48k())
		})
		.unwrap();

		let cfg = enc.catalog();
		let mut dec = Decoder::new(&cfg).unwrap();

		let frame = sine(440.0, 48_000, 2, enc.frame_size());
		for _ in 0..5 {
			let pkt = enc.encode(&frame).unwrap();
			let _ = dec.decode(&pkt.payload).unwrap();
		}

		let pkt = enc.encode(&frame).unwrap();
		let decoded = dec.decode(&pkt.payload).unwrap();
		assert_eq!(decoded.samples.len(), frame.len());

		let energy_in: f32 = frame.iter().map(|s| s * s).sum();
		let energy_out: f32 = decoded.samples.iter().map(|s| s * s).sum();
		let ratio = energy_out / energy_in;
		assert!(
			(0.5..2.0).contains(&ratio),
			"output energy ratio {ratio:.3} should be close to 1"
		);
	}

	#[test]
	fn opus_classification_covers_dtx_loss_and_recovery() {
		let mut enc = Encoder::new(&Config {
			dtx: true,
			bitrate: Some(24_000),
			..Config::new(Input {
				channels: 1,
				..Input::default()
			})
		})
		.unwrap();
		let mut dec = Decoder::new(&enc.catalog()).unwrap();
		let active = sine(440.0, enc.codec_rate(), enc.codec_channels(), enc.frame_size());
		let silence = vec![0.0; enc.frame_size()];

		let packet = enc.encode(&active).unwrap();
		assert_eq!(packet.activity, Activity::Active);
		assert_eq!(dec.decode(&packet.payload).unwrap().activity, Activity::Active);

		let mut dtx = None;
		for _ in 0..100 {
			let packet = enc.encode(&silence).unwrap();
			let decoded = dec.decode(&packet.payload).unwrap();
			assert_eq!(decoded.activity, packet.activity);
			if packet.activity.is_dtx() {
				dtx = Some(packet);
				break;
			}
		}
		let dtx = dtx.expect("silence should enter Opus DTX");
		assert!(
			dtx.payload.len() <= 2,
			"withholding audio is a bare TOC, got {} bytes",
			dtx.payload.len()
		);

		// Padding does not change what a packet codes, so it does not change how it
		// reads either.
		let mut padded = dtx.payload.to_vec();
		let original_len = padded.len();
		padded.resize(original_len + 8, 0);
		// SAFETY: the allocation is sized for the requested padded length and the
		// encoder produced a valid Opus packet.
		let rc =
			unsafe { unsafe_libopus::opus_packet_pad(padded.as_mut_ptr(), original_len as i32, padded.len() as i32) };
		assert_eq!(rc, unsafe_libopus::OPUS_OK);
		assert_eq!(dec.decode(&padded).unwrap().activity, Activity::Dtx);

		// An absent payload asks libopus for packet-loss concealment, which says
		// nothing: the classification stays where the last real packet left it.
		assert_eq!(dec.decode(&[]).unwrap().activity, Activity::Dtx);

		// A rejected packet must not mutate the state used to classify later loss.
		assert!(matches!(dec.decode(&[0xff; 3]), Err(Error::Decode(_))));
		assert_eq!(dec.decode(&[]).unwrap().activity, Activity::Dtx);

		let mut recovered = false;
		for _ in 0..10 {
			let packet = enc.encode(&active).unwrap();
			let decoded = dec.decode(&packet.payload).unwrap();
			assert_eq!(decoded.activity, packet.activity);
			if packet.activity.is_active() {
				recovered = true;
				break;
			}
		}
		assert!(recovered, "active audio should exit Opus DTX");
		assert_eq!(dec.decode(&[]).unwrap().activity, Activity::Active);
	}

	#[test]
	fn opus_rejects_a_bitrate_that_would_code_nothing() {
		let starved = Encoder::new(&Config {
			dtx: true,
			bitrate: Some(500),
			..Config::new(Input {
				channels: 1,
				..Input::default()
			})
		});
		assert!(
			matches!(starved, Err(Error::Unsupported(_))),
			"500 bps at 20 ms is under the 1200 bps floor"
		);

		// The floor moves with the frame duration: 2.5 ms needs 9600 bps.
		let short = Encoder::new(&Config {
			bitrate: Some(6_000),
			frame_duration: Duration::from_micros(2_500),
			..Config::new(Input {
				channels: 1,
				..Input::default()
			})
		});
		assert!(matches!(short, Err(Error::Unsupported(_))));

		// And a live retune cannot get under it either, which is how a stream that
		// started healthy could otherwise end up coding nothing.
		let mut enc = Encoder::new(&Config {
			dtx: true,
			bitrate: Some(24_000),
			..Config::new(Input {
				channels: 1,
				..Input::default()
			})
		})
		.unwrap();
		assert!(enc.set_bitrate(500).is_err());
		assert_eq!(enc.bitrate(), 24_000, "a refused retune leaves the bitrate alone");
	}

	/// A silence run is interrupted by an ordinarily coded frame of that silence,
	/// which carries no marker saying so. It reads active, because the framing
	/// that would catch it is the same framing a speech onset produces, and
	/// calling real audio silence is the worse error.
	#[test]
	fn opus_reports_silence_between_refreshes() {
		let mut enc = Encoder::new(&Config {
			dtx: true,
			bitrate: Some(24_000),
			..Config::new(Input {
				channels: 1,
				..Input::default()
			})
		})
		.unwrap();
		let mut dec = Decoder::new(&enc.catalog()).unwrap();
		let loud = sine(440.0, enc.codec_rate(), enc.codec_channels(), enc.frame_size());
		let silence = vec![0.0; enc.frame_size()];

		for _ in 0..6 {
			let packet = enc.encode(&loud).unwrap();
			assert_eq!(packet.activity, Activity::Active);
		}

		let mut dtx = 0;
		let mut refreshes = 0;
		for _ in 0..200 {
			let packet = enc.encode(&silence).unwrap();
			assert_eq!(
				dec.decode(&packet.payload).unwrap().activity,
				packet.activity,
				"both sides read the same packet"
			);
			match packet.activity {
				Activity::Dtx => dtx += 1,
				_ if dtx > 0 => refreshes += 1,
				_ => {}
			}
		}

		assert!(dtx > 150, "silence should mostly withhold audio, got {dtx} of 200");
		assert!(refreshes > 0, "a silence run should be refreshed periodically");
		assert!(
			refreshes < dtx / 10,
			"refreshes should be rare against the run they interrupt, got {refreshes} vs {dtx}"
		);
	}

	#[test]
	fn opus_rejects_unsupported_frame_duration() {
		let err = Encoder::new(&Config {
			frame_duration: Duration::from_millis(15),
			..Config::new(Input::default())
		});
		assert!(matches!(err, Err(Error::Unsupported(_))));
	}

	#[test]
	fn opus_rejects_misaligned_input() {
		let mut enc = Encoder::new(&Config::new(Input::default())).unwrap();
		assert!(matches!(enc.encode(&[0.0f32; 100]), Err(Error::Misaligned { .. })));
	}

	#[test]
	fn opus_catalog_includes_opushead() {
		let enc = Encoder::new(&Config {
			bitrate: Some(64_000),
			..Config::new(stereo_48k())
		})
		.unwrap();
		let cfg = enc.catalog();
		assert_eq!(cfg.sample_rate, 48_000);
		assert_eq!(cfg.channel_count, 2);
		assert_eq!(cfg.bitrate, Some(64_000));
		let desc = cfg.description.expect("OpusHead should be present");
		assert_eq!(desc.len(), 19);
		let head = moq_mux::codec::opus::Config::parse(&mut desc.as_ref()).unwrap();
		assert_eq!(head.pre_skip, enc.pre_skip);
		assert_eq!(head.pre_skip, 312);
	}

	#[test]
	fn opus_decoder_trims_encoder_lookahead_once() {
		let mut enc = Encoder::new(&Config::new(stereo_48k())).unwrap();
		let mut dec = Decoder::new(&enc.catalog()).unwrap();
		let frame = vec![0.0; enc.frame_size() * enc.codec_channels() as usize];

		let first = dec.decode(&enc.encode(&frame).unwrap().payload).unwrap();
		assert_eq!(
			first.samples.len(),
			(enc.frame_size() - enc.pre_skip as usize) * enc.codec_channels() as usize
		);

		let second = dec.decode(&enc.encode(&frame).unwrap().payload).unwrap();
		assert_eq!(second.samples.len(), frame.len());
	}

	#[test]
	fn opus_finish_accounts_for_partial_frame_padding() {
		let enc = Encoder::new(&Config::new(Input {
			channels: 1,
			..Input::default()
		}))
		.unwrap();

		// The 360 frames of terminal padding exceed the 312-frame lookahead,
		// so the partial packet itself completes the drain.
		let packets = enc.finish(&vec![0.0; 600]).unwrap();
		assert_eq!(packets.packets().len(), 1);
		assert_eq!(packets.discard_padding(), 48);
	}

	#[test]
	fn opus_finish_drains_lookahead_across_multiple_short_packets() {
		let mut enc = Encoder::new(&Config {
			frame_duration: Duration::from_micros(2_500),
			..Config::new(Input {
				channels: 1,
				..Input::default()
			})
		})
		.unwrap();
		let frame = vec![0.0; enc.frame_size()];
		enc.encode(&frame).unwrap();

		// Three 120-frame packets are required to push out 312 frames.
		let packets = enc.finish(&[]).unwrap();
		assert_eq!(packets.packets().len(), 3);
		assert_eq!(packets.discard_padding(), 48);
	}

	#[test]
	fn reset_drops_pending_opus_lookahead() {
		let mut enc = Encoder::new(&Config::new(Input {
			channels: 1,
			..Input::default()
		}))
		.unwrap();
		let mut old = vec![0.0; enc.frame_size()];
		old[enc.frame_size() - 1] = 1.0;
		enc.encode(&old).unwrap();

		enc.reset();
		let next = vec![0.0; enc.frame_size()];
		let actual = enc.encode(&next).unwrap();
		let mut decoder = Decoder::new(&enc.catalog()).unwrap();
		let decoded = decoder.decode(&actual.payload).unwrap();
		let peak = decoded
			.samples
			.iter()
			.fold(0.0f32, |peak, sample| peak.max(sample.abs()));
		assert!(peak < 0.001, "pre-reset impulse leaked into the next epoch: {peak}");

		enc.reset();
		let finish = enc.finish(&[]).unwrap();
		assert!(finish.packets().is_empty());
		assert_eq!(finish.discard_padding(), 0);
	}

	#[test]
	fn opus_runtime_bitrate_updates_encoder_state() {
		let mut enc = Encoder::new(&Config {
			bitrate: Some(64_000),
			..Config::new(stereo_48k())
		})
		.unwrap();

		enc.set_bitrate(32_000).unwrap();
		assert_eq!(enc.bitrate(), 32_000);
		assert_eq!(enc.config().bitrate, Some(32_000));
		assert_eq!(
			Encoder::get_opus_ctl(
				opus_inner(&enc),
				unsafe_libopus::OPUS_GET_BITRATE_REQUEST,
				"OPUS_GET_BITRATE"
			)
			.unwrap(),
			32_000
		);
	}

	#[test]
	fn opus_runtime_bitrate_rejects_values_libopus_would_clamp() {
		let mut enc = Encoder::new(&Config::new(stereo_48k())).unwrap();
		let original = enc.bitrate();
		assert!(enc.set_bitrate(1).is_err());
		assert!(enc.set_bitrate(600_001).is_err());
		assert_eq!(enc.bitrate(), original);
	}

	#[test]
	fn opus_applies_fec_and_dtx_controls() {
		let enc = Encoder::new(&Config {
			fec: true,
			dtx: true,
			..Config::new(stereo_48k())
		})
		.unwrap();

		assert_eq!(
			Encoder::get_opus_ctl(
				opus_inner(&enc),
				unsafe_libopus::OPUS_GET_INBAND_FEC_REQUEST,
				"OPUS_GET_INBAND_FEC"
			)
			.unwrap(),
			1
		);
		assert_eq!(
			Encoder::get_opus_ctl(opus_inner(&enc), unsafe_libopus::OPUS_GET_DTX_REQUEST, "OPUS_GET_DTX").unwrap(),
			1
		);
	}

	#[test]
	fn codec_roundtrips_as_str() {
		assert_eq!(Codec::Opus.as_str(), "opus");
		assert_eq!(Codec::Opus.to_string(), "opus");
		assert_eq!("opus".parse::<Codec>().unwrap(), Codec::Opus);
		assert_eq!(Codec::Pcm.as_str(), "pcm");
		assert_eq!(Codec::Pcm.to_string(), "pcm");
		assert_eq!("pcm".parse::<Codec>().unwrap(), Codec::Pcm);
		assert!("aac".parse::<Codec>().is_err());
	}

	#[test]
	fn config_sample_rate_overrides_the_codec_rate() {
		let enc = Encoder::new(&Config {
			sample_rate: Some(24_000),
			..Config::new(Input {
				sample_rate: 48_000,
				channels: 1,
				..Input::default()
			})
		})
		.unwrap();
		assert_eq!(enc.codec_rate(), 24_000);
		assert_eq!(enc.catalog().sample_rate, 24_000);
		assert_eq!(enc.pre_skip, 312);
	}

	#[test]
	fn pcm_roundtrip_is_lossless() {
		let mut enc = Encoder::new(&Config {
			codec: Codec::Pcm,
			..Config::new(stereo_48k())
		})
		.unwrap();
		let mut dec = Decoder::new(&enc.catalog()).unwrap();
		let input = sine(440.0, enc.codec_rate(), enc.codec_channels(), enc.frame_size());

		let packet = enc.encode(&input).unwrap();
		let output = dec.decode(&packet.payload).unwrap();

		assert_eq!(output.samples, input);
	}

	#[test]
	fn pcm_catalog_declares_fixed_bitrate() {
		let enc = Encoder::new(&Config {
			codec: Codec::Pcm,
			..Config::new(stereo_48k())
		})
		.unwrap();
		let catalog = enc.catalog();

		assert_eq!(catalog.codec, hang::catalog::AudioCodec::Pcm);
		assert_eq!(catalog.bitrate, Some(48_000 * 2 * 32));
		assert_eq!(catalog.description, None);
	}

	#[test]
	fn pcm_rejects_runtime_bitrate_change() {
		let mut enc = Encoder::new(&Config {
			codec: Codec::Pcm,
			..Config::new(stereo_48k())
		})
		.unwrap();
		let bitrate = enc.bitrate();

		assert!(matches!(enc.set_bitrate(bitrate), Err(Error::Unsupported(_))));
		assert_eq!(enc.bitrate(), bitrate);
	}

	#[test]
	fn pcm_rejects_fractional_sample_frame_duration() {
		let err = Encoder::new(&Config {
			codec: Codec::Pcm,
			frame_duration: Duration::from_micros(2_500),
			..Config::new(Input {
				sample_rate: 44_100,
				..Input::default()
			})
		});
		assert!(matches!(err, Err(Error::Unsupported(_))));
	}

	#[test]
	fn pcm_rejects_bitrate_overflow() {
		let err = Encoder::new(&Config {
			codec: Codec::Pcm,
			frame_duration: Duration::from_secs(1),
			..Config::new(Input {
				sample_rate: u32::MAX,
				channels: u32::MAX,
				..Input::default()
			})
		});
		assert!(matches!(err, Err(Error::Unsupported(_))));
	}
}