chore(docs): add downstream task evidence runbook artifacts
This commit consolidates operational documentation and runbooks used to drive task execution and release validation. It includes evidence writeups, caveat/matrix references, release gate outputs, plan/notepad context, and generated SDP fixture needed for reproducible downstream review, keeping them separate from code and generated artifacts. This separation lets runtime and harness changes be reviewed as implementation units while process documentation remains in an independent governance/history commit. Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This commit is contained in:
@@ -0,0 +1,207 @@
|
||||
# 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)
|
||||
@@ -0,0 +1,233 @@
|
||||
# ZLMediaKit Smoke Test Profile
|
||||
|
||||
## Status
|
||||
|
||||
**OPTIONAL / NON-BLOCKING**
|
||||
|
||||
This document provides optional interoperability checks for ZLMediaKit. These checks are not mandatory for acceptance. If the ZLMediaKit environment is unavailable, skip these tests without failing the mandatory acceptance criteria.
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
Validate RTMP streaming interoperability with ZLMediaKit, specifically for:
|
||||
- RTMP H.264 publishing and playback
|
||||
- Enhanced RTMP HEVC (H.265) support
|
||||
- Low-latency streaming configurations
|
||||
- HTTP-FLV, HTTP-TS, and WebRTC protocols
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Docker (recommended) or ZLMediaKit built from source
|
||||
- FFmpeg or the project streaming binary
|
||||
- Optional: ffplay, VLC for playback verification
|
||||
|
||||
---
|
||||
|
||||
## Quick Start (Docker)
|
||||
|
||||
```bash
|
||||
# Run ZLMediaKit with default configuration
|
||||
docker run --rm -it -p 1935:1935 -p 8080:80 -p 8554:554 \
|
||||
-p 10000:10000 -p 30000-30500:30000-30500/udp \
|
||||
zlmediakit/zlmediakit:master
|
||||
|
||||
# With custom config (mount your config.ini)
|
||||
docker run --rm -it -p 1935:1935 -p 8080:80 \
|
||||
-v $(pwd)/config.ini:/opt/media/conf/config.ini \
|
||||
zlmediakit/zlmediakit:master
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Smoke Commands
|
||||
|
||||
### 1. Basic RTMP H.264 Stream Test
|
||||
|
||||
```bash
|
||||
# Publish test stream to ZLMediaKit
|
||||
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 via RTMP
|
||||
ffplay rtmp://localhost/live/smoke_test
|
||||
|
||||
# Playback via HTTP-FLV
|
||||
ffplay http://localhost:8080/live/smoke_test.live.flv
|
||||
|
||||
# Playback via HTTP-TS
|
||||
ffplay http://localhost:8080/live/smoke_test.live.ts
|
||||
```
|
||||
|
||||
### 2. Enhanced RTMP HEVC (H.265) Test
|
||||
|
||||
**Prerequisites:**
|
||||
- ZLMediaKit with HEVC support enabled in config
|
||||
- FFmpeg 6.0+ with libx265 and enhanced RTMP support
|
||||
|
||||
**Configuration in config.ini:**
|
||||
```ini
|
||||
[rtmp]
|
||||
port=1935
|
||||
# h265 rtmp packing: 1 = Enhanced RTMP (standard), 0 = Domestic extension
|
||||
enhanced=1
|
||||
|
||||
[protocol]
|
||||
enable_rtmp=1
|
||||
```
|
||||
|
||||
```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 via various protocols
|
||||
ffplay rtmp://localhost/live/smoke_hevc
|
||||
ffplay http://localhost:8080/live/smoke_hevc.live.flv
|
||||
ffplay http://localhost:8080/live/smoke_hevc.live.ts
|
||||
```
|
||||
|
||||
### 3. Low-Latency Configuration
|
||||
|
||||
For minimal latency with ZLMediaKit, modify config.ini:
|
||||
|
||||
```ini
|
||||
[general]
|
||||
# Disable merge write (0 = immediate write)
|
||||
mergeWriteMS=0
|
||||
|
||||
[protocol]
|
||||
# Frame timestamp override: 0=source, 1=system, 2=relative
|
||||
modify_stamp=0
|
||||
|
||||
# Protocol demand mode (1 = generate on demand, reduces latency)
|
||||
rtmp_demand=1
|
||||
flv_demand=1
|
||||
ts_demand=1
|
||||
|
||||
[rtmp]
|
||||
handshakeSecond=5
|
||||
keepAliveSecond=5
|
||||
|
||||
[rtp]
|
||||
# Low latency mode (WARNING: may cause artifacts with H.264 multi-slice)
|
||||
lowLatency=1
|
||||
```
|
||||
|
||||
**Caveats for low-latency mode:**
|
||||
- mergeWriteMS=0 disables write buffering (higher CPU, more syscalls)
|
||||
- modify_stamp=0 uses source timestamps (requires stable encoder timing)
|
||||
- *_demand=1 causes first viewer to wait for next GOP
|
||||
- lowLatency=1 in RTP may cause artifacts with certain H.264 streams
|
||||
|
||||
### 4. Stream Proxy Test (Optional)
|
||||
|
||||
ZLMediaKit can proxy streams from other sources:
|
||||
|
||||
```bash
|
||||
# Add stream proxy via HTTP API
|
||||
curl -X POST "http://localhost:8080/index/api/addStreamProxy" \
|
||||
-H "Content-Type: application/x-www-form-urlencoded" \
|
||||
-d "secret=035c73f7-bb6b-4889-a715-d9eb2d1925cc" \
|
||||
-d "vhost=__defaultVhost__" \
|
||||
-d "app=proxy" \
|
||||
-d "stream=test" \
|
||||
-d "url=rtmp://localhost/live/smoke_test"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## HEVC Compatibility Notes
|
||||
|
||||
### Enhanced RTMP vs Domestic Extension
|
||||
|
||||
ZLMediaKit supports both HEVC packing formats via the enhanced config option:
|
||||
|
||||
**Enhanced RTMP (enhanced=1, RECOMMENDED):**
|
||||
- Uses standard FourCC hvc1
|
||||
- Compatible with FFmpeg 6.0+, OBS 29+
|
||||
- SRS 6.0+, ZLMediaKit master
|
||||
|
||||
**Domestic Extension (enhanced=0):**
|
||||
- Uses FLV codec ID 12
|
||||
- Required for some legacy Chinese CDN providers
|
||||
- May need patched FFmpeg for older versions
|
||||
|
||||
### Codec Priority in WebRTC
|
||||
|
||||
When using WebRTC with ZLMediaKit, codec priority can be configured:
|
||||
|
||||
```ini
|
||||
[rtc]
|
||||
# Video codec priority (first = highest)
|
||||
preferredCodecV=H264,H265,AV1,VP9,VP8
|
||||
```
|
||||
|
||||
**Note:** Chrome does not yet support HEVC in WebRTC; Safari does with experimental flags.
|
||||
|
||||
---
|
||||
|
||||
## Health Check
|
||||
|
||||
```bash
|
||||
# Get server statistics
|
||||
curl "http://localhost:8080/index/api/getStatistic?secret=035c73f7-bb6b-4889-a715-d9eb2d1925cc"
|
||||
|
||||
# Get MediaServer list
|
||||
curl "http://localhost:8080/index/api/getMediaList?secret=035c73f7-bb6b-4889-a715-d9eb2d1925cc"
|
||||
|
||||
# Check if stream exists
|
||||
curl "http://localhost:8080/index/api/isMediaOnline?secret=035c73f7-bb6b-4889-a715-d9eb2d1925cc&vhost=__defaultVhost__&app=live&stream=smoke_test&schema=rtmp"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Missing Server Environment Behavior
|
||||
|
||||
If ZLMediaKit 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 zlmediakit/zlmediakit:master true 2>/dev/null; then
|
||||
echo "ZLMediaKit environment unavailable - skipping smoke tests"
|
||||
exit 0
|
||||
fi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| Connection refused | Check port 1935/8080 not in use; verify server started |
|
||||
| Stream not found | Verify app/stream name; check ZLMediaKit logs |
|
||||
| HEVC playback fails | Ensure player supports HEVC; check enhanced setting |
|
||||
| High latency | Disable mergeWriteMS, use modify_stamp=0 |
|
||||
| Artifacts in stream | Disable rtp.lowLatency if H.264 multi-slice |
|
||||
| API returns 401 | Verify secret parameter matches config.ini |
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- [ZLMediaKit GitHub](https://github.com/ZLMediaKit/ZLMediaKit)
|
||||
- [ZLMediaKit Wiki](https://github.com/ZLMediaKit/ZLMediaKit/wiki)
|
||||
- [Enhanced RTMP Specification](https://github.com/veovera/enhanced-rtmp)
|
||||
Reference in New Issue
Block a user