Module encoders 

Encoder backends and the codec identities, wire framing, and rate-control policy they share. Encoder backends and what they share: the codec identities and wire framing, the rate-control policy, which software encoder a build resolves each codec to, and which hardware encoder a render node serves each with.

Re-exports

pub use codec::*;

Modules

bits

The bit writer the packed headers of the VA-API session are written with. A most-significant-bit-first writer for the headers a VA-API session packs itself: the fixed-width and Exp-Golomb fields of H.264, HEVC, and AV1 syntax, the RBSP trailing bits, and the emulation prevention an H.26x NAL unit needs on its way out.

codec

Codec identities, wire framing, quantizer domains, level ladders, bitstream reads. What every encoder backend shares about a codec: its name and wire identity, the quantizer domain the session-wide quality index maps onto, the level a stream of a given geometry advertises, and the bitstream reads that label a frame on the wire.

frame_rate

A frame rate as the fraction encoder parameters and bitstream timing take. A frame rate as the fraction of whole numbers that encoder parameters and bitstream timing take, read from the f64 a capture carries.

hevc

Software HEVC: x265 with the gpl feature, kvazaar without it. Software HEVC: x265 with the gpl feature, kvazaar without it, each at the fastest setting its library offers in real time (ultrafast, wavefront threads, no lookahead, no reordering) with the parameter sets repeated on every key frame. x265 carries 4:4:4 at full range like x264; kvazaar encodes 4:2:0. Neither library lets a session steer what a frame predicts from, so the session names no reference and refuses an invalidation, and the caller codes a key frame instead.

nvenc

NVIDIA NVENC hardware H.264 / HEVC / AV1 encoder loaded via runtime libcuda / libnvidia-encode. NVENC hardware H.264 / HEVC / AV1 encoder: CUDA-bound sessions that encode packed BGRA or RGBA frames from the X11 host and Wayland readback paths, or Wayland dmabufs in place.

overlay

PNG watermark overlay composited onto frames before encoding. PNG watermark overlay composited onto captured frames before encoding.

reference

Which frame a delivered frame predicts from, kept true across the frames a client reports lost.

session

What the full-frame software sessions share: planar input, quantizer, rate settings. What the full-frame software sessions share: the planar picture a packed host frame is converted into, at 8 or 10 bits, the constant quantizer that follows the session quality index, the rate-control settings a live change is compared against, and the frames an encoder has been handed but not yet answered.

software

CPU-based striped H.264 (libx264 or OpenH264, by build) / JPEG encoder with per-stripe change detection. CPU-based striped encoder: H.264 through the build’s software encoder — libx264 with the gpl feature, Cisco OpenH264 without it (software_encoder) — and turbojpeg for JPEG.

sps

The color an H.264 stream declares: read from a sequence parameter set, and written into one for a device that converts without saying what it converted with. The color a stream declares, read from an H.264 sequence parameter set and written into one.

svtav1

Software AV1 through SVT-AV1. Software AV1 through SVT-AV1 at preset 11 in its real-time mode (PRESET), one frame in and one packet out (two frames deep before 2.3), with rate control either constant-rate at the session’s bitrate and VBV or a constant quantizer. A new bitrate reaches the running encoder with the next picture where the release takes one (HAS_EVENTS); a quality, frame-rate, or VBV change re-opens it, as a bitrate change does on an earlier release.

v4l2m2m

Hardware H.264 through a generic stateful V4L2 M2M encoder: boards whose encoder sits behind the kernel’s own interface rather than a vendor library or a render node, such as a Raspberry Pi 4, RK356x, or i.MX8M. Built everywhere, since the interface is the kernel’s. Hardware H.264 through a generic stateful V4L2 M2M encoder.

vaapi

VA-API hardware sessions on a DRM render node, driven through libva directly. VA-API hardware sessions on a DRM render node for every video codec, driven through libva directly.

vpx

Software VP8 and VP9 through libvpx. Software VP8 and VP9 through libvpx, with every frame’s references under the session’s control.

Structs

Formats

The codecs a render node encodes in hardware, each with the backend’s name. The formats past 8-bit 4:2:0 an engine encodes a codec in: 4:4:4 for a video_fullcolor session, and 10 bits for a video_bit_depth one at 4:2:0 and at 4:4:4.

SoftwareEncoder

A software encoder the build runs for one codec: the library’s name as reported to Python and the logs.

Enums

FrameEncoder

