hls-streamer
Stream your heart's content with HLS.
Movtivation
I've got a CCTV camera from AliExpress, I know I can use ffmpeg hls demuxer to split up the stream into HLS segments and serve nginx over the files to make an HLS stream.
But then I learned that my camera can only do H265 stream, while HLS supports H265, no mainstream browsers support H265 natively. FFMPEG tries to transcode the video on the fly and it is a very expensive operation, even with hardware support: 400% software vs 100% hardware CPU usage. I've come up with this idea that only when someone accesses the stream should the transcoding start.
Highlight
- Written in Rust, minimal resource usage: the app itself takes <5K memory to run1.
- FFMPEG/transcoding only starts first time accessing the stream.
- FFMPEG/transcoding stops when access stops.
- Comes with a simple web page: it's ready to view the result!
Installation
Docker
For an onvif compatible camera, we can use its rtsp stream.
$ docker run -d \
-e FFMPEG_INPUT="-rtsp_transport tcp -i rtsp://NAME:PASSWORD@CAMERA_IP/onvif2"
ghcr.io/simophin/hls-streamer
Docker compose
Refer to the rest of the documentation for the usage of FFMPEG_INPUT.
docker-compose.yaml
services:
webcam:
image: ghcr.io/simophin/hls-streamer:latest
restart: always
ports:
- 8989:8989
devices:
# Device mapping only needed for hardware acceleration
- /dev/dri/renderD128:/dev/dri/renderD128
volumes:
# Optional. Use a tmpfs for data storage to reduce writes to your disks.
- hls-data:/data
environment:
- FFMPEG_INPUT=-vaapi_device /dev/dri/renderD128 -rtsp_transport tcp -i rtsp://USER:PASS@CAMERA_IP/onvif2 -vf format=nv12,hwupload -b:v 2M -c:v h264_vaapi
volumes:
hls-data:
driver: local
driver_opts:
type: tmpfs
device: tmpfs
o: size=200m
Build from source
You'll need to set up Rust toolchain first, see rustup
Clone the source and build
$ cargo build --release
Once built, you can run via:
$ FFMPEG_INPUT=xxx ./target/release/hls-streamer
You'll also need to have ffmpeg>4.0 installed to use the app.
Only Linux system is tested at this time.
Configuration
Environment varaiables
| Name | Default value | Description |
|---|---|---|
| FFMPEG_INPUT | FFMPEG input parameters. e.g. -rtsp_transport tcp -i rtsp://NAME:PASSWORD@CAMERA_IP/onvif2. See below for examples. |
|
| HLS_DIR | /data | HLS data storage directory. It's recommended to use a memory based system like tmpfs to avoid frequent write to disks. |
| LISTEN_ADDRESS | 0.0.0.0 | Http server listening address |
| LISTEN_PORT | 8989 | Http server listening port |
| TIMEOUT_SECONDS | 120 | The waiting time before a stream is considered idle. |
Usage
Once you have the app running, by default, you will have these two links:
http://localhost:8989 -> a simple webpage showing the HLS stream
http://localhost:8989/master.m3u8 -> the HLS playlist itself
The playlist file request will be withheld until the playlist file is generated. This is to avoid the first time you access the playlist because ffmpeg is not ready and you'd have got a 404 for that file.
Screenshots
Input examples
These examples demostrate what you can put into FFMPEG_INPUT environment variable.
Copying the camera stream (i.e. no transcoding)
-rtsp_transport tcp -i rtsp://NAME:PASSWORD@CAMERA_IP/onvif2 -vf copy
Hardware H264 encoding (VAAPI)
-vaapi_device /dev/dri/renderD128 -rtsp_transport tcp -i rtsp://NAME:PASSWORD@CAMERA_IP/onvif2 -vf format=nv12,hwupload -b:v 2M -c:v h264_vaapi
Footnotes
-
The measurement was indicative only. FFMPEG process is excluded.
↩
7 Dec 18, 2022
6 Jun 17, 2022
42 Dec 28, 2022
3 Apr 10, 2024
4 Jan 26, 2023
602 Jan 2, 2023
4 Feb 26, 2022
30 Jun 24, 2023
45 Dec 14, 2022
384 Jan 2, 2023
6 Dec 1, 2023
51 Dec 16, 2022
92 Jan 1, 2023
26 Feb 22, 2023
2 Mar 20, 2022
1.3k Jan 2, 2023
4 Apr 11, 2023
7 Dec 28, 2022
53 Dec 23, 2022
602 Jan 2, 2023
45 Dec 14, 2022
384 Jan 2, 2023
51 Dec 16, 2022
92 Jan 1, 2023
26 Feb 22, 2023
6 May 7, 2022
21 Mar 22, 2023
13 Dec 26, 2022
108 Jan 8, 2023