crosstyan/cvmmap-streamer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(streamer): remove gstreamer and legacy rtmp paths

Browse Source
This commit is contained in:
crosstyan
2026-03-11 16:43:29 +08:00
parent ed3f32ff6e
commit 782af9481c
22 changed files with 817 additions and 3339 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/compat_matrix.md
+52 -166
View File
@@ -1,188 +1,74 @@
# 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 Acceptance Matrix
## Mandatory Checks (Blocking for Release)
The deterministic acceptance matrix is driven by tester binaries, not by a dummy pipeline source.
These checks must ALL pass for a release to be considered valid. They require no external servers and run entirely in standalone mode.
Run it with:
### Protocol/Codec Matrix
```bash
cmake -B build -S .
cmake --build build
./scripts/acceptance_standalone.sh
```
| 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 |
Covered rows:
**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
| Row | Protocol | Codec | Transport | Runner |
|-----|----------|-------|-----------|--------|
| 1 | RTP | H.264 | UDP RTP | `./scripts/acceptance_standalone.sh` |
| 2 | RTP | H.265 | UDP RTP | `./scripts/acceptance_standalone.sh` |
| 3 | RTMP | H.264 | `libavformat` | `./scripts/acceptance_standalone.sh` |
| 4 | RTMP | H.265 | `libavformat` | `./scripts/acceptance_standalone.sh` |
| 5 | RTMP | H.264 | `ffmpeg_process` | `./scripts/acceptance_standalone.sh` |
| 6 | RTMP | H.265 | `ffmpeg_process` | `./scripts/acceptance_standalone.sh` |
### Fault Scenarios
Notes:
| 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 |
- RTMP is Enhanced RTMP only.
- The custom RTMP packetizer and domestic mode are removed.
- `encoder.backend` remains `auto|ffmpeg`; both resolve to FFmpeg.
## 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.
These are useful interoperability checks, but they are not part of the mandatory acceptance gate:
### Server Smoke Tests
- `./scripts/rtmp_srs_smoke.sh`
- `./scripts/live_srs_forward_smoke.sh '<cvmmap-uri>'`
- manual WHEP playback through SRS
- manual ZLMediaKit interoperability checks
- live MCAP capture, validation, and paced replay
| 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 |
## Recording Coverage
**Skip Conditions:**
- Docker not available
- Port 1935 in use by another service
- Server container fails to start
- Network isolation prevents connection
MCAP support is validated separately with:
**Expected Behavior When Skipped:**
- Script exits with status 0 (SKIP)
- Evidence file notes the skip reason
- Mandatory acceptance still proceeds
- `./build/mcap_reader_tester`
- `./build/mcap_replay_tester`
- `./scripts/replay_mcap.sh`
## RTMP H.265 Dual Mode Details
Current recording scope:
### Enhanced-RTMP Mode (Recommended)
| Output | Codec | Notes |
|--------|-------|-------|
| MCAP `foxglove.CompressedVideo` | H.264 | Stored as Annex B access units |
| MCAP `foxglove.CompressedVideo` | H.265 | Stored as Annex B access units |
**Specification:** [Enhanced RTMP](https://github.com/veovera/enhanced-rtmp)
## Current Defaults
**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
| Setting | Value |
|---------|-------|
| Encoder backend | `auto` -> FFmpeg |
| RTMP transport | `libavformat` |
| RTMP mode | Enhanced only |
| Encoder device | `auto` |
| Low-latency GOP | `30` |
| B-frames | `0` |
**When to use:**
- Greenfield deployments
- Modern CDN ingestion
- Cross-platform compatibility requirements
## What Is No Longer Supported
### 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
```bash
cd downstream/cvmmap-streamer
./scripts/acceptance_standalone.sh
echo "Exit code: $?"
```
### Verify Individual Row (RTP H.264)
```bash
# Terminal 1: Tester
./build/rtp_receiver_tester \
--port 51040 \
--expect-pt 96 \
--packet-threshold 1 \
--timeout-ms 10000
# Terminal 2: Streamer in dummy input mode
./build/cvmmap_streamer \
--run-mode pipeline \
--input-mode dummy \
--shm-name test_rtp_h264 \
--zmq-endpoint "ipc:///tmp/test_rtp_h264.ipc" \
--dummy-label rtp_h264 \
--dummy-frames 320 \
--dummy-fps 200 \
--dummy-width 640 \
--dummy-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
```bash
# 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 |
- GStreamer encoder backend
- custom RTMP packetizer
- RTMP domestic mode
- dummy input flags in the main runtime
- direct in-repo RTSP/WebRTC publishing