cvmmap-streamer/docs/smoke/zlm.md

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