cvmmap-streamer/docs/smoke/srs.md

# SRS Smoke Test Profile

## Status

**OPTIONAL / NON-BLOCKING**

Use these checks when you want to verify RTMP interoperability or a real cvmmap-to-SRS forward path. They are not part of the mandatory acceptance matrix.

## Covered Paths

- Synthetic RTMP smoke using `rtmp_output_tester`
- Live cvmmap ingest -> FFmpeg encoder -> RTMP -> SRS HTTP-FLV forward
- Live cvmmap ingest -> FFmpeg encoder -> RTMP -> SRS WHEP/WebRTC playback

## Prerequisites

- Project built under `./build`
- Local SRS checkout at `~/Code/srs`, or override `SRS_ROOT`
- `ffprobe`, `ffmpeg`, and `curl` available in `PATH`
- For the live test, a running cvmmap producer. Pass the URI explicitly.

## Reproducible Test: Synthetic RTMP Matrix

This is the fast interoperability smoke for the RTMP sink implementations:

```bash
cmake -B build -S .
cmake --build build
./scripts/rtmp_srs_smoke.sh
```

Useful overrides:

```bash
ENCODER_DEVICE=nvidia ./scripts/rtmp_srs_smoke.sh
SRS_ROOT=~/Code/srs ./scripts/rtmp_srs_smoke.sh
```

What it verifies:

- `libavformat` RTMP output with `h264`
- `ffmpeg_process` RTMP output with `h264`
- `libavformat` RTMP output with `h265`
- `ffmpeg_process` RTMP output with `h265`
- Pullback from SRS HTTP-FLV with `ffprobe`

## Reproducible Test: Live cvmmap Forward

This is the end-to-end live test for a real cvmmap source:

```bash
cmake -B build -S .
cmake --build build
./scripts/live_srs_forward_smoke.sh 'cvmmap://zed@/tmp/cvmmap'
```

The script defaults to:

- `CODEC=h264`
- `ENCODER_BACKEND=ffmpeg`
- `ENCODER_DEVICE=nvidia`
- `RTMP_TRANSPORT=libavformat`
- `RTMP_MODE=enhanced`
- `INGEST_MAX_FRAMES=120`
- `STREAM_NAME=<instance>_live`, derived from `INPUT_URI`

Useful overrides:

```bash
INPUT_URI='cvmmap://zed@/tmp/cvmmap' ./scripts/live_srs_forward_smoke.sh
./scripts/live_srs_forward_smoke.sh 'cvmmap://front_cam@/tmp/cvmmap' front_cam_smoke
ENCODER_DEVICE=software ./scripts/live_srs_forward_smoke.sh 'cvmmap://zed@/tmp/cvmmap'
STREAM_NAME=zed_test INGEST_MAX_FRAMES=300 ./scripts/live_srs_forward_smoke.sh 'cvmmap://zed@/tmp/cvmmap'
SRS_ROOT=~/Code/srs ./scripts/live_srs_forward_smoke.sh 'cvmmap://zed@/tmp/cvmmap'
```

What it does:

1. Reuses a healthy local SRS instance if one is already listening on `127.0.0.1:1985`
2. Otherwise starts SRS from `~/Code/srs`
3. Writes a temporary SRS config with:
   - `daemon off`
   - `max_connections` reduced to avoid the common local `ulimit -n 1024` failure
4. Publishes the cvmmap stream to `rtmp://127.0.0.1/live/<stream>`
5. Verifies the forwarded HTTP-FLV mount at `http://127.0.0.1:8080/live/<stream>.flv`
6. Attempts to decode a short sample through `ffmpeg`
7. Stores logs and probe output under `build/live_srs_forward_smoke_*`

Expected success signals:

- The script exits `0`
- `ffprobe_httpflv.log` reports the expected codec and dimensions
- `streamer.log` shows `RTMP_OUTPUT_READY`
- `streamer.log` ends with `PIPELINE_METRICS` and `RTMP_OUTPUT_METRICS`

