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; and the split of an Annex-B stream into its NAL units on the way in. Nothing here reaches outside the module, so a fuzz build (fuzz/) compiles it on its own.

blit_semaphore 🔒

The GPU semaphore an X server’s blit signals for the encoder, made through Vulkan. A GPU semaphore an X server’s renderer signals and the encoder’s CUDA stream waits on, so the encoder’s work on a frame is queued behind the server’s blit on the GPU itself instead of after the CPU has learnt the blit landed (crate::x11’s DRI3 path, through the SELKIES-SEMAPHORE extension of the images’ Xvfb).

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.

dmabuf_identity 🔒

The identity of a dmabuf behind an fd, for the sessions that keep an import of each buffer. What a dmabuf is, beyond the fd number that names it, for the hardware sessions that keep an import of each recurring capture buffer (NVENC’s CUDA registrations, VA-API’s surfaces).

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

The CPU path: striped JPEG and whole-frame software H.264 (libx264 or OpenH264, by build), with per-region change detection. The CPU encode path: JPEG through turbojpeg in horizontal stripes, and H.264 through the build’s software encoder — libx264 with the gpl feature, Cisco OpenH264 without it (software_encoder) — as one whole-frame session.

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.

Macros

each 🔒

Apply one expression to the session behind whichever variant self is.

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.

Constants

CAPPED_VBV_FRAMES

The buffer, in frames of its peak, a capped constant-quality session takes (CaptureSettings::video_vbv_multiplier): software H.264’s constant-rate buffer, so a cap that binds codes a frame as the constant rate congestion control steers does, and a cap that does not leaves the rate factor its picture.

HARDWARE_ORDER 🔒

The video codecs by compression efficiency: the order a fallthrough tries the ones an engine on the encode node carries, where CPU is no constraint.

HELD_KEY_BUDGET_S 🔒

Seconds of a constant-rate target a held frame (the cleanup of a still screen) may spend: a held key frame larger than that is coded again at a coarser quantizer (held_key_retry), or planned with that budget where the library’s own rate control sizes it (x264, SVT-AV1), and a held refresh is coarsened to fit from the rate control’s last quantizer (pipeline::decide_hw_fullframe), and on NVENC coded again to fit where it comes out past HELD_REFRESH_LIMIT_S. A second of the target drains in 0.4 s at the pace the WebRTC pacer holds video to, so a user acting just as the cleanup goes out waits that long at most for it. It holds a 1080p key frame at the paint-over quantizer down to 2 Mbit/s (NVENC 144 kB, x264 182 kB); a quarter second made that key frame coarser than the picture it was cleaning (x264 52 kB at 31.7 dB, NVENC 99 kB at 45.3 dB at 2 Mbit/s).

HELD_REFRESH_LIMIT_S 🔒

Seconds of a constant-rate target a held refresh of the whole picture, a predicted frame, may spend before it is coded again to fit HELD_KEY_BUDGET_S where the encoder can take it back (NVENC): what a cleanup through the rate control spends at most (pipeline’s CONVERGE_S). A refresh under it stands, since coding it coarser costs the picture more than the time it saves: NVENC’s of a 1080p texture at 0.25 and 0.1 Mbit/s, 1.8 and 3.1 s of the target, came out at 1.3 and 1.7 s six to ten steps coarser, 6.4-6.8 dB worse. One of dense text at 0.1 Mbit/s at 1080p took 52 s.

QP_HYSTERESIS_LIMIT 🔒

Damps visible quality “blinking”: the number of consecutive frames a QP increase (a quality drop under sustained motion) must be requested before a fixed-QP encoder commits it. Moving the quantizer costs a codec re-open (x265, kvazaar, SVT-AV1) or a full encoder rebuild (OpenH264), and either forces a key frame, so acting on every transient increase — and then reversing it as motion settles — would make the picture pulse. Quality increases (a lower QP, e.g. a paint-over refresh) apply at once and never wait. Shared so the fixed-QP encoders cannot disagree about how long a drop must persist.

