xiu

中文文档

Xiu is a simple,high performance and secure live media server written in pure Rust, it now supports popular live protocols like RTMP[cluster]/RTSP/WebRTC[Whip/Whep]/HLS/HTTP-FLV.

Features

• Support multiple platforms(Linux/MacOS/Windows).

• Support RTMP.

  • Support publishing or subscribing H.264/AAC streams.
  • Support GOP cache which can be configured in the configuration file.
  • Support protocol conversion from RTMP to HTTP-FLV/HLS.
  • Support cluster.

• Support RTSP.

  • Support publishing or subscribing H.265/H.264/AAC stream over both TCP(Interleaved) and UDP.
  • Support protocol conversion from RTSP to RTMP/HLS/HTTP-FLV.

• Support WebRTC(Whip/Whep).

  • Support publishing rtc stream using Whip.
  • Support subscribing rtc stream using Whep.

• Support HTTP-FLV/HLS protocols(Transferred from RTMP/RTSP).

• Support configuring the service using command line or a configuration file.

• Support HTTP API/Notifications.

  • Support querying stream information.
  • Support notification of stream status.

• Support token authentications.

• Support recording live streams into HLS files(m3u8+ts).

Preparation

Install Rust and Cargo

Document

Install and run

There are two ways to install xiu :

• Using cargo to install

• Building from source

Install using cargo

Issue the following command to install xiu:

cargo install xiu

Start the service with the following command to get help:

xiu -h
A secure and easy to use live media server, hope you love it!!!

Usage: xiu [OPTIONS] 

Options:
  -c, --config <path>   Specify the xiu server configuration file path.
  -r, --rtmp <port>     Specify the RTMP listening port(e.g.:1935).
  -t, --rtsp <port>     Specify the rtsp listening port.(e.g.:5544).
  -w, --webrtc <port>   Specify the whip/whep listening port.(e.g.:8900).
  -f, --httpflv <port>  Specify the HTTP-FLV listening port(e.g.:8080).
  -s, --hls <port>      Specify the HLS listening port(e.g.:8081).
  -l, --log <level>     Specify the log level. [possible values: trace, debug, info, warn, error, debug]
  -h, --help            Print help.
  -V, --version         Print version.

Build from souce

Clone Xiu

git clone https://github.com/harlanc/xiu.git

use master branch

Build

We use makefile to build xiu and revelant libraries.

• Using make local to build local source codes:

    make local && make build
  

• Using make online to pull the online crates codes and build:

    make online && make build 
  

Run

cd ./xiu/target/release or ./xiu/target/debug
./xiu -h

CLI

Instructions

You can use command line to configure the xiu server easily. You can specify to configure xiu using configuration file or from the command lines.

Configure using file

xiu -c configuration_file_path

Configure using command line

xiu -r 1935 -t 5544 -f 8080 -s 8081 -l info

How to Configure the configuration file

RTMP

[rtmp]
enabled = true
port = 1935

# pull streams from other server node.
[rtmp.pull]
enabled = false
address = "192.168.0.1"
port = 1935

# push streams to other server node.
[[rtmp.push]]
enabled = true
address = "localhost"
port = 1936
[[rtmp.push]]
enabled = true
address = "192.168.0.3"
port = 1935

RTSP

[rtsp]
enabled = false
port = 5544

WebRTC(Whip/Whep)

[webrtc]
enabled = false
port = 8900

HTTPFLV

[httpflv]
# true or false to enable or disable the feature
enabled = true
# listening port
port = 8080

HLS

[hls]
# true or false to enable or disable the feature
enabled = true
# listening port
port = 8081
# need record the live stream or not
need_record = true

Log

[log]
level = "info"
[log.file]
# write log to file or not（Writing logs to file or console cannot be satisfied at the same time）.
enabled = true
# set the rotate
rotate = "hour" #[day,hour,minute]
# set the path where the logs are saved
path = "./logs"

Configuration examples

I edit some configuration files under the following path which can be used directly:

xiu/application/xiu/src/config

It contains the following 4 files:

config_rtmp.toml //enable rtmp only
config_rtmp_hls.toml //enable rtmp and hls
config_rtmp_httpflv.toml //enable rtmp and httpflv
config_rtmp_httpflv_hls.toml //enable all the 3 protocols

Scenarios

Push

Push RTMP

You can use two ways:

• Use OBS to push a live rtmp stream

• Or use FFmpeg to push a rtmp stream:

    ffmpeg -re -stream_loop -1 -i test.mp4 -c:a copy -c:v copy -f flv -flvflags no_duration_filesize rtmp://127.0.0.1:1935/live/test
  

Push RTSP

• Over TCP(Interleaved mode)

    ffmpeg -re -stream_loop -1  -i test.mp4 -c:v copy  -c:a copy  -rtsp_transport tcp   -f rtsp rtsp://127.0.0.1:5544/live/test
  

• Over UDP

    ffmpeg -re -stream_loop -1  -i test.mp4 -c:v copy  -c:a copy     -f rtsp rtsp://127.0.0.1:5544/live/test
  

Push RTC(Whip)

Now OBS (version 3.0 or above) can support whip output. The configurations are as follows:

Play

Use ffplay to play the rtmp/rtsp/httpflv/hls live stream:

ffplay -i rtmp://localhost:1935/live/test
ffplay -i rtsp://127.0.0.1:5544/live/test
ffplay -rtsp_transport tcp -i rtsp://127.0.0.1:5544/live/test
ffplay -i http://localhost:8080/live/test.flv
ffplay -i http://localhost:8081/live/test/test.m3u8

• How to play WebRTC stream*(Whep)

  1. Copy the files under xiu/protocol/webrtc/src/clients/ folder to the same level directory of the binary file xiu.
  2. Open the address http://localhost:8900 in the browser.
  3. Enter the app name and stream name corresponding to the OBS whip publish address.
  4. Click Start WHEP(After OBS publish) to play the RTC stream.

Relay - Static push

The configuration files are as follows:

The configuration file of Service 1 named config.toml:

[rtmp]
enabled = true
port = 1935
[[rtmp.push]]
enabled = true
address = "localhost"
port = 1936

The configuration file of Service 2 named config_push.toml:

[rtmp]
enabled = true
port = 1936

Run the 2 services:

./xiu config.toml
./xiu config_push.toml

Use the above methods to push rtmp live stream to service 1, then the stream can be pushed to service 2 automatically, you can play the same live stream from both the two services:

ffplay -i rtmp://localhost:1935/live/test
ffplay -i rtmp://localhost:1936/live/test

Relay - Static pull

The configuration file are as follows:

The configuration file of Service 1 named config.toml:

[rtmp]
enabled = true
port = 1935

The configuration file of Service 2 named config_pull.toml:

[rtmp]
enabled = true
port = 1936
[rtmp.pull]
enabled = false
address = "localhost"
port = 1935

Run the 2 services:

./xiu config.toml
./xiu config_pull.toml

Use the above methods to push live stream to service 1, when you play the stream from serivce 2, it will pull the stream from service 1:

ffplay -i rtmp://localhost:1935/live/test
ffplay -i rtmp://localhost:1936/live/test

Star History

Thanks

• media_server

Others

Open issues if you have any problems. Star and pull requests are welcomed. Your stars can make this project go faster and further.