ghostream/README.md

135 lines
5.4 KiB
Markdown
Raw Permalink Normal View History

2020-09-23 11:52:12 +00:00
# Ghostream
2020-09-25 13:26:33 +00:00
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
2020-09-28 08:51:20 +00:00
[![PkgGoDev](https://pkg.go.dev/badge/mod/gitlab.crans.org/nounous/ghostream)](https://pkg.go.dev/mod/gitlab.crans.org/nounous/ghostream)
2020-09-28 08:53:10 +00:00
[![Go Report Card](https://goreportcard.com/badge/gitlab.crans.org/nounous/ghostream)](https://goreportcard.com/report/gitlab.crans.org/nounous/ghostream)
2020-10-05 08:34:58 +00:00
[![pipeline status](https://gitlab.crans.org/nounous/ghostream/badges/dev/pipeline.svg)](https://gitlab.crans.org/nounous/ghostream/commits/dev)
[![coverage report](https://gitlab.crans.org/nounous/ghostream/badges/dev/coverage.svg)](https://gitlab.crans.org/nounous/ghostream/-/commits/dev)
2020-10-14 19:44:51 +00:00
[![Docker Cloud Build Status](https://img.shields.io/docker/cloud/build/erdnaxe/ghostream)](https://hub.docker.com/r/erdnaxe/ghostream)
2020-09-23 11:52:12 +00:00
*Boooo!* A simple streaming server with authentication and open-source technologies.
2020-09-25 13:26:33 +00:00
This project was developped at [Cr@ns](https://crans.org/) to stream events.
2020-09-23 11:52:12 +00:00
Features:
- WebRTC playback with a lightweight web interface.
2020-09-29 11:43:49 +00:00
- SRT stream input, supported by FFMpeg, OBS and Gstreamer.
2020-09-23 11:52:12 +00:00
- Low-latency streaming, sub-second with web player.
2020-10-01 21:33:29 +00:00
- Authentication of incoming stream using LDAP server.
2020-09-30 13:07:36 +00:00
- Possibility to forward stream to other streaming servers.
2020-09-23 11:52:12 +00:00
2020-09-28 14:29:24 +00:00
## Installation on Debian/Ubuntu
2020-10-10 22:41:49 +00:00
On Ubuntu 20.10+ or Debian 11+, you can install directly ghostream,
```bash
sudo apt install git golang ffmpeg libsrt1-openssl
go get gitlab.crans.org/nounous/ghostream
```
2020-10-10 22:55:04 +00:00
On Ubuntu 20.04 or Debian Buster, you may manually install libsrt 1.4.1: install [libsrt1-openssl 1.4.1](http://ftp.fr.debian.org/debian/pool/main/s/srt/libsrt1-openssl_1.4.1-5+b1_amd64.deb) then [libsrt-openssl-dev 1.4.1](http://ftp.fr.debian.org/debian/pool/main/s/srt/libsrt-openssl-dev_1.4.1-5+b1_amd64.deb).
2020-10-10 22:41:49 +00:00
For development, you may clone this repository, then `go run main.go`.
2020-09-28 14:29:24 +00:00
2020-09-23 11:52:12 +00:00
## Installation with Docker
An example is given in [docs/docker-compose.yml](docs/docker-compose.yml).
2020-09-23 11:52:12 +00:00
It uses Traefik reverse proxy.
2020-09-27 20:13:51 +00:00
You can also launch the Docker image using,
```
2020-09-27 20:14:35 +00:00
docker build . -t ghostream
2020-09-29 13:31:08 +00:00
docker run -it --rm -p 2112:2112 -p 9710:9710/udp -p 8080:8080 -p 10000-10005:10000-10005/udp ghostream
2020-09-27 20:13:51 +00:00
```
2020-10-09 15:37:32 +00:00
## Configuration
2020-10-14 13:38:03 +00:00
Ghostream can be configured by placing [ghostream.yml](docs/ghostream.example.yml) in `/etc/ghostream/`.
You can overwrite the configuration path with `GHOSTREAM_CONFIG` environnement variable.
You can also overwride any value using environnement variables, e.g. `GHOSTREAM_AUTH_BACKEND=ldap` will change the authentification backend.
2020-10-09 15:37:32 +00:00
2020-09-29 11:36:12 +00:00
## Streaming
As stated by OBS wiki, when streaming you should adapt the latency to `2.5 * (the round-trip time with server, in μs)`.
2020-09-29 11:43:49 +00:00
### With OBS
As OBS uses FFMpeg, you need to have FFMpeg compiled with SRT support. To check if SR is available, run `ffmpeg -protocols | grep srt`.
On Windows and MacOS, OBS comes with his own FFMpeg that will work.
2020-10-04 09:20:25 +00:00
In OBS, go to "Settings" -> "Output" -> "Recording" the select "Output to URL" and change the URL to `srt://127.0.0.1:9710?streamid=demo:demo`.
For container, you may use MPEGTS for now (will change).
2020-09-29 11:43:49 +00:00
2020-09-29 11:36:12 +00:00
### With GStreamer
2020-10-14 08:12:37 +00:00
To stream your X11 screen,
2020-09-29 11:36:12 +00:00
```bash
gst-launch-1.0 ximagesrc startx=0 show-pointer=true use-damage=0 \
! videoconvert \
! x264enc bitrate=32000 tune=zerolatency speed-preset=veryfast byte-stream=true threads=1 key-int-max=15 intra-refresh=true ! video/x-h264, profile=baseline, framerate=30/1 \
! mpegtsmux \
! srtserversink uri=srt://127.0.0.1:9710/ latency=1000000 streamid=demo:demo
2020-09-29 11:36:12 +00:00
```
2020-10-14 08:12:37 +00:00
*This might not work at the moment.*
2020-10-03 16:28:06 +00:00
## Playing stream
### With a web browser and WebRTC
Ghostream expose a web server on `0.0.0.0:8080` by default.
2020-10-03 16:28:42 +00:00
By opening this in a browser, you will be able to get instructions on how to stream, and if you append `/streamname` to the URL, then you will be able to watch the stream named `streamname`.
2020-10-03 16:28:06 +00:00
The web player also integrates a side widget that is configurable.
2020-10-13 17:40:31 +00:00
#### Integrate the player in an iframe
To integrate the player without the side widget, you can append `?nowidget` to the URL.
```HTML
<iframe src="https://example.com/stream_name?nowidget" scrolling="no" allowfullscreen="true" width="1280" height="750.4" frameborder="0"></iframe>
```
The iframe size should be a 16/9 ratio, with additionnal 30.4px for the control bar.
2020-10-03 16:28:06 +00:00
### With ffplay
You may directly open the SRT stream with ffplay:
```bash
ffplay -fflags nobuffer srt://127.0.0.1:9710?streamid=demo
```
2020-10-04 09:20:25 +00:00
### With MPV
As MPV uses ffmpeg libav, support for SRT streams can be easily added.
[See current pull request.](https://github.com/mpv-player/mpv/pull/8139)
2020-10-03 19:16:48 +00:00
## Troubleshooting
### ld returns an error when launching ghostream
2020-10-14 08:12:37 +00:00
When missing `libsrt-openssl-dev` on Debian/Ubuntu,
2020-10-03 19:16:48 +00:00
then srtgo package is unable to build.
```bash
~/ghostream$ go run main.go
# github.com/haivision/srtgo
2020-10-03 19:19:57 +00:00
/usr/bin/ld: cannot find -lsrt
/usr/bin/ld: cannot find -lsrt
/usr/bin/ld: cannot find -lsrt
2020-10-03 19:16:48 +00:00
collect2: error: ld returned 1 exit status
```
2020-09-23 11:52:12 +00:00
## References
- Phil Cluff (2019), *[Streaming video on the internet without MPEG.](https://mux.com/blog/streaming-video-on-the-internet-without-mpeg/)*
- MDN web docs, *[Signaling and video calling.](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API/Signaling_and_video_calling)*
2020-09-24 17:01:26 +00:00
- [WebRTC For The Curious](https://webrtcforthecurious.com/)
2020-09-29 11:14:26 +00:00
- OBS Wiki, *[Streaming With SRT Protocol.](https://obsproject.com/wiki/Streaming-With-SRT-Protocol)*
- Livepeer media server, *[Evaluate Go-FFmpeg Bindings](https://github.com/livepeer/lpms/issues/24)*