README.md
1<p align="center" width="100%">
2 <img width="38%" src="https://user-images.githubusercontent.com/10411078/149529602-7dcbaf26-55cd-4588-8989-206b76d32f07.png">
3</p>
4
5
6[](https://crates.io/crates/xiu)
7[](https://crates.io/crates/xiu)
8[](https://crates.io/crates/rtmp)
9[](https://crates.io/crates/rtmp)
10[](https://crates.io/crates/xrtsp)
11[](https://crates.io/crates/xrtsp)
12[](https://crates.io/crates/xwebrtc)
13[](https://crates.io/crates/xwebrtc)
14[](https://crates.io/crates/httpflv)
15[](https://crates.io/crates/httpflv)
16[](https://crates.io/crates/hls)
17[](https://crates.io/crates/hls)
18[](https://crates.io/crates/xflv)
19[](https://crates.io/crates/xflv)
20[](https://crates.io/crates/xmpegts)
21[](https://crates.io/crates/xmpegts)
22[](https://app.travis-ci.com/github/harlanc/xiu)
23[](https://discord.gg/gS5wBRtpcB)
24
25
26
27
28
29
30
31[中文文档](https://github.com/harlanc/xiu/blob/master/README_CN.md)
32
33Xiu 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.
34
35## Features
36- [x] Support multiple platforms(Linux/MacOS/Windows).
37- [x] Support RTMP.
38 - [x] Support publishing or subscribing H.264/AAC streams.
39 - [x] Support GOP cache which can be configured in the configuration file.
40 - [x] Support protocol conversion from RTMP to HTTP-FLV/HLS.
41 - [x] Support cluster.
42- [x] Support RTSP.
43 - [x] Support publishing or subscribing H.265/H.264/AAC stream over both TCP(Interleaved) and UDP.
44 - [x] Support protocol conversion from RTSP to RTMP/HLS/HTTP-FLV.
45- [x] Support WebRTC(Whip/Whep).
46 - [x] Support publishing rtc stream using Whip.
47 - [x] Support subscribing rtc stream using Whep.
48- [x] Support HTTP-FLV/HLS protocols(Transferred from RTMP/RTSP).
49- [x] Support configuring the service using command line or a configuration file.
50- [x] Support HTTP API/Notifications.
51 - [x] Support querying stream information.
52 - [x] Support notification of stream status.
53- [x] Support token authentications.
54- [x] Support recording live streams into HLS files(m3u8+ts).
55
56
57## Preparation
58#### Install Rust and Cargo
59
60[Document](https://doc.rust-lang.org/cargo/getting-started/installation.html)
61
62## Install and run
63
64There are two ways to install xiu :
65
66 - Using cargo to install
67 - Building from source
68
69
70### Install using cargo
71
72Issue the following command to install xiu:
73
74 cargo install xiu
75Start the service with the following command to get help:
76
77 xiu -h
78 A secure and easy to use live media server, hope you love it!!!
79
80 Usage: xiu [OPTIONS]
81
82 Options:
83 -c, --config <path> Specify the xiu server configuration file path.
84 -r, --rtmp <port> Specify the RTMP listening port(e.g.:1935).
85 -t, --rtsp <port> Specify the rtsp listening port.(e.g.:554).
86 -w, --webrtc <port> Specify the whip/whep listening port.(e.g.:8900).
87 -f, --httpflv <port> Specify the HTTP-FLV listening port(e.g.:8080).
88 -s, --hls <port> Specify the HLS listening port(e.g.:8081).
89 -l, --log <level> Specify the log level. [possible values: trace, debug, info, warn, error, debug]
90 -h, --help Print help.
91 -V, --version Print version.
92
93### Build from souce
94
95#### Clone Xiu
96
97 git clone https://github.com/harlanc/xiu.git
98
99use master branch
100
101#### Build
102
103We use makefile to build xiu and revelant libraries.
104
105- Using make local to build local source codes:
106
107 make local && make build
108- Using make online to pull the online crates codes and build:
109
110 make online && make build
111
112#### Run
113
114 cd ./xiu/target/release or ./xiu/target/debug
115 ./xiu -h
116
117## CLI
118
119#### Instructions
120
121You can use command line to configure the xiu server easily. You can specify to configure xiu using configuration file or from the command lines.
122
123##### Configure using file
124
125 xiu -c configuration_file_path
126
127##### Configure using command line
128
129 xiu -r 1935 -t 5544 -f 8080 -s 8081 -l info
130
131
132#### How to Configure the configuration file
133
134##### RTMP
135 [rtmp]
136 enabled = true
137 port = 1935
138
139 # pull streams from other server node.
140 [rtmp.pull]
141 enabled = false
142 address = "192.168.0.1"
143 port = 1935
144
145 # push streams to other server node.
146 [[rtmp.push]]
147 enabled = true
148 address = "localhost"
149 port = 1936
150 [[rtmp.push]]
151 enabled = true
152 address = "192.168.0.3"
153 port = 1935
154
155
156##### RTSP
157 [rtsp]
158 enabled = false
159 port = 5544
160
161##### WebRTC(Whip/Whep)
162 [webrtc]
163 enabled = false
164 port = 8900
165
166##### HTTPFLV
167
168 [httpflv]
169 # true or false to enable or disable the feature
170 enabled = true
171 # listening port
172 port = 8081
173
174##### HLS
175 [hls]
176 # true or false to enable or disable the feature
177 enabled = true
178 # listening port
179 port = 8080
180 # need record the live stream or not
181 need_record = true
182
183##### Log
184
185 [log]
186 level = "info"
187 [log.file]
188 # write log to file or not（Writing logs to file or console cannot be satisfied at the same time）.
189 enabled = true
190 # set the rotate
191 rotate = "hour" #[day,hour,minute]
192 # set the path where the logs are saved
193 path = "./logs"
194
195### Configuration examples
196
197I edit some configuration files under the following path which can be used directly:
198
199 xiu/application/xiu/src/config
200
201It contains the following 4 files:
202
203 config_rtmp.toml //enable rtmp only
204 config_rtmp_hls.toml //enable rtmp and hls
205 config_rtmp_httpflv.toml //enable rtmp and httpflv
206 config_rtmp_httpflv_hls.toml //enable all the 3 protocols
207
208
209
210
211## Scenarios
212
213##### Push
214
215###### Push RTMP
216
217You can use two ways:
218
219- Use OBS to push a live rtmp stream
220- Or use FFmpeg to push a rtmp stream:
221
222 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
223
224###### Push RTSP
225
226- Over TCP(Interleaved mode)
227
228 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
229
230- Over UDP
231
232 ffmpeg -re -stream_loop -1 -i test.mp4 -c:v copy -c:a copy -f rtsp rtsp://127.0.0.1:5544/live/test
233
234###### Push RTC(Whip)
235
236Now OBS (version 3.0 or above) can support whip output. The configurations are as follows:
237
238
239
240
241##### Play
242
243Use ffplay to play the rtmp/rtsp/httpflv/hls live stream:
244
245 ffplay -i rtmp://localhost:1935/live/test
246 ffplay -i rtsp://127.0.0.1:5544/live/test
247 ffplay -rtsp_transport tcp -i rtsp://127.0.0.1:5544/live/test
248 ffplay -i http://localhost:8081/live/test.flv
249 ffplay -i http://localhost:8080/live/test/test.m3u8
250
251- How to play WebRTC stream*(Whep)
252
253 1. Copy the files under xiu/protocol/webrtc/src/clients/ folder to the same level directory of the binary file xiu.
254 2. Open the address http://localhost:8900 in the browser.
255 3. Enter the app name and stream name corresponding to the OBS whip publish address.
256 4. Click Start WHEP(After OBS publish) to play the RTC stream.
257
258
259
260##### Relay - Static push
261
262The configuration files are as follows:
263
264The configuration file of Service 1 named config.toml:
265
266 [rtmp]
267 enabled = true
268 port = 1935
269 [[rtmp.push]]
270 enabled = true
271 address = "localhost"
272 port = 1936
273
274The configuration file of Service 2 named config_push.toml:
275
276 [rtmp]
277 enabled = true
278 port = 1936
279
280Run the 2 services:
281
282 ./xiu config.toml
283 ./xiu config_push.toml
284
285
286Use 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:
287
288 ffplay -i rtmp://localhost:1935/live/test
289 ffplay -i rtmp://localhost:1936/live/test
290
291
292
293##### Relay - Static pull
294
295The configuration file are as follows:
296
297The configuration file of Service 1 named config.toml:
298
299 [rtmp]
300 enabled = true
301 port = 1935
302
303
304The configuration file of Service 2 named config_pull.toml:
305
306 [rtmp]
307 enabled = true
308 port = 1936
309 [rtmp.pull]
310 enabled = false
311 address = "localhost"
312 port = 1935
313
314Run the 2 services:
315
316 ./xiu config.toml
317 ./xiu config_pull.toml
318
319Use 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:
320
321 ffplay -i rtmp://localhost:1935/live/test
322 ffplay -i rtmp://localhost:1936/live/test
323## Star History
324
325[](https://star-history.com/#harlanc/xiu)
326
327
328## Thanks
329
330 - [media_server](https://github.com/ireader/media-server.git)
331
332## Others
333
334Open issues if you have any problems. Star and pull requests are welcomed. Your stars can make this project go faster and further.
335
336
README_CN.md
1<p align="center" width="100%">
2 <img width="38%" src="https://user-images.githubusercontent.com/10411078/149529602-7dcbaf26-55cd-4588-8989-206b76d32f07.png">
3</p>
4
5
6[](https://crates.io/crates/xiu)
7[](https://crates.io/crates/xiu)
8[](https://crates.io/crates/rtmp)
9[](https://crates.io/crates/rtmp)
10[](https://crates.io/crates/xrtsp)
11[](https://crates.io/crates/xrtsp)
12[](https://crates.io/crates/xwebrtc)
13[](https://crates.io/crates/xwebrtc)
14[](https://crates.io/crates/httpflv)
15[](https://crates.io/crates/httpflv)
16[](https://crates.io/crates/hls)
17[](https://crates.io/crates/hls)
18[](https://crates.io/crates/xflv)
19[](https://crates.io/crates/xflv)
20[](https://crates.io/crates/xmpegts)
21[](https://crates.io/crates/xmpegts)
22[](https://app.travis-ci.com/github/harlanc/xiu)
23[](https://discord.gg/gS5wBRtpcB)
24
25
26
27XIU是用纯Rust开发的一款简单和安全的流媒体服务器，目前支持的流媒体协议包括RTMP[cluster]/RTSP/WebRTC[Whip/Whep]/HLS/HTTPFLV。
28
29## 功能
30
31- [x] 支持多平台（Linux/Mac/Windows）
32- [x] 支持RTMP
33 - [x] 支持发布和订阅H264/AAC 直播流；
34 - [x] 支持秒开（Gop cache）；
35 - [x] 支持转换到HLS/HTTP-FLV协议；
36 - [x] 支持部署集群；
37- [x] 支持RTSP
38 - [x] 支持通过TCP（Interleaved）和UDP发布或订阅H.265/H.264/AAC流；
39 - [x] 支持转换到RTMP/HLS/HTTP-FLV协议；
40- [x] 支持WebRTC（Whip/Whep）
41 - [x] 支持使用Whip发布rtc流；
42 - [x] 支持使用Whep订阅rtc流；
43- [x] 支持订阅HLS/HTTPFLV直播流
44- [x] 支持命令行或者配置文件配置服务
45- [x] 支持HTTP API/notify
46 - [x] 支持查询流信息；
47 - [x] 支持流事件通知；
48- [x] 支持token鉴权
49- [x] 支持把直播流录制成HLS协议(m3u8+ts)文件
50
51## 准备工作
52#### 安装 Rust and Cargo
53
54
55[Document](https://doc.rust-lang.org/cargo/getting-started/installation.html)
56
57## 安装和运行
58
59有两种方式来安装xiu：
60
61 - 直接用cargo来安装
62 - 源码编译安装
63
64
65### 用cargo命令安装
66
67执行下面的命令来安装xiu:
68
69 cargo install xiu
70
71执行下面的命令来查看帮助信息:
72
73 xiu -h
74
75 A secure and easy to use live media server, hope you love it!!!
76
77 Usage: xiu [OPTIONS]
78
79 Options:
80 -c, --config <path> Specify the xiu server configuration file path.
81 -r, --rtmp <port> Specify the RTMP listening port(e.g.:1935).
82 -t, --rtsp <port> Specify the rtsp listening port.(e.g.:554).
83 -w, --webrtc <port> Specify the whip/whep listening port.(e.g.:8900).
84 -f, --httpflv <port> Specify the HTTP-FLV listening port(e.g.:8080).
85 -s, --hls <port> Specify the HLS listening port(e.g.:8081).
86 -l, --log <level> Specify the log level. [possible values: trace, debug, info, warn, error, debug]
87 -h, --help Print help
88 -V, --version Print version
89
90### 源码编译安装
91
92#### 克隆 Xiu
93
94 git clone https://github.com/harlanc/xiu.git
95 Checkout最新发布的版本代码：
96
97 git checkout tags/<tag_name> -b <branch_name>
98
99#### 编译
100为了编译方便，把cargo相关的编译命令封装到了makefle中，使用下面的命令进行编译：
101
102- 使用make local编译本地代码：
103
104 make local && make build
105- 使用make online拉取线上crates仓库代码进行编译
106
107 make online && make build
108
109
110#### 运行
111
112 cd ./xiu/target/release or ./xiu/target/debug
113 ./xiu -h
114
115## CLI
116
117#### 说明
118
119可以使用配置文件或者在命令行对服务进行配置。比如：
120
121##### 通过配置文件进行配置
122
123 xiu -c configuration_file_path
124
125##### 通过命令行
126
127 xiu -r 1935 -t 5544 -f 8080 -s 8081 -l info
128
129
130#### 配置文件说明
131
132##### RTMP
133 [rtmp]
134 enabled = true
135 port = 1935
136
137 # pull streams from other server node.
138 [rtmp.pull]
139 enabled = false
140 address = "192.168.0.1"
141 port = 1935
142
143 # push streams to other server node.
144 [[rtmp.push]]
145 enabled = true
146 address = "localhost"
147 port = 1936
148 [[rtmp.push]]
149 enabled = true
150 address = "192.168.0.3"
151 port = 1935
152
153##### RTSP
154 [rtsp]
155 enabled = false
156 port = 5544
157
158##### HTTPFLV
159
160 [httpflv]
161 # true or false to enable or disable the feature
162 enabled = true
163 # listening port
164 port = 8081
165
166##### HLS
167 [hls]
168 # true or false to enable or disable the feature
169 enabled = true
170 # listening port
171 port = 8080
172 # need record the live stream or not
173 need_record = true
174
175##### Log
176
177 [log]
178 level = "info"
179 [log.file]
180 # 打开或者关闭输出日志到文件（注意：输出日志到控制台和文件只能2选1）.
181 enabled = true
182 # set the rotate
183 rotate = "hour" #[day,hour,minute]
184 # set the path where the logs are saved
185 path = "./logs"
186
187### 一些配置的例子
188
189有一些现成的配置文件放在下面的目录：
190
191 xiu/application/xiu/src/config
192
193包括4个配置文件：
194
195 config_rtmp.toml //只打开rtmp
196 config_rtmp_hls.toml //打开 rtmp 和 hls
197 config_rtmp_httpflv.toml //打开 rtmp 和 httpflv
198 config_rtmp_httpflv_hls.toml //打开所有的 3 个协议
199
200
201
202## 应用场景
203
204##### 推流
205
206###### RTMP推流
207
208可以用任何推流软件或者命令工具来推RTMP流，比如使用OBS或者用ffmpeg命令行：
209
210 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
211
212###### RTSP推流
213
214- 基于TCP推流(Interleaved mode)
215
216 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
217
218- 基于UDP推流
219
220 ffmpeg -re -stream_loop -1 -i test.mp4 -c:v copy -c:a copy -f rtsp rtsp://127.0.0.1:5544/live/test
221
222###### 使用Whip协议推送RTC流
223
224OBS（3.0或者更高版本）支持whip协议，按照如下配置推流：
225
226
227
228##### 播放
229
230使用ffplay来播放 rtmp/rtsp/httpflv/hls协议的直播流:
231
232 ffplay -i rtmp://localhost:1935/live/test
233 ffplay -i rtsp://127.0.0.1:5544/live/test
234 ffplay -rtsp_transport tcp -i rtsp://127.0.0.1:5544/live/test
235 ffplay -i http://localhost:8081/live/test.flv
236 ffplay -i http://localhost:8080/live/test/test.m3u8
237
238- 如何播放RTC流（使用Whep协议）
239
240 1. 把xiu/protocol/webrtc/src/clients/目录下的文件拷贝到xiu可执行文件同级目录下；
241 2. 在浏览器中打开地址：http://localhost:8900；
242 3. 输入和推流地址相对应的app name和stream name；
243 4. 点击Start WHEP进行播放.
244
245
246
247##### 转发 - 静态转推
248
249应用场景为边缘节点的直播流被转推到源站，配置如下：
250
251边缘节点的配置文件config_push.toml:
252
253 [rtmp]
254 enabled = true
255 port = 1935
256 [[rtmp.push]]
257 enabled = true
258 address = "localhost"
259 port = 1936
260
261源站节点的配置文件config.toml:
262
263 [rtmp]
264 enabled = true
265 port = 1936
266
267启动两个服务:
268
269 ./xiu config.toml
270 ./xiu config_push.toml
271
272将一路RTMP直播流推送到边缘节点，此直播流会被自动转推到源站，可以同时播放源站或者边缘节点的直播流：
273
274 ffplay -i rtmp://localhost:1935/live/test
275 ffplay -i rtmp://localhost:1936/live/test
276
277
278
279##### 转发 - 静态回源
280
281应用场景为播放过程中用户从边缘节点拉流，边缘节点无此流，则回源拉流，配置文件如下：
282
283源站节点的配置文件为 config.toml:
284
285 [rtmp]
286 enabled = true
287 port = 1935
288
289
290边缘节点的配置文件为 config_pull.toml:
291
292 [rtmp]
293 enabled = true
294 port = 1936
295 [rtmp.pull]
296 enabled = false
297 address = "localhost"
298 port = 1935
299
300运行两个服务:
301
302 ./xiu config.toml
303 ./xiu config_pull.toml
304
305直接将直播流推送到源站，到边缘节点请求此路直播流，边缘节点会回源拉流，可以同时播放边缘和源站节点上的直播流：
306
307 ffplay -i rtmp://localhost:1935/live/test
308 ffplay -i rtmp://localhost:1936/live/test
309
310## Star History
311
312[](https://star-history.com/#harlanc/xiu)
313
314
315## 鸣谢
316
317 - [media_server](https://github.com/ireader/media-server.git)
318
319## 其它
320
321有任何问题请在issues提问，欢迎star和提pull request。你的关注可以让此项目走的更快更远。
322
323
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}