From 3ae52625105ecca505e24b224cd13b384dcd7d48 Mon Sep 17 00:00:00 2001 From: Alessandro Ros Date: Wed, 29 Oct 2025 10:51:02 +0100 Subject: [PATCH] docs: update (#5125) --- docs/1-kickoff/2-install.md | 44 +++++++-------- docs/2-usage/02-publish.md | 2 +- docs/2-usage/03-read.md | 2 +- docs/2-usage/24-rtsp-specific-features.md | 48 ---------------- docs/2-usage/26-decrease-packet-loss.md | 69 +++++++++++++++++++++++ 5 files changed, 93 insertions(+), 72 deletions(-) create mode 100644 docs/2-usage/26-decrease-packet-loss.md diff --git a/docs/1-kickoff/2-install.md b/docs/1-kickoff/2-install.md index e4ff853e..0e0bc48c 100644 --- a/docs/1-kickoff/2-install.md +++ b/docs/1-kickoff/2-install.md @@ -14,26 +14,7 @@ There are several installation methods available: standalone binary, Docker imag ## Docker image -Download and launch the image: - -```sh -docker run --rm -it --network=host bluenviron/mediamtx:1 -``` - -The `1` tag corresponds to the latest `1.x.x` release, that should guarantee backward compatibility when upgrading. It is also possible to bind the image to a specific release, by using the release name as tag (`bluenviron/mediamtx:{docker_version_tag}`). - -There are four image variants: - -| name | FFmpeg included | RPI Camera support | -| -------------------------------- | ------------------ | ------------------ | -| bluenviron/mediamtx:1 | :x: | :x: | -| bluenviron/mediamtx:1-ffmpeg | :heavy_check_mark: | :x: | -| bluenviron/mediamtx:1-rpi | :x: | :heavy_check_mark: | -| bluenviron/mediamtx:1-ffmpeg-rpi | :heavy_check_mark: | :heavy_check_mark: | - -The `--network=host` flag is mandatory for RTSP to work, since Docker can change the source port of UDP packets for routing reasons, and this doesn't allow the server to identify the senders of the packets. - -If the `--network=host` cannot be used (for instance, it is not compatible with Windows or Kubernetes), you can disable the RTSP UDP transport protocol, add the server IP to `MTX_WEBRTCADDITIONALHOSTS` and expose ports manually: +Download and launch the `bluenviron/mediamtx:1` image with the following environment variables and ports: ```sh docker run --rm -it \ @@ -45,12 +26,31 @@ docker run --rm -it \ -p 8889:8889 \ -p 8890:8890/udp \ -p 8189:8189/udp \ -bluenviron/mediamtx +bluenviron/mediamtx:1 ``` +Fill the `MTX_WEBRTCADDITIONALHOSTS` environment variable with the IP that will be used to connect to the server. + +The `MTX_RTSPTRANSPORTS=tcp` environment variable is meant to disable the RTSP UDP transport protocol. If you want to use it, you also need `--network=host` (which is not compatible with Windows, macOS and Kubernetes): + +```sh +docker run --rm -it --network=host bluenviron/mediamtx:1 +``` + +There are four image variants: + +| name | FFmpeg included | RPI Camera support | +| -------------------------------- | ------------------ | ------------------ | +| bluenviron/mediamtx:1 | :x: | :x: | +| bluenviron/mediamtx:1-ffmpeg | :heavy_check_mark: | :x: | +| bluenviron/mediamtx:1-rpi | :x: | :heavy_check_mark: | +| bluenviron/mediamtx:1-ffmpeg-rpi | :heavy_check_mark: | :heavy_check_mark: | + +The `1` tag corresponds to the latest `1.x.x` release, that should guarantee backward compatibility when upgrading. It is also possible to bind the image to a specific release, by using the release name as tag (`bluenviron/mediamtx:{docker_version_tag}`). + ## Arch Linux package -If you are running the Arch Linux distribution, run: +If you are running the Arch Linux distribution, launch: ```sh git clone https://aur.archlinux.org/mediamtx.git diff --git a/docs/2-usage/02-publish.md b/docs/2-usage/02-publish.md index cc9a2a7a..7a5311fb 100644 --- a/docs/2-usage/02-publish.md +++ b/docs/2-usage/02-publish.md @@ -162,7 +162,7 @@ Advanced RTSP features are described in [RTSP-specific features](rtsp-specific-f ### RTMP clients -RTMP is a protocol that allows to read and publish streams, but is less versatile and less efficient than RTSP and WebRTC (doesn't support UDP, doesn't support most RTSP codecs, doesn't support feedback mechanism). Streams can be published to the server by using the URL: +RTMP is a protocol that allows to read and publish streams. It supports encryption, see [RTMP-specific features](rtmp-specific-features). Streams can be published to the server by using the URL: ``` rtmp://localhost/mystream diff --git a/docs/2-usage/03-read.md b/docs/2-usage/03-read.md index f7a91a29..742bdf31 100644 --- a/docs/2-usage/03-read.md +++ b/docs/2-usage/03-read.md @@ -77,7 +77,7 @@ vlc --network-caching=50 rtsp://... ### RTMP -RTMP is a protocol that allows to read and publish streams, but is less versatile and less efficient than RTSP and WebRTC (doesn't support UDP, doesn't support most RTSP codecs, doesn't support feedback mechanism). Streams can be read from the server by using the URL: +RTMP is a protocol that allows to read and publish streams. It supports encryption, see [RTMP-specific features](rtmp-specific-features). Streams can be read from the server by using the URL: ``` rtmp://localhost/mystream diff --git a/docs/2-usage/24-rtsp-specific-features.md b/docs/2-usage/24-rtsp-specific-features.md index e453b852..49d198b3 100644 --- a/docs/2-usage/24-rtsp-specific-features.md +++ b/docs/2-usage/24-rtsp-specific-features.md @@ -104,51 +104,3 @@ paths: ``` There are also the `rtsp+https`, `rtsp+ws`, `rtsp+wss` schemes to handle any variant. - -## Decreasing corrupted frames - -In some scenarios, when publishing or reading from the server with RTSP, frames can get corrupted. This can be caused by several reasons: - -- When the transport protocol is UDP (which is default one), packets sent to the server might get discarded because the UDP read buffer size is too small. This can be noticed in logs through the "RTP packets lost" message. Try increasing the UDP read buffer size: - - ```yml - rtspUDPReadBufferSize: 1000000 - ``` - - If the source of the stream is a camera: - - ```yml - paths: - test: - source: rtsp://.. - rtspUDPReadBufferSize: 1000000 - ``` - - Both these options require the `net.core.rmem_max` system parameter to be equal or greater than `rtspUDPReadBufferSize`: - - ```sh - sudo sysctl net.core.rmem_max=100000000 - ``` - -- When the transport protocol is UDP (which is the default one), packets sent from the server to readers might get discarded because the write queue is too small. This can be noticed in logs through the "reader is too slow" message. Try increasing the write queue: - - ```yml - writeQueueSize: 1024 - ``` - -- The stream is too big and it can't be transmitted correctly with the UDP transport protocol. UDP is more performant, faster and more efficient than TCP, but doesn't have a retransmission mechanism, that is needed in case of streams that need a large bandwidth. A solution consists in switching to TCP: - - ```yml - rtspTransports: [tcp] - ``` - - In case the source is a camera: - - ```yml - paths: - test: - source: rtsp://.. - rtspTransport: tcp - ``` - -- The stream throughput is too big to be handled by the network between server and readers. Upgrade the network or decrease the stream bitrate by re-encoding it. diff --git a/docs/2-usage/26-decrease-packet-loss.md b/docs/2-usage/26-decrease-packet-loss.md new file mode 100644 index 00000000..b3f2d92d --- /dev/null +++ b/docs/2-usage/26-decrease-packet-loss.md @@ -0,0 +1,69 @@ +# Decrease packet loss + +MediaMTX is meant for routing live streams, and makes use of a series of protocol which try to minimize latency at cost of losing packets in transmit. In particular, most protocols are built on UDP, which is an "unrealiable transport", specifically picked because it allows to drop late packets in case of network congestions, preserving the real-time aspect of streams. + +These packet losses are usually detected and printed in MediaMTX logs. + +If you need to improve the stream reliability and decrease packet losses, the first thing to do is to check whether the network between the MediaMTX instance and the intended publishers and readers has sufficient bandwidth for transmitting the media stream. Most of the times, packet losses are caused by a network which is not fit for this scope. This limitation can be overcome by either recompressing the stream with a lower bitrate, or by changing network. + +There are however some parameters that can be tuned to improve the situation, at cost of increasing RAM consumption: + +- When publishing a stream with RTSP, MPEG-TS or RTP, packets might get discarded by the server because the UDP read buffer size is too small. Try increasing the UDP read buffer size: + + ```yml + rtspUDPReadBufferSize: 1000000 + ``` + + If the source of the stream is a camera: + + ```yml + paths: + test: + source: rtsp://.. + rtspUDPReadBufferSize: 1000000 + ``` + + There are similar options for the MPEG-TS and RTP protocol: + + ```yml + paths: + test: + source: udp+mpegts://.. + mpegtsUDPReadBufferSize: 1000000 + ``` + + or: + + ```yml + paths: + test: + source: udp+rtp://.. + rtpUDPReadBufferSize: 1000000 + ``` + + All these options require the `net.core.rmem_max` system parameter to be equal or greater than `rtspUDPReadBufferSize`: + + ```sh + sudo sysctl net.core.rmem_max=100000000 + ``` + +- When reading a stream, packets might get discarded because the write queue is too small. This can be noticed in logs through the "reader is too slow" message. Try increasing the write queue: + + ```yml + writeQueueSize: 1024 + ``` + +- When publishing or reading a stream with RTSP, it's possible to switch from the UDP transport protocol to the TCP transport protocol, which is less performant but has a packet retransmission mechanism: + + ```yml + rtspTransports: [tcp] + ``` + + In case the source is a camera: + + ```yml + paths: + test: + source: rtsp://.. + rtspTransport: tcp + ```