FAQ

FAQ & Known Limitations

Answers to the recurring questions that show up across the jocover and Keylost trackers, plus what this fork fixes and adds. Each entry follows symptom → cause → resolution/workaround → references, and cites the upstream issues so searchers land here.

Sourced from the 237-fork network sweep — see Fork Network Overview, the full report, and the cross-referenced results.

Sections

Page	Covers
Hardware & Platform Limits	4K encode cap, Orin Nano has no NVENC, mod-16 alignment, VP8 availability
Versions & Compatibility	Supported FFmpeg 4.2→8.0 matrix, HEVC-over-RTMP needs ≥ 6.1
Build & Install	pkg-config "nvmpi not found", glibc ≥ 2.34 segfault, Ubuntu 22.04
Performance	WITH_NVUTILS CPU delta, max-perf-mode speedup, long-decode CPU rise, pool sizing
Features & Fork Differences	What this fork fixed vs jocover/Keylost, and the roadmap

Quick answers

• "Which FFmpeg versions are supported?" → 6.0, 6.1, 7.0, 7.1, 8.0, 8.1 (v3.0.0+). See Compatibility.
• "Can the Orin Nano encode?" → No NVENC silicon; decode-only. Details.
• "Encode above 4K fails." → NVENC hardware cap, not software-fixable. Details.
• "pkg-config can't find nvmpi." → PKG_CONFIG_PATH + ldconfig. Details.
• "Segfault on Ubuntu 22.04 / glibc ≥ 2.34." → fixed in this fork. Details.
• "How do I use hardware MJPEG decode?" → ffmpeg -c:v mjpeg_nvmpi -i input.mjpeg .... Baseline JPEG only; progressive is rejected. Details.
• "Does FFmpeg need libnvmpi.so to run?" → No (v3.7.0+). libnvmpi is loaded at runtime via dlopen; FFmpeg starts without it. Details.

MJPEG Decoder

How do I use hardware MJPEG decode?

Use the mjpeg_nvmpi decoder:

ffmpeg -c:v mjpeg_nvmpi -i input.mjpeg -c:v libx264 output.mp4

The decoder handles baseline JPEG only. Progressive JPEG (SOF2) is rejected with an error — the NVJPG engine does not support it.

Why is MJPEG decode quality slightly different from software?

The hardware path goes through a VIC (Video Image Compositor) transform to convert from block-linear to pitch-linear format. This introduces minor color-space rounding differences compared to pure software libjpeg decode. PSNR is typically ~28 dB — visually identical for all practical purposes.

Orin Nano MJPEG performance

The NVJPG engine clock on Orin Nano defaults to 115 MHz (pre-JetPack 5.1.2). For maximum MJPEG decode throughput, run sudo jetson_clocks or configure nvpmodel to boost the NVJPG clock.

MJPEG Encoder

How do I use hardware MJPEG encode?

Use the mjpeg_nvmpi encoder with the -quality option (1–100, default 85):

ffmpeg -i input.mp4 -c:v mjpeg_nvmpi -quality 90 output.mjpeg

The encoder uses the Tegra NVJPG engine via NvJPEGEncoder. It is synchronous (one frame at a time) and produces baseline JPEG output.

Note: The Orin Nano does not have NVJPG encode capability — NvJPEGEncoder::createJPEGEncoder() returns NULL on this module. Use software mjpeg as a fallback.

Encoder Runtime Controls

Can I change bitrate or force keyframes mid-stream?

Yes, as of v3.6.6:

• Force IDR: -force_key_frames or programmatically via nvmpi_encoder_force_idr()
• Dynamic bitrate: programmatically via nvmpi_encoder_set_bitrate()
• Encoder flush: avcodec_flush_buffers() now resets the encoder pipeline without closing/reopening the codec context (v3.6.4+)

Additional encoder AVOptions added in v3.6.6:

• -cabac 1 — enable CABAC entropy coding (H.264 only; default is CAVLC)
• -aud 1 — insert Access Unit Delimiter NALs
• -lossless 1 — lossless encoding (constant QP 0, H.264 only)

Can I use blocking wait for encoded packets?

Yes, as of v3.2.0. Use -flags low_delay to activate blocking get_packet. The timeout is configurable via the wait_timeout AVOption (0–5000ms, default 500ms).