Vivoh Logo

Vivoh HLS Relay General Usage

๐Ÿ”—

Usage: ./vivoh-hls-relay

Vivoh HLS Relay will receive multicast video from a source that is specified as a parameter to the HLS URL, for example: "http://10.0.0.1:8888/playlist.m3u8?s=rtp://239.0.0.1:1234"

Vivoh HLS Relay requires
VLC (http://videolan.org)
or
FFmpeg (http://ffmpeg.org)
Usage:

vivoh-hls-relay -d /var/www -f

REQUIRED:

-d local directory to write HLS data ... eg "/var/www"
-f use FFMPEG as the TS segmenter
-v use VLC as the TS segmenter

You must specify one of either -v or -f for the TS segmenter

OPTIONAL:

-o Overwrite TS or m3u8 files in the directory if already there. It is
    best to clean up (delete) those files before starting Vivoh HLS Relay.
-i ip address or hostname to use, otherwise listens on all (0.0.0.0) 
-s "secure" mode. Specify a URL that will return "on" or "off" as 
    JSON. Override default poll time (10 seconds) via the "-t" switch. Override 
    the port in the JSON response: e.g.: { "on": true, "port": 54321 }
-p port of local web server ... eg "8888"
-e HTTPS encryption. Uses self-signed certificates unless cert paths specified. 
   e.g.: -e 'key.pem,cert.pem,chain.pem' 
--ffmpegBin full path to ffmpeg. 
--ffmpegExtras extra switches to provide to ffmpeg
--vlcBin full path to VLC. Defaults to "cvlc" for Linux, "vlc.exe" for Windows
    and "/Applications/VLC.app/Contents/MacOS/VLC" for OSX
--vlcExtras extra switches to provide to VLC

Basic Usage

๐Ÿ”—

Usage: ./vivoh-hls-relay -d /tmp -v

Vivoh HLS Relay starts VLC or FFMPEG when the HLS stream is requested and holds open the request until the TS files are ready. When ready, it responds with the playlist.

Access this stream via: http://10.0.0.1:8888/playlist.m3u8?s=rtp://239.0.0.1:1234
Vivoh HLS Relay 1.0.12

LEGEND

!: Starting VLC process
@: waiting, waiting for the TS files to be ready

HLS Relay listening on http://10.0.0.183:8888


[email protected]@@@@@@@@@@@@@@@.....

Poll Mode

๐Ÿ”—

Usage: ./vivoh-hls-relay -v -d /tmp -s http://broadcaststatus/status.txt

In "poll" mode, Vivoh HLS Relay polls a server for status. Vivoh HLS Relay does not start listening as a web server until it receives a successful status response from the poll server. It will immediately shutdown its web server when it receives a status message of โ€œoffโ€. You specify a status URL using the -s switch. This server must return either the text "on" or "off", or JSON like { "on" : true }. You can specify the -t switch to indicate the time in seconds you want to wait until polling again (it defaults to 10 seconds)

Access this stream via: http://10.0.0.1:8888/playlist.m3u8?s=udp://239.0.0.1:1234
$ ./vivoh-hls-relay -v -d /tmp -s http://broadcaststatus/status.txt -t 5

Vivoh HLS Relay 1.0.12

LEGEND

!: Starting VLC process
.: TS files and m3u8 file ready, broadcast started
@: holding for the TS files to be ready
๐Ÿ›ซ: started listening for playlist requests (HTTP server on)
๐Ÿ›ฌ: stopped listening for playlist requests (HTTP server off)
โœˆ: the server indicates broadcasting is on
๐Ÿšซ: the server indicates broadcasting is off
โ†ฏ: an error occurred when contacting the server

In POLL (SECURE) mode 
โ†ฏ๐Ÿšซ๐Ÿ“ป๐Ÿ›ซ
Listening for connections on 0.0.0.0 on port 8888

๐Ÿšซ๐Ÿ›ฌ
Shutting down server

๐Ÿšซ๐Ÿ“ป๐Ÿ›ซ
Listening for connections on 0.0.0.0 on port 8888

Custom ffmpeg extras

๐Ÿ”—

Usage: vivoh-hls-relay-linux -d tmp -f --ffmpegExtras='-c:a aac -ar 48000 -b:a 128k -c:v h264 -profile:v main -crf 20 -g 48 -keyint_min 48 -sc_threshold 0 -b:v 2500k -maxrate 2675k -bufsize 3750k -hls_time 4 -hls_flags delete_segments'

There may be times when you need to customize the ffmpeg command. You can provide extra switches with the --ffmpegExtras switch

$ vivoh-hls-relay-linux -d tmp -f \
--ffmpegExtras='-c:a aac -ar 48000 -b:a 128k -c:v h264 -profile:v main -crf 20 -g 48 -keyint_min 48 -sc_threshold 0 -b:v 2500k -maxrate 2675k -bufsize 3750k -hls_time 4 -hls_flags delete_segments'

Vivoh HLS Relay 1.0.13

LEGEND

*: Starting ffmpeg process
.: TS files and m3u8 file ready, broadcast started
@: holding for the TS files to be ready

๐Ÿ›ซ
Listening for connections on 0.0.0.0 on port 8888

*@@@@....