improve documentation (#5586)
This commit is contained in:
Alessandro Ros
@@ -37,7 +37,7 @@ 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 UDP transport protocol of the RTSP server (which require the real IP address and port of incoming UDP packets, that are sometimes replaced by the Docker network stack). If you want to use it, you need to bypass the Docker network stack through the `--network=host` flag (which is not compatible with Windows, macOS and Kubernetes):
|
||||
The `MTX_RTSPTRANSPORTS=tcp` environment variable is meant to disable the UDP transport protocol of the RTSP server (which requires the real IP address and port of incoming UDP packets, that are sometimes replaced by the Docker network stack). If you want to use it, you need to bypass the Docker network stack through the `--network=host` flag (which is not compatible with Windows, macOS and Kubernetes):
|
||||
|
||||
```sh
|
||||
docker run --rm -it --network=host bluenviron/mediamtx:1
|
||||
|
||||
@@ -4,7 +4,7 @@ If you have an existing _MediaMTX_ installation, you can upgrade it to the lates
|
||||
|
||||
## Standalone binary
|
||||
|
||||
The standalone binary comes with a upgrade utility that can be launched with:
|
||||
The standalone binary comes with an upgrade utility that can be launched with:
|
||||
|
||||
```sh
|
||||
./mediamtx --upgrade
|
||||
|
||||
@@ -44,7 +44,7 @@ Be aware that cameras that require a custom `libcamera` (like some ArduCam produ
|
||||
|
||||
## Adding audio
|
||||
|
||||
In order to add audio from a USB microfone, install GStreamer and alsa-utils:
|
||||
In order to add audio from a USB microphone, install GStreamer and alsa-utils:
|
||||
|
||||
```sh
|
||||
sudo apt install -y gstreamer1.0-tools gstreamer1.0-rtsp gstreamer1.0-alsa alsa-utils
|
||||
@@ -67,7 +67,7 @@ default:CARD=U0x46d0x809
|
||||
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:
|
||||
Find the audio card of the microphone 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:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 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:
|
||||
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 an HLS stream, that is accessible through a web page:
|
||||
|
||||
```
|
||||
http://localhost:8888/mystream
|
||||
|
||||
@@ -14,7 +14,7 @@ See [Embed streams in a website](../4-other/14-embed-streams-in-a-website.md) fo
|
||||
|
||||
## 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:
|
||||
Web browsers can also read a stream with the [HLS protocol](06-hls.md). Latency is higher but there are fewer 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
|
||||
|
||||
@@ -117,7 +117,7 @@ The iframe method is fit for most use cases, but it has some limitations:
|
||||
|
||||
In order to overcome the limitations of the iframe-based method, it is possible to load the stream directly inside a `<video>` tag in the web page, through the _hls.js_ library.
|
||||
|
||||
If you are using a JavaScript bundler, you can import _hls.js_ it by adding [its npm package](https://www.npmjs.com/package/hls.js) as dependency and then importing it:
|
||||
If you are using a JavaScript bundler, you can import _hls.js_ by adding [its npm package](https://www.npmjs.com/package/hls.js) as dependency and then importing it:
|
||||
|
||||
```js
|
||||
import Hls from "hls.js";
|
||||
|
||||
@@ -24,7 +24,7 @@ runOnConnectRestart: no
|
||||
|
||||
```yml
|
||||
# Command to run when a client disconnects from the server.
|
||||
# Environment variables are the same of runOnConnect.
|
||||
# Environment variables are the same as runOnConnect.
|
||||
runOnDisconnect: curl http://my-custom-server/webhook?conn_type=$MTX_CONN_TYPE&conn_id=$MTX_CONN_ID
|
||||
```
|
||||
|
||||
@@ -74,7 +74,7 @@ pathDefaults:
|
||||
```yml
|
||||
pathDefaults:
|
||||
# Command to run when there are no readers anymore.
|
||||
# Environment variables are the same of runOnDemand.
|
||||
# Environment variables are the same as runOnDemand.
|
||||
runOnUnDemand:
|
||||
```
|
||||
|
||||
@@ -107,7 +107,7 @@ pathDefaults:
|
||||
```yml
|
||||
pathDefaults:
|
||||
# Command to run when the stream is not available anymore.
|
||||
# Environment variables are the same of runOnReady.
|
||||
# Environment variables are the same as runOnReady.
|
||||
runOnNotReady: curl http://my-custom-server/webhook?path=$MTX_PATH&source_type=$MTX_SOURCE_TYPE&source_id=$MTX_SOURCE_ID
|
||||
```
|
||||
|
||||
@@ -139,7 +139,7 @@ pathDefaults:
|
||||
```yml
|
||||
pathDefaults:
|
||||
# Command to run when a client stops reading.
|
||||
# Environment variables are the same of runOnRead.
|
||||
# Environment variables are the same as runOnRead.
|
||||
runOnUnread: curl http://my-custom-server/webhook?path=$MTX_PATH&reader_type=$MTX_READER_TYPE&reader_id=$MTX_READER_ID
|
||||
```
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ SRT is a protocol that can be used for publishing and reading streams. Regarding
|
||||
|
||||
## Standard stream ID syntax
|
||||
|
||||
In SRT, the stream ID is a string that is sent to the remote part in order to advertise what action the caller is gonna do (publish or read), the path and the credentials. All this information have to be encoded into a single string. This server supports two stream ID syntaxes, a custom one (that is the one reported in rest of the README) and also a [standard one](https://github.com/Haivision/srt/blob/master/docs/features/access-control.md) proposed by the authors of the protocol and enforced by some hardware. The standard syntax can be used in this way:
|
||||
In SRT, the stream ID is a string that is sent to the remote part in order to advertise what action the caller is going to do (publish or read), the path and the credentials. All this information has to be encoded into a single string. This server supports two stream ID syntaxes, a custom one (that is the one reported in the rest of the README) and also a [standard one](https://github.com/Haivision/srt/blob/master/docs/features/access-control.md) proposed by the authors of the protocol and enforced by some hardware. The standard syntax can be used in this way:
|
||||
|
||||
```
|
||||
srt://localhost:8890?streamid=#!::m=publish,r=mypath,u=myuser,s=mypass&pkt_size=1316
|
||||
|
||||
@@ -111,7 +111,7 @@ coturn/coturn \
|
||||
|
||||
We are suggesting and using the following settings:
|
||||
|
||||
- enable the TCP transport only. We are assuming you are setupping Coturn because other connectivity methods have failed, thus TCP is more reliable.
|
||||
- enable the TCP transport only. We are assuming you are setting up Coturn because other connectivity methods have failed, thus TCP is more reliable.
|
||||
- toggle `--network=host` since Coturn allocates a TCP port for each peer connection.
|
||||
- set `min-port` and `max-port` to specify the range of TCP ports.
|
||||
- enable secret-based authentication, that prevents clients from storing permanently valid credentials.
|
||||
|
||||
@@ -6,7 +6,7 @@ RTSP is a protocol that can be used for publishing and reading streams. Regardin
|
||||
|
||||
A RTSP session is split in two parts: the handshake, which is always performed with the TCP protocol, and data streaming, which can be performed with an arbitrary underlying transport protocol, which is chosen by the client during the handshake:
|
||||
|
||||
- UDP: the most performant, but require clients to access two additional UDP ports on the server, which is often impossible due to blocking or remapping by NATs/firewalls in between.
|
||||
- UDP: the most performant, but requires clients to access two additional UDP ports on the server, which is often impossible due to blocking or remapping by NATs/firewalls in between.
|
||||
- UDP-multicast: allows to save bandwidth when clients are all in the same LAN, by sending packets once to a fixed multicast IP.
|
||||
- TCP: the most versatile.
|
||||
|
||||
|
||||
@@ -2,12 +2,12 @@
|
||||
|
||||
MediaMTX is meant for routing live streams, and makes use of a series of protocols and techniques which try to preserve the real-time aspect of streams and minimize latency at cost of losing packets in transmit, in particular:
|
||||
|
||||
- most protocols are built on UDP, which is an "unreliable transport", specifically picked because it allows to drop late packets in case of network congestions.
|
||||
- most protocols are built on UDP, which is an "unreliable transport", specifically picked because it allows dropping late packets in case of network congestion.
|
||||
- there's a circular buffer that stores outgoing packets and drops packets if full.
|
||||
|
||||
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 physical 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 upgrading the network infrastructure (routers, cables, Wi-Fi, firewalls, topology, etc).
|
||||
If you need to improve the stream reliability and decrease packet losses, the first thing to do is to check whether the physical network between the _MediaMTX_ instance and the intended publishers and readers has sufficient bandwidth for transmitting the media stream. Most of the time, 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 upgrading the network infrastructure (routers, cables, Wi-Fi, firewalls, topology, etc).
|
||||
|
||||
Nonetheless there are some parameters that can be tuned to improve the situation, at cost of increasing RAM consumption:
|
||||
|
||||
|
||||
@@ -47,7 +47,7 @@ If you need to use a custom or external libcamera to interact with some Raspberr
|
||||
|
||||
## Cross compile
|
||||
|
||||
Cross compilation allows to build an executable for a target machine from another machine with different operating system or architecture. This is useful in case the target machine doesn't have enough resources for compilation or if you don't want to install the compilation dependencies on it.
|
||||
Cross compilation allows to build an executable for a target machine from another machine with a different operating system or architecture. This is useful in case the target machine doesn't have enough resources for compilation or if you don't want to install the compilation dependencies on it.
|
||||
|
||||
1. On the machine you want to use to compile, install git and Go ≥ 1.25.
|
||||
|
||||
|
||||
+10
-10
@@ -45,7 +45,7 @@ runOnConnect:
|
||||
# Restart the command if it exits.
|
||||
runOnConnectRestart: false
|
||||
# Command to run when a client disconnects from the server.
|
||||
# Environment variables are the same of runOnConnect.
|
||||
# Environment variables are the same as runOnConnect.
|
||||
runOnDisconnect:
|
||||
|
||||
###############################################
|
||||
@@ -123,7 +123,7 @@ authHTTPExclude:
|
||||
- action: pprof
|
||||
|
||||
# JWT-based authentication.
|
||||
# Users have to login through an external identity server and obtain a JWT.
|
||||
# Users have to log in through an external identity server and obtain a JWT.
|
||||
# This JWT must contain the claim "mediamtx_permissions" with permissions,
|
||||
# for instance:
|
||||
# {
|
||||
@@ -302,7 +302,7 @@ rtspAuthMethods: [basic]
|
||||
|
||||
# Enable publishing and reading streams with the RTMP protocol.
|
||||
rtmp: true
|
||||
# Use the secure protocol variant (RTMP).
|
||||
# Use the secure protocol variant (RTMPS).
|
||||
# Available values are "no", "strict", "optional".
|
||||
rtmpEncryption: "no"
|
||||
# Address of the RTMP listener. This is needed only when encryption is "no" or "optional".
|
||||
@@ -501,7 +501,7 @@ pathDefaults:
|
||||
###############################################
|
||||
# Default path settings -> Always available
|
||||
|
||||
# Enable always-available mode, in which a offline segment is played on repeat when the stream is not available.
|
||||
# Enable always-available mode, in which an offline segment is played on repeat when the stream is not available.
|
||||
alwaysAvailable: false
|
||||
# Tracks of the default offline segment.
|
||||
alwaysAvailableTracks: []
|
||||
@@ -512,7 +512,7 @@ pathDefaults:
|
||||
# channelCount: 2
|
||||
# # in case of G711, muLaw must be provided too.
|
||||
# muLaw: false
|
||||
# A MP4 file can be used instead of the default offline segment.
|
||||
# An MP4 file can be used instead of the default offline segment.
|
||||
alwaysAvailableFile: ''
|
||||
|
||||
###############################################
|
||||
@@ -597,8 +597,8 @@ pathDefaults:
|
||||
###############################################
|
||||
# Default path settings -> Redirect source (when source is "redirect")
|
||||
|
||||
# path which clients will be redirected to.
|
||||
# It can be can be a relative path (i.e. /otherstream) or an absolute RTSP URL.
|
||||
# Path to which clients will be redirected.
|
||||
# It can be a relative path (i.e. /otherstream) or an absolute RTSP URL.
|
||||
sourceRedirect:
|
||||
|
||||
###############################################
|
||||
@@ -730,7 +730,7 @@ pathDefaults:
|
||||
# readers connected and this amount of time has passed.
|
||||
runOnDemandCloseAfter: 10s
|
||||
# Command to run when there are no readers anymore.
|
||||
# Environment variables are the same of runOnDemand.
|
||||
# Environment variables are the same as runOnDemand.
|
||||
runOnUnDemand:
|
||||
|
||||
# Command to run when the stream is ready to be read, whenever it is
|
||||
@@ -748,7 +748,7 @@ pathDefaults:
|
||||
# Restart the command if it exits.
|
||||
runOnReadyRestart: false
|
||||
# Command to run when the stream is not available anymore.
|
||||
# Environment variables are the same of runOnReady.
|
||||
# Environment variables are the same as runOnReady.
|
||||
runOnNotReady:
|
||||
|
||||
# Command to run when a client starts reading.
|
||||
@@ -765,7 +765,7 @@ pathDefaults:
|
||||
# Restart the command if it exits.
|
||||
runOnReadRestart: false
|
||||
# Command to run when a client stops reading.
|
||||
# Environment variables are the same of runOnRead.
|
||||
# Environment variables are the same as runOnRead.
|
||||
runOnUnread:
|
||||
|
||||
# Command to run when a recording segment is created.
|
||||
|
||||
Reference in New Issue
Block a user