cvmmap-streamer/docs/caveats.md

Operational Caveats

This document captures the current runtime constraints for cvmmap-streamer after the FFmpeg-only cleanup.

Input Model

cvmmap URI Only

The runtime ingests from a cvmmap URI, for example:

./build/cvmmap_streamer --run-mode pipeline --input-uri 'cvmmap://zed@/tmp/cvmmap'

Legacy flags such as --shm-name, --zmq-endpoint, --input-mode, and the dummy-input options are no longer supported.

Encoder Path

FFmpeg Is The Only Encoder Backend

The public backend surface is:

• --encoder-backend auto
• --encoder-backend ffmpeg

Both resolve to the FFmpeg encoder path. The removed GStreamer backend is no longer available.

NVENC Is Optional

When --encoder-device nvidia is selected, FFmpeg must expose h264_nvenc and hevc_nvenc.

Useful local checks:

ffmpeg -hide_banner -encoders | rg 'nvenc|libx264|libx265'

If NVENC is unavailable, use:

--encoder-device software

Low-Latency Defaults

The current low-latency defaults are:

• gop=30
• b_frames=0
• NVENC preset/tune tuned for low latency

This favors immediacy over compression efficiency.

Transport Caveats

RTMP Is Enhanced RTMP Only

The repo now supports:

• libavformat RTMP output
• ffmpeg_process RTMP output

The removed custom RTMP packetizer and domestic mode are no longer available. RTMP is always Enhanced RTMP.

RTP SDP Is Optional

The RTP publisher can write an SDP sidecar when --rtp-sdp is set. This is only for generic receivers that need an out-of-band description. If the consumer is preconfigured, skip the SDP output.

No Direct RTSP/WebRTC Publishing

This repo does not contain a direct RTSP publisher or a direct WebRTC/WHEP publisher.

If you want browser playback or WHEP, publish RTMP to a media server such as SRS and let that server expose WHEP/WebRTC.

Media Scope

No Audio Support

This project is video-only. It publishes or records encoded video access units only.

If you need audio transport, muxing, or A/V sync, that is outside the current repo scope.

Recording Caveats

MCAP Stores Encoded Video Frames

MCAP recording stores one foxglove.CompressedVideo message per encoded access unit. Replay depends on encoded keyframes carrying decoder configuration; this is handled by the current writer on keyframes.

MCAP Body Recording Is Raw Packet Capture

When the producer exposes ZED body tracking, MCAP recording stores one raw cvmmap.body_tracking.v1 message per body PUB packet on /camera/body by default. These payload bytes are not normalized by cvmmap-streamer; downstream consumers should parse them with the cv-mmap body-tracking v1 contract.

External Server Caveats

Local SRS Defaults Can Hit ulimit

On this machine, stock SRS configs can fail at startup if max_connections exceeds the local ulimit -n. The checked-in smoke profile uses max_connections 64 to avoid that local failure mode.

Server Latency Still Matters

Low encoder latency does not guarantee low end-to-end latency. SRS, ZLMediaKit, HTTP-FLV players, and browser buffering can all add delay on top of the encoder path.