One full-frame encoder session, whichever backend produced it, so the render and delivery code passes “the frame encoder” around without caring which vendor path or library produced the frames.

FrameSource

How a session’s frames arrive: Wayland dmabufs (with the EGL display NVENC imports them through), or packed host pixels in R,G,B,A (rgba) or B,G,R,A byte order.

Functions

chroma_name

The chroma sampling of a session as the logs name it.

colorspace_desc

The Colorspace: field of a stream log line, from what the session negotiated rather than what was asked for: a hardware encoder can refuse 4:4:4, software 4:4:4 of x264’s kind carries full range, and a device converting in fixed function picks the range itself. Shared so the X11 and Wayland logs describe an identical session identically.

driver_name

The kernel driver’s name out of the sysfs link get_gpu_driver read, unknown without one.

hardware_encoders

The hardware backend that serves each video codec on an encode node, as the name a session logs it in lower case ("nvenc", "vaapi", or "tegra"), probed once per node and remembered for the life of the process: the ladder picks the backend by the node’s driver exactly as select_frame_encoder does, and that backend lists the codecs its device has an engine for (nvenc::probe_codecs, vaapi::probe_codecs). A node whose backend cannot be brought up serves nothing, said once in the log, so a caller offers the codec only where a session would come up on hardware rather than demote. What a session is then refused for (a size past the engine’s maximum, a 4:4:4 the engine lacks) is still the ladder’s to fall through on.

paint_over_desc

The paint-over field of a stream’s log line, or None where paint-over changes nothing. The cleanup reads a still screen from its content, so it acts with Turbo as without. JPEG resends a still stripe at the paint-over quality when it is above the stream’s. At a constant quality the cleanup, where the paint-over CRF is below the stream’s, moves the session to that CRF for its frames and their burst, except on a backend with one rate control (fixed), which takes no quality from the caller and sends them at its own. At a constant rate it acts wherever the rate control codes coarser than the paint-over quantizer: held at it where the session holds a frame at a quantizer (holds, FrameEncoder::holds_quantizer), and as a refresh and its burst at the rate control’s own quality elsewhere.

rate_desc

The rate-control field of a video stream’s log line, as the session applies it: a backend with one rate control (fixed, from FrameEncoder::fixed_rate_control) runs it at the bitrate target whatever the mode, and every other session runs its mode, a CRF one with no bitrate cap.

reference_frames

Size the CBR VBV/HRD buffer so rate control has enough slack to hold quality steady without letting end-to-end latency drift upward.

select_frame_encoder

Choose and build the full-frame encoder of a session, or None when the striped software path serves it. One ladder for X11, Wayland zero-copy, and Wayland readback, so the three cannot pick differently for the same settings:

session_bit_depth

The bits per sample a session carries, which is not always what was asked for: a full-frame session’s own answer, and for the striped path (None) what its H.264 encoder opens at.

session_full_range

Whether a session signals full range: a software 4:4:4 session of x264’s kind, which the striped path (None) is whenever it carries 4:4:4, or a device that converted in fixed function at a range it chose. The one answer every description of a session reads, so no two of them can disagree.

session_fullcolor

The chroma format a session actually carries, which is not always the one requested: a hardware session only when the device carries it, the software path only when the build’s encoder for the codec does. Every consumer of “is this stream 4:4:4” reads it from here.

software_encoder

The software encoder this build runs for codec on this machine, or None for JPEG and for a codec whose encoder does not run here.

software_formats

The formats the software encoder of a codec codes it in.

software_fullcolor

Whether the software encoder of a codec carries a 4:4:4 (video_fullcolor) request: x264 (High 4:4:4, full range), x265, and libvpx’s VP9 (profile 1) do; OpenH264, kvazaar, VP8, and SVT-AV1 encode such a request 4:2:0.

software_library

The name of the software encoder this build runs for codec, for logs; "none" for JPEG, which is striped stills.

software_session

The full-frame software session of codec on host frames in the byte order rgba names.

software_ten_bit

Whether the software encoder of a codec carries a 10-bit video_bit_depth request, at whichever chroma it codes: x264 (High 10, and High 4:4:4 Predictive), x265 where the build links its 10-bit encoder, libvpx’s VP9 (profiles 2 and 3) where it was built with high bit depth, and SVT-AV1 do; OpenH264, kvazaar, and VP8 encode such a request at 8 bits.

vbv_bits

Type Aliases

HardwareEncoders

Each video codec an engine on a node encodes, the backend’s name, and the formats it encodes the codec in.