use std::time::Duration;
use bytes::Bytes;
use hang::catalog::VideoCodec;
use crate::clock::StreamClock;
use crate::convert::{I420, Planes, yuv_to_packed};
use crate::{Error, Image, PixelFormat, Result};
mod annexb;
#[cfg(feature = "av1")]
mod av1;
#[cfg(feature = "hw")]
mod gst;
#[cfg(feature = "h264")]
mod h264;
mod obu;
#[cfg(feature = "vp8")]
mod vp8;
mod vp8_header;
#[cfg(feature = "h264")]
pub use h264::set_openh264_library;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Codec {
Vp8,
H264,
Av1,
}
impl Codec {
#[cfg(test)]
pub(crate) const ALL: &[Codec] = &[Codec::Vp8, Codec::H264, Codec::Av1];
pub const fn available() -> &'static [Codec] {
&[
#[cfg(feature = "vp8")]
Codec::Vp8,
#[cfg(feature = "av1")]
Codec::Av1,
#[cfg(feature = "h264")]
Codec::H264,
]
}
pub fn is_available(self) -> bool {
Self::available().contains(&self)
}
pub(crate) fn from_catalog(codec: &VideoCodec) -> Option<Self> {
match codec {
VideoCodec::VP8 => Some(Self::Vp8),
VideoCodec::H264(_) => Some(Self::H264),
VideoCodec::AV1(_) => Some(Self::Av1),
_ => None,
}
}
pub fn is_keyframe(self, data: &[u8]) -> bool {
match self {
Self::Vp8 => vp8_header::is_keyframe(data),
Self::H264 => annexb::is_keyframe(data),
Self::Av1 => obu::is_keyframe(data),
}
}
pub(crate) fn catalog_codec(self, keyframe: &[u8]) -> VideoCodec {
match self {
Self::Vp8 => VideoCodec::VP8,
Self::H264 => annexb::catalog_codec(keyframe),
Self::Av1 => obu::catalog_codec(keyframe),
}
}
}
crate::names::named_enum!(Codec, "codec", {
Vp8 => "vp8",
H264 => "h264" | "avc",
Av1 => "av1" | "av01",
});
impl Default for Codec {
fn default() -> Self {
Self::available().first().copied().unwrap_or(Self::Vp8)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[non_exhaustive]
pub enum Hardware {
Off,
#[default]
Auto,
Require,
}
crate::names::named_enum!(Hardware, "hardware mode", {
Off => "off",
Auto => "auto",
Require => "require",
});
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct EncoderSettings {
pub codec: Codec,
pub bitrate: u32,
pub max_fps: f32,
pub keyframe_interval: Duration,
pub threads: u16,
pub hardware: Hardware,
}
impl Default for EncoderSettings {
fn default() -> Self {
Self {
codec: Codec::default(),
bitrate: 2_000_000,
max_fps: 30.0,
keyframe_interval: Duration::from_secs(2),
threads: 0,
hardware: Hardware::default(),
}
}
}
impl EncoderSettings {
pub fn with_codec(mut self, codec: Codec) -> Self {
self.codec = codec;
self
}
pub fn with_bitrate(mut self, bitrate: u32) -> Self {
self.bitrate = bitrate;
self
}
pub fn with_max_fps(mut self, max_fps: f32) -> Self {
self.max_fps = max_fps;
self
}
pub fn with_keyframe_interval(mut self, keyframe_interval: Duration) -> Self {
self.keyframe_interval = keyframe_interval;
self
}
pub fn with_threads(mut self, threads: u16) -> Self {
self.threads = threads;
self
}
pub fn with_hardware(mut self, hardware: Hardware) -> Self {
self.hardware = hardware;
self
}
pub(crate) fn threads(&self) -> u32 {
match self.threads {
0 => default_threads(),
n => u32::from(n),
}
}
#[expect(
clippy::cast_possible_truncation,
clippy::cast_sign_loss,
reason = "float casts saturate"
)]
pub(crate) fn gop_frames(&self) -> u32 {
(self.max_fps * self.keyframe_interval.as_secs_f32() * 2.0)
.ceil()
.max(1.0) as u32
}
#[expect(
clippy::cast_possible_truncation,
clippy::cast_sign_loss,
reason = "float casts saturate"
)]
pub(crate) fn frame_duration_micros(&self) -> u64 {
(1_000_000.0 / self.max_fps.max(1.0)) as u64
}
}
pub(crate) fn default_threads() -> u32 {
std::thread::available_parallelism().map_or(1, |n| u32::try_from(n.get()).unwrap_or(4).min(4))
}
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct EncodedFrame {
pub data: Bytes,
pub keyframe: bool,
pub width: u32,
pub height: u32,
pub timestamp: Duration,
pub codec: Codec,
}
impl EncodedFrame {
pub fn new(
codec: Codec,
data: impl Into<Bytes>,
keyframe: bool,
width: u32,
height: u32,
timestamp: Duration,
) -> Self {
Self {
data: data.into(),
keyframe,
width,
height,
timestamp,
codec,
}
}
pub fn codec_string(&self) -> Option<String> {
self.keyframe.then(|| self.codec.catalog_codec(&self.data).to_string())
}
}
pub(crate) struct EncodedChunk {
pub data: Bytes,
pub keyframe: bool,
}
pub(crate) trait EncoderBackend: Send {
fn encode(&mut self, frame: &I420, pts: u64, force_keyframe: bool) -> Result<Option<EncodedChunk>>;
fn set_bitrate(&mut self, bitrate: u32) -> Result<bool> {
let _ = bitrate;
Ok(false)
}
}
pub(crate) trait DecoderBackend: Send {
fn decode(&mut self, data: &[u8], max_pixels: u64, format: PixelFormat) -> Result<Option<(u32, u32, Vec<u8>)>>;
}
pub(crate) fn packed_picture(planes: &Planes<'_>, max_pixels: u64, format: PixelFormat) -> Result<(u32, u32, Vec<u8>)> {
let dim = |n: usize| u32::try_from(n).unwrap_or(u32::MAX);
let (width, height) = (dim(planes.width), dim(planes.height));
check_size(width, height, max_pixels)?;
Ok((width, height, yuv_to_packed(planes, format)?))
}
pub const DEFAULT_MAX_PIXELS: u64 = 7680 * 4320;
pub(crate) fn check_size(width: u32, height: u32, max: u64) -> Result<()> {
if u64::from(width) * u64::from(height) > max {
return Err(Error::TooLarge { width, height, max });
}
Ok(())
}
pub struct Encoder {
settings: EncoderSettings,
active: Option<ActiveBackend>,
hardware: Option<&'static str>,
last_keyframe: Option<u64>,
clock: StreamClock,
yuv: I420,
}
struct ActiveBackend {
backend: Box<dyn EncoderBackend>,
dims: (usize, usize),
}
impl ActiveBackend {
fn new(backend: Box<dyn EncoderBackend>, dims: (usize, usize)) -> Self {
Self { backend, dims }
}
}
impl Encoder {
pub fn new(settings: EncoderSettings) -> Result<Self> {
if !settings.codec.is_available() {
return Err(unavailable(settings.codec));
}
if settings.hardware == Hardware::Require && !cfg!(feature = "hw") {
return Err(Error::CodecUnavailable(
"hardware encoding is not compiled in (enable the `hw` feature)".into(),
));
}
Ok(Self {
settings,
active: None,
hardware: None,
last_keyframe: None,
clock: StreamClock::default(),
yuv: I420::default(),
})
}
pub fn settings(&self) -> &EncoderSettings {
&self.settings
}
pub fn hardware_encoder(&self) -> Option<&'static str> {
self.hardware
}
pub fn set_bitrate(&mut self, bitrate: u32) {
if bitrate == self.settings.bitrate {
return;
}
self.settings.bitrate = bitrate;
let Some(active) = self.active.as_mut() else {
return;
};
match active.backend.set_bitrate(bitrate) {
Ok(true) => tracing::debug!(codec = %self.settings.codec, bitrate, "changed the bitrate"),
Ok(false) => {
tracing::debug!(codec = %self.settings.codec, bitrate, "recreating the encoder for the new bitrate");
self.active = None;
}
Err(err) => {
tracing::warn!(codec = %self.settings.codec, bitrate, %err, "changing the bitrate failed; recreating the encoder");
self.active = None;
}
}
}
pub fn force_keyframe(&mut self) {
self.last_keyframe = None;
}
pub fn encode(&mut self, image: &Image) -> Result<Option<EncodedFrame>> {
self.yuv.fill_from_image(image)?;
let yuv = std::mem::take(&mut self.yuv);
let frame = self.encode_yuv(&yuv, image.timestamp);
self.yuv = yuv;
frame
}
#[expect(
clippy::cast_possible_truncation,
reason = "I420 dimensions come from `u32` image dimensions"
)]
pub(crate) fn encode_yuv(&mut self, yuv: &I420, timestamp: Duration) -> Result<Option<EncodedFrame>> {
let dims = (yuv.width(), yuv.height());
if self.active.as_ref().is_none_or(|active| active.dims != dims) {
tracing::debug!(codec = %self.settings.codec, width = dims.0, height = dims.1, "creating encoder");
self.active = None;
self.active = Some(ActiveBackend::new(self.create_backend(dims)?, dims));
self.last_keyframe = None;
}
let pts = self.clock.micros(timestamp);
let interval = u64::try_from(self.settings.keyframe_interval.as_micros()).unwrap_or(u64::MAX);
let force = self
.last_keyframe
.is_none_or(|last| pts.saturating_sub(last) >= interval);
let Some(EncodedChunk { data, keyframe }) = self.encode_with_fallback(yuv, pts, force)? else {
return Ok(None);
};
if keyframe {
self.last_keyframe = Some(pts);
}
Ok(Some(EncodedFrame {
data,
keyframe,
width: dims.0 as u32,
height: dims.1 as u32,
timestamp,
codec: self.settings.codec,
}))
}
fn encode_with_fallback(&mut self, yuv: &I420, pts: u64, force: bool) -> Result<Option<EncodedChunk>> {
let active = self.active.as_mut().expect("backend created before encoding");
let dims = active.dims;
match active.backend.encode(yuv, pts, force) {
Ok(chunk) => Ok(chunk),
Err(err) if self.hardware.is_some() && self.settings.hardware == Hardware::Auto => {
tracing::warn!(codec = %self.settings.codec, element = self.hardware, %err, "hardware encoder failed; encoding in software");
self.hardware = None;
self.active = None;
let backend = create_software_encoder(&self.settings, dims)?;
let active = self.active.insert(ActiveBackend::new(backend, dims));
active.backend.encode(yuv, pts, true)
}
Err(err) => {
if self.hardware.is_some() {
self.active = None;
}
Err(err)
}
}
}
fn create_backend(&mut self, dims: (usize, usize)) -> Result<Box<dyn EncoderBackend>> {
#[cfg(feature = "hw")]
if self.settings.hardware != Hardware::Off {
let first_attempt = gst::first_attempt(self.settings.codec, dims);
match gst::GstEncoder::new(&self.settings, dims, self.hardware) {
Ok(encoder) => {
if self.hardware != Some(encoder.element()) {
tracing::info!(codec = %self.settings.codec, element = encoder.element(), "using hardware encoder");
}
self.hardware = Some(encoder.element());
return Ok(Box::new(encoder));
}
Err(err) if self.settings.hardware == Hardware::Require => return Err(err),
Err(err) => {
if first_attempt {
tracing::warn!(codec = %self.settings.codec, %err, "no usable hardware encoder; encoding in software");
} else {
tracing::debug!(codec = %self.settings.codec, %err, "no usable hardware encoder; encoding in software");
}
self.hardware = None;
}
}
}
create_software_encoder(&self.settings, dims)
}
}
pub struct Decoder {
codec: Codec,
inner: Box<dyn DecoderBackend>,
max_pixels: u64,
output: PixelFormat,
}
impl Decoder {
pub fn new(codec: Codec) -> Result<Self> {
let inner: Box<dyn DecoderBackend> = match codec {
#[cfg(feature = "vp8")]
Codec::Vp8 => Box::new(vp8::Vp8Decoder::new()?),
#[cfg(feature = "h264")]
Codec::H264 => Box::new(h264::H264Decoder::new()?),
#[cfg(feature = "av1")]
Codec::Av1 => Box::new(av1::Av1Decoder::new()?),
#[allow(unreachable_patterns)]
other => return Err(unavailable(other)),
};
Ok(Self {
codec,
inner,
max_pixels: DEFAULT_MAX_PIXELS,
output: PixelFormat::Rgb8,
})
}
pub fn codec(&self) -> Codec {
self.codec
}
pub fn max_pixels(&self) -> u64 {
self.max_pixels
}
pub fn set_max_pixels(&mut self, max_pixels: u64) {
self.max_pixels = max_pixels;
}
pub fn output_format(&self) -> PixelFormat {
self.output
}
pub fn set_output_format(&mut self, format: PixelFormat) -> Result<()> {
if matches!(format, PixelFormat::Uyvy | PixelFormat::Yuyv) {
return Err(Error::InvalidSettings(format!("can't decode into {format}")));
}
self.output = format;
Ok(())
}
pub fn decode(&mut self, data: &[u8], timestamp: Duration) -> Result<Option<Image>> {
let Some((width, height, pixels)) = self.inner.decode(data, self.max_pixels, self.output)? else {
return Ok(None);
};
Ok(Some(Image::new(width, height, self.output, pixels, timestamp)?))
}
}
#[expect(
clippy::cast_possible_truncation,
reason = "I420 dimensions come from `u32` image dimensions"
)]
fn create_software_encoder(
settings: &EncoderSettings,
(width, height): (usize, usize),
) -> Result<Box<dyn EncoderBackend>> {
Ok(match settings.codec {
#[cfg(feature = "vp8")]
Codec::Vp8 => Box::new(vp8::Vp8Encoder::new(settings, width as u32, height as u32)?),
#[cfg(feature = "h264")]
Codec::H264 => Box::new(h264::H264Encoder::new(settings)?),
#[cfg(feature = "av1")]
Codec::Av1 => Box::new(av1::Av1Encoder::new(settings, width as u32, height as u32)?),
#[allow(unreachable_patterns)]
other => {
let _ = (width, height);
return Err(unavailable(other));
}
})
}
fn unavailable(codec: Codec) -> Error {
Error::CodecUnavailable(format!(
"{codec} support is not compiled in (enable the `{codec}` feature)"
))
}
#[cfg(test)]
pub(crate) mod tests;