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)

# 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

# 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

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

[rtmp]
port=1935
# h265 rtmp packing: 1 = Enhanced RTMP (standard), 0 = Domestic extension
enhanced=1

[protocol]
enable_rtmp=1

# 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

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

[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:

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

[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

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

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
• ZLMediaKit Wiki
• Enhanced RTMP Specification