SOFTWARE_ORDER 🔒

The video codecs by the measured time per frame of their software encoders, x264 to libvpx VP9: the order a fallthrough tries the ones the build encodes in software.

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.

encodes_in_child 🔒

Whether opening codec’s software session on a small frame and encoding one leaves a process alive, tried in a forked child: a library that faults on this machine, with an instruction the CPU lacks or a register the kernel does not emulate, takes the child down and not a session.

engine_may_serve 🔒

Whether an engine may take the codec settings names at another size: software is not forced, and the encode node’s probe found an engine for it, at the depth asked, or found every session taken. A session the ladder left in software where this holds was refused for something a resize can change (an engine’s maximum size), so it runs the ladder again.

fallback_codecs 🔒

The video codecs a capture falls through to where the one it asked for has no path on this host: those an engine on the encode node carries, named in hardware, in HARDWARE_ORDER, then those the build encodes in software, in SOFTWARE_ORDER.

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.

hardware_lacks_ten_bit 🔒

Whether a 10-bit request is the software encoder’s to serve: the node’s engine encodes the codec without 10 bits at the chroma it would run, and the build’s software encoder codes them, so the session takes the software path as a 4:4:4 the engine lacks does rather than streaming 8 bits on hardware.

held_key_retry 🔒

The quality index a held key frame of len bytes is coded again at, from crf, where it came out larger than a budget of cap bytes; None where it fits. A quality index is a quantizer on the H.26x scale, where six steps halve the bits.

held_key_start 🔒

The quality index a held key frame of a constant-rate session is first coded at, from crf, where the session’s last held key frame, last = (bytes, quality index), says one at crf would come out past a budget of cap bytes: as much coarser as held_key_retry would take it, so the frame is coded once rather than twice, since a rate control that runs through the held frame (libvpx’s) charges its buffer with both. A key frame coded more than twelve steps from crf says too little about one at it, and the frame is tried at crf.

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.

probe_node 🔒

hardware_encoders with the refusal of a node whose backend could not be brought up. A device with no NVENC session to spare (nvenc::SESSIONS_TAKEN) says nothing lasting, so that answer is asked again.

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 under the peak of its bitrate where it is capped (session_capped) and with no bitrate cap otherwise.

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_for_codec 🔒

The ladder for the one codec settings names; None where no backend of it opened, and for H.264 on host frames, whose software path the caller encodes itself.

select_frame_encoder

Choose and build the full-frame encoder of a session, or None when the CPU path (software::encode_cpu) serves it: JPEG, or H.264 through the build’s software encoder. 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 CPU path (None) what its H.264 encoder opens at.

session_capped

Whether a session runs its constant quality under the peak it was asked for (RateSettings::capped): a full-frame session’s own answer, and for the CPU path (None) x264’s, which caps, where the build carries it.

session_full_range

Whether a session signals full range: a software 4:4:4 session of x264’s kind, which the CPU 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_fallback 🔒

The codec’s software encoder; None for H.264, whose software path is the CPU path the caller encodes itself, and where the build carries none for the codec, which the ladder then falls through on.

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.

survives_in_child 🔒

Whether a forked child outlives f: a fatal signal in it is the finding, an exit is not, and neither reaches the caller. The child has a minute, and one that neither returns nor dies in it has stalled, which is as final. What it prints goes nowhere, so a library that announces itself on open speaks for a session and not for the probe. The fork waits until no SVT-AV1 handle is alive (svtav1::LIFECYCLE), as at the import-time probe: one being created, released, or run holds process-wide state the child would inherit half-built or locked. One a sandbox refuses to fork counts as alive.

ten_bit_is_softwares 🔒

hardware_lacks_ten_bit for the encode node settings names, for a capture path that opens its engine’s session itself (NvFBC).

threads_desc 🔒

How many threads a software session encodes on, for its Encoder: line.

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.

ProbeAnswer 🔒

An encode node’s probe answer: its hardware table, or the refusal of its NVENC or VA-API backend as (backend, error).