API Reference

libnvmpi API Reference

Public C API defined in include/nvmpi.h. Both decoder and encoder expose opaque context handles (nvmpictx*) — a handle must only be passed back to the API family that created it.

For thread safety details, see THREAD_SAFETY.md.

---

Constants

NVMPI_ENC_CHUNK_SIZE

#define NVMPI_ENC_CHUNK_SIZE 10*1024*1024

Maximum size (bytes) of encoded buffers on the encoder capture plane. Also used as the allocation size of each pooled packet buffer. A single encoded frame must not exceed this; frames larger than 10 MiB are dropped.

---

Enums

nvPixFormat

Raw (uncompressed) pixel layouts for decoder output and encoder input.

Value	Description
NV_PIX_NV12	4:2:0 semi-planar (Y + interleaved UV). Default encoder input.
NV_PIX_YUV420	4:2:0 planar (Y + U + V separate planes).
NV_PIX_P010	10-bit 4:2:0 semi-planar (matches FFmpeg P010LE). Decode-only, HEVC Main10, requires NvUtils buffer API.

nvCodingType

Compressed bitstream codec selector.

Value	Codec	Decode	Encode
NV_VIDEO_CodingUnused	None	—	—
NV_VIDEO_CodingH264	H.264/AVC	Yes	Yes
NV_VIDEO_CodingMPEG4	MPEG-4 Part 2	Yes	No
NV_VIDEO_CodingMPEG2	MPEG-2	Yes	No
NV_VIDEO_CodingVP8	VP8	Yes	No
NV_VIDEO_CodingVP9	VP9	Yes	No
NV_VIDEO_CodingHEVC	H.265/HEVC	Yes	Yes
NV_VIDEO_CodingMJPEG	MJPEG	Yes	Yes

---

Structures

nvDecParam

Decoder creation parameters. Consumed once by nvmpi_create_decoder().

Field	Type	Description	Default
frame_pool_size	int	Decoded frames buffered before user must read.	12
codingType	nvCodingType	Input bitstream codec.	— (required)
pixFormat	nvPixFormat	Requested output pixel layout.	— (required)
resized	nvSize	Optional hw scaling target; {0,0} keeps stream resolution.	{0,0}
chunk_size	unsigned int	Bytes per compressed-input V4L2 buffer. 0 = default 10 MiB.	0
max_perf	int	Non-zero: lift NVDEC clock governor (max clocks).	0
disable_dpb	int	Non-zero: skip DPB reordering (low-latency, no B-frames).	0
wait_timeout	int	Blocking wait timeout in ms. 0 = use default 500ms. Range: 50–5000.	0
width	unsigned int	Stream width from container headers (0 = unknown/use resolution-change events).	0
height	unsigned int	Stream height from container headers (0 = unknown/use resolution-change events).	0

nvEncParam

Encoder creation parameters. Consumed once by nvmpi_create_encoder().

Field	Type	Description	Default
width	unsigned int	Frame width in pixels.	— (required)
height	unsigned int	Frame height in pixels.	— (required)
profile	unsigned int	FFmpeg-style H.264 profile id (66/77/100).	0
level	unsigned int	H.264 level_idc (e.g. 41 = 4.1).	0
bitrate	unsigned int	Target bitrate in bit/s.	0
peak_bitrate	unsigned int	Peak bitrate for VBR (0 = derive from bitrate).	0
enableLossless	char	Non-zero: constant QP 0 / High 4:4:4 (H.264 only).	0
mode_vbr	char	Non-zero: VBR rate control instead of CBR.	0
insert_spspps_idr	char	Non-zero: repeat SPS/PPS at every IDR frame.	0
insert_vui	char	Non-zero: embed VUI timing_info (fps) in bitstream.	0
pixFormat	nvPixFormat	Raw input layout: NV_PIX_YUV420 or NV_PIX_NV12.	NV_PIX_YUV420
iframe_interval	unsigned int	I-frame period in frames.	0
idr_interval	unsigned int	IDR period in frames.	0
fps_n	unsigned int	Framerate numerator.	0
fps_d	unsigned int	Framerate denominator.	0
capture_num	int	Number of V4L2 buffers per plane.	0
max_b_frames	unsigned int	B frames between references (H.264 only).	0
refs	unsigned int	Reference frames (0 = encoder default).	0
qmax	unsigned int	Max quantizer (applied only with qmin).	0
qmin	unsigned int	Min quantizer (applied only with qmax).	0
hw_preset_type	unsigned int	Speed/quality preset: 1=ultrafast .. 4=slow.	0
vbv_buffer_size	unsigned int	Virtual buffer size of the encoder.	0
codingType	nvCodingType	NV_VIDEO_CodingH264 or NV_VIDEO_CodingHEVC.	— (required)
max_perf	int	Non-zero: lift NVENC clock governor (max clocks).	0
poc_type	unsigned int	H.264 picture order count type (0=default, 2=low-latency).	0
wait_timeout	unsigned int	Blocking-wait timeout in ms (0 = default 500ms).	0
enable_cabac	char	Non-zero: enable CABAC entropy coding (H.264 only; default CAVLC).	0
insert_aud	char	Non-zero: insert Access Unit Delimiter NALs.	0