The HTTP-FLV probe is the authoritative pass/fail signal. The optional `ffmpeg` decode sample is best-effort because a very short bounded publish can disappear before the second client attaches.

## Manual Test: WHEP / WebRTC

SRS supports WHEP playback, and it is the better path when RTMP or HTTP-FLV playback feels too slow.

This repo includes a local SRS config copy at [srs.local.conf](/home/crosstyan/Code/cvmmap-streamer-ffmpeg-mcap/docs/smoke/srs.local.conf). It enables:

- RTMP publish on `:1935`
- HTTP API on `:1985`
- HTTP player pages on `:8080`
- WebRTC UDP on `:8000`
- `rtmp_to_rtc on`

Start SRS with that config:

```bash
cd ~/Code/srs/trunk
./objs/srs -t -c /home/crosstyan/Code/cvmmap-streamer-ffmpeg-mcap/docs/smoke/srs.local.conf
./objs/srs -c /home/crosstyan/Code/cvmmap-streamer-ffmpeg-mcap/docs/smoke/srs.local.conf
```

Publish from the streamer:

```bash
cd ~/Code/cvmmap-streamer-ffmpeg-mcap
./build/cvmmap_streamer \
  --run-mode pipeline \
  --input-uri 'cvmmap://zed@/tmp/cvmmap' \
  --codec h264 \
  --encoder-backend ffmpeg \
  --encoder-device nvidia \
  --rtmp \
  --rtmp-url 'rtmp://127.0.0.1/live/zed_live' \
  --rtmp-transport libavformat \
  --rtmp-mode enhanced
```

Open the WHEP player page in a browser:

- Player page: `http://127.0.0.1:8080/players/whep.html`
- WHEP API URL: `http://127.0.0.1:1985/rtc/v1/whep/?app=live&stream=zed_live`

Notes:

- VLC is not the right client for WHEP. Use a browser or another WebRTC/WHEP-capable player.
- Keep the stream codec on `h264` for browser compatibility.
- If the browser runs on another host and SRS picks the wrong NIC, replace `candidate *;` in [srs.local.conf](/home/crosstyan/Code/cvmmap-streamer-ffmpeg-mcap/docs/smoke/srs.local.conf) with the reachable host IP.
- On this machine, likely candidates are `192.168.2.13` or `192.168.2.184`.

## Example Live Result

For a ZED source running at `cvmmap://zed@/tmp/cvmmap`, the successful forward probe looked like:

```text
index=0
codec_name=h264
width=1280
height=720
avg_frame_rate=30/1
```

## Artifacts

Both smoke scripts write evidence under `build/`:

- `srs-smoke.log`
- `live_srs_forward_smoke_*/streamer.log`
- `live_srs_forward_smoke_*/ffprobe_httpflv.log`
- `live_srs_forward_smoke_*/ffmpeg_decode_httpflv.log`
- `live_srs_forward_smoke_*/srs_api_streams.json`

## Troubleshooting

| Issue | Cause | Action |
|-------|-------|--------|
| SRS exits immediately | `max_connections` too high for local `ulimit` | Use the script-generated config or raise `ulimit -n` |
| HTTP-FLV never mounts | Publish failed or source is idle | Check `streamer.log` and confirm the cvmmap URI is active |
| NVENC unavailable | FFmpeg cannot open `h264_nvenc` / `hevc_nvenc` | Set `ENCODER_DEVICE=software` |
| RTMP probe hangs | Live RTMP playback probe can block on some builds | Use the HTTP-FLV verification path; this is what the script treats as authoritative |

## References

- [SRS RTMP Documentation](https://ossrs.io/lts/en-us/docs/v7/doc/rtmp)
- [SRS HEVC Documentation](https://ossrs.io/lts/en-us/docs/v7/doc/hevc)
- [Enhanced RTMP Specification](https://github.com/veovera/enhanced-rtmp)