cvmmap-streamer/docs/caveats.md

Operational Caveats

This document captures known environment constraints, behavioral edge cases, and operational considerations for the cv-mmap streamer.

Environment Constraints

Simulator Label Length Limit

The cv-mmap simulator uses POSIX shared memory naming that imposes a 24-byte maximum on the --label parameter.

Constraint:

• Maximum label length: 24 bytes
• Exceeding this causes immediate exit with code 2

Error message:

--label exceeds 24 bytes

Workaround: Use compact deterministic labels:

# Good (19 bytes)
./build/cvmmap_sim --label acc_1_rtp_h264 ...

# Bad (28 bytes, will fail)
./build/cvmmap_sim --label acceptance_rtp_h264_test ...

Deterministic Simulator Sizing

Small frame sizes can trigger GStreamer caps negotiation failures before the first encoded access unit on certain hosts.

Constraint:

• Minimum recommended frame size: 640x360
• Smaller sizes may cause not-negotiated pipeline errors

Recommended simulator parameters for validation:

./build/cvmmap_sim \
    --width 640 \
    --height 360 \
    --fps 200 \
    --frames 320

Build Path Isolation

The downstream project must use its own build directory. Sharing the root build/ folder with the main cv-mmap project causes cache collision.

Constraint:

• Use downstream/cvmmap-streamer/build
• Do not use root build/

Error symptom: Configure errors referencing sibling repo paths or stale cache entries.

Resolution:

cmake --fresh -B downstream/cvmmap-streamer/build -S downstream/cvmmap-streamer

GStreamer Version Requirements

The NVENC pipeline requires GStreamer 1.20+ with full development headers. Missing elements are detected at configure time.

Constraint:

• GStreamer 1.20+ required
• Development headers required for build
• nvh264enc and nvh265enc elements checked at runtime

Missing NVENC error:

FATAL: NVENC encoder not available (nvh264enc/nvh265enc)
Run: gst-inspect-1.0 nvh264enc nvh265enc

Note: The pipeline falls back to software encoding (x264enc, x265enc) if NVENC produces zero encoded access units after 60 frames.

Dual-Mode H.265 RTMP Caveats

Mode Selection is Binding

Once selected, the RTMP mode cannot be changed without restarting the streamer process. The mode determines packetization format for the entire session.

Enhanced-RTMP mode:

• Uses 0x90/0x91 header bytes
• FourCC signaling (hvc1)
• Compatible with FFmpeg 6.0+, OBS 29+, SRS 6.0+, ZLMediaKit

Domestic extension mode:

• Uses 0x1c/0x2c header bytes
• FLV codec-id 12 signaling
• Legacy Chinese CDN compatibility
• Not supported by all players

Server Configuration Requirements

ZLMediaKit: Must set enhanced=1 in config.ini for Enhanced-RTMP mode:

[rtmp]
port=1935
enhanced=1  # 1 = Enhanced RTMP, 0 = Domestic extension

SRS: Use hevc.flv.conf or hevc.ts.conf for HEVC support:

docker run --rm -it -p 1935:1935 ossrs/srs:6 \
  ./objs/srs -c conf/hevc.flv.conf

Player Compatibility

Player	H.264 RTMP	H.265 Enhanced	H.265 Domestic
FFmpeg 6.0+	Yes	Yes	With patch
ffplay	Yes	Yes	Variable
VLC 3.0+	Yes	Yes	No
Chrome 105+ (MSE)	Yes	HTTP-FLV/TS only	No
OBS 29+	Yes	Yes	No

Mode Mismatch Detection

The rtmp_stub_tester validates mode expectations and fails with exit code 6 on mismatch:

# Start stub expecting domestic mode
./build/rtmp_stub_tester --mode h265-domestic ...

# Streamer sends enhanced mode
./build/cvmmap_streamer --codec h265 --rtmp-mode enhanced ...

# Result: tester exits 6 (ModeMismatch)

Low-Latency Configuration Trade-offs

Queue Size

Setting	Latency	Behavior
--queue-size 1	Lowest	Latest-frame semantics, drops old frames
--queue-size 5	Medium	Small backlog, some frame retention
--queue-size 0	N/A	Unbounded (NOT recommended)

Encoder Settings

Setting	Low-Latency Value	Trade-off
--b-frames 0	Disabled	Slightly lower compression efficiency
--gop 30	1 second at 30fps	Larger GOP = better compression, higher seek latency
rc-lookahead	0 (NVENC)	Slightly lower quality prediction
zerolatency	true	Disables encoder buffering

Server-Side Latency (Optional)

When using SRS or ZLMediaKit, additional latency can be introduced by server buffering.

SRS low-latency settings:

publish { mr off; }
play { gop_cache off; queue_length 5; tcp_nodelay on; }

Trade-offs:

• gop_cache off: Players wait for next I-frame (startup delay)
• mr off: Higher CPU usage
• queue_length 5: More susceptible to network jitter

Fault Scenario Behaviors

Torn Frame Handling

When the coherent snapshot detects a torn read (metadata changed during copy):

1. Frame is dropped
2. torn_frames counter increments
3. Ingest loop continues
4. Next sync message triggers new snapshot attempt

Expected log:

SNAPSHOT_TORN frame_count=A/B timestamp=X/Y

Stream Reset Handling

When MODULE_STATUS_STREAM_RESET is received:

1. Ingest queue is flushed
2. Frame counters reset
3. Pipeline may rebuild if resolution/format changed
4. RTMP publishers send sequence header rebase
5. resets counter increments

Expected log:

STREAM_RESET_RECEIVED
RTMP_STREAM_RESET_REBASE mode=<mode>

Backpressure Containment

When downstream sinks are slower than ingest:

1. Queue fills to capacity
2. Oldest frames evicted before push
3. dropped_frames counter increments
4. Latest frame always prioritized
5. Latency remains bounded

Expected log:

QUEUE_DROP dropped_frames=N queue_depth=1

Known Limitations

No Audio Support

Version 1.0 does not support audio capture or muxing. Video-only streams.

No Direct RTSP/WebRTC Publishing

RTSP and WebRTC are not direct publisher outputs. They require server-side conversion from RTMP or RTP.

Single Codec Per Session

Runtime codec switching is not supported. To change codecs, restart the streamer process.

NVENC Requires NVIDIA GPU

NVENC hardware encoding requires an NVIDIA GPU with encode support. Falls back to software encoding on non-NVIDIA systems or when NVENC is unavailable.

UDP RTP Only

RTP output uses UDP unicast only. No multicast or TCP interleaving support in v1.

Debugging Tips

Enable Verbose Logging

All binaries use spdlog. Set the environment variable for debug output:

export SPDLOG_LEVEL=debug
./build/cvmmap_streamer ...

Check Evidence Logs

Failed runs leave detailed logs:

# Find latest run
ls -lt .sisyphus/evidence/task-14-acceptance/ | head

# Examine specific row logs
cat .sisyphus/evidence/task-14-acceptance/RUN_ID/1-rtp_h264/streamer.log

Verify Binary Existence

Before running scripts, verify all binaries are built:

for bin in cvmmap_sim cvmmap_streamer rtp_receiver_tester rtmp_stub_tester; do
    test -x "downstream/cvmmap-streamer/build/$bin" || echo "Missing: $bin"
done

Test Individual Components

# Test simulator only
./build/cvmmap_sim --help

# Test streamer config validation only
./build/cvmmap_streamer --codec h264 --shm-name test --zmq-endpoint ipc:///tmp/test.ipc
# (Will fail with "No output enabled" but validates config parsing)