nvPacket

Compressed packet exchanged across the API boundary.

Field	Type	Description
flags	unsigned long	Keyframe flag (matches AV_PKT_FLAG_KEY).
payload_size	unsigned long	Valid bytes in payload.
payload	unsigned char*	Bitstream data.
pts	unsigned long	Presentation timestamp in microseconds.
privData	void*	Internal: NVMPI_pkt pointer (encoder only).

Ownership: Decoder direction — caller owns payload (memcpy'd into V4L2 buffer, may be freed on return). Encoder direction — packets are pooled; see qEmptyPacket/dqEmptyPacket.

nvFrame

Raw planar frame exchanged across the API boundary.

Field	Type	Description
flags	unsigned long	Frame flags.
payload_size[3]	unsigned long[3]	Per-plane byte size.
payload[3]	unsigned char*[3]	Per-plane data pointers (caller-owned).
linesize[3]	unsigned int[3]	Per-plane stride in bytes.
type	nvPixFormat	Pixel format.
width	unsigned int	Frame width.
height	unsigned int	Frame height.
timestamp	time_t	Microseconds (carried via V4L2 buffer timestamp).

Ownership: Payload pointers always reference caller-owned memory. The decoder memcpy's into them (get_frame), the encoder memcpy's out (put_frame). No plane buffer changes ownership.

nvSize

Simple width/height pair for the optional decoder resize target.

Field	Type	Description
width	unsigned int	Target width (0 = no resize).
height	unsigned int	Target height (0 = no resize).

---

Decoder API

nvmpi_create_decoder

nvmpictx* nvmpi_create_decoder(nvDecParam* param);

Create a decoder context. Opens the V4L2 decoder device, sets up the bitstream (OUTPUT) plane, and spawns the internal capture thread. The param struct is read once and not retained.

Returns: Opaque context handle. NULL on failure.

Thread safety: Call from user thread only. No concurrent access exists yet at creation time.

nvmpi_decoder_put_packet

int nvmpi_decoder_put_packet(nvmpictx* ctx, nvPacket* packet);

Feed one compressed packet (Annex-B for H.264/HEVC). May block waiting for a free V4L2 OUTPUT-plane buffer once all buffers are in flight.

A packet with payload_size == 0 signals end-of-stream (starts flushing).

Returns:

Code	Meaning
0	Success.
-1	Dequeue failure (V4L2 output plane).
-2	Queue failure (V4L2 output plane).
-3	Packet exceeds chunk_size — dropped. Smaller packets continue.

Thread safety: User thread only.

nvmpi_decoder_get_frame

int nvmpi_decoder_get_frame(nvmpictx* ctx, nvFrame* frame, bool wait);

Retrieve one decoded frame by copying it into frame->payload planes (which must already be allocated with matching linesize).

Behavior depends on wait:

wait	Behavior
false	Non-blocking. Returns -1 immediately if no frame is ready.
true	Blocks up to wait_timeout_ms (default 500ms, configurable via nvDecParam.wait_timeout). Returns -1 on timeout or shutdown.

The blocking path uses condition-variable waits with 100ms internal granularity for shutdown responsiveness. See THREAD_SAFETY.md for full details.

Returns: 0 on success, -1 on no frame available / timeout / shutdown.

Thread safety: User thread only. The blocking path holds m_filledBuf during CV waits but releases it between iterations.

nvmpi_decoder_flush

int nvmpi_decoder_flush(nvmpictx* ctx);

Reset the decoder pipeline for seek / stream restart. Stops the capture thread, drains in-flight frames, clears the shutdown flag, and restarts.

The caller must re-prime extradata (SPS/PPS) after this call so the hardware decoder can reconfigure its capture plane.

Returns: Always 0.

Thread safety: User thread only. Joins the capture thread internally.

nvmpi_decoder_close

int nvmpi_decoder_close(nvmpictx* ctx);

Stop the capture thread, free all DMA buffers/pools, and destroy ctx. The handle is invalid afterwards.

Internally: sets eos, calls shutdown() on the frame pool (unblocking any waiting consumer), stops the V4L2 stream, joins the capture thread, then frees all resources.

Returns: Always 0.

Thread safety: User thread only.

---

JPEG Decoder API

Synchronous JPEG decode backed by the Tegra NVJPG engine. No V4L2 device is opened and no background capture thread is spawned — each frame is decoded synchronously in nvmpi_jpeg_decoder_put_packet. Only baseline JPEG is supported; progressive JPEG is rejected.

nvmpi_create_jpeg_decoder

nvmpictx* nvmpi_create_jpeg_decoder(void);

Create a JPEG decoder context backed by the Tegra NVJPG engine. No parameters are required — the decoder auto-configures per frame from the JPEG header.

Returns: Opaque context handle. NULL on failure (NvJPEGDecoder creation error).

Thread safety: Call from user thread only.

nvmpi_jpeg_decoder_put_packet

int nvmpi_jpeg_decoder_put_packet(nvmpictx* ctx, nvPacket* packet);

Decode one JPEG frame. A packet with payload_size == 0 signals EOS (no decode is performed; the internal EOS flag is set).

Only baseline JPEG is supported. Progressive JPEG returns an error.

Returns: 0 on success, -1 on decode error or unsupported format (e.g. progressive JPEG).

Thread safety: User thread only.

nvmpi_jpeg_decoder_get_frame

int nvmpi_jpeg_decoder_get_frame(nvmpictx* ctx, nvFrame* frame, bool wait);

Retrieve one decoded frame.

wait	Behavior
false	Non-blocking. Returns -1 immediately if no frame is ready.
true	Blocks up to 500ms for a frame. Returns -1 on timeout or EOS.

Returns: 0 on success, -1 when no frame is available.

Thread safety: User thread only.

nvmpi_jpeg_decoder_close

int nvmpi_jpeg_decoder_close(nvmpictx* ctx);

Destroy the JPEG decoder context and free all DMA buffers. The handle is invalid afterwards.

Returns: 0.

Thread safety: User thread only.

---

JPEG Encoder API

Synchronous JPEG encode backed by the Tegra NVJPG engine. No V4L2 device is opened and no DQ thread is spawned — encoding is synchronous per frame. Input must be YUV420. Every output packet is flagged as a keyframe.

Hardware note: On modules without NVJPG encode capability (e.g. Orin Nano), nvmpi_create_jpeg_encoder returns NULL. The FFmpeg wrapper reports a clear error suggesting -c:v mjpeg software fallback in that case.

nvmpi_create_jpeg_encoder

nvmpictx* nvmpi_create_jpeg_encoder(int quality);

Create a JPEG encoder context backed by the Tegra NVJPG engine. quality follows libjpeg semantics: 1 (lowest) to 100 (highest). Values outside this range are clamped to the nearest bound; 85 is used as the internal default when the value is out of range.

Returns: Opaque context handle. NULL on failure (NVJPG engine unavailable or creation error).

Thread safety: Call from user thread only.

nvmpi_jpeg_encoder_put_frame

int nvmpi_jpeg_encoder_put_frame(nvmpictx* ctx, nvFrame* frame);

Encode one YUV420 frame to JPEG. The encoded JPEG is staged internally for retrieval via nvmpi_jpeg_encoder_get_packet. frame == NULL signals EOS.

Returns: 0 on success, -1 on error.

Thread safety: User thread only.

nvmpi_jpeg_encoder_get_packet

int nvmpi_jpeg_encoder_get_packet(nvmpictx* ctx, nvPacket* packet);

Retrieve the encoded JPEG packet. The caller must pre-allocate packet->payload with sufficient capacity before calling. packet->flags is set to 1 (keyframe) for every JPEG frame.

Returns:

Code	Meaning
0	Success.
-1	No packet ready.
-2	EOS with no packet.

Thread safety: User thread only.

nvmpi_jpeg_encoder_close

int nvmpi_jpeg_encoder_close(nvmpictx* ctx);

Destroy the JPEG encoder context and free all resources. The handle is invalid afterwards.

Returns: 0.

Thread safety: User thread only.

---

Encoder API

nvmpi_create_encoder

nvmpictx* nvmpi_create_encoder(nvEncParam* param);

Create an encoder context. Opens the V4L2 encoder device, programs profile/level/rate-control from param, sets up both planes, and starts the capture-plane dequeue thread.

The caller must still fill the packet pool (qEmptyPacket) before encoded output can be delivered.

Returns: Opaque context handle.

Thread safety: User thread only.

nvmpi_encoder_put_frame

int nvmpi_encoder_put_frame(nvmpictx* ctx, nvFrame* frame);

Copy frame planes into a V4L2 OUTPUT-plane buffer and queue it. May block waiting for a free buffer.

frame == NULL sends EOS and puts the encoder into flushing mode.

Returns: 0 on success, negative on error or if already flushing.

Thread safety: User thread only.

nvmpi_encoder_get_packet

int nvmpi_encoder_get_packet(nvmpictx* ctx, nvPacket** packet, bool wait);

Dequeue one encoded packet.

Behavior depends on wait and flushing state:

wait	Flushing	Behavior
false	No	Non-blocking. Returns -1 immediately if no packet ready.
true	No	Blocks up to wait_timeout_ms (default 500ms, configurable via nvEncParam.wait_timeout) using the pool's CV-based tiered wait. Returns -1 on timeout or shutdown.
false or true	Yes	Blocks until a packet arrives or EOS. Returns -2 on EOS.

On success, the caller owns the packet until it re-queues it with nvmpi_encoder_qEmptyPacket().

Thread safety: User thread only.

nvmpi_encoder_dqEmptyPacket

int nvmpi_encoder_dqEmptyPacket(nvmpictx* ctx, nvPacket** packet);

Non-blocking dequeue from the empty packet pool. Returns -1 when exhausted. Used by the FFmpeg wrapper to drain/teardown the pool.

Thread safety: User thread only.

nvmpi_encoder_qEmptyPacket

void nvmpi_encoder_qEmptyPacket(nvmpictx* ctx, nvPacket* packet);

Hand a caller-allocated packet (payload buffer included) to the pool. The encoder's capture thread fills it later. The pool stores only the pointer — the caller remains responsible for eventually freeing it.

Thread safety: User thread only. The pool itself is thread-safe (the DQ thread reads from the other end).

nvmpi_encoder_force_idr

int nvmpi_encoder_force_idr(nvmpictx* ctx);

Force the encoder to produce an IDR frame for the next queued input. Calls NvVideoEncoder::forceIDR() which sets V4L2_CID_MPEG_MFC51_VIDEO_FORCE_FRAME_TYPE. May be called at any time while the encoder is running.

Returns: 0 on success, -1 on error.

Thread safety: User thread only.

nvmpi_encoder_set_bitrate

int nvmpi_encoder_set_bitrate(nvmpictx* ctx, unsigned int bitrate);

Change the encoder target bitrate mid-stream (adaptive bitrate). Calls NvVideoEncoder::setBitrate() which updates V4L2_CID_MPEG_VIDEO_BITRATE. Takes effect from the next encoded frame.

Returns: 0 on success, -1 on error.

Thread safety: User thread only.

nvmpi_encoder_flush

int nvmpi_encoder_flush(nvmpictx* ctx);

Mid-stream encoder reset. Stops the DQ thread, STREAMOFF both planes, drains the packet pool, resets flushing/EOS state, STREAMON, re-queues capture buffers, and restarts the DQ thread. Encoding can resume immediately after this call.

Returns: Always 0.

Thread safety: User thread only.

nvmpi_encoder_close

int nvmpi_encoder_close(nvmpictx* ctx);

Stop the dequeue thread and free the context. Packets still held in the pools are not freed here — drain them first.

Returns: Always 0.

Thread safety: User thread only.