| sidebar_position | 6 |
|---|
Use this setup when a PUDA machine host has one or more USB cameras, webcams, or IP cameras and you want live video available over RTSP, RTMP, HLS, or WebRTC.
This guide assumes Docker Engine and Docker Compose are installed, and that the host can be reached by operators over the same VPN network used for PUDA.
-
Find the camera device or IP camera URL.
For local USB cameras or webcams, list the video devices on the livestream host:
ls -l /dev/video*If
v4l-utilsis installed, inspect the cameras:v4l2-ctl --list-devices
Choose the device paths to expose, such as
/dev/video0or/dev/video2.For IP cameras, find the stream URL from the camera admin UI or vendor docs. RTSP URLs usually look like:
rtsp://user:pass@192.168.1.50:554/stream1 -
Clone this repository.
git clone <repo-url> cd livestream
-
Copy
.env.exampleto.envand set the host address.cp .env.example .env
Edit
.envand setMTX_WEBRTCADDITIONALHOSTSto the address operators will use to reach this host, usually the Tailscale IP or DNS name:MTX_WEBRTCADDITIONALHOSTS=100.64.0.10
-
Update
streams.conf.Each non-blank, non-comment line defines one stream: the input and the public stream name, separated by whitespace.
/dev/video0 livestream rtsp://user:pass@192.168.1.50:554/stream1 ipcam0The input can be a local
/dev/video*device or an IP camera URL. -
Update
compose.ymlto add local/devdevices.Docker containers do not automatically see host video devices. Each local camera used in
streams.confmust also be exposed to theffmpegcontainer with a matchingdevices:entry incompose.yml.devices: - /dev/video0:/dev/video0 - /dev/video2:/dev/video2
IP camera URLs do not need a Docker device mapping.
-
Start the livestream services.
docker compose up -d
Check that both services are running:
docker compose ps
The livestream will be available on the ports published by compose.yml:
ports:
- "8554:8554" # RTSP
- "1935:1935" # RTMP
- "8888:8888" # HLS
- "8889:8889" # WebRTC HTTP/WHIP/WHEP
- "8189:8189/udp" # WebRTC ICE/UDP
- "8189:8189/tcp" # WebRTC ICE/TCPVideo feeds can be accessed at these URLs. For each stream name in streams.conf, replace STREAM_NAME and use the host from MTX_WEBRTCADDITIONALHOSTS in .env:
| Protocol | URL |
|---|---|
| RTSP | rtsp://MTX_WEBRTCADDITIONALHOSTS:8554/STREAM_NAME |
| RTMP | rtmp://MTX_WEBRTCADDITIONALHOSTS:1935/STREAM_NAME |
| HLS | http://MTX_WEBRTCADDITIONALHOSTS:8888/STREAM_NAME/ |
| WebRTC | http://MTX_WEBRTCADDITIONALHOSTS:8889/STREAM_NAME/ |
With the example streams.conf, livestream is available at those URLs.
Publishing the MediaMTX stack is not enough for PUDA to discover the feed. Livestreams are fleet records in NATS KV, not a field on one edge. After the stack is up, register the MediaMTX host (the same value as MTX_WEBRTCADDITIONALHOSTS) and the stream name from streams.conf. The CLI derives RTSP, RTMP, HLS, and WebRTC URLs from those two values and the standard MediaMTX ports. Attach every machine that should use this feed:
puda livestream add --name STREAM_NAME --host HOST \
--description "Short visual context" --machines machine-a,machine-b
puda livestream list
puda livestream list --hosts first,lab
puda livestream list --machines first
puda machine ping machine-a--machines can be omitted and filled later with puda livestream attach STREAM_NAME --machines machine-c. Detach or remove with puda livestream detach / puda livestream rm.
puda livestream list groups streams as host then name. Use --hosts to list only those MediaMTX hosts. Use --machines to list only streams attached to those machine IDs.
puda machine list advertises livestream_count. That count is registered PUDA livestreams only; unregistered cameras on the host may exist and are not included. Use puda livestream list --machines <id> for registered names, hosts, and URLs. Do not write URLs into an edge .env.
View logs if a stream does not appear:
docker compose logs -f mediamtx ffmpegFrom another machine that can reach the livestream host, verify a stream:
ffprobe rtsp://MTX_WEBRTCADDITIONALHOSTS:8554/livestreamFor browser viewing, open the HLS or WebRTC URL.