cvmmap-streamer/docs/compat_matrix.md

Compatibility Matrix

This document defines the complete protocol, codec, and RTMP mode compatibility matrix for cv-mmap streamer. It explicitly separates mandatory (blocking) checks from optional (non-blocking) checks.

Mandatory Checks (Blocking for Release)

These checks must ALL pass for a release to be considered valid. They require no external servers and run entirely in standalone mode.

Protocol/Codec Matrix

Row	Protocol	Codec	RTMP Mode	Test Command	Evidence
1	RTP	H.264	N/A	./scripts/acceptance_standalone.sh (row 1)	task-14-acceptance.txt
2	RTP	H.265	N/A	./scripts/acceptance_standalone.sh (row 2)	task-14-acceptance.txt
3	RTMP	H.264	enhanced	./scripts/acceptance_standalone.sh (row 3)	task-14-acceptance.txt
4	RTMP	H.265	enhanced	./scripts/acceptance_standalone.sh (row 4)	task-14-acceptance.txt
5	RTMP	H.265	domestic	./scripts/acceptance_standalone.sh (row 5)	task-14-acceptance.txt

Pass Criteria:

• Exit code 0 from acceptance_standalone.sh
• JSON summary shows total=5 pass=5 fail=0 skip=0
• All tester processes receive expected packet/frame counts

Fault Scenarios

Scenario	Description	Test Command	Evidence
Torn Read	Coherent snapshot rejects torn frames	./scripts/fault_suite.sh	task-15-fault-suite.txt
Sink Stall	Backpressure containment under slow consumer	./scripts/fault_suite.sh	task-15-fault-suite.txt
Reset Storm	Stream reset recovery	./scripts/fault_suite.sh	task-15-fault-suite.txt

Pass Criteria:

• Exit code 0 from fault_suite.sh
• All fault scenarios PASS status
• No violations of latency/drop thresholds

Invalid Combinations (Explicitly Rejected)

These combinations are rejected at startup with clear error messages and non-zero exit codes.

Combination	Error	Exit Code
RTMP + H.264 + domestic mode	H.264 does not support domestic mode	1
RTP without --rtp-endpoint	Missing required RTP endpoint	1
RTMP without --rtmp-url	Missing required RTMP URL	1
--rtmp-mode without H.265 codec	Domestic mode requires H.265	1

Optional Checks (Non-Blocking)

These checks are provided for interoperability validation but are NOT required for release acceptance. If the environment is unavailable, these should be skipped.

Server Smoke Tests

Server	Protocols	H.265 Support	Status
SRS 6.0+	RTMP, HTTP-FLV, HLS, WebRTC	Enhanced-RTMP	Optional
ZLMediaKit	RTMP, HTTP-FLV, HTTP-TS, RTSP, WebRTC	Enhanced + Domestic	Optional

Skip Conditions:

• Docker not available
• Port 1935 in use by another service
• Server container fails to start
• Network isolation prevents connection

Expected Behavior When Skipped:

• Script exits with status 0 (SKIP)
• Evidence file notes the skip reason
• Mandatory acceptance still proceeds

RTMP H.265 Dual Mode Details

Enhanced-RTMP Mode (Recommended)

Specification: Enhanced RTMP

Characteristics:

• Video codec header byte: 0x90 (sequence) / 0x91 (frame)
• FourCC: hvc1 or hev1
• Standardized, widely supported
• FFmpeg 6.0+ native support
• OBS 29+ support
• SRS 6.0+ native support
• ZLMediaKit default mode

When to use:

• Greenfield deployments
• Modern CDN ingestion
• Cross-platform compatibility requirements

Domestic Extension Mode (Legacy Compatibility)

Specification: Proprietary FLV extension using codec-id 12

Characteristics:

• Video codec header byte: 0x1c (keyframe) / 0x2c (inter)
• FLV codec-id: 12 (non-standard)
• Legacy Chinese CDN compatibility
• Requires explicit config in ZLMediaKit (enhanced=0)
• Not supported by all players

When to use:

• Legacy CDN requirements
• Existing domestic-mode infrastructure
• Backward compatibility with older systems

Mode Selection Decision Tree

Is codec H.265?
├── No (H.264) ──> Use enhanced mode only (domestic invalid)
└── Yes (H.265)
    ├── Target is modern CDN/player? ──> enhanced
    ├── Target requires domestic mode? ──> domestic
    └── Unknown? ──> enhanced (safer default)

Validation Commands

Verify Mandatory Matrix

cd downstream/cvmmap-streamer
./scripts/acceptance_standalone.sh
echo "Exit code: $?"

Verify Individual Row (RTP H.264)

# Terminal 1: Tester
./build/rtp_receiver_tester \
    --port 51040 \
    --expect-pt 96 \
    --packet-threshold 1 \
    --timeout-ms 10000

# Terminal 2: Simulator + Streamer
./build/cvmmap_sim \
    --shm-name test_rtp_h264 \
    --zmq-endpoint "ipc:///tmp/test_rtp_h264.ipc" \
    --label rtp_h264 \
    --frames 320 \
    --fps 200 \
    --width 640 \
    --height 360 &

./build/cvmmap_streamer \
    --run-mode pipeline \
    --codec h264 \
    --shm-name test_rtp_h264 \
    --zmq-endpoint "ipc:///tmp/test_rtp_h264.ipc" \
    --queue-size 1 \
    --gop 30 \
    --b-frames 0 \
    --ingest-max-frames 120 \
    --rtp \
    --rtp-endpoint "127.0.0.1:51040" \
    --rtp-payload-type 96 \
    --rtp-sdp /tmp/test_rtp_h264.sdp

Verify Invalid Combination Rejection

# Should fail with clear error
./build/cvmmap_streamer \
    --codec h264 \
    --rtmp-mode domestic \
    --shm-name test \
    --zmq-endpoint "ipc:///tmp/test.ipc"

echo "Exit code: $?"  # Expected: 2 (invalid mode matrix)

Evidence Locations

All test evidence is written to .sisyphus/evidence/:

Evidence File	Description
task-14-acceptance.txt	Latest acceptance run pointer
task-14-acceptance-summary.json	Acceptance summary JSON
task-14-acceptance/RUN_ID/	Per-run logs for each matrix row
task-15-fault-suite.txt	Latest fault suite run pointer
task-15-fault-suite-summary.json	Fault suite summary JSON
task-15-fault-suite/RUN_ID/	Per-run logs for each scenario