refactor documentation (#5509)
expand "publish" and "read" pages into several subpages.
This commit is contained in:
Alessandro Ros
@@ -6,21 +6,21 @@ _MediaMTX_ is a ready-to-use and zero-dependency live media server and media pro
|
||||
|
||||
Main features:
|
||||
|
||||
- [Publish](../2-usage/02-publish.md) live streams to the server with SRT, WebRTC, RTSP, RTMP, HLS, MPEG-TS, RTP
|
||||
- [Read](../2-usage/03-read.md) live streams from the server with SRT, WebRTC, RTSP, RTMP, HLS
|
||||
- [Publish](../2-publish/01-overview.md) live streams to the server with SRT, WebRTC, RTSP, RTMP, HLS, MPEG-TS, RTP
|
||||
- [Read](../3-read/01-overview.md) live streams from the server with SRT, WebRTC, RTSP, RTMP, HLS
|
||||
- Streams are automatically converted from a protocol to another
|
||||
- Serve several streams at once in separate paths
|
||||
- Reload the configuration without disconnecting existing clients (hot reloading)
|
||||
- [Serve always-available streams](../2-usage/07-always-available.md) even when the publisher is offline
|
||||
- [Record](../2-usage/08-record.md) streams to disk in fMP4 or MPEG-TS format
|
||||
- [Playback](../2-usage/09-playback.md) recorded streams
|
||||
- [Authenticate](../2-usage/05-authentication.md) users with internal, HTTP or JWT authentication
|
||||
- [Forward](../2-usage/10-forward.md) streams to other servers
|
||||
- [Proxy](../2-usage/11-proxy.md) requests to other servers
|
||||
- [Control](../2-usage/20-control-api.md) the server through the Control API
|
||||
- [Extract metrics](../2-usage/21-metrics.md) from the server in a Prometheus-compatible format
|
||||
- [Monitor performance](../2-usage/22-performance.md) to investigate CPU and RAM consumption
|
||||
- [Run hooks](../2-usage/19-hooks.md) (external commands) when clients connect, disconnect, read or publish streams
|
||||
- [Serve always-available streams](../4-other/05-always-available.md) even when the publisher is offline
|
||||
- [Record](../4-other/06-record.md) streams to disk in fMP4 or MPEG-TS format
|
||||
- [Playback](../4-other/07-playback.md) recorded streams
|
||||
- [Authenticate](../4-other/03-authentication.md) users with internal, HTTP or JWT authentication
|
||||
- [Forward](../4-other/08-forward.md) streams to other servers
|
||||
- [Proxy](../4-other/09-proxy.md) requests to other servers
|
||||
- [Control](../4-other/18-control-api.md) the server through the Control API
|
||||
- [Extract metrics](../4-other/19-metrics.md) from the server in a Prometheus-compatible format
|
||||
- [Monitor performance](../4-other/20-performance.md) to investigate CPU and RAM consumption
|
||||
- [Run hooks](../4-other/17-hooks.md) (external commands) when clients connect, disconnect, read or publish streams
|
||||
- Compatible with Linux, Windows and macOS, does not require any dependency or interpreter, it's a single executable
|
||||
|
||||
Use the menu to navigate through the documentation.
|
||||
|
||||
@@ -90,6 +90,6 @@ pkg install mediamtx
|
||||
|
||||
## OpenWrt binary
|
||||
|
||||
If the architecture of the OpenWrt device is amd64, armv6, armv7 or arm64, use the [standalone binary method](2-install.md#standalone-binary) and download a Linux binary that corresponds to your architecture.
|
||||
If the architecture of the OpenWrt device is amd64, armv6, armv7 or arm64, use the [standalone binary method](#standalone-binary) and download a Linux binary that corresponds to your architecture.
|
||||
|
||||
Otherwise, [compile the server from source](../4-other/1-compile.md).
|
||||
Otherwise, [compile the server from source](../6-misc/1-compile.md).
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Basic usage
|
||||
|
||||
1. [Publish](02-publish.md) a stream. For instance, you can publish a stream from a MP4 file with _FFmpeg_:
|
||||
1. [Publish](../2-publish/01-overview.md) a stream. For instance, you can publish a stream from a MP4 file with _FFmpeg_:
|
||||
|
||||
```sh
|
||||
ffmpeg -re -stream_loop -1 -i file.mp4 -c copy \
|
||||
@@ -14,7 +14,7 @@
|
||||
! qtdemux name=d d.video_0 ! queue ! s.sink_0 d.audio_0 ! queue ! s.sink_1
|
||||
```
|
||||
|
||||
2. [Read](03-read.md) the stream. For instance, you can read the stream with _VLC_:
|
||||
2. [Read](../3-read/01-overview.md) the stream. For instance, you can read the stream with _VLC_:
|
||||
|
||||
```sh
|
||||
vlc --network-caching=50 rtsp://localhost:8554/mystream
|
||||
@@ -0,0 +1,32 @@
|
||||
# Publish a stream
|
||||
|
||||
Live streams can be published to the server with the following protocols and codecs:
|
||||
|
||||
| protocol | variants | codecs |
|
||||
| ---------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| [SRT clients](02-srt-clients.md) | | **Video**: H265, H264, MPEG-4 Video (H263, Xvid), MPEG-1/2 Video<br/>**Audio**: Opus, MPEG-4 Audio (AAC), MPEG-1/2 Audio (MP3), AC-3<br/>**Other**: KLV |
|
||||
| [SRT cameras and servers](03-srt-cameras-and-servers.md) | | **Video**: H265, H264, MPEG-4 Video (H263, Xvid), MPEG-1/2 Video<br/>**Audio**: Opus, MPEG-4 Audio (AAC), MPEG-1/2 Audio (MP3), AC-3<br/>**Other**: KLV |
|
||||
| [WebRTC clients](04-webrtc-clients.md) | WHIP | **Video**: AV1, VP9, VP8, H265, H264<br/>**Audio**: Opus, G722, G711 (PCMA, PCMU) |
|
||||
| [WebRTC servers](05-webrtc-servers.md) | WHEP | **Video**: AV1, VP9, VP8, H265, H264<br/>**Audio**: Opus, G722, G711 (PCMA, PCMU) |
|
||||
| [RTSP clients](06-rtsp-clients.md) | UDP, TCP, RTSPS | **Video**: AV1, VP9, VP8, H265, H264, MPEG-4 Video (H263, Xvid), MPEG-1/2 Video, MJPEG<br/>**Audio**: Opus, MPEG-4 Audio (AAC), MPEG-1/2 Audio (MP3), AC-3, G726, G722, G711 (PCMA, PCMU), LPCM<br/>**Other**: KLV, MPEG-TS, any RTP-compatible codec |
|
||||
| [RTSP cameras and servers](07-rtsp-cameras-and-servers) | UDP, UDP-Multicast, TCP, RTSPS | **Video**: AV1, VP9, VP8, H265, H264, MPEG-4 Video (H263, Xvid), MPEG-1/2 Video, MJPEG<br/>**Audio**: Opus, MPEG-4 Audio (AAC), MPEG-1/2 Audio (MP3), AC-3, G726, G722, G711 (PCMA, PCMU), LPCM<br/>**Other**: KLV, MPEG-TS, any RTP-compatible codec |
|
||||
| [RTMP clients](08-rtmp-clients.md) | RTMP, RTMPS, Enhanced RTMP | **Video**: AV1, VP9, H265, H264<br/>**Audio**: Opus, MPEG-4 Audio (AAC), MPEG-1/2 Audio (MP3), AC-3, G711 (PCMA, PCMU), LPCM |
|
||||
| [RTMP cameras and servers](09-rtmp-cameras-and-servers.md) | RTMP, RTMPS, Enhanced RTMP | **Video**: AV1, VP9, H265, H264<br/>**Audio**: Opus, MPEG-4 Audio (AAC), MPEG-1/2 Audio (MP3), AC-3, G711 (PCMA, PCMU), LPCM |
|
||||
| [HLS cameras and servers](10-hls-cameras-and-servers.md) | Low-Latency HLS, MP4-based HLS, legacy HLS | **Video**: AV1, VP9, H265, H264<br/>**Audio**: Opus, MPEG-4 Audio (AAC) |
|
||||
| [MPEG-TS](11-mpeg-ts.md) | MPEG-TS over UDP, MPEG-TS over Unix socket | **Video**: H265, H264, MPEG-4 Video (H263, Xvid), MPEG-1/2 Video<br/>**Audio**: Opus, MPEG-4 Audio (AAC), MPEG-1/2 Audio (MP3), AC-3<br/>**Other**: KLV |
|
||||
| [RTP](12-rtp.md) | RTP over UDP | **Video**: AV1, VP9, VP8, H265, H264, MPEG-4 Video (H263, Xvid), MPEG-1/2 Video, M-JPEG<br/>**Audio**: Opus, MPEG-4 Audio (AAC), MPEG-1/2 Audio (MP3), AC-3, G726, G722, G711 (PCMA, PCMU), LPCM<br/>**Other**: KLV, MPEG-TS, any RTP-compatible codec |
|
||||
|
||||
We provide instructions for publishing with the following devices:
|
||||
|
||||
- [Raspberry Pi Cameras](13-raspberry-pi-cameras.md)
|
||||
- [Generic webcams](14-generic-webcams.md)
|
||||
|
||||
We provide instructions for publishing with the following software:
|
||||
|
||||
- [FFmpeg](15-ffmpeg.md)
|
||||
- [GStreamer](16-gstreamer.md)
|
||||
- [OBS Studio](17-obs-studio.md)
|
||||
- [Python and OpenCV](18-python-opencv.md)
|
||||
- [Golang](19-golang.md)
|
||||
- [Unity](20-unity.md)
|
||||
- [Web browsers](21-web-browsers.md)
|
||||
@@ -0,0 +1,15 @@
|
||||
# SRT clients
|
||||
|
||||
SRT is a protocol that allows to publish and read live data stream, providing encryption, integrity and a retransmission mechanism. It is usually used to transfer media streams encoded with MPEG-TS. In order to publish a stream to the server with the SRT protocol, use this URL:
|
||||
|
||||
```
|
||||
srt://localhost:8890?streamid=publish:mystream&pkt_size=1316
|
||||
```
|
||||
|
||||
Replace `mystream` with any name you want. The resulting stream will be available on path `/mystream`.
|
||||
|
||||
If you need to use the standard stream ID syntax instead of the custom one in use by this server, see [Standard stream ID syntax](../4-other/21-srt-specific-features.md#standard-stream-id-syntax).
|
||||
|
||||
If you want to publish a stream by using a client in listening mode (i.e. with `mode=listener` appended to the URL), read the next section.
|
||||
|
||||
Some clients that can publish with SRT are [FFmpeg](15-ffmpeg.md), [GStreamer](16-gstreamer.md), [OBS Studio](17-obs-studio.md).
|
||||
@@ -0,0 +1,10 @@
|
||||
# SRT cameras and servers
|
||||
|
||||
In order to ingest a SRT stream from a remote server, camera or client in listening mode (i.e. with `mode=listener` appended to the URL), add the corresponding URL into the `source` parameter of a path:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
proxied:
|
||||
# url of the source stream, in the format srt://host:port?streamid=streamid&other_parameters
|
||||
source: srt://original-url
|
||||
```
|
||||
@@ -0,0 +1,21 @@
|
||||
# WebRTC clients
|
||||
|
||||
WebRTC is an API that makes use of a set of protocols and methods to connect two clients together and allow them to exchange live media or data streams. You can publish a stream with WebRTC and a web browser by visiting:
|
||||
|
||||
```
|
||||
http://localhost:8889/mystream/publish
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/mystream`.
|
||||
|
||||
WHIP is a WebRTC extensions that allows to publish streams by using a URL, without passing through a web page. This allows to use WebRTC as a general purpose streaming protocol. If you are using a software that supports WHIP (for instance, latest versions of OBS Studio), you can publish a stream to the server by using this URL:
|
||||
|
||||
```
|
||||
http://localhost:8889/mystream/whip
|
||||
```
|
||||
|
||||
Be aware that not all browsers can read any codec, check [Supported browsers](../4-other/22-webrtc-specific-features.md#supported-browsers).
|
||||
|
||||
Depending on the network it might be difficult to establish a connection between server and clients, read [Solving WebRTC connectivity issues](../4-other/22-webrtc-specific-features.md#solving-webrtc-connectivity-issues).
|
||||
|
||||
Some clients that can publish with WebRTC and WHIP are [FFmpeg](15-ffmpeg.md), [GStreamer](16-gstreamer.md), [OBS Studio](17-obs-studio.md), [Unity](20-unity.md) and [Web browsers](21-web-browsers.md).
|
||||
@@ -0,0 +1,18 @@
|
||||
# WebRTC servers
|
||||
|
||||
In order to ingest a WebRTC stream from a remote server, add the corresponding WHEP URL into the `source` parameter of a path:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
proxied:
|
||||
# url of the source stream, in the format whep://host:port/path (HTTP) or wheps:// (HTTPS)
|
||||
source: wheps://host:port/path
|
||||
```
|
||||
|
||||
If the remote server is a _MediaMTX_ instance, remember to add a `/whep` suffix after the stream name, since in _MediaMTX_ [it's part of the WHEP URL](../3-read/03-webrtc.md):
|
||||
|
||||
```yml
|
||||
paths:
|
||||
proxied:
|
||||
source: whep://host:port/mystream/whep
|
||||
```
|
||||
@@ -0,0 +1,11 @@
|
||||
# RTSP clients
|
||||
|
||||
RTSP is a protocol that allows to publish and read streams. It supports several underlying transport protocols and encryption (see [RTSP-specific features](../4-other/23-rtsp-specific-features.md)). In order to publish a stream to the server with the RTSP protocol, use this URL:
|
||||
|
||||
```
|
||||
rtsp://localhost:8554/mystream
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/mystream`.
|
||||
|
||||
Some clients that can publish with RTSP are [FFmpeg](15-ffmpeg.md), [GStreamer](16-gstreamer.md), [OBS Studio](17-obs-studio.md), [Python and OpenCV](18-python-opencv.md).
|
||||
@@ -0,0 +1,47 @@
|
||||
# RTSP cameras and servers
|
||||
|
||||
Most IP cameras expose their video stream by using a RTSP server that is embedded into the camera itself. In particular, cameras that are compliant with ONVIF profile S or T meet this requirement. You can use _MediaMTX_ to connect to one or several existing RTSP servers and read their media streams:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
proxied:
|
||||
# url of the source stream, in the format rtsp://user:pass@host:port/path
|
||||
source: rtsp://original-url
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/proxied`.
|
||||
|
||||
It is possible to tune the connection by using some additional parameters:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
proxied:
|
||||
# url of the source stream, in the format rtsp://user:pass@host:port/path
|
||||
source: rtsp://original-url
|
||||
# Transport protocol used to pull the stream. available values are "automatic", "udp", "multicast", "tcp".
|
||||
rtspTransport: automatic
|
||||
# Support sources that don't provide server ports or use random server ports. This is a security issue
|
||||
# and must be used only when interacting with sources that require it.
|
||||
rtspAnyPort: no
|
||||
# Range header to send to the source, in order to start streaming from the specified offset.
|
||||
# available values:
|
||||
# * clock: Absolute time
|
||||
# * npt: Normal Play Time
|
||||
# * smpte: SMPTE timestamps relative to the start of the recording
|
||||
rtspRangeType:
|
||||
# Available values:
|
||||
# * clock: UTC ISO 8601 combined date and time string, e.g. 20230812T120000Z
|
||||
# * npt: duration such as "300ms", "1.5m" or "2h45m", valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h"
|
||||
# * smpte: duration such as "300ms", "1.5m" or "2h45m", valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h"
|
||||
rtspRangeStart:
|
||||
# Size of the UDP buffer of the RTSP client.
|
||||
# This can be increased to mitigate packet losses.
|
||||
# It defaults to the default value of the operating system.
|
||||
rtspUDPReadBufferSize: 0
|
||||
# Range of ports used as source port in outgoing UDP packets.
|
||||
rtspUDPSourcePortRange: [10000, 65535]
|
||||
```
|
||||
|
||||
All available parameters are listed in the [configuration file](../5-references/1-configuration-file.md).
|
||||
|
||||
Advanced RTSP features are described in [RTSP-specific features](../4-other/23-rtsp-specific-features.md).
|
||||
@@ -0,0 +1,11 @@
|
||||
# RTMP clients
|
||||
|
||||
RTMP is a protocol that allows to read and publish streams. It supports encryption, see [RTMP-specific features](../4-other/24-rtmp-specific-features.md). Streams can be published to the server by using the URL:
|
||||
|
||||
```
|
||||
rtmp://localhost/mystream
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/mystream`.
|
||||
|
||||
Some clients that can publish with RTMP are [FFmpeg](15-ffmpeg.md), [GStreamer](16-gstreamer.md), [OBS Studio](17-obs-studio.md).
|
||||
@@ -0,0 +1,12 @@
|
||||
# RTMP cameras and servers
|
||||
|
||||
You can use _MediaMTX_ to connect to one or several existing RTMP servers and read their media streams:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
proxied:
|
||||
# url of the source stream, in the format rtmp://user:pass@host:port/path
|
||||
source: rtmp://original-url
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/proxied`.
|
||||
@@ -0,0 +1,12 @@
|
||||
# HLS cameras and servers
|
||||
|
||||
HLS is a streaming protocol that works by splitting streams into segments, and by serving these segments and a playlist with the HTTP protocol. You can use _MediaMTX_ to connect to one or several existing HLS servers and read their media streams:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
proxied:
|
||||
# url of the playlist of the stream, in the format http://user:pass@host:port/path
|
||||
source: http://original-url/stream/index.m3u8
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/proxied`.
|
||||
@@ -0,0 +1,39 @@
|
||||
# MPEG-TS
|
||||
|
||||
The server supports ingesting MPEG-TS streams, shipped in two different ways (UDP packets or Unix sockets).
|
||||
|
||||
In order to read a UDP MPEG-TS stream, edit `mediamtx.yml` and replace everything inside section `paths` with the following content:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
mypath:
|
||||
source: udp+mpegts://238.0.0.1:1234
|
||||
```
|
||||
|
||||
Where `238.0.0.1` is the IP for listening packets, in this case a multicast IP.
|
||||
|
||||
If the listening IP is a multicast IP, _MediaMTX_ will listen for incoming packets on the default multicast interface, picked by the operating system. It is possible to specify the interface manually by using the `interface` parameter:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
mypath:
|
||||
source: udp+mpegts://238.0.0.1:1234?interface=eth0
|
||||
```
|
||||
|
||||
It is possible to restrict who can send packets by using the `source` parameter:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
mypath:
|
||||
source: udp+mpegts://0.0.0.0:1234?source=192.168.3.5
|
||||
```
|
||||
|
||||
Some clients that can publish with UDP and MPEG-TS are [FFmpeg](15-ffmpeg.md) and [GStreamer](16-gstreamer.md).
|
||||
|
||||
Unix sockets are more efficient than UDP packets and can be used as transport by specifying the `unix+mpegts` scheme:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
mypath:
|
||||
source: unix+mpegts:///tmp/socket.sock
|
||||
```
|
||||
@@ -0,0 +1,26 @@
|
||||
# RTP
|
||||
|
||||
The server supports ingesting RTP streams, shipped in two different ways (UDP packets or Unix sockets).
|
||||
|
||||
In order to read a UDP RTP stream, edit `mediamtx.yml` and replace everything inside section `paths` with the following content:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
mypath:
|
||||
source: udp+rtp://238.0.0.1:1234
|
||||
rtpSDP: |
|
||||
v=0
|
||||
o=- 123456789 123456789 IN IP4 192.168.1.100
|
||||
s=H264 Video Stream
|
||||
c=IN IP4 192.168.1.100
|
||||
t=0 0
|
||||
m=video 5004 RTP/AVP 96
|
||||
a=rtpmap:96 H264/90000
|
||||
a=fmtp:96 profile-level-id=42e01e;packetization-mode=1;sprop-parameter-sets=Z0LAHtkDxWhAAAADAEAAAAwDxYuS,aMuMsg==
|
||||
```
|
||||
|
||||
`rtpSDP` must contain a valid SDP, that is a description of the RTP session.
|
||||
|
||||
Some clients that can publish with UDP and MPEG-TS are [FFmpeg](15-ffmpeg.md) and [GStreamer](16-gstreamer.md).
|
||||
|
||||
## Devices
|
||||
@@ -0,0 +1,121 @@
|
||||
# Raspberry Pi Cameras
|
||||
|
||||
_MediaMTX_ natively supports most Raspberry Pi Camera models, enabling high-quality and low-latency video streaming from the camera to any user, for any purpose. There are some additional requirements:
|
||||
|
||||
1. The server must run on a Raspberry Pi, with one of the following operating systems:
|
||||
- Raspberry Pi OS Trixie
|
||||
- Raspberry Pi OS Bookworm
|
||||
- Raspberry Pi OS Bullseye
|
||||
|
||||
Both 32-bit and 64-bit architectures are supported.
|
||||
|
||||
2. If you are using Raspberry Pi OS Bullseye, make sure that the legacy camera stack is disabled. Type `sudo raspi-config`, then go to `Interfacing options`, `enable/disable legacy camera support`, choose `no`. Reboot the system.
|
||||
|
||||
The setup procedure depends on whether you want to run the server outside or inside Docker:
|
||||
|
||||
- If you want to run the standard (non-Dockerized) version of the server:
|
||||
1. Download the server executable. If you're using 64-bit version of the operative system, make sure to pick the `arm64` variant.
|
||||
|
||||
2. Edit `mediamtx.yml` and replace everything inside section `paths` with the following content:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
cam:
|
||||
source: rpiCamera
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/cam`.
|
||||
|
||||
- If you want to run the server inside Docker, you need to use the `1-rpi` image and launch the container with some additional flags:
|
||||
|
||||
```sh
|
||||
docker run --rm -it \
|
||||
--network=host \
|
||||
--privileged \
|
||||
--tmpfs /dev/shm:exec \
|
||||
-v /run/udev:/run/udev:ro \
|
||||
-e MTX_PATHS_CAM_SOURCE=rpiCamera \
|
||||
bluenviron/mediamtx:1-rpi
|
||||
```
|
||||
|
||||
The Raspberry Pi Camera can be controlled through a wide range of parameters, that are listed in the [configuration file](../5-references/1-configuration-file.md).
|
||||
|
||||
Be aware that cameras that require a custom `libcamera` (like some ArduCam products) are not compatible with precompiled binaries and Docker images of _MediaMTX_, since these come with a bundled `libcamera`. If you want to use a custom one, you need to [compile from source](../6-misc/1-compile.md#custom-libcamera).
|
||||
|
||||
## Adding audio
|
||||
|
||||
In order to add audio from a USB microfone, install GStreamer and alsa-utils:
|
||||
|
||||
```sh
|
||||
sudo apt install -y gstreamer1.0-tools gstreamer1.0-rtsp gstreamer1.0-alsa alsa-utils
|
||||
```
|
||||
|
||||
list available audio cards with:
|
||||
|
||||
```sh
|
||||
arecord -L
|
||||
```
|
||||
|
||||
Sample output:
|
||||
|
||||
```
|
||||
surround51:CARD=ICH5,DEV=0
|
||||
Intel ICH5, Intel ICH5
|
||||
5.1 Surround output to Front, Center, Rear and Subwoofer speakers
|
||||
default:CARD=U0x46d0x809
|
||||
USB Device 0x46d:0x809, USB Audio
|
||||
Default Audio Device
|
||||
```
|
||||
|
||||
Find the audio card of the microfone and take note of its name, for instance `default:CARD=U0x46d0x809`. Then create a new path that takes the video stream from the camera and audio from the microphone:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
cam:
|
||||
source: rpiCamera
|
||||
|
||||
cam_with_audio:
|
||||
runOnInit: >
|
||||
gst-launch-1.0
|
||||
rtspclientsink name=s location=rtsp://localhost:$RTSP_PORT/cam_with_audio
|
||||
rtspsrc location=rtsp://127.0.0.1:$RTSP_PORT/cam latency=0 ! rtph264depay ! s.
|
||||
alsasrc device=default:CARD=U0x46d0x809 ! opusenc bitrate=16000 ! s.
|
||||
runOnInitRestart: yes
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/cam_with_audio`.
|
||||
|
||||
## Secondary stream
|
||||
|
||||
It is possible to enable a secondary stream from the same camera, with a different resolution, FPS and codec. Configuration is the same of a primary stream, with `rpiCameraSecondary` set to `true` and parameters adjusted accordingly:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
# primary stream
|
||||
rpi:
|
||||
source: rpiCamera
|
||||
# Width of frames.
|
||||
rpiCameraWidth: 1920
|
||||
# Height of frames.
|
||||
rpiCameraHeight: 1080
|
||||
# FPS.
|
||||
rpiCameraFPS: 30
|
||||
|
||||
# secondary stream
|
||||
secondary:
|
||||
source: rpiCamera
|
||||
# This is a secondary stream.
|
||||
rpiCameraSecondary: true
|
||||
# Width of frames.
|
||||
rpiCameraWidth: 640
|
||||
# Height of frames.
|
||||
rpiCameraHeight: 480
|
||||
# FPS.
|
||||
rpiCameraFPS: 10
|
||||
# Codec. in case of secondary streams, it defaults to M-JPEG.
|
||||
rpiCameraCodec: auto
|
||||
# JPEG quality.
|
||||
rpiCameraMJPEGQuality: 60
|
||||
```
|
||||
|
||||
The secondary stream will be available on path `/secondary`.
|
||||
@@ -0,0 +1,27 @@
|
||||
# Generic webcams
|
||||
|
||||
If the operating system is Linux, edit `mediamtx.yml` and replace everything inside section `paths` with the following content:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
cam:
|
||||
runOnInit: ffmpeg -f v4l2 -i /dev/video0 -c:v libx264 -pix_fmt yuv420p -preset ultrafast -b:v 600k -f rtsp rtsp://localhost:$RTSP_PORT/$MTX_PATH
|
||||
runOnInitRestart: yes
|
||||
```
|
||||
|
||||
If the operating system is Windows:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
cam:
|
||||
runOnInit: ffmpeg -f dshow -i video="USB2.0 HD UVC WebCam" -c:v libx264 -pix_fmt yuv420p -preset ultrafast -b:v 600k -f rtsp rtsp://localhost:$RTSP_PORT/$MTX_PATH
|
||||
runOnInitRestart: yes
|
||||
```
|
||||
|
||||
Where `USB2.0 HD UVC WebCam` is the name of a webcam, that can be obtained with:
|
||||
|
||||
```sh
|
||||
ffmpeg -list_devices true -f dshow -i dummy
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/cam`.
|
||||
@@ -0,0 +1,63 @@
|
||||
# FFmpeg
|
||||
|
||||
FFmpeg can publish a stream to the server in several ways. The recommended one consists in publishing with RTSP.
|
||||
|
||||
## FFmpeg and RTSP
|
||||
|
||||
```sh
|
||||
ffmpeg -re -stream_loop -1 -i file.mp4 -c copy -f rtsp rtsp://localhost:8554/mystream
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/mystream`.
|
||||
|
||||
## FFmpeg and RTMP
|
||||
|
||||
```sh
|
||||
ffmpeg -re -stream_loop -1 -i file.mp4 -c copy -f flv rtmp://localhost:1935/mystream
|
||||
```
|
||||
|
||||
## FFmpeg and MPEG-TS over UDP
|
||||
|
||||
In _MediaMTX_ configuration, add a path with `source: udp+mpegts://238.0.0.1:1234`. Then:
|
||||
|
||||
```sh
|
||||
ffmpeg -re -stream_loop -1 -i file.mp4 -c copy -f mpegts 'udp://238.0.0.1:1234?pkt_size=1316'
|
||||
```
|
||||
|
||||
## FFmpeg and MPEG-TS over Unix socket
|
||||
|
||||
In _MediaMTX_ configuration, add a path with `source: unix+mpegts:///tmp/socket.sock`. Then:
|
||||
|
||||
```sh
|
||||
ffmpeg -re -f lavfi -i testsrc=size=1280x720:rate=30 \
|
||||
-c:v libx264 -pix_fmt yuv420p -preset ultrafast -b:v 600k \
|
||||
-f mpegts unix:/tmp/socket.sock
|
||||
```
|
||||
|
||||
## FFmpeg and RTP over UDP
|
||||
|
||||
In _MediaMTX_ configuration, add a path with `source: udp+rtp://238.0.0.1:1234` and a valid `rtpSDP` (see [RTP](12-rtp.md)). Then:
|
||||
|
||||
```sh
|
||||
ffmpeg -re -f lavfi -i testsrc=size=1280x720:rate=30 \
|
||||
-c:v libx264 -pix_fmt yuv420p -preset ultrafast -b:v 600k \
|
||||
-f rtp udp://238.0.0.1:1234?pkt_size=1316
|
||||
```
|
||||
|
||||
## FFmpeg and SRT
|
||||
|
||||
```sh
|
||||
ffmpeg -re -stream_loop -1 -i file.mp4 -c copy -f mpegts 'srt://localhost:8890?streamid=publish:stream&pkt_size=1316'
|
||||
```
|
||||
|
||||
## FFmpeg and WebRTC
|
||||
|
||||
```sh
|
||||
ffmpeg -re -f lavfi -i testsrc=size=1280x720:rate=30 \
|
||||
-f lavfi -i "sine=frequency=1000:sample_rate=48000" \
|
||||
-c:v libx264 -pix_fmt yuv420p -preset ultrafast -b:v 600k \
|
||||
-c:a libopus -ar 48000 -ac 2 -b:a 128k \
|
||||
-f whip http://localhost:8889/stream/whip
|
||||
```
|
||||
|
||||
WARNING: in case of FFmpeg 8.0, a video track and an audio track must both be present.
|
||||
@@ -0,0 +1,53 @@
|
||||
# GStreamer
|
||||
|
||||
GStreamer can publish a stream to the server in several ways. The recommended one consists in publishing with RTSP.
|
||||
|
||||
## GStreamer and RTSP
|
||||
|
||||
```sh
|
||||
gst-launch-1.0 rtspclientsink name=s location=rtsp://localhost:8554/mystream \
|
||||
filesrc location=file.mp4 ! qtdemux name=d \
|
||||
d.video_0 ! queue ! s.sink_0 \
|
||||
d.audio_0 ! queue ! s.sink_1
|
||||
```
|
||||
|
||||
If the stream is video only:
|
||||
|
||||
```sh
|
||||
gst-launch-1.0 filesrc location=file.mp4 ! qtdemux name=d \
|
||||
d.video_0 ! rtspclientsink location=rtsp://localhost:8554/mystream
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/mystream`.
|
||||
|
||||
For advanced options, see [RTSP-specific features](../4-other/23-rtsp-specific-features.md).
|
||||
|
||||
## GStreamer and RTMP
|
||||
|
||||
```sh
|
||||
gst-launch-1.0 -v flvmux name=mux ! rtmpsink location=rtmp://localhost/stream \
|
||||
videotestsrc ! video/x-raw,width=1280,height=720,format=I420 ! x264enc speed-preset=ultrafast bitrate=3000 key-int-max=60 ! video/x-h264,profile=high ! mux. \
|
||||
audiotestsrc ! audioconvert ! avenc_aac ! mux.
|
||||
```
|
||||
|
||||
## GStreamer and MPEG-TS over UDP
|
||||
|
||||
```sh
|
||||
gst-launch-1.0 -v mpegtsmux name=mux alignment=1 ! udpsink host=238.0.0.1 port=1234 \
|
||||
videotestsrc ! video/x-raw,width=1280,height=720,format=I420 ! x264enc speed-preset=ultrafast bitrate=3000 key-int-max=60 ! video/x-h264,profile=high ! mux. \
|
||||
audiotestsrc ! audioconvert ! avenc_aac ! mux.
|
||||
```
|
||||
|
||||
For advanced options, see [RTSP-specific features](../4-other/23-rtsp-specific-features.md).
|
||||
|
||||
## GStreamer and WebRTC
|
||||
|
||||
Make sure that GStreamer version is at least 1.22, and that if the codec is H264, the profile is baseline. Use the `whipclientsink` element:
|
||||
|
||||
```sh
|
||||
gst-launch-1.0 videotestsrc \
|
||||
! video/x-raw,width=1920,height=1080,format=I420 \
|
||||
! x264enc speed-preset=ultrafast bitrate=2000 \
|
||||
! video/x-h264,profile=baseline \
|
||||
! whipclientsink signaller::whip-endpoint=http://localhost:8889/mystream/whip
|
||||
```
|
||||
@@ -0,0 +1,117 @@
|
||||
# OBS Studio
|
||||
|
||||
OBS Studio can publish to the server in several ways. The recommended one consists in publishing with RTMP.
|
||||
|
||||
## OBS Studio and RTMP
|
||||
|
||||
In `Settings -> Stream` (or in the Auto-configuration Wizard), use the following parameters:
|
||||
|
||||
- Service: `Custom...`
|
||||
- Server: `rtmp://localhost/mystream`
|
||||
- Stream key: (empty)
|
||||
|
||||
Save the configuration and click `Start streaming`.
|
||||
|
||||
The resulting stream will be available on path `/mystream`.
|
||||
|
||||
If you want to generate a stream that can be read with WebRTC, open `Settings -> Output -> Recording` and use the following parameters:
|
||||
|
||||
- FFmpeg output type: `Output to URL`
|
||||
- File path or URL: `rtsp://localhost:8554/mystream`
|
||||
- Container format: `rtsp`
|
||||
- Check `show all codecs (even if potentially incompatible)`
|
||||
- Video encoder: `h264_nvenc (libx264)`
|
||||
- Video encoder settings (if any): `bf=0`
|
||||
- Audio track: `1`
|
||||
- Audio encoder: `libopus`
|
||||
|
||||
Then use the button `Start Recording` (instead of `Start Streaming`) to start streaming.
|
||||
|
||||
## OBS Studio and RTMP, multitrack video
|
||||
|
||||
OBS Studio can publish multiple video tracks or renditions at once. Make sure that the OBS Studio version is ≥ 31.0.0. Open `Settings -> Stream` and use the following parameters:
|
||||
|
||||
- Service: `Custom...`
|
||||
- Server: `rtmp://localhost/mystream`
|
||||
- Stream key: (empty)
|
||||
- Turn on `Enable Multitrack Video`
|
||||
- Leave `Maximum Streaming Bandwidth` and `Maximum Video Tracks` to `Auto`
|
||||
- Turn on `Enable Config Override`
|
||||
- Fill `Config Override (JSON)` with the following text:
|
||||
|
||||
```json
|
||||
{
|
||||
"encoder_configurations": [
|
||||
{
|
||||
"type": "obs_x264",
|
||||
"width": 1920,
|
||||
"height": 1080,
|
||||
"framerate": {
|
||||
"numerator": 30,
|
||||
"denominator": 1
|
||||
},
|
||||
"settings": {
|
||||
"rate_control": "CBR",
|
||||
"bitrate": 6000,
|
||||
"keyint_sec": 2,
|
||||
"preset": "veryfast",
|
||||
"profile": "high",
|
||||
"tune": "zerolatency"
|
||||
},
|
||||
"canvas_index": 0
|
||||
},
|
||||
{
|
||||
"type": "obs_x264",
|
||||
"width": 640,
|
||||
"height": 480,
|
||||
"framerate": {
|
||||
"numerator": 30,
|
||||
"denominator": 1
|
||||
},
|
||||
"settings": {
|
||||
"rate_control": "CBR",
|
||||
"bitrate": 3000,
|
||||
"keyint_sec": 2,
|
||||
"preset": "veryfast",
|
||||
"profile": "main",
|
||||
"tune": "zerolatency"
|
||||
},
|
||||
"canvas_index": 0
|
||||
}
|
||||
],
|
||||
"audio_configurations": {
|
||||
"live": [
|
||||
{
|
||||
"codec": "ffmpeg_aac",
|
||||
"track_id": 1,
|
||||
"channels": 2,
|
||||
"settings": {
|
||||
"bitrate": 160
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This can be adjusted according to specific needs. In particular, the `type` field is used to set the video encoder, and these are the available parameters:
|
||||
- `obs_nvenc_av1_tex`: NVIDIA NVENC AV1
|
||||
- `obs_nvenc_hevc_tex`: NVIDIA NVENC H265
|
||||
- `obs_nvenc_h264_tex`: NVIDIA NVENC H264
|
||||
- `av1_texture_amf`: AMD AV1
|
||||
- `h265_texture_amf`: AMD H265
|
||||
- `h264_texture_amf`: AMD H264
|
||||
- `obs_qsv11_av1`: QuickSync AV1
|
||||
- `obs_qsv11_v2`: QuickSync H264
|
||||
- `obs_x264`: software H264
|
||||
|
||||
## OBS Studio and WebRTC
|
||||
|
||||
Recent versions of OBS Studio can also publish to the server with the [WebRTC / WHIP protocol](21-webrtc-clients.md) Use the following parameters:
|
||||
|
||||
- Service: `WHIP`
|
||||
- Server: `http://localhost:8889/mystream/whip`
|
||||
|
||||
Save the configuration and click `Start streaming`.
|
||||
|
||||
The resulting stream will be available on path `/mystream`.
|
||||
@@ -0,0 +1,74 @@
|
||||
# Python and OpenCV
|
||||
|
||||
Python-based software can publish to the server with the OpenCV library and its GStreamer plugin, acting as a [RTSP client](06-rtsp-clients.md). OpenCV must be compiled with support for GStreamer, by following this procedure:
|
||||
|
||||
```sh
|
||||
sudo apt install -y libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev gstreamer1.0-plugins-ugly gstreamer1.0-rtsp python3-dev python3-numpy
|
||||
git clone --depth=1 -b 4.5.4 https://github.com/opencv/opencv
|
||||
cd opencv
|
||||
mkdir build && cd build
|
||||
cmake -D CMAKE_INSTALL_PREFIX=/usr -D WITH_GSTREAMER=ON ..
|
||||
make -j$(nproc)
|
||||
sudo make install
|
||||
```
|
||||
|
||||
You can check that OpenCV has been installed correctly by running:
|
||||
|
||||
```sh
|
||||
python3 -c 'import cv2; print(cv2.getBuildInformation())'
|
||||
```
|
||||
|
||||
Check that the output contains `GStreamer: YES`.
|
||||
|
||||
Videos can then be published with `cv2.VideoWriter`:
|
||||
|
||||
```python
|
||||
from datetime import datetime
|
||||
from time import sleep, time
|
||||
|
||||
import cv2
|
||||
import numpy as np
|
||||
|
||||
fps = 15
|
||||
width = 800
|
||||
height = 600
|
||||
colors = [
|
||||
(0, 0, 255),
|
||||
(255, 0, 0),
|
||||
(0, 255, 0),
|
||||
]
|
||||
|
||||
out = cv2.VideoWriter('appsrc ! videoconvert' + \
|
||||
' ! video/x-raw,format=I420' + \
|
||||
' ! x264enc speed-preset=ultrafast bitrate=600 key-int-max=' + str(fps * 2) + \
|
||||
' ! video/x-h264,profile=baseline' + \
|
||||
' ! rtspclientsink location=rtsp://localhost:8554/mystream',
|
||||
cv2.CAP_GSTREAMER, 0, fps, (width, height), True)
|
||||
if not out.isOpened():
|
||||
raise Exception("can't open video writer")
|
||||
|
||||
curcolor = 0
|
||||
start = time()
|
||||
|
||||
while True:
|
||||
frame = np.zeros((height, width, 3), np.uint8)
|
||||
|
||||
# create a rectangle
|
||||
color = colors[curcolor]
|
||||
curcolor += 1
|
||||
curcolor %= len(colors)
|
||||
for y in range(0, int(frame.shape[0] / 2)):
|
||||
for x in range(0, int(frame.shape[1] / 2)):
|
||||
frame[y][x] = color
|
||||
|
||||
out.write(frame)
|
||||
print("%s frame written to the server" % datetime.now())
|
||||
|
||||
now = time()
|
||||
diff = (1 / fps) - now - start
|
||||
if diff > 0:
|
||||
sleep(diff)
|
||||
start = now
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/mystream`.
|
||||
@@ -0,0 +1,3 @@
|
||||
# Golang
|
||||
|
||||
You can publish to the server from the Go programming language by using [gortsplib](https://github.com/bluenviron/gortsplib), a RTSP client/server library, and [gortmplib](https://github.com/bluenviron/gortmplib), a RTMP client/server library. Both powers _MediaMTX_ itself. In the repositories of these projects there are several examples on how to connect to a server and push data.
|
||||
@@ -0,0 +1,110 @@
|
||||
# Unity
|
||||
|
||||
Software written with the Unity Engine can publish a stream to the server by using the [WebRTC protocol](04-webrtc-clients.md).
|
||||
|
||||
Create a new Unity project or open an existing one.
|
||||
|
||||
Open _Window -> Package Manager_, click on the plus sign, _Add Package by name..._ and insert `com.unity.webrtc`. Wait for the package to be installed.
|
||||
|
||||
In the _Project_ window, under `Assets`, create a new C# Script called `WebRTCPublisher.cs` with this content:
|
||||
|
||||
```cs
|
||||
using System.Collections;
|
||||
using UnityEngine;
|
||||
using Unity.WebRTC;
|
||||
using UnityEngine.Networking;
|
||||
|
||||
public class WebRTCPublisher : MonoBehaviour
|
||||
{
|
||||
public string url = "http://localhost:8889/unity/whip";
|
||||
public int videoWidth = 1280;
|
||||
public int videoHeight = 720;
|
||||
|
||||
private RTCPeerConnection pc;
|
||||
private MediaStream videoStream;
|
||||
|
||||
void Start()
|
||||
{
|
||||
pc = new RTCPeerConnection();
|
||||
Camera sourceCamera = gameObject.GetComponent<Camera>();
|
||||
videoStream = sourceCamera.CaptureStream(videoWidth, videoHeight);
|
||||
foreach (var track in videoStream.GetTracks())
|
||||
{
|
||||
pc.AddTrack(track);
|
||||
}
|
||||
|
||||
StartCoroutine(WebRTC.Update());
|
||||
StartCoroutine(createOffer());
|
||||
}
|
||||
|
||||
private IEnumerator createOffer()
|
||||
{
|
||||
var op = pc.CreateOffer();
|
||||
yield return op;
|
||||
if (op.IsError) {
|
||||
Debug.LogError("CreateOffer() failed");
|
||||
yield break;
|
||||
}
|
||||
|
||||
yield return setLocalDescription(op.Desc);
|
||||
}
|
||||
|
||||
private IEnumerator setLocalDescription(RTCSessionDescription offer)
|
||||
{
|
||||
var op = pc.SetLocalDescription(ref offer);
|
||||
yield return op;
|
||||
if (op.IsError) {
|
||||
Debug.LogError("SetLocalDescription() failed");
|
||||
yield break;
|
||||
}
|
||||
|
||||
yield return postOffer(offer);
|
||||
}
|
||||
|
||||
private IEnumerator postOffer(RTCSessionDescription offer)
|
||||
{
|
||||
var content = new System.Net.Http.StringContent(offer.sdp);
|
||||
content.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue("application/sdp");
|
||||
var client = new System.Net.Http.HttpClient();
|
||||
|
||||
var task = System.Threading.Tasks.Task.Run(async () => {
|
||||
var res = await client.PostAsync(new System.UriBuilder(url).Uri, content);
|
||||
res.EnsureSuccessStatusCode();
|
||||
return await res.Content.ReadAsStringAsync();
|
||||
});
|
||||
yield return new WaitUntil(() => task.IsCompleted);
|
||||
if (task.Exception != null) {
|
||||
Debug.LogError(task.Exception);
|
||||
yield break;
|
||||
}
|
||||
|
||||
yield return setRemoteDescription(task.Result);
|
||||
}
|
||||
|
||||
private IEnumerator setRemoteDescription(string answer)
|
||||
{
|
||||
RTCSessionDescription desc = new RTCSessionDescription();
|
||||
desc.type = RTCSdpType.Answer;
|
||||
desc.sdp = answer;
|
||||
var op = pc.SetRemoteDescription(ref desc);
|
||||
yield return op;
|
||||
if (op.IsError) {
|
||||
Debug.LogError("SetRemoteDescription() failed");
|
||||
yield break;
|
||||
}
|
||||
|
||||
yield break;
|
||||
}
|
||||
|
||||
void OnDestroy()
|
||||
{
|
||||
pc?.Close();
|
||||
pc?.Dispose();
|
||||
videoStream?.Dispose();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In the _Hierarchy_ window, find or create a scene and a camera, then add the `WebRTCPublisher.cs` script as component of the camera, by dragging it inside the _Inspector_ window. then Press the _Play_ button at the top of the page.
|
||||
|
||||
The resulting stream will be available on path `/unity`.
|
||||
@@ -0,0 +1,17 @@
|
||||
# Web browsers
|
||||
|
||||
Web browsers can publish a stream to the server by using the [WebRTC protocol](04-webrtc-clients.md). Start the server and open the web page:
|
||||
|
||||
```
|
||||
http://localhost:8889/mystream/publish
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/mystream`.
|
||||
|
||||
This web page can be embedded into another web page by using an iframe:
|
||||
|
||||
```html
|
||||
<iframe src="http://mediamtx-ip:8889/mystream/publish" scrolling="no"></iframe>
|
||||
```
|
||||
|
||||
For more advanced setups, you can create and serve a custom web page by starting from the [source code of the WebRTC publish page](https://github.com/bluenviron/mediamtx/blob/{version_tag}/internal/servers/webrtc/publish_index.html). In particular, there's a ready-to-use, standalone JavaScript class for publishing streams with WebRTC, available in [publisher.js](https://github.com/bluenviron/mediamtx/blob/{version_tag}/internal/servers/webrtc/publisher.js).
|
||||
@@ -0,0 +1 @@
|
||||
# Publish
|
||||
@@ -1,865 +0,0 @@
|
||||
# Publish a stream
|
||||
|
||||
## Compatibility matrix
|
||||
|
||||
Live streams can be published to the server with the following protocols and codecs:
|
||||
|
||||
| protocol | variants | codecs |
|
||||
| ----------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| [SRT clients](#srt-clients) | | **Video**: H265, H264, MPEG-4 Video (H263, Xvid), MPEG-1/2 Video<br/>**Audio**: Opus, MPEG-4 Audio (AAC), MPEG-1/2 Audio (MP3), AC-3<br/>**Other**: KLV |
|
||||
| [SRT cameras and servers](#srt-cameras-and-servers) | | **Video**: H265, H264, MPEG-4 Video (H263, Xvid), MPEG-1/2 Video<br/>**Audio**: Opus, MPEG-4 Audio (AAC), MPEG-1/2 Audio (MP3), AC-3<br/>**Other**: KLV |
|
||||
| [WebRTC clients](#webrtc-clients) | WHIP | **Video**: AV1, VP9, VP8, H265, H264<br/>**Audio**: Opus, G722, G711 (PCMA, PCMU) |
|
||||
| [WebRTC servers](#webrtc-servers) | WHEP | **Video**: AV1, VP9, VP8, H265, H264<br/>**Audio**: Opus, G722, G711 (PCMA, PCMU) |
|
||||
| [RTSP clients](#rtsp-clients) | UDP, TCP, RTSPS | **Video**: AV1, VP9, VP8, H265, H264, MPEG-4 Video (H263, Xvid), MPEG-1/2 Video, MJPEG<br/>**Audio**: Opus, MPEG-4 Audio (AAC), MPEG-1/2 Audio (MP3), AC-3, G726, G722, G711 (PCMA, PCMU), LPCM<br/>**Other**: KLV, MPEG-TS, any RTP-compatible codec |
|
||||
| [RTSP cameras and servers](#rtsp-cameras-and-servers) | UDP, UDP-Multicast, TCP, RTSPS | **Video**: AV1, VP9, VP8, H265, H264, MPEG-4 Video (H263, Xvid), MPEG-1/2 Video, MJPEG<br/>**Audio**: Opus, MPEG-4 Audio (AAC), MPEG-1/2 Audio (MP3), AC-3, G726, G722, G711 (PCMA, PCMU), LPCM<br/>**Other**: KLV, MPEG-TS, any RTP-compatible codec |
|
||||
| [RTMP clients](#rtmp-clients) | RTMP, RTMPS, Enhanced RTMP | **Video**: AV1, VP9, H265, H264<br/>**Audio**: Opus, MPEG-4 Audio (AAC), MPEG-1/2 Audio (MP3), AC-3, G711 (PCMA, PCMU), LPCM |
|
||||
| [RTMP cameras and servers](#rtmp-cameras-and-servers) | RTMP, RTMPS, Enhanced RTMP | **Video**: AV1, VP9, H265, H264<br/>**Audio**: Opus, MPEG-4 Audio (AAC), MPEG-1/2 Audio (MP3), AC-3, G711 (PCMA, PCMU), LPCM |
|
||||
| [HLS cameras and servers](#hls-cameras-and-servers) | Low-Latency HLS, MP4-based HLS, legacy HLS | **Video**: AV1, VP9, H265, H264<br/>**Audio**: Opus, MPEG-4 Audio (AAC) |
|
||||
| [MPEG-TS](#mpeg-ts) | MPEG-TS over UDP, MPEG-TS over Unix socket | **Video**: H265, H264, MPEG-4 Video (H263, Xvid), MPEG-1/2 Video<br/>**Audio**: Opus, MPEG-4 Audio (AAC), MPEG-1/2 Audio (MP3), AC-3<br/>**Other**: KLV |
|
||||
| [RTP](#rtp) | RTP over UDP | **Video**: AV1, VP9, VP8, H265, H264, MPEG-4 Video (H263, Xvid), MPEG-1/2 Video, M-JPEG<br/>**Audio**: Opus, MPEG-4 Audio (AAC), MPEG-1/2 Audio (MP3), AC-3, G726, G722, G711 (PCMA, PCMU), LPCM<br/>**Other**: KLV, MPEG-TS, any RTP-compatible codec |
|
||||
|
||||
We provide instructions for publishing with the following devices:
|
||||
|
||||
- [Raspberry Pi Cameras](#raspberry-pi-cameras)
|
||||
- [Generic webcams](#generic-webcams)
|
||||
|
||||
We provide instructions for publishing with the following software:
|
||||
|
||||
- [FFmpeg](#ffmpeg)
|
||||
- [GStreamer](#gstreamer)
|
||||
- [OBS Studio](#obs-studio)
|
||||
- [Python and OpenCV](#python-and-opencv)
|
||||
- [Golang](#golang)
|
||||
- [Unity](#unity)
|
||||
- [Web browsers](#web-browsers)
|
||||
|
||||
## Protocols
|
||||
|
||||
### SRT clients
|
||||
|
||||
SRT is a protocol that allows to publish and read live data stream, providing encryption, integrity and a retransmission mechanism. It is usually used to transfer media streams encoded with MPEG-TS. In order to publish a stream to the server with the SRT protocol, use this URL:
|
||||
|
||||
```
|
||||
srt://localhost:8890?streamid=publish:mystream&pkt_size=1316
|
||||
```
|
||||
|
||||
Replace `mystream` with any name you want. The resulting stream will be available on path `/mystream`.
|
||||
|
||||
If you need to use the standard stream ID syntax instead of the custom one in use by this server, see [Standard stream ID syntax](23-srt-specific-features.md#standard-stream-id-syntax).
|
||||
|
||||
If you want to publish a stream by using a client in listening mode (i.e. with `mode=listener` appended to the URL), read the next section.
|
||||
|
||||
Some clients that can publish with SRT are [FFmpeg](#ffmpeg), [GStreamer](#gstreamer), [OBS Studio](#obs-studio).
|
||||
|
||||
### SRT cameras and servers
|
||||
|
||||
In order to ingest a SRT stream from a remote server, camera or client in listening mode (i.e. with `mode=listener` appended to the URL), add the corresponding URL into the `source` parameter of a path:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
proxied:
|
||||
# url of the source stream, in the format srt://host:port?streamid=streamid&other_parameters
|
||||
source: srt://original-url
|
||||
```
|
||||
|
||||
### WebRTC clients
|
||||
|
||||
WebRTC is an API that makes use of a set of protocols and methods to connect two clients together and allow them to exchange live media or data streams. You can publish a stream with WebRTC and a web browser by visiting:
|
||||
|
||||
```
|
||||
http://localhost:8889/mystream/publish
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/mystream`.
|
||||
|
||||
WHIP is a WebRTC extensions that allows to publish streams by using a URL, without passing through a web page. This allows to use WebRTC as a general purpose streaming protocol. If you are using a software that supports WHIP (for instance, latest versions of OBS Studio), you can publish a stream to the server by using this URL:
|
||||
|
||||
```
|
||||
http://localhost:8889/mystream/whip
|
||||
```
|
||||
|
||||
Be aware that not all browsers can read any codec, check [Supported browsers](24-webrtc-specific-features.md#supported-browsers).
|
||||
|
||||
Depending on the network it might be difficult to establish a connection between server and clients, read [Solving WebRTC connectivity issues](24-webrtc-specific-features.md#solving-webrtc-connectivity-issues).
|
||||
|
||||
Some clients that can publish with WebRTC and WHIP are [FFmpeg](#ffmpeg), [GStreamer](#gstreamer), [OBS Studio](#obs-studio), [Unity](#unity) and [Web browsers](#web-browsers).
|
||||
|
||||
### WebRTC servers
|
||||
|
||||
In order to ingest a WebRTC stream from a remote server, add the corresponding WHEP URL into the `source` parameter of a path:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
proxied:
|
||||
# url of the source stream, in the format whep://host:port/path (HTTP) or wheps:// (HTTPS)
|
||||
source: wheps://host:port/path
|
||||
```
|
||||
|
||||
If the remote server is a _MediaMTX_ instance, remember to add a `/whep` suffix after the stream name, since in _MediaMTX_ [it's part of the WHEP URL](03-read.md#webrtc):
|
||||
|
||||
```yml
|
||||
paths:
|
||||
proxied:
|
||||
source: whep://host:port/mystream/whep
|
||||
```
|
||||
|
||||
### RTSP clients
|
||||
|
||||
RTSP is a protocol that allows to publish and read streams. It supports several underlying transport protocols and encryption (see [RTSP-specific features](25-rtsp-specific-features.md)). In order to publish a stream to the server with the RTSP protocol, use this URL:
|
||||
|
||||
```
|
||||
rtsp://localhost:8554/mystream
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/mystream`.
|
||||
|
||||
Some clients that can publish with RTSP are [FFmpeg](#ffmpeg), [GStreamer](#gstreamer), [OBS Studio](#obs-studio), [Python and OpenCV](#python-and-opencv).
|
||||
|
||||
### RTSP cameras and servers
|
||||
|
||||
Most IP cameras expose their video stream by using a RTSP server that is embedded into the camera itself. In particular, cameras that are compliant with ONVIF profile S or T meet this requirement. You can use _MediaMTX_ to connect to one or several existing RTSP servers and read their media streams:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
proxied:
|
||||
# url of the source stream, in the format rtsp://user:pass@host:port/path
|
||||
source: rtsp://original-url
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/proxied`.
|
||||
|
||||
It is possible to tune the connection by using some additional parameters:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
proxied:
|
||||
# url of the source stream, in the format rtsp://user:pass@host:port/path
|
||||
source: rtsp://original-url
|
||||
# Transport protocol used to pull the stream. available values are "automatic", "udp", "multicast", "tcp".
|
||||
rtspTransport: automatic
|
||||
# Support sources that don't provide server ports or use random server ports. This is a security issue
|
||||
# and must be used only when interacting with sources that require it.
|
||||
rtspAnyPort: no
|
||||
# Range header to send to the source, in order to start streaming from the specified offset.
|
||||
# available values:
|
||||
# * clock: Absolute time
|
||||
# * npt: Normal Play Time
|
||||
# * smpte: SMPTE timestamps relative to the start of the recording
|
||||
rtspRangeType:
|
||||
# Available values:
|
||||
# * clock: UTC ISO 8601 combined date and time string, e.g. 20230812T120000Z
|
||||
# * npt: duration such as "300ms", "1.5m" or "2h45m", valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h"
|
||||
# * smpte: duration such as "300ms", "1.5m" or "2h45m", valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h"
|
||||
rtspRangeStart:
|
||||
# Size of the UDP buffer of the RTSP client.
|
||||
# This can be increased to mitigate packet losses.
|
||||
# It defaults to the default value of the operating system.
|
||||
rtspUDPReadBufferSize: 0
|
||||
# Range of ports used as source port in outgoing UDP packets.
|
||||
rtspUDPSourcePortRange: [10000, 65535]
|
||||
```
|
||||
|
||||
All available parameters are listed in the [configuration file](../3-references/1-configuration-file.md).
|
||||
|
||||
Advanced RTSP features are described in [RTSP-specific features](25-rtsp-specific-features.md).
|
||||
|
||||
### RTMP clients
|
||||
|
||||
RTMP is a protocol that allows to read and publish streams. It supports encryption, see [RTMP-specific features](26-rtmp-specific-features.md). Streams can be published to the server by using the URL:
|
||||
|
||||
```
|
||||
rtmp://localhost/mystream
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/mystream`.
|
||||
|
||||
Some clients that can publish with RTMP are [FFmpeg](#ffmpeg), [GStreamer](#gstreamer), [OBS Studio](#obs-studio).
|
||||
|
||||
### RTMP cameras and servers
|
||||
|
||||
You can use _MediaMTX_ to connect to one or several existing RTMP servers and read their media streams:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
proxied:
|
||||
# url of the source stream, in the format rtmp://user:pass@host:port/path
|
||||
source: rtmp://original-url
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/proxied`.
|
||||
|
||||
### HLS cameras and servers
|
||||
|
||||
HLS is a streaming protocol that works by splitting streams into segments, and by serving these segments and a playlist with the HTTP protocol. You can use _MediaMTX_ to connect to one or several existing HLS servers and read their media streams:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
proxied:
|
||||
# url of the playlist of the stream, in the format http://user:pass@host:port/path
|
||||
source: http://original-url/stream/index.m3u8
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/proxied`.
|
||||
|
||||
### MPEG-TS
|
||||
|
||||
The server supports ingesting MPEG-TS streams, shipped in two different ways (UDP packets or Unix sockets).
|
||||
|
||||
In order to read a UDP MPEG-TS stream, edit `mediamtx.yml` and replace everything inside section `paths` with the following content:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
mypath:
|
||||
source: udp+mpegts://238.0.0.1:1234
|
||||
```
|
||||
|
||||
Where `238.0.0.1` is the IP for listening packets, in this case a multicast IP.
|
||||
|
||||
If the listening IP is a multicast IP, _MediaMTX_ will listen for incoming packets on the default multicast interface, picked by the operating system. It is possible to specify the interface manually by using the `interface` parameter:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
mypath:
|
||||
source: udp+mpegts://238.0.0.1:1234?interface=eth0
|
||||
```
|
||||
|
||||
It is possible to restrict who can send packets by using the `source` parameter:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
mypath:
|
||||
source: udp+mpegts://0.0.0.0:1234?source=192.168.3.5
|
||||
```
|
||||
|
||||
Some clients that can publish with UDP and MPEG-TS are [FFmpeg](#ffmpeg) and [GStreamer](#gstreamer).
|
||||
|
||||
Unix sockets are more efficient than UDP packets and can be used as transport by specifying the `unix+mpegts` scheme:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
mypath:
|
||||
source: unix+mpegts:///tmp/socket.sock
|
||||
```
|
||||
|
||||
### RTP
|
||||
|
||||
The server supports ingesting RTP streams, shipped in two different ways (UDP packets or Unix sockets).
|
||||
|
||||
In order to read a UDP RTP stream, edit `mediamtx.yml` and replace everything inside section `paths` with the following content:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
mypath:
|
||||
source: udp+rtp://238.0.0.1:1234
|
||||
rtpSDP: |
|
||||
v=0
|
||||
o=- 123456789 123456789 IN IP4 192.168.1.100
|
||||
s=H264 Video Stream
|
||||
c=IN IP4 192.168.1.100
|
||||
t=0 0
|
||||
m=video 5004 RTP/AVP 96
|
||||
a=rtpmap:96 H264/90000
|
||||
a=fmtp:96 profile-level-id=42e01e;packetization-mode=1;sprop-parameter-sets=Z0LAHtkDxWhAAAADAEAAAAwDxYuS,aMuMsg==
|
||||
```
|
||||
|
||||
`rtpSDP` must contain a valid SDP, that is a description of the RTP session.
|
||||
|
||||
Some clients that can publish with UDP and MPEG-TS are [FFmpeg](#ffmpeg) and [GStreamer](#gstreamer).
|
||||
|
||||
## Devices
|
||||
|
||||
### Raspberry Pi Cameras
|
||||
|
||||
_MediaMTX_ natively supports most Raspberry Pi Camera models, enabling high-quality and low-latency video streaming from the camera to any user, for any purpose. There are some additional requirements:
|
||||
|
||||
1. The server must run on a Raspberry Pi, with one of the following operating systems:
|
||||
- Raspberry Pi OS Trixie
|
||||
- Raspberry Pi OS Bookworm
|
||||
- Raspberry Pi OS Bullseye
|
||||
|
||||
Both 32-bit and 64-bit architectures are supported.
|
||||
|
||||
2. If you are using Raspberry Pi OS Bullseye, make sure that the legacy camera stack is disabled. Type `sudo raspi-config`, then go to `Interfacing options`, `enable/disable legacy camera support`, choose `no`. Reboot the system.
|
||||
|
||||
The setup procedure depends on whether you want to run the server outside or inside Docker:
|
||||
|
||||
- If you want to run the standard (non-Dockerized) version of the server:
|
||||
1. Download the server executable. If you're using 64-bit version of the operative system, make sure to pick the `arm64` variant.
|
||||
|
||||
2. Edit `mediamtx.yml` and replace everything inside section `paths` with the following content:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
cam:
|
||||
source: rpiCamera
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/cam`.
|
||||
|
||||
- If you want to run the server inside Docker, you need to use the `1-rpi` image and launch the container with some additional flags:
|
||||
|
||||
```sh
|
||||
docker run --rm -it \
|
||||
--network=host \
|
||||
--privileged \
|
||||
--tmpfs /dev/shm:exec \
|
||||
-v /run/udev:/run/udev:ro \
|
||||
-e MTX_PATHS_CAM_SOURCE=rpiCamera \
|
||||
bluenviron/mediamtx:1-rpi
|
||||
```
|
||||
|
||||
The Raspberry Pi Camera can be controlled through a wide range of parameters, that are listed in the [configuration file](/docs/references/configuration-file).
|
||||
|
||||
Be aware that cameras that require a custom `libcamera` (like some ArduCam products) are not compatible with precompiled binaries and Docker images of _MediaMTX_, since these come with a bundled `libcamera`. If you want to use a custom one, you need to [compile from source](../4-other/1-compile.md#custom-libcamera).
|
||||
|
||||
#### Adding audio
|
||||
|
||||
In order to add audio from a USB microfone, install GStreamer and alsa-utils:
|
||||
|
||||
```sh
|
||||
sudo apt install -y gstreamer1.0-tools gstreamer1.0-rtsp gstreamer1.0-alsa alsa-utils
|
||||
```
|
||||
|
||||
list available audio cards with:
|
||||
|
||||
```sh
|
||||
arecord -L
|
||||
```
|
||||
|
||||
Sample output:
|
||||
|
||||
```
|
||||
surround51:CARD=ICH5,DEV=0
|
||||
Intel ICH5, Intel ICH5
|
||||
5.1 Surround output to Front, Center, Rear and Subwoofer speakers
|
||||
default:CARD=U0x46d0x809
|
||||
USB Device 0x46d:0x809, USB Audio
|
||||
Default Audio Device
|
||||
```
|
||||
|
||||
Find the audio card of the microfone and take note of its name, for instance `default:CARD=U0x46d0x809`. Then create a new path that takes the video stream from the camera and audio from the microphone:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
cam:
|
||||
source: rpiCamera
|
||||
|
||||
cam_with_audio:
|
||||
runOnInit: >
|
||||
gst-launch-1.0
|
||||
rtspclientsink name=s location=rtsp://localhost:$RTSP_PORT/cam_with_audio
|
||||
rtspsrc location=rtsp://127.0.0.1:$RTSP_PORT/cam latency=0 ! rtph264depay ! s.
|
||||
alsasrc device=default:CARD=U0x46d0x809 ! opusenc bitrate=16000 ! s.
|
||||
runOnInitRestart: yes
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/cam_with_audio`.
|
||||
|
||||
#### Secondary stream
|
||||
|
||||
It is possible to enable a secondary stream from the same camera, with a different resolution, FPS and codec. Configuration is the same of a primary stream, with `rpiCameraSecondary` set to `true` and parameters adjusted accordingly:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
# primary stream
|
||||
rpi:
|
||||
source: rpiCamera
|
||||
# Width of frames.
|
||||
rpiCameraWidth: 1920
|
||||
# Height of frames.
|
||||
rpiCameraHeight: 1080
|
||||
# FPS.
|
||||
rpiCameraFPS: 30
|
||||
|
||||
# secondary stream
|
||||
secondary:
|
||||
source: rpiCamera
|
||||
# This is a secondary stream.
|
||||
rpiCameraSecondary: true
|
||||
# Width of frames.
|
||||
rpiCameraWidth: 640
|
||||
# Height of frames.
|
||||
rpiCameraHeight: 480
|
||||
# FPS.
|
||||
rpiCameraFPS: 10
|
||||
# Codec. in case of secondary streams, it defaults to M-JPEG.
|
||||
rpiCameraCodec: auto
|
||||
# JPEG quality.
|
||||
rpiCameraMJPEGQuality: 60
|
||||
```
|
||||
|
||||
The secondary stream will be available on path `/secondary`.
|
||||
|
||||
### Generic webcams
|
||||
|
||||
If the operating system is Linux, edit `mediamtx.yml` and replace everything inside section `paths` with the following content:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
cam:
|
||||
runOnInit: ffmpeg -f v4l2 -i /dev/video0 -c:v libx264 -pix_fmt yuv420p -preset ultrafast -b:v 600k -f rtsp rtsp://localhost:$RTSP_PORT/$MTX_PATH
|
||||
runOnInitRestart: yes
|
||||
```
|
||||
|
||||
If the operating system is Windows:
|
||||
|
||||
```yml
|
||||
paths:
|
||||
cam:
|
||||
runOnInit: ffmpeg -f dshow -i video="USB2.0 HD UVC WebCam" -c:v libx264 -pix_fmt yuv420p -preset ultrafast -b:v 600k -f rtsp rtsp://localhost:$RTSP_PORT/$MTX_PATH
|
||||
runOnInitRestart: yes
|
||||
```
|
||||
|
||||
Where `USB2.0 HD UVC WebCam` is the name of a webcam, that can be obtained with:
|
||||
|
||||
```sh
|
||||
ffmpeg -list_devices true -f dshow -i dummy
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/cam`.
|
||||
|
||||
## Software
|
||||
|
||||
### FFmpeg
|
||||
|
||||
FFmpeg can publish a stream to the server in several ways. The recommended one consists in publishing with RTSP.
|
||||
|
||||
#### FFmpeg and RTSP
|
||||
|
||||
```sh
|
||||
ffmpeg -re -stream_loop -1 -i file.mp4 -c copy -f rtsp rtsp://localhost:8554/mystream
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/mystream`.
|
||||
|
||||
#### FFmpeg and RTMP
|
||||
|
||||
```sh
|
||||
ffmpeg -re -stream_loop -1 -i file.mp4 -c copy -f flv rtmp://localhost:1935/mystream
|
||||
```
|
||||
|
||||
#### FFmpeg and MPEG-TS over UDP
|
||||
|
||||
In _MediaMTX_ configuration, add a path with `source: udp+mpegts://238.0.0.1:1234`. Then:
|
||||
|
||||
```sh
|
||||
ffmpeg -re -stream_loop -1 -i file.mp4 -c copy -f mpegts 'udp://238.0.0.1:1234?pkt_size=1316'
|
||||
```
|
||||
|
||||
#### FFmpeg and MPEG-TS over Unix socket
|
||||
|
||||
In _MediaMTX_ configuration, add a path with `source: unix+mpegts:///tmp/socket.sock`. Then:
|
||||
|
||||
```sh
|
||||
ffmpeg -re -f lavfi -i testsrc=size=1280x720:rate=30 \
|
||||
-c:v libx264 -pix_fmt yuv420p -preset ultrafast -b:v 600k \
|
||||
-f mpegts unix:/tmp/socket.sock
|
||||
```
|
||||
|
||||
#### FFmpeg and RTP over UDP
|
||||
|
||||
In _MediaMTX_ configuration, add a path with `source: udp+rtp://238.0.0.1:1234` and a valid `rtpSDP` (see [RTP](#rtp)). Then:
|
||||
|
||||
```sh
|
||||
ffmpeg -re -f lavfi -i testsrc=size=1280x720:rate=30 \
|
||||
-c:v libx264 -pix_fmt yuv420p -preset ultrafast -b:v 600k \
|
||||
-f rtp udp://238.0.0.1:1234?pkt_size=1316
|
||||
```
|
||||
|
||||
#### FFmpeg and SRT
|
||||
|
||||
```sh
|
||||
ffmpeg -re -stream_loop -1 -i file.mp4 -c copy -f mpegts 'srt://localhost:8890?streamid=publish:stream&pkt_size=1316'
|
||||
```
|
||||
|
||||
#### FFmpeg and WebRTC
|
||||
|
||||
```sh
|
||||
ffmpeg -re -f lavfi -i testsrc=size=1280x720:rate=30 \
|
||||
-f lavfi -i "sine=frequency=1000:sample_rate=48000" \
|
||||
-c:v libx264 -pix_fmt yuv420p -preset ultrafast -b:v 600k \
|
||||
-c:a libopus -ar 48000 -ac 2 -b:a 128k \
|
||||
-f whip http://localhost:8889/stream/whip
|
||||
```
|
||||
|
||||
WARNING: in case of FFmpeg 8.0, a video track and an audio track must both be present.
|
||||
|
||||
### GStreamer
|
||||
|
||||
GStreamer can publish a stream to the server in several ways. The recommended one consists in publishing with RTSP.
|
||||
|
||||
#### GStreamer and RTSP
|
||||
|
||||
```sh
|
||||
gst-launch-1.0 rtspclientsink name=s location=rtsp://localhost:8554/mystream \
|
||||
filesrc location=file.mp4 ! qtdemux name=d \
|
||||
d.video_0 ! queue ! s.sink_0 \
|
||||
d.audio_0 ! queue ! s.sink_1
|
||||
```
|
||||
|
||||
If the stream is video only:
|
||||
|
||||
```sh
|
||||
gst-launch-1.0 filesrc location=file.mp4 ! qtdemux name=d \
|
||||
d.video_0 ! rtspclientsink location=rtsp://localhost:8554/mystream
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/mystream`.
|
||||
|
||||
For advanced options, see [RTSP-specific features](25-rtsp-specific-features.md).
|
||||
|
||||
#### GStreamer and RTMP
|
||||
|
||||
```sh
|
||||
gst-launch-1.0 -v flvmux name=mux ! rtmpsink location=rtmp://localhost/stream \
|
||||
videotestsrc ! video/x-raw,width=1280,height=720,format=I420 ! x264enc speed-preset=ultrafast bitrate=3000 key-int-max=60 ! video/x-h264,profile=high ! mux. \
|
||||
audiotestsrc ! audioconvert ! avenc_aac ! mux.
|
||||
```
|
||||
|
||||
#### GStreamer and MPEG-TS over UDP
|
||||
|
||||
```sh
|
||||
gst-launch-1.0 -v mpegtsmux name=mux alignment=1 ! udpsink host=238.0.0.1 port=1234 \
|
||||
videotestsrc ! video/x-raw,width=1280,height=720,format=I420 ! x264enc speed-preset=ultrafast bitrate=3000 key-int-max=60 ! video/x-h264,profile=high ! mux. \
|
||||
audiotestsrc ! audioconvert ! avenc_aac ! mux.
|
||||
```
|
||||
|
||||
For advanced options, see [RTSP-specific features](25-rtsp-specific-features.md).
|
||||
|
||||
#### GStreamer and WebRTC
|
||||
|
||||
Make sure that GStreamer version is at least 1.22, and that if the codec is H264, the profile is baseline. Use the `whipclientsink` element:
|
||||
|
||||
```sh
|
||||
gst-launch-1.0 videotestsrc \
|
||||
! video/x-raw,width=1920,height=1080,format=I420 \
|
||||
! x264enc speed-preset=ultrafast bitrate=2000 \
|
||||
! video/x-h264,profile=baseline \
|
||||
! whipclientsink signaller::whip-endpoint=http://localhost:8889/mystream/whip
|
||||
```
|
||||
|
||||
### OBS Studio
|
||||
|
||||
OBS Studio can publish to the server in several ways. The recommended one consists in publishing with RTMP.
|
||||
|
||||
#### OBS Studio and RTMP
|
||||
|
||||
In `Settings -> Stream` (or in the Auto-configuration Wizard), use the following parameters:
|
||||
|
||||
- Service: `Custom...`
|
||||
- Server: `rtmp://localhost/mystream`
|
||||
- Stream key: (empty)
|
||||
|
||||
Save the configuration and click `Start streaming`.
|
||||
|
||||
The resulting stream will be available on path `/mystream`.
|
||||
|
||||
If you want to generate a stream that can be read with WebRTC, open `Settings -> Output -> Recording` and use the following parameters:
|
||||
|
||||
- FFmpeg output type: `Output to URL`
|
||||
- File path or URL: `rtsp://localhost:8554/mystream`
|
||||
- Container format: `rtsp`
|
||||
- Check `show all codecs (even if potentially incompatible)`
|
||||
- Video encoder: `h264_nvenc (libx264)`
|
||||
- Video encoder settings (if any): `bf=0`
|
||||
- Audio track: `1`
|
||||
- Audio encoder: `libopus`
|
||||
|
||||
Then use the button `Start Recording` (instead of `Start Streaming`) to start streaming.
|
||||
|
||||
#### OBS Studio and RTMP, multitrack video
|
||||
|
||||
OBS Studio can publish multiple video tracks or renditions at once. Make sure that the OBS Studio version is ≥ 31.0.0. Open `Settings -> Stream` and use the following parameters:
|
||||
|
||||
- Service: `Custom...`
|
||||
- Server: `rtmp://localhost/mystream`
|
||||
- Stream key: (empty)
|
||||
- Turn on `Enable Multitrack Video`
|
||||
- Leave `Maximum Streaming Bandwidth` and `Maximum Video Tracks` to `Auto`
|
||||
- Turn on `Enable Config Override`
|
||||
- Fill `Config Override (JSON)` with the following text:
|
||||
|
||||
```json
|
||||
{
|
||||
"encoder_configurations": [
|
||||
{
|
||||
"type": "obs_x264",
|
||||
"width": 1920,
|
||||
"height": 1080,
|
||||
"framerate": {
|
||||
"numerator": 30,
|
||||
"denominator": 1
|
||||
},
|
||||
"settings": {
|
||||
"rate_control": "CBR",
|
||||
"bitrate": 6000,
|
||||
"keyint_sec": 2,
|
||||
"preset": "veryfast",
|
||||
"profile": "high",
|
||||
"tune": "zerolatency"
|
||||
},
|
||||
"canvas_index": 0
|
||||
},
|
||||
{
|
||||
"type": "obs_x264",
|
||||
"width": 640,
|
||||
"height": 480,
|
||||
"framerate": {
|
||||
"numerator": 30,
|
||||
"denominator": 1
|
||||
},
|
||||
"settings": {
|
||||
"rate_control": "CBR",
|
||||
"bitrate": 3000,
|
||||
"keyint_sec": 2,
|
||||
"preset": "veryfast",
|
||||
"profile": "main",
|
||||
"tune": "zerolatency"
|
||||
},
|
||||
"canvas_index": 0
|
||||
}
|
||||
],
|
||||
"audio_configurations": {
|
||||
"live": [
|
||||
{
|
||||
"codec": "ffmpeg_aac",
|
||||
"track_id": 1,
|
||||
"channels": 2,
|
||||
"settings": {
|
||||
"bitrate": 160
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This can be adjusted according to specific needs. In particular, the `type` field is used to set the video encoder, and these are the available parameters:
|
||||
- `obs_nvenc_av1_tex`: NVIDIA NVENC AV1
|
||||
- `obs_nvenc_hevc_tex`: NVIDIA NVENC H265
|
||||
- `obs_nvenc_h264_tex`: NVIDIA NVENC H264
|
||||
- `av1_texture_amf`: AMD AV1
|
||||
- `h265_texture_amf`: AMD H265
|
||||
- `h264_texture_amf`: AMD H264
|
||||
- `obs_qsv11_av1`: QuickSync AV1
|
||||
- `obs_qsv11_v2`: QuickSync H264
|
||||
- `obs_x264`: software H264
|
||||
|
||||
#### OBS Studio and WebRTC
|
||||
|
||||
Recent versions of OBS Studio can also publish to the server with the [WebRTC / WHIP protocol](#webrtc-clients) Use the following parameters:
|
||||
|
||||
- Service: `WHIP`
|
||||
- Server: `http://localhost:8889/mystream/whip`
|
||||
|
||||
Save the configuration and click `Start streaming`.
|
||||
|
||||
The resulting stream will be available on path `/mystream`.
|
||||
|
||||
### Python and OpenCV
|
||||
|
||||
Python-based software can publish to the server with the OpenCV library and its GStreamer plugin, acting as a [RTSP client](#rtsp-clients). OpenCV must be compiled with support for GStreamer, by following this procedure:
|
||||
|
||||
```sh
|
||||
sudo apt install -y libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev gstreamer1.0-plugins-ugly gstreamer1.0-rtsp python3-dev python3-numpy
|
||||
git clone --depth=1 -b 4.5.4 https://github.com/opencv/opencv
|
||||
cd opencv
|
||||
mkdir build && cd build
|
||||
cmake -D CMAKE_INSTALL_PREFIX=/usr -D WITH_GSTREAMER=ON ..
|
||||
make -j$(nproc)
|
||||
sudo make install
|
||||
```
|
||||
|
||||
You can check that OpenCV has been installed correctly by running:
|
||||
|
||||
```sh
|
||||
python3 -c 'import cv2; print(cv2.getBuildInformation())'
|
||||
```
|
||||
|
||||
Check that the output contains `GStreamer: YES`.
|
||||
|
||||
Videos can then be published with `cv2.VideoWriter`:
|
||||
|
||||
```python
|
||||
from datetime import datetime
|
||||
from time import sleep, time
|
||||
|
||||
import cv2
|
||||
import numpy as np
|
||||
|
||||
fps = 15
|
||||
width = 800
|
||||
height = 600
|
||||
colors = [
|
||||
(0, 0, 255),
|
||||
(255, 0, 0),
|
||||
(0, 255, 0),
|
||||
]
|
||||
|
||||
out = cv2.VideoWriter('appsrc ! videoconvert' + \
|
||||
' ! video/x-raw,format=I420' + \
|
||||
' ! x264enc speed-preset=ultrafast bitrate=600 key-int-max=' + str(fps * 2) + \
|
||||
' ! video/x-h264,profile=baseline' + \
|
||||
' ! rtspclientsink location=rtsp://localhost:8554/mystream',
|
||||
cv2.CAP_GSTREAMER, 0, fps, (width, height), True)
|
||||
if not out.isOpened():
|
||||
raise Exception("can't open video writer")
|
||||
|
||||
curcolor = 0
|
||||
start = time()
|
||||
|
||||
while True:
|
||||
frame = np.zeros((height, width, 3), np.uint8)
|
||||
|
||||
# create a rectangle
|
||||
color = colors[curcolor]
|
||||
curcolor += 1
|
||||
curcolor %= len(colors)
|
||||
for y in range(0, int(frame.shape[0] / 2)):
|
||||
for x in range(0, int(frame.shape[1] / 2)):
|
||||
frame[y][x] = color
|
||||
|
||||
out.write(frame)
|
||||
print("%s frame written to the server" % datetime.now())
|
||||
|
||||
now = time()
|
||||
diff = (1 / fps) - now - start
|
||||
if diff > 0:
|
||||
sleep(diff)
|
||||
start = now
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/mystream`.
|
||||
|
||||
### Golang
|
||||
|
||||
You can publish to the server from the Go programming language by using [gortsplib](https://github.com/bluenviron/gortsplib), a RTSP client/server library, and [gortmplib](https://github.com/bluenviron/gortmplib), a RTMP client/server library. Both powers _MediaMTX_ itself. In the repositories of these projects there are several examples on how to connect to a server and push data.
|
||||
|
||||
### Unity
|
||||
|
||||
Software written with the Unity Engine can publish a stream to the server by using the [WebRTC protocol](#webrtc-clients).
|
||||
|
||||
Create a new Unity project or open an existing one.
|
||||
|
||||
Open _Window -> Package Manager_, click on the plus sign, _Add Package by name..._ and insert `com.unity.webrtc`. Wait for the package to be installed.
|
||||
|
||||
In the _Project_ window, under `Assets`, create a new C# Script called `WebRTCPublisher.cs` with this content:
|
||||
|
||||
```cs
|
||||
using System.Collections;
|
||||
using UnityEngine;
|
||||
using Unity.WebRTC;
|
||||
using UnityEngine.Networking;
|
||||
|
||||
public class WebRTCPublisher : MonoBehaviour
|
||||
{
|
||||
public string url = "http://localhost:8889/unity/whip";
|
||||
public int videoWidth = 1280;
|
||||
public int videoHeight = 720;
|
||||
|
||||
private RTCPeerConnection pc;
|
||||
private MediaStream videoStream;
|
||||
|
||||
void Start()
|
||||
{
|
||||
pc = new RTCPeerConnection();
|
||||
Camera sourceCamera = gameObject.GetComponent<Camera>();
|
||||
videoStream = sourceCamera.CaptureStream(videoWidth, videoHeight);
|
||||
foreach (var track in videoStream.GetTracks())
|
||||
{
|
||||
pc.AddTrack(track);
|
||||
}
|
||||
|
||||
StartCoroutine(WebRTC.Update());
|
||||
StartCoroutine(createOffer());
|
||||
}
|
||||
|
||||
private IEnumerator createOffer()
|
||||
{
|
||||
var op = pc.CreateOffer();
|
||||
yield return op;
|
||||
if (op.IsError) {
|
||||
Debug.LogError("CreateOffer() failed");
|
||||
yield break;
|
||||
}
|
||||
|
||||
yield return setLocalDescription(op.Desc);
|
||||
}
|
||||
|
||||
private IEnumerator setLocalDescription(RTCSessionDescription offer)
|
||||
{
|
||||
var op = pc.SetLocalDescription(ref offer);
|
||||
yield return op;
|
||||
if (op.IsError) {
|
||||
Debug.LogError("SetLocalDescription() failed");
|
||||
yield break;
|
||||
}
|
||||
|
||||
yield return postOffer(offer);
|
||||
}
|
||||
|
||||
private IEnumerator postOffer(RTCSessionDescription offer)
|
||||
{
|
||||
var content = new System.Net.Http.StringContent(offer.sdp);
|
||||
content.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue("application/sdp");
|
||||
var client = new System.Net.Http.HttpClient();
|
||||
|
||||
var task = System.Threading.Tasks.Task.Run(async () => {
|
||||
var res = await client.PostAsync(new System.UriBuilder(url).Uri, content);
|
||||
res.EnsureSuccessStatusCode();
|
||||
return await res.Content.ReadAsStringAsync();
|
||||
});
|
||||
yield return new WaitUntil(() => task.IsCompleted);
|
||||
if (task.Exception != null) {
|
||||
Debug.LogError(task.Exception);
|
||||
yield break;
|
||||
}
|
||||
|
||||
yield return setRemoteDescription(task.Result);
|
||||
}
|
||||
|
||||
private IEnumerator setRemoteDescription(string answer)
|
||||
{
|
||||
RTCSessionDescription desc = new RTCSessionDescription();
|
||||
desc.type = RTCSdpType.Answer;
|
||||
desc.sdp = answer;
|
||||
var op = pc.SetRemoteDescription(ref desc);
|
||||
yield return op;
|
||||
if (op.IsError) {
|
||||
Debug.LogError("SetRemoteDescription() failed");
|
||||
yield break;
|
||||
}
|
||||
|
||||
yield break;
|
||||
}
|
||||
|
||||
void OnDestroy()
|
||||
{
|
||||
pc?.Close();
|
||||
pc?.Dispose();
|
||||
videoStream?.Dispose();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In the _Hierarchy_ window, find or create a scene and a camera, then add the `WebRTCPublisher.cs` script as component of the camera, by dragging it inside the _Inspector_ window. then Press the _Play_ button at the top of the page.
|
||||
|
||||
The resulting stream will be available on path `/unity`.
|
||||
|
||||
### Web browsers
|
||||
|
||||
Web browsers can publish a stream to the server by using the [WebRTC protocol](#webrtc-clients). Start the server and open the web page:
|
||||
|
||||
```
|
||||
http://localhost:8889/mystream/publish
|
||||
```
|
||||
|
||||
The resulting stream will be available on path `/mystream`.
|
||||
|
||||
This web page can be embedded into another web page by using an iframe:
|
||||
|
||||
```html
|
||||
<iframe src="http://mediamtx-ip:8889/mystream/publish" scrolling="no"></iframe>
|
||||
```
|
||||
|
||||
For more advanced setups, you can create and serve a custom web page by starting from the [source code of the WebRTC publish page](https://github.com/bluenviron/mediamtx/blob/{version_tag}/internal/servers/webrtc/publish_index.html). In particular, there's a ready-to-use, standalone JavaScript class for publishing streams with WebRTC, available in [publisher.js](https://github.com/bluenviron/mediamtx/blob/{version_tag}/internal/servers/webrtc/publisher.js).
|
||||
@@ -1,427 +0,0 @@
|
||||
# Read a stream
|
||||
|
||||
## Compatibility matrix
|
||||
|
||||
Live streams can be read from the server with the following protocols and codecs:
|
||||
|
||||
| protocol | variants | codecs |
|
||||
| ----------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| [SRT](#srt) | | **Video**: H265, H264, MPEG-4 Video (H263, Xvid), MPEG-1/2 Video<br/>**Audio**: Opus, MPEG-4 Audio (AAC), MPEG-1/2 Audio (MP3), AC-3<br/>**Other**: KLV |
|
||||
| [WebRTC](#webrtc) | WHEP | **Video**: AV1, VP9, VP8, H265, H264<br/>**Audio**: Opus, G722, G711 (PCMA, PCMU)<br/>**Other**: KLV |
|
||||
| [RTSP](#rtsp) | UDP, UDP-Multicast, TCP, RTSPS | **Video**: AV1, VP9, VP8, H265, H264, MPEG-4 Video (H263, Xvid), MPEG-1/2 Video, M-JPEG<br/>**Audio**: Opus, MPEG-4 Audio (AAC), MPEG-1/2 Audio (MP3), AC-3, G726, G722, G711 (PCMA, PCMU), LPCM<br/>**Other**: KLV, MPEG-TS, any RTP-compatible codec |
|
||||
| [RTMP](#rtmp) | RTMP, RTMPS, Enhanced RTMP | **Video**: AV1, VP9, H265, H264<br/>**Audio**: Opus, MPEG-4 Audio (AAC), MPEG-1/2 Audio (MP3), AC-3, G711 (PCMA, PCMU), LPCM |
|
||||
| [HLS](#hls) | Low-Latency HLS, MP4-based HLS, legacy HLS | **Video**: AV1, VP9, H265, H264<br/>**Audio**: Opus, MPEG-4 Audio (AAC) |
|
||||
|
||||
We provide instructions for reading with the following software:
|
||||
|
||||
- [FFmpeg](#ffmpeg)
|
||||
- [GStreamer](#gstreamer)
|
||||
- [VLC](#vlc)
|
||||
- [OBS Studio](#obs-studio)
|
||||
- [Unity](#unity)
|
||||
- [Web browsers](#web-browsers)
|
||||
|
||||
## Protocols
|
||||
|
||||
### SRT
|
||||
|
||||
SRT is a protocol that allows to publish and read live data stream, providing encryption, integrity and a retransmission mechanism. It is usually used to transfer media streams encoded with MPEG-TS. In order to read a stream from the server with the SRT protocol, use this URL:
|
||||
|
||||
```
|
||||
srt://localhost:8890?streamid=read:mystream
|
||||
```
|
||||
|
||||
Replace `mystream` with the path name.
|
||||
|
||||
If you need to use the standard stream ID syntax instead of the custom one in use by this server, see [Standard stream ID syntax](23-srt-specific-features.md#standard-stream-id-syntax).
|
||||
|
||||
Some clients that can read with SRT are [FFmpeg](#ffmpeg), [GStreamer](#gstreamer) and [VLC](#vlc).
|
||||
|
||||
### WebRTC
|
||||
|
||||
WebRTC is an API that makes use of a set of protocols and methods to connect two clients together and allow them to exchange live media or data streams. You can read a stream with WebRTC and a web browser by visiting:
|
||||
|
||||
```
|
||||
http://localhost:8889/mystream
|
||||
```
|
||||
|
||||
WHEP is a WebRTC extensions that allows to read streams by using a URL, without passing through a web page. This allows to use WebRTC as a general purpose streaming protocol. If you are using a software that supports WHEP, you can read a stream from the server by using this URL:
|
||||
|
||||
```
|
||||
http://localhost:8889/mystream/whep
|
||||
```
|
||||
|
||||
Be aware that not all browsers can read any codec, check [Supported browsers](24-webrtc-specific-features.md#supported-browsers).
|
||||
|
||||
Depending on the network it may be difficult to establish a connection between server and clients, read [Solving WebRTC connectivity issues](24-webrtc-specific-features.md#solving-webrtc-connectivity-issues).
|
||||
|
||||
Some clients that can read with WebRTC and WHEP are [FFmpeg](#ffmpeg), [GStreamer](#gstreamer), [Unity](#unity) and [web browsers](#web-browsers).
|
||||
|
||||
### RTSP
|
||||
|
||||
RTSP is a protocol that allows to publish and read streams. It supports different underlying transport protocols and encryption (see [RTSP-specific features](25-rtsp-specific-features.md)). In order to read a stream with the RTSP protocol, use this URL:
|
||||
|
||||
```
|
||||
rtsp://localhost:8554/mystream
|
||||
```
|
||||
|
||||
Some clients that can read with RTSP are [FFmpeg](#ffmpeg), [GStreamer](#gstreamer) and [VLC](#vlc).
|
||||
|
||||
#### Latency
|
||||
|
||||
The RTSP protocol doesn't introduce any latency by itself. Latency is usually introduced by clients, that put frames in a buffer to compensate network fluctuations. In order to decrease latency, the best way consists in tuning the client. For instance, in VLC, latency can be decreased by decreasing the _Network caching_ parameter, that is available in the _Open network stream_ dialog or alternatively can be set with the command line:
|
||||
|
||||
```
|
||||
vlc --network-caching=50 rtsp://...
|
||||
```
|
||||
|
||||
### RTMP
|
||||
|
||||
RTMP is a protocol that allows to read and publish streams. It supports encryption, see [RTMP-specific features](26-rtmp-specific-features.md). Streams can be read from the server by using the URL:
|
||||
|
||||
```
|
||||
rtmp://localhost/mystream
|
||||
```
|
||||
|
||||
Some clients that can read with RTMP are [FFmpeg](#ffmpeg), [GStreamer](#gstreamer) and [VLC](#vlc).
|
||||
|
||||
### HLS
|
||||
|
||||
HLS is a protocol that works by splitting streams into segments, and by serving these segments and a playlist with the HTTP protocol. You can use _MediaMTX_ to generate a HLS stream, that is accessible through a web page:
|
||||
|
||||
```
|
||||
http://localhost:8888/mystream
|
||||
```
|
||||
|
||||
and can also be accessed without using the browsers, by software that supports the HLS protocol (for instance VLC or _MediaMTX_ itself) by using this URL:
|
||||
|
||||
```
|
||||
http://localhost:8888/mystream/index.m3u8
|
||||
```
|
||||
|
||||
Some clients that can read with HLS are [FFmpeg](#ffmpeg), [GStreamer](#gstreamer), [VLC](#vlc) and [web browsers](#web-browsers).
|
||||
|
||||
#### LL-HLS
|
||||
|
||||
Low-Latency HLS is a recently standardized variant of the protocol that allows to greatly reduce playback latency. It works by splitting segments into parts, that are served before the segment is complete. LL-HLS is enabled by default. If the stream is not shown correctly, try tuning the hlsPartDuration parameter, for instance:
|
||||
|
||||
```yml
|
||||
hlsPartDuration: 500ms
|
||||
```
|
||||
|
||||
#### Codec support in browsers
|
||||
|
||||
The server can produce HLS streams with a variety of video and audio codecs (that are listed at the beginning of the README), but not all browsers can read all codecs due to internal limitations that cannot be overcome by this or any other server.
|
||||
|
||||
You can check what codecs your browser can read with HLS by [using this tool](https://jsfiddle.net/tjcyv5aw/).
|
||||
|
||||
If you want to support most browsers, you can re-encode the stream by using H264 and AAC codecs, for instance by using FFmpeg:
|
||||
|
||||
```sh
|
||||
ffmpeg -i rtsp://original-source \
|
||||
-c:v libx264 -pix_fmt yuv420p -preset ultrafast -b:v 600k \
|
||||
-c:a aac -b:a 160k \
|
||||
-f rtsp rtsp://localhost:8554/mystream
|
||||
```
|
||||
|
||||
#### Encryption required by Apple devices
|
||||
|
||||
In order to correctly display Low-Latency HLS streams in Safari running on Apple devices (iOS or macOS), a TLS certificate is needed and can be generated with OpenSSL:
|
||||
|
||||
```sh
|
||||
openssl genrsa -out server.key 2048
|
||||
openssl req -new -x509 -sha256 -key server.key -out server.crt -days 3650
|
||||
```
|
||||
|
||||
Set the `hlsEncryption`, `hlsServerKey` and `hlsServerCert` parameters in the configuration file:
|
||||
|
||||
```yml
|
||||
hlsEncryption: yes
|
||||
hlsServerKey: server.key
|
||||
hlsServerCert: server.crt
|
||||
```
|
||||
|
||||
Keep also in mind that not all H264 video streams can be played on Apple Devices due to some intrinsic properties (distance between I-Frames, profile). If the video can't be played correctly, you can either:
|
||||
|
||||
- re-encode it by following instructions in this README
|
||||
- disable the Low-latency variant of HLS and go back to the legacy variant:
|
||||
|
||||
```yml
|
||||
hlsVariant: mpegts
|
||||
```
|
||||
|
||||
#### Latency
|
||||
|
||||
in HLS, latency is introduced since a client must wait for the server to generate segments before downloading them. This latency amounts to 500ms-3s when the low-latency HLS variant is enabled (and it is by default), otherwise amounts to 1-15secs.
|
||||
|
||||
To decrease the latency, you can:
|
||||
|
||||
- try decreasing the hlsPartDuration parameter
|
||||
- try decreasing the hlsSegmentDuration parameter
|
||||
- try decreasing the interval between random access frames of the video track, which are frames that can be decoded independently from others. The server adjusts the segment duration in order to include at least one random access frame into every segment. This interval can be changed in two ways:
|
||||
- if the stream is being hardware-generated (i.e. by a camera), there's usually a setting called "Key Frame Interval" in the camera configuration page
|
||||
- otherwise, the stream must be re-encoded. It is possible to tune the random access frame interval by using ffmpeg's -g option:
|
||||
|
||||
```sh
|
||||
ffmpeg -i rtsp://original-stream -c:v libx264 -pix_fmt yuv420p -preset ultrafast -b:v 600k -max_muxing_queue_size 1024 -g 30 -f rtsp rtsp://localhost:$RTSP_PORT/compressed
|
||||
```
|
||||
|
||||
## Software
|
||||
|
||||
### FFmpeg
|
||||
|
||||
FFmpeg can read a stream from the server in several ways. The recommended one consists in reading with RTSP.
|
||||
|
||||
#### FFmpeg and RTSP
|
||||
|
||||
```sh
|
||||
ffmpeg -i rtsp://localhost:8554/mystream -c copy output.mp4
|
||||
```
|
||||
|
||||
#### FFmpeg and RTMP
|
||||
|
||||
```sh
|
||||
ffmpeg -i rtmp://localhost/mystream -c copy output.mp4
|
||||
```
|
||||
|
||||
In order to read AV1, VP9, H265, Opus, AC3 tracks and in order to read multiple video or audio tracks, the `-rtmp_enhanced_codecs` flag must be present:
|
||||
|
||||
```sh
|
||||
ffmpeg -rtmp_enhanced_codecs ac-3,av01,avc1,ec-3,fLaC,hvc1,.mp3,mp4a,Opus,vp09 \
|
||||
-i rtmp://localhost/mystream -c copy output.mp4
|
||||
```
|
||||
|
||||
#### FFmpeg and SRT
|
||||
|
||||
```sh
|
||||
ffmpeg -i 'srt://localhost:8890?streamid=read:test' -c copy output.mp4
|
||||
```
|
||||
|
||||
### GStreamer
|
||||
|
||||
GStreamer can read a stream from the server in several ways. The recommended one consists in reading with RTSP.
|
||||
|
||||
#### GStreamer and RTSP
|
||||
|
||||
```sh
|
||||
gst-launch-1.0 rtspsrc location=rtsp://127.0.0.1:8554/mystream latency=0 ! decodebin ! autovideosink
|
||||
```
|
||||
|
||||
For advanced options, see [RTSP-specific features](25-rtsp-specific-features.md).
|
||||
|
||||
#### GStreamer and WebRTC
|
||||
|
||||
GStreamer also supports reading streams with WebRTC/WHEP, although track codecs must be specified in advance through the `video-caps` and `audio-caps` parameters. Furthermore, if audio is not present, `audio-caps` must be set anyway and must point to a PCMU codec. For instance, the command for reading a video-only H264 stream is:
|
||||
|
||||
```sh
|
||||
gst-launch-1.0 whepsrc whep-endpoint=http://127.0.0.1:8889/stream/whep use-link-headers=true \
|
||||
video-caps="application/x-rtp,media=video,encoding-name=H264,payload=127,clock-rate=90000" \
|
||||
audio-caps="application/x-rtp,media=audio,encoding-name=PCMU,payload=0,clock-rate=8000" \
|
||||
! rtph264depay ! decodebin ! autovideosink
|
||||
```
|
||||
|
||||
While the command for reading an audio-only Opus stream is:
|
||||
|
||||
```sh
|
||||
gst-launch-1.0 whepsrc whep-endpoint="http://127.0.0.1:8889/stream/whep" use-link-headers=true \
|
||||
audio-caps="application/x-rtp,media=audio,encoding-name=OPUS,payload=111,clock-rate=48000,encoding-params=(string)2" \
|
||||
! rtpopusdepay ! decodebin ! autoaudiosink
|
||||
```
|
||||
|
||||
While the command for reading a H264 and Opus stream is:
|
||||
|
||||
```sh
|
||||
gst-launch-1.0 whepsrc whep-endpoint=http://127.0.0.1:8889/stream/whep use-link-headers=true \
|
||||
video-caps="application/x-rtp,media=video,encoding-name=H264,payload=127,clock-rate=90000" \
|
||||
audio-caps="application/x-rtp,media=audio,encoding-name=OPUS,payload=111,clock-rate=48000,encoding-params=(string)2" \
|
||||
! decodebin ! autovideosink
|
||||
```
|
||||
|
||||
### VLC
|
||||
|
||||
VLC can read a stream from the server in several ways. The recommended one consists in reading with RTSP:
|
||||
|
||||
```sh
|
||||
vlc --network-caching=50 rtsp://localhost:8554/mystream
|
||||
```
|
||||
|
||||
#### RTSP and Ubuntu compatibility
|
||||
|
||||
The VLC shipped with Ubuntu 21.10 doesn't support playing RTSP due to a license issue (see [here](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=982299) and [here](https://stackoverflow.com/questions/69766748/cvlc-cannot-play-rtsp-omxplayer-instead-can)). To fix the issue, remove the default VLC instance and install the snap version:
|
||||
|
||||
```sh
|
||||
sudo apt purge -y vlc
|
||||
snap install vlc
|
||||
```
|
||||
|
||||
#### Encrypted RTSP compatibility
|
||||
|
||||
At the moment VLC doesn't support reading encrypted RTSP streams. However, you can use a proxy like [stunnel](https://www.stunnel.org) or [nginx](https://nginx.org/) or a local _MediaMTX_ instance to decrypt streams before reading them.
|
||||
|
||||
### OBS Studio
|
||||
|
||||
OBS Studio can read streams from the server by using the [RTSP protocol](#rtsp).
|
||||
|
||||
Open OBS, click on _Add Source_, _Media source_, _OK_, uncheck _Local file_, insert in _Input_:
|
||||
|
||||
```
|
||||
rtsp://localhost:8554/stream
|
||||
```
|
||||
|
||||
Then _Ok_.
|
||||
|
||||
### Unity
|
||||
|
||||
Software written with the Unity Engine can read a stream from the server by using the [WebRTC protocol](#webrtc).
|
||||
|
||||
Create a new Unity project or open an existing one.
|
||||
|
||||
Open _Window -> Package Manager_, click on the plus sign, _Add Package by name..._ and insert `com.unity.webrtc`. Wait for the package to be installed.
|
||||
|
||||
In the _Project_ window, under `Assets`, create a new C# Script called `WebRTCReader.cs` with this content:
|
||||
|
||||
```cs
|
||||
using System.Collections;
|
||||
using UnityEngine;
|
||||
using Unity.WebRTC;
|
||||
|
||||
public class WebRTCReader : MonoBehaviour
|
||||
{
|
||||
public string url = "http://localhost:8889/stream/whep";
|
||||
|
||||
private RTCPeerConnection pc;
|
||||
private MediaStream receiveStream;
|
||||
|
||||
void Start()
|
||||
{
|
||||
UnityEngine.UI.RawImage rawImage = gameObject.GetComponentInChildren<UnityEngine.UI.RawImage>();
|
||||
AudioSource audioSource = gameObject.GetComponentInChildren<AudioSource>();
|
||||
pc = new RTCPeerConnection();
|
||||
receiveStream = new MediaStream();
|
||||
|
||||
pc.OnTrack = e =>
|
||||
{
|
||||
receiveStream.AddTrack(e.Track);
|
||||
};
|
||||
|
||||
receiveStream.OnAddTrack = e =>
|
||||
{
|
||||
if (e.Track is VideoStreamTrack videoTrack)
|
||||
{
|
||||
videoTrack.OnVideoReceived += (tex) =>
|
||||
{
|
||||
rawImage.texture = tex;
|
||||
};
|
||||
}
|
||||
else if (e.Track is AudioStreamTrack audioTrack)
|
||||
{
|
||||
audioSource.SetTrack(audioTrack);
|
||||
audioSource.loop = true;
|
||||
audioSource.Play();
|
||||
}
|
||||
};
|
||||
|
||||
RTCRtpTransceiverInit init = new RTCRtpTransceiverInit();
|
||||
init.direction = RTCRtpTransceiverDirection.RecvOnly;
|
||||
pc.AddTransceiver(TrackKind.Audio, init);
|
||||
pc.AddTransceiver(TrackKind.Video, init);
|
||||
|
||||
StartCoroutine(WebRTC.Update());
|
||||
StartCoroutine(createOffer());
|
||||
}
|
||||
|
||||
private IEnumerator createOffer()
|
||||
{
|
||||
var op = pc.CreateOffer();
|
||||
yield return op;
|
||||
if (op.IsError) {
|
||||
Debug.LogError("CreateOffer() failed");
|
||||
yield break;
|
||||
}
|
||||
|
||||
yield return setLocalDescription(op.Desc);
|
||||
}
|
||||
|
||||
private IEnumerator setLocalDescription(RTCSessionDescription offer)
|
||||
{
|
||||
var op = pc.SetLocalDescription(ref offer);
|
||||
yield return op;
|
||||
if (op.IsError) {
|
||||
Debug.LogError("SetLocalDescription() failed");
|
||||
yield break;
|
||||
}
|
||||
|
||||
yield return postOffer(offer);
|
||||
}
|
||||
|
||||
private IEnumerator postOffer(RTCSessionDescription offer)
|
||||
{
|
||||
var content = new System.Net.Http.StringContent(offer.sdp);
|
||||
content.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue("application/sdp");
|
||||
var client = new System.Net.Http.HttpClient();
|
||||
|
||||
var task = System.Threading.Tasks.Task.Run(async () => {
|
||||
var res = await client.PostAsync(new System.UriBuilder(url).Uri, content);
|
||||
res.EnsureSuccessStatusCode();
|
||||
return await res.Content.ReadAsStringAsync();
|
||||
});
|
||||
yield return new WaitUntil(() => task.IsCompleted);
|
||||
if (task.Exception != null) {
|
||||
Debug.LogError(task.Exception);
|
||||
yield break;
|
||||
}
|
||||
|
||||
yield return setRemoteDescription(task.Result);
|
||||
}
|
||||
|
||||
private IEnumerator setRemoteDescription(string answer)
|
||||
{
|
||||
RTCSessionDescription desc = new RTCSessionDescription();
|
||||
desc.type = RTCSdpType.Answer;
|
||||
desc.sdp = answer;
|
||||
var op = pc.SetRemoteDescription(ref desc);
|
||||
yield return op;
|
||||
if (op.IsError) {
|
||||
Debug.LogError("SetRemoteDescription() failed");
|
||||
yield break;
|
||||
}
|
||||
|
||||
yield break;
|
||||
}
|
||||
|
||||
void OnDestroy()
|
||||
{
|
||||
pc?.Close();
|
||||
pc?.Dispose();
|
||||
receiveStream?.Dispose();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Edit the `url` variable according to your needs.
|
||||
|
||||
In the _Hierarchy_ window, find or create a scene. Inside the scene, add a _Canvas_. Inside the Canvas, add a _Raw Image_ and an _Audio Source_. Then add the `WebRTCReader.cs` script as component of the canvas, by dragging it inside the _Inspector_ window. then Press the _Play_ button at the top of the page.
|
||||
|
||||
### Web browsers
|
||||
|
||||
Web browsers can read a stream from the server in several ways.
|
||||
|
||||
#### Web browsers and WebRTC
|
||||
|
||||
You can read a stream by using the [WebRTC protocol](#webrtc) by visiting the web page:
|
||||
|
||||
```
|
||||
http://localhost:8889/mystream
|
||||
```
|
||||
|
||||
See [Embed streams in a website](16-embed-streams-in-a-website.md) for instructions on how to embed the stream into an external website.
|
||||
|
||||
#### Web browsers and HLS
|
||||
|
||||
Web browsers can also read a stream with the [HLS protocol](#hls). Latency is higher but there are less problems related to connectivity between server and clients, furthermore the server load can be balanced by using a common HTTP CDN (like Cloudflare or CloudFront), and this allows to handle an unlimited amount of readers. Visit the web page:
|
||||
|
||||
```
|
||||
http://localhost:8888/mystream
|
||||
```
|
||||
|
||||
See [Embed streams in a website](16-embed-streams-in-a-website.md) for instructions on how to embed the stream into an external website.
|
||||
@@ -1 +0,0 @@
|
||||
# Usage
|
||||
@@ -0,0 +1,20 @@
|
||||
# Read a stream
|
||||
|
||||
Live streams can be read from the server with the following protocols and codecs:
|
||||
|
||||
| protocol | variants | codecs |
|
||||
| ---------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| [SRT](02-srt.md) | | **Video**: H265, H264, MPEG-4 Video (H263, Xvid), MPEG-1/2 Video<br/>**Audio**: Opus, MPEG-4 Audio (AAC), MPEG-1/2 Audio (MP3), AC-3<br/>**Other**: KLV |
|
||||
| [WebRTC](03-webrtc.md) | WHEP | **Video**: AV1, VP9, VP8, H265, H264<br/>**Audio**: Opus, G722, G711 (PCMA, PCMU)<br/>**Other**: KLV |
|
||||
| [RTSP](04-rtsp.md) | UDP, UDP-Multicast, TCP, RTSPS | **Video**: AV1, VP9, VP8, H265, H264, MPEG-4 Video (H263, Xvid), MPEG-1/2 Video, M-JPEG<br/>**Audio**: Opus, MPEG-4 Audio (AAC), MPEG-1/2 Audio (MP3), AC-3, G726, G722, G711 (PCMA, PCMU), LPCM<br/>**Other**: KLV, MPEG-TS, any RTP-compatible codec |
|
||||
| [RTMP](05-rtmp.md) | RTMP, RTMPS, Enhanced RTMP | **Video**: AV1, VP9, H265, H264<br/>**Audio**: Opus, MPEG-4 Audio (AAC), MPEG-1/2 Audio (MP3), AC-3, G711 (PCMA, PCMU), LPCM |
|
||||
| [HLS](06-hls.md) | Low-Latency HLS, MP4-based HLS, legacy HLS | **Video**: AV1, VP9, H265, H264<br/>**Audio**: Opus, MPEG-4 Audio (AAC) |
|
||||
|
||||
We provide instructions for reading with the following software:
|
||||
|
||||
- [FFmpeg](07-ffmpeg.md)
|
||||
- [GStreamer](08-gstreamer.md)
|
||||
- [VLC](09-vlc.md)
|
||||
- [OBS Studio](10-obs-studio.md)
|
||||
- [Unity](11-unity.md)
|
||||
- [Web browsers](12-web-browsers.md)
|
||||
@@ -0,0 +1,13 @@
|
||||
# SRT
|
||||
|
||||
SRT is a protocol that allows to publish and read live data stream, providing encryption, integrity and a retransmission mechanism. It is usually used to transfer media streams encoded with MPEG-TS. In order to read a stream from the server with the SRT protocol, use this URL:
|
||||
|
||||
```
|
||||
srt://localhost:8890?streamid=read:mystream
|
||||
```
|
||||
|
||||
Replace `mystream` with the path name.
|
||||
|
||||
If you need to use the standard stream ID syntax instead of the custom one in use by this server, see [Standard stream ID syntax](../4-other/21-srt-specific-features.md#standard-stream-id-syntax).
|
||||
|
||||
Some clients that can read with SRT are [FFmpeg](07-ffmpeg.md), [GStreamer](08-gstreamer.md) and [VLC](09-vlc.md).
|
||||
@@ -0,0 +1,19 @@
|
||||
# WebRTC
|
||||
|
||||
WebRTC is an API that makes use of a set of protocols and methods to connect two clients together and allow them to exchange live media or data streams. You can read a stream with WebRTC and a web browser by visiting:
|
||||
|
||||
```
|
||||
http://localhost:8889/mystream
|
||||
```
|
||||
|
||||
WHEP is a WebRTC extensions that allows to read streams by using a URL, without passing through a web page. This allows to use WebRTC as a general purpose streaming protocol. If you are using a software that supports WHEP, you can read a stream from the server by using this URL:
|
||||
|
||||
```
|
||||
http://localhost:8889/mystream/whep
|
||||
```
|
||||
|
||||
Be aware that not all browsers can read any codec, check [Supported browsers](../4-other/22-webrtc-specific-features.md#supported-browsers).
|
||||
|
||||
Depending on the network it may be difficult to establish a connection between server and clients, read [Solving WebRTC connectivity issues](../4-other/22-webrtc-specific-features.md#solving-webrtc-connectivity-issues).
|
||||
|
||||
Some clients that can read with WebRTC and WHEP are [FFmpeg](07-ffmpeg.md), [GStreamer](08-gstreamer.md), [Unity](11-unity.md) and [web browsers](12-web-browsers.md).
|
||||
@@ -0,0 +1,9 @@
|
||||
# RTSP
|
||||
|
||||
RTSP is a protocol that allows to publish and read streams. It supports different underlying transport protocols and encryption (see [RTSP-specific features](../4-other/23-rtsp-specific-features.md)). In order to read a stream with the RTSP protocol, use this URL:
|
||||
|
||||
```
|
||||
rtsp://localhost:8554/mystream
|
||||
```
|
||||
|
||||
Some clients that can read with RTSP are [FFmpeg](07-ffmpeg.md), [GStreamer](08-gstreamer.md) and [VLC](09-vlc.md).
|
||||
@@ -0,0 +1,9 @@
|
||||
# RTMP
|
||||
|
||||
RTMP is a protocol that allows to read and publish streams. It supports encryption, see [RTMP-specific features](../4-other/24-rtmp-specific-features.md). Streams can be read from the server by using the URL:
|
||||
|
||||
```
|
||||
rtmp://localhost/mystream
|
||||
```
|
||||
|
||||
Some clients that can read with RTMP are [FFmpeg](07-ffmpeg.md), [GStreamer](08-gstreamer.md) and [VLC](09-vlc.md).
|
||||
@@ -0,0 +1,15 @@
|
||||
# HLS
|
||||
|
||||
HLS is a protocol that works by splitting streams into segments, and by serving these segments and a playlist with the HTTP protocol. You can use _MediaMTX_ to generate a HLS stream, that is accessible through a web page:
|
||||
|
||||
```
|
||||
http://localhost:8888/mystream
|
||||
```
|
||||
|
||||
and can also be accessed without using the browsers, by software that supports the HLS protocol (for instance VLC or _MediaMTX_ itself) by using this URL:
|
||||
|
||||
```
|
||||
http://localhost:8888/mystream/index.m3u8
|
||||
```
|
||||
|
||||
Some clients that can read with HLS are [FFmpeg](07-ffmpeg.md), [GStreamer](08-gstreamer.md), [VLC](09-vlc.md) and [web browsers](12-web-browsers.md).
|
||||
@@ -0,0 +1,28 @@
|
||||
# FFmpeg
|
||||
|
||||
FFmpeg can read a stream from the server in several ways. The recommended one consists in reading with RTSP.
|
||||
|
||||
## FFmpeg and RTSP
|
||||
|
||||
```sh
|
||||
ffmpeg -i rtsp://localhost:8554/mystream -c copy output.mp4
|
||||
```
|
||||
|
||||
## FFmpeg and RTMP
|
||||
|
||||
```sh
|
||||
ffmpeg -i rtmp://localhost/mystream -c copy output.mp4
|
||||
```
|
||||
|
||||
In order to read AV1, VP9, H265, Opus, AC3 tracks and in order to read multiple video or audio tracks, the `-rtmp_enhanced_codecs` flag must be present:
|
||||
|
||||
```sh
|
||||
ffmpeg -rtmp_enhanced_codecs ac-3,av01,avc1,ec-3,fLaC,hvc1,.mp3,mp4a,Opus,vp09 \
|
||||
-i rtmp://localhost/mystream -c copy output.mp4
|
||||
```
|
||||
|
||||
## FFmpeg and SRT
|
||||
|
||||
```sh
|
||||
ffmpeg -i 'srt://localhost:8890?streamid=read:test' -c copy output.mp4
|
||||
```
|
||||
@@ -0,0 +1,39 @@
|
||||
# GStreamer
|
||||
|
||||
GStreamer can read a stream from the server in several ways. The recommended one consists in reading with RTSP.
|
||||
|
||||
## GStreamer and RTSP
|
||||
|
||||
```sh
|
||||
gst-launch-1.0 rtspsrc location=rtsp://127.0.0.1:8554/mystream latency=0 ! decodebin ! autovideosink
|
||||
```
|
||||
|
||||
For advanced options, see [RTSP-specific features](../4-other/23-rtsp-specific-features.md).
|
||||
|
||||
## GStreamer and WebRTC
|
||||
|
||||
GStreamer also supports reading streams with WebRTC/WHEP, although track codecs must be specified in advance through the `video-caps` and `audio-caps` parameters. Furthermore, if audio is not present, `audio-caps` must be set anyway and must point to a PCMU codec. For instance, the command for reading a video-only H264 stream is:
|
||||
|
||||
```sh
|
||||
gst-launch-1.0 whepsrc whep-endpoint=http://127.0.0.1:8889/stream/whep use-link-headers=true \
|
||||
video-caps="application/x-rtp,media=video,encoding-name=H264,payload=127,clock-rate=90000" \
|
||||
audio-caps="application/x-rtp,media=audio,encoding-name=PCMU,payload=0,clock-rate=8000" \
|
||||
! rtph264depay ! decodebin ! autovideosink
|
||||
```
|
||||
|
||||
While the command for reading an audio-only Opus stream is:
|
||||
|
||||
```sh
|
||||
gst-launch-1.0 whepsrc whep-endpoint="http://127.0.0.1:8889/stream/whep" use-link-headers=true \
|
||||
audio-caps="application/x-rtp,media=audio,encoding-name=OPUS,payload=111,clock-rate=48000,encoding-params=(string)2" \
|
||||
! rtpopusdepay ! decodebin ! autoaudiosink
|
||||
```
|
||||
|
||||
While the command for reading a H264 and Opus stream is:
|
||||
|
||||
```sh
|
||||
gst-launch-1.0 whepsrc whep-endpoint=http://127.0.0.1:8889/stream/whep use-link-headers=true \
|
||||
video-caps="application/x-rtp,media=video,encoding-name=H264,payload=127,clock-rate=90000" \
|
||||
audio-caps="application/x-rtp,media=audio,encoding-name=OPUS,payload=111,clock-rate=48000,encoding-params=(string)2" \
|
||||
! decodebin ! autovideosink
|
||||
```
|
||||
@@ -0,0 +1,20 @@
|
||||
# VLC
|
||||
|
||||
VLC can read a stream from the server in several ways. The recommended one consists in reading with RTSP:
|
||||
|
||||
```sh
|
||||
vlc --network-caching=50 rtsp://localhost:8554/mystream
|
||||
```
|
||||
|
||||
## RTSP and Ubuntu compatibility
|
||||
|
||||
The VLC shipped with Ubuntu 21.10 doesn't support playing RTSP due to a license issue (see [here](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=982299) and [here](https://stackoverflow.com/questions/69766748/cvlc-cannot-play-rtsp-omxplayer-instead-can)). To fix the issue, remove the default VLC instance and install the snap version:
|
||||
|
||||
```sh
|
||||
sudo apt purge -y vlc
|
||||
snap install vlc
|
||||
```
|
||||
|
||||
## Encrypted RTSP compatibility
|
||||
|
||||
At the moment VLC doesn't support reading encrypted RTSP streams. However, you can use a proxy like [stunnel](https://www.stunnel.org) or [nginx](https://nginx.org/) or a local _MediaMTX_ instance to decrypt streams before reading them.
|
||||
@@ -0,0 +1,11 @@
|
||||
# OBS Studio
|
||||
|
||||
OBS Studio can read streams from the server by using the [RTSP protocol](04-rtsp.md).
|
||||
|
||||
Open OBS, click on _Add Source_, _Media source_, _OK_, uncheck _Local file_, insert in _Input_:
|
||||
|
||||
```
|
||||
rtsp://localhost:8554/stream
|
||||
```
|
||||
|
||||
Then _Ok_.
|
||||
@@ -0,0 +1,131 @@
|
||||
# Unity
|
||||
|
||||
Software written with the Unity Engine can read a stream from the server by using the [WebRTC protocol](03-webrtc.md).
|
||||
|
||||
Create a new Unity project or open an existing one.
|
||||
|
||||
Open _Window -> Package Manager_, click on the plus sign, _Add Package by name..._ and insert `com.unity.webrtc`. Wait for the package to be installed.
|
||||
|
||||
In the _Project_ window, under `Assets`, create a new C# Script called `WebRTCReader.cs` with this content:
|
||||
|
||||
```cs
|
||||
using System.Collections;
|
||||
using UnityEngine;
|
||||
using Unity.WebRTC;
|
||||
|
||||
public class WebRTCReader : MonoBehaviour
|
||||
{
|
||||
public string url = "http://localhost:8889/stream/whep";
|
||||
|
||||
private RTCPeerConnection pc;
|
||||
private MediaStream receiveStream;
|
||||
|
||||
void Start()
|
||||
{
|
||||
UnityEngine.UI.RawImage rawImage = gameObject.GetComponentInChildren<UnityEngine.UI.RawImage>();
|
||||
AudioSource audioSource = gameObject.GetComponentInChildren<AudioSource>();
|
||||
pc = new RTCPeerConnection();
|
||||
receiveStream = new MediaStream();
|
||||
|
||||
pc.OnTrack = e =>
|
||||
{
|
||||
receiveStream.AddTrack(e.Track);
|
||||
};
|
||||
|
||||
receiveStream.OnAddTrack = e =>
|
||||
{
|
||||
if (e.Track is VideoStreamTrack videoTrack)
|
||||
{
|
||||
videoTrack.OnVideoReceived += (tex) =>
|
||||
{
|
||||
rawImage.texture = tex;
|
||||
};
|
||||
}
|
||||
else if (e.Track is AudioStreamTrack audioTrack)
|
||||
{
|
||||
audioSource.SetTrack(audioTrack);
|
||||
audioSource.loop = true;
|
||||
audioSource.Play();
|
||||
}
|
||||
};
|
||||
|
||||
RTCRtpTransceiverInit init = new RTCRtpTransceiverInit();
|
||||
init.direction = RTCRtpTransceiverDirection.RecvOnly;
|
||||
pc.AddTransceiver(TrackKind.Audio, init);
|
||||
pc.AddTransceiver(TrackKind.Video, init);
|
||||
|
||||
StartCoroutine(WebRTC.Update());
|
||||
StartCoroutine(createOffer());
|
||||
}
|
||||
|
||||
private IEnumerator createOffer()
|
||||
{
|
||||
var op = pc.CreateOffer();
|
||||
yield return op;
|
||||
if (op.IsError) {
|
||||
Debug.LogError("CreateOffer() failed");
|
||||
yield break;
|
||||
}
|
||||
|
||||
yield return setLocalDescription(op.Desc);
|
||||
}
|
||||
|
||||
private IEnumerator setLocalDescription(RTCSessionDescription offer)
|
||||
{
|
||||
var op = pc.SetLocalDescription(ref offer);
|
||||
yield return op;
|
||||
if (op.IsError) {
|
||||
Debug.LogError("SetLocalDescription() failed");
|
||||
yield break;
|
||||
}
|
||||
|
||||
yield return postOffer(offer);
|
||||
}
|
||||
|
||||
private IEnumerator postOffer(RTCSessionDescription offer)
|
||||
{
|
||||
var content = new System.Net.Http.StringContent(offer.sdp);
|
||||
content.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue("application/sdp");
|
||||
var client = new System.Net.Http.HttpClient();
|
||||
|
||||
var task = System.Threading.Tasks.Task.Run(async () => {
|
||||
var res = await client.PostAsync(new System.UriBuilder(url).Uri, content);
|
||||
res.EnsureSuccessStatusCode();
|
||||
return await res.Content.ReadAsStringAsync();
|
||||
});
|
||||
yield return new WaitUntil(() => task.IsCompleted);
|
||||
if (task.Exception != null) {
|
||||
Debug.LogError(task.Exception);
|
||||
yield break;
|
||||
}
|
||||
|
||||
yield return setRemoteDescription(task.Result);
|
||||
}
|
||||
|
||||
private IEnumerator setRemoteDescription(string answer)
|
||||
{
|
||||
RTCSessionDescription desc = new RTCSessionDescription();
|
||||
desc.type = RTCSdpType.Answer;
|
||||
desc.sdp = answer;
|
||||
var op = pc.SetRemoteDescription(ref desc);
|
||||
yield return op;
|
||||
if (op.IsError) {
|
||||
Debug.LogError("SetRemoteDescription() failed");
|
||||
yield break;
|
||||
}
|
||||
|
||||
yield break;
|
||||
}
|
||||
|
||||
void OnDestroy()
|
||||
{
|
||||
pc?.Close();
|
||||
pc?.Dispose();
|
||||
receiveStream?.Dispose();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Edit the `url` variable according to your needs.
|
||||
|
||||
In the _Hierarchy_ window, find or create a scene. Inside the scene, add a _Canvas_. Inside the Canvas, add a _Raw Image_ and an _Audio Source_. Then add the `WebRTCReader.cs` script as component of the canvas, by dragging it inside the _Inspector_ window. then Press the _Play_ button at the top of the page.
|
||||
@@ -0,0 +1,23 @@
|
||||
# Web browsers
|
||||
|
||||
Web browsers can read a stream from the server in several ways.
|
||||
|
||||
## Web browsers and WebRTC
|
||||
|
||||
You can read a stream by using the [WebRTC protocol](03-webrtc.md) by visiting the web page:
|
||||
|
||||
```
|
||||
http://localhost:8889/mystream
|
||||
```
|
||||
|
||||
See [Embed streams in a website](../4-other/14-embed-streams-in-a-website.md) for instructions on how to embed the stream into an external website.
|
||||
|
||||
## Web browsers and HLS
|
||||
|
||||
Web browsers can also read a stream with the [HLS protocol](06-hls.md). Latency is higher but there are less problems related to connectivity between server and clients, furthermore the server load can be balanced by using a common HTTP CDN (like Cloudflare or CloudFront), and this allows to handle an unlimited amount of readers. Visit the web page:
|
||||
|
||||
```
|
||||
http://localhost:8888/mystream
|
||||
```
|
||||
|
||||
See [Embed streams in a website](../4-other/14-embed-streams-in-a-website.md) for instructions on how to embed the stream into an external website.
|
||||
@@ -0,0 +1 @@
|
||||
# Read
|
||||
@@ -1,6 +1,6 @@
|
||||
# Configuration
|
||||
|
||||
All the configuration parameters are listed and commented in the [configuration file](../3-references/1-configuration-file.md) (`mediamtx.yml`).
|
||||
All the configuration parameters are listed and commented in the [configuration file](../5-references/1-configuration-file.md) (`mediamtx.yml`).
|
||||
|
||||
## Change the configuration
|
||||
|
||||
@@ -47,7 +47,7 @@ There are several ways to change the configuration:
|
||||
docker run --rm -it --network=host -e MTX_PATHS_TEST_SOURCE=rtsp://myurl bluenviron/mediamtx:1
|
||||
```
|
||||
|
||||
3. By using the [Control API](20-control-api.md).
|
||||
3. By using the [Control API](18-control-api.md).
|
||||
|
||||
## Encrypt the configuration
|
||||
|
||||
@@ -1,7 +1,5 @@
|
||||
# Authentication
|
||||
|
||||
## Overview
|
||||
|
||||
_MediaMTX_ can be configured to ask clients for credentials, either in the form of username/password or a string-based token. These credentials are then validated through a chosen method.
|
||||
|
||||
## Credential validation
|
||||
@@ -287,7 +285,7 @@ Username and password can be passed through the `Authorization: Basic` HTTP head
|
||||
Authorization: Basic base64(user:pass)
|
||||
```
|
||||
|
||||
When using a web browser, a dialog is first shown to users, asking for credentials, and then the header is automatically inserted into every request. If you need to automatically fill credentials from a parent web page, see [Embed streams in a website](16-embed-streams-in-a-website.md).
|
||||
When using a web browser, a dialog is first shown to users, asking for credentials, and then the header is automatically inserted into every request. If you need to automatically fill credentials from a parent web page, see [Embed streams in a website](14-embed-streams-in-a-website.md).
|
||||
|
||||
If the `Authorization: Basic` header cannot be used (for instance, in software like OBS Studio, which only allows to provide a "Bearer Token"), credentials can be passed through the `Authorization: Bearer` header (i.e. the "Bearer Token" in OBS), where the value is the concatenation of username and password, separated by a colon:
|
||||
|
||||
@@ -299,7 +297,7 @@ Authorization: Bearer username:password
|
||||
|
||||
### RTSP
|
||||
|
||||
Pass the token as query parameter:
|
||||
Pass the token as a query parameter:
|
||||
|
||||
```
|
||||
rtsp://localhost:8554/mystream?jwt=jwt
|
||||
@@ -309,7 +307,7 @@ WARNING: FFmpeg implementation of RTSP does not support URLs that are longer tha
|
||||
|
||||
### RTMP
|
||||
|
||||
Pass the token as query parameter:
|
||||
Pass the token as a query parameter:
|
||||
|
||||
```
|
||||
rtmp://localhost/mystream?jwt=jwt
|
||||
@@ -339,4 +337,4 @@ In OBS Studio, this is the "Bearer Token" field.
|
||||
|
||||
If the `Authorization: Bearer` token cannot be directly provided (for instance, with web browsers that directly access _MediaMTX_ and show a credential dialog), you can pass the token as password, using an arbitrary user.
|
||||
|
||||
In web browsers, if you need to automatically fill credentials from a parent web page, read [Embed streams in a website](16-embed-streams-in-a-website.md).
|
||||
In web browsers, if you need to automatically fill credentials from a parent web page, read [Embed streams in a website](14-embed-streams-in-a-website.md).
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
# Remuxing, re-encoding, compression
|
||||
# Re-encoding
|
||||
|
||||
To change the format, codec or compression of a stream, use _FFmpeg_ or _GStreamer_ together with _MediaMTX_. For instance, to re-encode an existing stream, that is available in the `/original` path, and publish the resulting stream in the `/compressed` path, edit `mediamtx.yml` and replace everything inside section `paths` with the following content:
|
||||
|
||||
@@ -1,8 +1,6 @@
|
||||
# Record streams to disk
|
||||
# Record
|
||||
|
||||
## Compatibility matrix
|
||||
|
||||
Live streams be recorded and played back with the following file containers and codecs:
|
||||
Live streams be recorded to disk and played back with the following file containers and codecs:
|
||||
|
||||
| container | codecs |
|
||||
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
@@ -47,7 +45,7 @@ pathDefaults:
|
||||
recordDeleteAfter: 1d
|
||||
```
|
||||
|
||||
All available recording parameters are listed in the [configuration file](../3-references/1-configuration-file.md).
|
||||
All available recording parameters are listed in the [configuration file](../5-references/1-configuration-file.md).
|
||||
|
||||
## Remote upload
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Playback recorded streams
|
||||
# Playback
|
||||
|
||||
Existing recordings can be served to users through a dedicated HTTP server, that can be enabled inside the configuration:
|
||||
Existing recordings can be played back to users through a dedicated HTTP server, that can be enabled inside the configuration:
|
||||
|
||||
```yml
|
||||
playback: yes
|
||||
@@ -1,4 +1,4 @@
|
||||
# Forward streams to other servers
|
||||
# Forward
|
||||
|
||||
To forward incoming streams to another server, use _FFmpeg_ inside the `runOnReady` parameter:
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Proxy requests to other servers
|
||||
# Proxy
|
||||
|
||||
The server allows to proxy incoming requests to other servers or cameras. This is useful to expose servers or cameras behind a NAT. Edit `mediamtx.yml` and replace everything inside section `paths` with the following content:
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
# Embed streams in a website
|
||||
|
||||
Live streams can be embedded into an external website by using the WebRTC or HLS protocol. Before embedding, check that the stream is ready and can be accessed with intended protocol by using URLs mentioned in [Read a stream](03-read.md).
|
||||
Live streams can be embedded into an external website by using the WebRTC or HLS protocol. Before embedding, check that the stream is ready and can be accessed with intended protocol by using URLs mentioned in [Read a stream](../3-read/01-overview.md).
|
||||
|
||||
## WebRTC in iframe
|
||||
|
||||
@@ -37,7 +37,7 @@ Log entries can be queried by using:
|
||||
journalctl SYSLOG_IDENTIFIER=mediamtx
|
||||
```
|
||||
|
||||
If _MediaMTX_ is also running as a [system service](17-start-on-boot.md), log entries can be queried by using:
|
||||
If _MediaMTX_ is also running as a [system service](15-start-on-boot.md), log entries can be queried by using:
|
||||
|
||||
```sh
|
||||
journalctl -u mediamtx
|
||||
@@ -12,6 +12,6 @@ To obtain a list of active paths, run:
|
||||
curl http://127.0.0.1:9997/v3/paths/list
|
||||
```
|
||||
|
||||
The control API is documented in the [Control API Reference page](../3-references/2-control-api.md) and in the [OpenAPI / Swagger file](https://github.com/bluenviron/mediamtx/blob/{version_tag}/api/openapi.yaml).
|
||||
The control API is documented in the [Control API Reference page](../5-references/2-control-api.md) and in the [OpenAPI / Swagger file](https://github.com/bluenviron/mediamtx/blob/{version_tag}/api/openapi.yaml).
|
||||
|
||||
Be aware that by default the Control API is accessible by localhost only; to increase visibility or add authentication, check [Authentication](05-authentication.md).
|
||||
Be aware that by default the Control API is accessible by localhost only; to increase visibility or add authentication, check [Authentication](03-authentication.md).
|
||||
@@ -1,6 +1,6 @@
|
||||
# SRT-specific features
|
||||
|
||||
SRT is a protocol that can be used for publishing and reading streams. Regarding specific tasks, see [Publish](02-publish.md#srt-clients) and [Read](03-read.md#srt). Features in this page are shared among both tasks.
|
||||
SRT is a protocol that can be used for publishing and reading streams. Regarding specific tasks, see [Publish](../2-publish/02-srt-clients.md) and [Read](../3-read/02-srt.md). Features in this page are shared among both tasks.
|
||||
|
||||
## Standard stream ID syntax
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
# WebRTC-specific features
|
||||
|
||||
WebRTC is a protocol that can be used for publishing and reading streams. Regarding specific tasks, see [Publish](02-publish.md#webrtc-clients) and [Read](03-read.md#webrtc). Features in this page are shared among both tasks.
|
||||
WebRTC is a protocol that can be used for publishing and reading streams. Regarding specific tasks, see [Publish](../2-publish/04-webrtc-clients.md) and [Read](../3-read/03-webrtc.md). Features in this page are shared among both tasks.
|
||||
|
||||
## Codec support in browsers
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
# RTSP-specific features
|
||||
|
||||
RTSP is a protocol that can be used for publishing and reading streams. Regarding specific tasks, see [Publish](02-publish.md#rtsp-clients) and [Read](03-read.md#rtsp). Features in this page are shared among both tasks.
|
||||
RTSP is a protocol that can be used for publishing and reading streams. Regarding specific tasks, see [Publish](../2-publish/06-rtsp-clients.md) and [Read](../3-read/04-rtsp.md). Features in this page are shared among both tasks.
|
||||
|
||||
## Transport protocols
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
# RTMP-specific features
|
||||
|
||||
RTMP is a protocol that can be used for publishing and reading streams. Regarding specific tasks, see [Publish](02-publish.md#rtmp-clients) and [Read](03-read.md#rtmp). Features in this page are shared among both tasks.
|
||||
RTMP is a protocol that can be used for publishing and reading streams. Regarding specific tasks, see [Publish](../2-publish/08-rtmp-clients.md) and [Read](../3-read/05-rtmp.md). Features in this page are shared among both tasks.
|
||||
|
||||
## Encryption
|
||||
|
||||
@@ -1 +1 @@
|
||||
# Other
|
||||
# Other features
|
||||
|
||||
+1
-1
@@ -1,3 +1,3 @@
|
||||
# Configuration file reference
|
||||
|
||||
This is a copy of the configuration file (`mediamtx.yml`) of the latest _MediaMTX_ release ({version_tag}), that contains all available parameters. Check the [Configuration usage page](../2-usage/04-configuration.md) for instructions on how to change it.
|
||||
This is a copy of the configuration file (`mediamtx.yml`) of the latest _MediaMTX_ release ({version_tag}), that contains all available parameters. Check the [Configuration usage page](../4-other/02-configuration.md) for instructions on how to change it.
|
||||
@@ -1,3 +1,3 @@
|
||||
# Control API reference
|
||||
|
||||
This is the reference of the Control API of the latest _MediaMTX_ release ({version_tag}), generated automatically from the [OpenAPI / Swagger file](https://github.com/bluenviron/mediamtx/blob/{version_tag}/api/openapi.yaml) available in the repository. Check the [Control API usage page](../2-usage/20-control-api.md) for instructions on how to use the API.
|
||||
This is the reference of the Control API of the latest _MediaMTX_ release ({version_tag}), generated automatically from the [OpenAPI / Swagger file](https://github.com/bluenviron/mediamtx/blob/{version_tag}/api/openapi.yaml) available in the repository. Check the [Control API usage page](../4-other/18-control-api.md) for instructions on how to use the API.
|
||||
@@ -0,0 +1 @@
|
||||
# Misc
|
||||
+36
-1
@@ -1,2 +1,37 @@
|
||||
kickoff/installation: kickoff/install
|
||||
usage/log-management: usage/logging
|
||||
|
||||
usage/publish: publish/overview
|
||||
usage/read: read/overview
|
||||
|
||||
usage/log-management: other/logging
|
||||
usage/basic-usage: other/basic-usage
|
||||
usage/configuration: other/configuration
|
||||
usage/authentication: other/authentication
|
||||
usage/remuxing-reencoding-compression: other/remuxing-reencoding-compression
|
||||
usage/always-available: other/always-available
|
||||
usage/record: other/record
|
||||
usage/playback: other/playback
|
||||
usage/forward: other/forward
|
||||
usage/proxy: other/proxy
|
||||
usage/extract-snapshots: other/extract-snapshots
|
||||
usage/on-demand-publishing: other/on-demand-publishing
|
||||
usage/route-absolute-timestamps: other/route-absolute-timestamps
|
||||
usage/expose-the-server-in-a-subfolder: other/expose-the-server-in-a-subfolder
|
||||
usage/embed-streams-in-a-website: other/embed-streams-in-a-website
|
||||
usage/start-on-boot: other/start-on-boot
|
||||
usage/logging: other/logging
|
||||
usage/hooks: other/hooks
|
||||
usage/control-api: other/control-api
|
||||
usage/metrics: other/metrics
|
||||
usage/performance: other/performance
|
||||
usage/srt-specific-features: other/srt-specific-features
|
||||
usage/webrtc-specific-features: other/webrtc-specific-features
|
||||
usage/rtsp-specific-features: other/rtsp-specific-features
|
||||
usage/rtmp-specific-features: other/rtmp-specific-features
|
||||
usage/decrease-packet-loss: other/decrease-packet-loss
|
||||
|
||||
other/compile: misc/compile
|
||||
other/license: misc/license
|
||||
other/security: misc/security
|
||||
other/specifications: misc/specifications
|
||||
other/related-projects: misc/related-projects
|
||||
|
||||
Reference in New Issue
Block a user