Home

Complete Guide to ZLMediaKit - Open Source Streaming Server Setup and Usage

ZLMediaKit Streaming Server RTSP RTMP WebRTC SRT Live Streaming Video Surveillance
ยท 4 min read
img of Complete Guide to ZLMediaKit - Open Source Streaming Server Setup and Usage

What is ZLMediaKit?

ZLMediaKit is a high-performance production-grade streaming media server framework developed in C++11. It supports multiple mainstream streaming protocols and can be used as a streaming server for live streaming, video surveillance, video conferencing, and other applications.

Core Features

  • ๐Ÿš€ High Performance - Supports 100K+ players, 100Gb/s level IO bandwidth
  • ๐Ÿ”„ Multi-Protocol Support - RTSP/RTMP/HLS/HTTP-FLV/WebRTC etc.
  • ๐ŸŒŸ Cross-Platform - Supports Linux/macOS/iOS/Android/Windows
  • ๐Ÿ”’ Secure & Reliable - Supports push/pull authentication, HTTPS encryption
  • ๐ŸŽฏ Low Latency - Under 500ms, can reach as low as 100ms
  • ๐ŸŽฅ Codec Support - H265/H264/AAC/G711/OPUS

Supported Protocols

Main Protocol Support

ProtocolPushPullFeatures
RTSPโœ“โœ“Low latency, supports TCP/UDP
RTMPโœ“โœ“Widely used, relatively low latency
WebRTCโœ“โœ“Ultra-low latency, supports P2P
HLS-โœ“Good compatibility, higher latency
HTTP-FLV-โœ“Good compatibility, lower latency
SRTโœ“โœ“Anti-packet loss, suitable for public network transmission
RTPโœ“โœ“Supports RTP/UDP

Quick Start

Get the Program

ZLMediaKit provides pre-compiled versions for multiple platforms, available at:

Tips:

  1. If you need the latest version, you can compile it yourself
  2. For compilation methods, please refer to official documentation

Download Summary: https://github.com/ZLMediaKit/ZLMediaKit/issues/483

Windows Version

https://github.com/ZLMediaKit/ZLMediaKit/actions/runs/11970177032/artifacts/2223468517

Linux Version

https://github.com/ZLMediaKit/ZLMediaKit/actions/runs/11970177030/artifacts/2223503747

macOS Version

https://github.com/ZLMediaKit/ZLMediaKit/actions/runs/11970177053/artifacts/2223498187

URL Rules

URL Components

Taking rtsp://somedomain.com:554/live/0?token=abcdefg&field=value as an example, the URL contains:

  • Protocol(scheme) : rtsp protocol, default port 554
  • Virtual host(vhost) : somedomain.com, can be domain or IP
  • Server port(port) : 554, uses protocol default if not specified
  • Application name(app) : live
  • Stream ID(streamid) : 0
  • Parameters(args) : token=abcdefg&field=value

Media Source Types

ZLMediaKit supports 5 types of media sources:

  • RtspMediaSource : Supports rtsp play/push, webrtc play/push
  • RtmpMediaSource : Supports rtmp push/play, http-flv play, ws-flv play
  • HlsMediaSource : Supports hls play
  • TSMediaSource : Supports http-ts play, ws-ts play
  • FMP4MediaSource : Supports http-fmp4 play, ws-fmp4 play

Playback URL Examples

For a RTSP media source with:

  • Protocol: rtsp
  • Virtual host: somedomain.com
  • Application name: live
  • Stream ID: 0

It can be accessed via:

    # RTSP Playback
rtsp://somedomain.com/live/0
rtsps://somedomain.com/live/0
rtsp://127.0.0.1/live/0?vhost=somedomain.com

# RTMP Playback
rtmp://somedomain.com/live/0
rtmps://somedomain.com/live/0

# HTTP-FLV Playback
http://somedomain.com/live/0.live.flv
https://somedomain.com/live/0.live.flv

# WebSocket-FLV Playback
ws://somedomain.com/live/0.live.flv
wss://somedomain.com/live/0.live.flv

# HLS Playback
http://somedomain.com/live/0/hls.m3u8
https://somedomain.com/live/0/hls.m3u8

# HTTP-TS Playback
http://somedomain.com/live/0.live.ts
https://somedomain.com/live/0.live.ts

# WebSocket-TS Playback
ws://somedomain.com/live/0.live.ts
wss://somedomain.com/live/0.live.ts

# HTTP-FMP4 Playback
http://somedomain.com/live/0.live.mp4
https://somedomain.com/live/0.live.mp4

# WebSocket-FMP4 Playback
ws://somedomain.com/live/0.live.mp4
wss://somedomain.com/live/0.live.mp4

VOD URL Rules

ZLMediaKit supports MP4 video on demand with default application name record :

    # HTTP VOD (Recommended)
http://somedomain.com/record/video.mp4

