cvmmap-streamer/docs/smoke/srs.md

# SRS Smoke Test Profile

## Status

**OPTIONAL / NON-BLOCKING**

This document provides optional interoperability checks for SRS (Simple Realtime Server). These checks are not mandatory for acceptance. If the SRS environment is unavailable, skip these tests without failing the mandatory acceptance criteria.

---

## Purpose

Validate RTMP streaming interoperability with SRS, specifically for:
- RTMP H.264 publishing and playback
- Enhanced RTMP HEVC (H.265) via [Enhanced RTMP spec](https://github.com/veovera/enhanced-rtmp)
- Low-latency streaming configurations

---

## Prerequisites

- Docker (recommended) or SRS built from source
- FFmpeg or the project streaming binary
- Optional: ffplay, VLC for playback verification

---

## Quick Start (Docker)

```bash
# Run SRS with RTMP support
docker run --rm -it -p 1935:1935 -p 8080:8080 ossrs/srs:6 \
  ./objs/srs -c conf/rtmp.conf

# For HEVC support, use hevc.flv.conf or hevc.ts.conf
docker run --rm -it -p 1935:1935 -p 8080:8080 ossrs/srs:6 \
  ./objs/srs -c conf/hevc.flv.conf
```

---

## Smoke Commands

### 1. Basic RTMP H.264 Stream Test

```bash
# Publish test stream to SRS
ffmpeg -re -f lavfi -i testsrc=duration=60:size=1280x720:rate=30 \
  -f lavfi -i sine=frequency=1000:duration=60 \
  -pix_fmt yuv420p -c:v libx264 -preset fast -b:v 3000k \
  -c:a aac -b:a 128k -f flv rtmp://localhost/live/smoke_test
```

```bash
# Playback verification
ffplay rtmp://localhost/live/smoke_test
```

### 2. Enhanced RTMP HEVC (H.265) Test

**Prerequisites:**
- SRS 6.0.4+ with HEVC configuration
- FFmpeg 6.0+ with libx265 and enhanced RTMP support (or use `ossrs/srs:encoder` Docker image)

```bash
# Publish HEVC stream (Enhanced RTMP)
ffmpeg -re -f lavfi -i testsrc=duration=60:size=1280x720:rate=30 \
  -f lavfi -i sine=frequency=1000:duration=60 \
  -pix_fmt yuv420p -c:v libx265 -preset fast -b:v 2000k \
  -c:a aac -b:a 128k -f flv rtmp://localhost/live/smoke_hevc

# Alternative using project binary (if HEVC enabled)
# ./cvmmap-streamer --output rtmp://localhost/live/smoke_hevc --codec hevc
```

```bash
# Playback HEVC stream
ffplay rtmp://localhost/live/smoke_hevc
```

### 3. Low-Latency Configuration

For minimal latency with SRS, use this configuration snippet:

```bash
# rtmp.conf with low-latency settings
listen 1935;
chunk_size 128;

vhost __defaultVhost__ {
    # Disable merged-read for lower latency
    publish {
        mr off;
        mr_latency 100;
    }
    
    play {
        # Disable GOP cache for lower latency (may cause startup delay)
        gop_cache off;
        
        # Reduce queue length
        queue_length 5;
        
        # Enable TCP_NODELAY
        tcp_nodelay on;
        
        # Reduce merged-write latency
        mw_latency 100;
        mw_msgs 1;
    }
}
```

**Caveats for low-latency mode:**
- `gop_cache off` means players wait for next I-frame (startup delay)
- Lower `mw_latency` increases CPU usage
- Network jitter may cause more visible artifacts

---

## HEVC Compatibility Notes

### Enhanced RTMP (Standard)

SRS 6.0+ supports HEVC via the [Enhanced RTMP](https://github.com/veovera/enhanced-rtmp) specification:
- Uses FourCC `hvc1` for HEVC
- Supported by FFmpeg 6.0+ without patches
- Supported by OBS 29+

### Domestic HEVC Extension

Some older systems use the domestic HEVC FLV extension (code 12):
- Requires patched FFmpeg for some versions
- SRS supports both formats but prefers Enhanced RTMP
- When using FFmpeg 4.x/5.x, you may need the [runner365 patch](https://github.com/runner365/ffmpeg_rtmp_h265)

**Recommendation:** Use FFmpeg 6.0+ or the `ossrs/srs:encoder` Docker image to avoid compatibility issues.

---

## Environment Variable Overrides

SRS supports environment variable configuration:

```bash
# Override listen port
docker run --rm -it -p 1935:1935 -e SRS_LISTEN=1935 ossrs/srs:6 \
  ./objs/srs -c conf/rtmp.conf

# Enable low latency for all vhosts
docker run --rm -it -p 1935:1935 \
  -e SRS_VHOST_PUBLISH_MR=off \
  -e SRS_VHOST_PLAY_GOP_CACHE=off \
  -e SRS_VHOST_PLAY_MW_LATENCY=100 \
  ossrs/srs:6 \
  ./objs/srs -c conf/rtmp.conf
```

---

## Health Check

```bash
# Check SRS HTTP API (if enabled)
curl http://localhost:8080/api/v1/versions

# Check stream statistics
curl http://localhost:8080/api/v1/streams
```

---

## Missing Server Environment Behavior

If SRS is not available or the Docker container fails to start:

1. **SKIP** - Do not fail mandatory acceptance
2. **Log** - Document the environment issue
3. **Continue** - Proceed with other tests

Example skip condition:
```bash
if ! docker run --rm -p 1935:1935 ossrs/srs:6 true 2>/dev/null; then
    echo "SRS environment unavailable - skipping smoke tests"
    exit 0
fi
```

---

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Connection refused | Check port 1935 is not in use; verify SRS started |
| Stream not found | Verify app/stream name matches; check SRS logs |
| HEVC playback fails | Ensure player supports HEVC (Chrome 105+, ffplay, VLC 3.0+) |
| High latency | Disable gop_cache, reduce mw_latency/mr_latency |
| Artifacts in stream | Check encoder settings; verify network stability |

---

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