# 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:

```bash
./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:

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

If NVENC is unavailable, use:

```bash
--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.