# RTSP VOD
rtsp://somedomain.com/record/video.mp4

# RTMP VOD
rtmp://somedomain.com/record/video.mp4

# HTTP-FLV VOD
http://somedomain.com/record/video.mp4.live.flv

# HTTP-TS VOD
http://somedomain.com/record/video.mp4.live.ts

# HTTP-FMP4 VOD
http://somedomain.com/record/video.mp4.live.mp4

URL Parameters

  • String after question mark in URL is recognized as parameters
  • Parameter vhost is built-in supported virtual host parameter
  • URL parameters can be used for push/pull authentication
  • Parameters will be submitted to business server when triggering hook api

Push Stream Testing

1. RTSP Push

    # H264 Encoding Push
ffmpeg -re -i test.mp4 -vcodec h264 -acodec aac -f rtsp -rtsp_transport tcp rtsp://127.0.0.1/live/test

# H265 Encoding Push
ffmpeg -re -i test.mp4 -vcodec h265 -acodec aac -f rtsp -rtsp_transport tcp rtsp://127.0.0.1/live/test

2. RTMP Push

    # H264 Push
ffmpeg -re -i test.mp4 -vcodec h264 -acodec aac -f flv rtmp://127.0.0.1/live/test

# OBS Push URL
rtmp://127.0.0.1/live/test

3. RTP Push (Supports RTP/UDP)

    # h264 Push
ffmpeg -re -i test.mp4 -vcodec h264 -acodec aac -f rtp_mpegts rtp://127.0.0.1:10000
# h265 Push
ffmpeg -re -i test.mp4 -vcodec h265 -acodec aac -f rtp_mpegts rtp://127.0.0.1:10000

4. SRT Push

    # OBS Push
srt://192.168.1.105:9000?streamid=#!::r=live/test,m=publish

# FFmpeg Push
ffmpeg -re -stream_loop -1 -i test.ts -c:v copy -c:a copy -f mpegts srt://192.168.1.105:9000?streamid=#!::r=live/test,m=publish

Pull Stream Playback

RTSP Pull

    ffplay rtsp://127.0.0.1/live/test

RTMP Pull

    ffplay rtmp://127.0.0.1/live/test

SRT Pull

    # FFplay Pull
ffplay -i srt://192.168.1.105:9000?streamid=#!::r=live/test

# VLC Pull
# 1. Set streamid to #!::r=live/test in SRT output settings
# 2. Enter address srt://192.168.1.105:9000

WebRTC Pull

WebRTC supports WHIP/WHEP standard, accessible via:

Push URL

https://zlmediakit.com/index/api/whip?app=live&stream=test

Pull URL

https://zlmediakit.com/index/api/whep?app=live&stream=test

Advanced Features

1. Push Authentication

Implement push authentication through configuration file and Web Hook:

    {
  "api": {
    "secret": "035c73f7-bb6b-4889-a715-d9eb2d1925cc",
    "hooks": [
      "http://127.0.0.1:8080/index/hook"
    ]
  }
}

2. On-Demand Pull

Support automatic pull stream closure when no viewers, saving resources:

    {
  "general": {
    "streamNoneReaderDelayMS": 20000
  }
}

3. Cluster Deployment

Support edge cluster mode deployment for load balancing:

    {
  "cluster": {
    "enable": true,
    "origin_url": "rtmp://master.com/live/stream_id"
  }
}

Container Deployment

ZLMediaKit provides official Docker image for quick deployment:

    # Pull latest image
docker pull zlmediakit/zlmediakit:master

# Start container
docker run -id \
  -p 1935:1935 \  # RTMP port
  -p 8080:80 \    # HTTP port
  -p 8443:443 \   # HTTPS port
  -p 8554:554 \   # RTSP port
  -p 10000:10000 \     # RTP port
  -p 10000:10000/udp \ # RTP UDP port
  -p 8000:8000/udp \   # RTSP UDP port
  -p 9000:9000/udp \   # SRT port
  zlmediakit/zlmediakit:master

Default Ports

ZLMediaKit opens these ports by default:

PortProtocolUsage
554TCPRTSP push/pull
1935TCPRTMP push/pull
80TCPHTTP access(WebAPI/HTTP-FLV/HLS)
443TCPHTTPS access
8000UDPRTSP UDP push/pull
9000UDPSRT push/pull
10000TCP/UDPRTP push/pull

Tips:

  1. Port mapping required for container external access
  2. Default ports can be modified via configuration file
  3. UDP ports recommended to be open to avoid protocol issues

Configuration Persistence

For configuration and data persistence, mount these directories:

    docker run -id \
  -v /your/config:/opt/media/conf \  # Configuration directory
  -v /your/logs:/opt/media/log \     # Log directory
  -v /your/media:/opt/media/www \    # Media directory
  ... # Other port mappings
  zlmediakit/zlmediakit:master