From 20e7f1db75ea9f63396848bad60c717cae841531 Mon Sep 17 00:00:00 2001 From: Alessandro Ros Date: Sat, 27 Dec 2025 13:55:13 +0100 Subject: [PATCH] docs: improve (#5277) --- docs/1-kickoff/1-introduction.md | 2 +- docs/1-kickoff/2-install.md | 2 +- docs/1-kickoff/3-upgrade.md | 4 ++-- docs/2-usage/01-basic-usage.md | 2 +- docs/2-usage/02-publish.md | 6 +++--- docs/2-usage/04-configuration.md | 12 ++++++++++++ docs/2-usage/05-authentication.md | 4 ++-- docs/2-usage/06-encrypt-the-configuration.md | 9 --------- ...sion.md => 06-remuxing-reencoding-compression.md} | 0 docs/2-usage/{08-record.md => 07-record.md} | 0 docs/2-usage/{09-playback.md => 08-playback.md} | 0 docs/2-usage/{10-forward.md => 09-forward.md} | 0 docs/2-usage/{11-proxy.md => 10-proxy.md} | 0 ...-extract-snapshots.md => 11-extract-snapshots.md} | 0 ...mand-publishing.md => 12-on-demand-publishing.md} | 0 ...timestamps.md => 13-route-absolute-timestamps.md} | 0 ...der.md => 14-expose-the-server-in-a-subfolder.md} | 2 +- ...a-website.md => 15-embed-streams-in-a-website.md} | 4 ++-- .../{17-start-on-boot.md => 16-start-on-boot.md} | 0 .../{18-log-management.md => 17-log-management.md} | 0 docs/2-usage/{19-hooks.md => 18-hooks.md} | 0 .../2-usage/{20-control-api.md => 19-control-api.md} | 0 docs/2-usage/{21-metrics.md => 20-metrics.md} | 2 +- .../2-usage/{22-performance.md => 21-performance.md} | 0 ...cific-features.md => 22-srt-specific-features.md} | 0 ...ic-features.md => 23-webrtc-specific-features.md} | 2 +- ...ific-features.md => 24-rtsp-specific-features.md} | 0 ...ific-features.md => 25-rtmp-specific-features.md} | 2 +- ...ase-packet-loss.md => 26-decrease-packet-loss.md} | 6 +++--- docs/3-references/1-configuration-file.md | 2 +- docs/3-references/2-control-api.md | 2 +- docs/4-other/2-license.md | 2 +- 32 files changed, 34 insertions(+), 31 deletions(-) delete mode 100644 docs/2-usage/06-encrypt-the-configuration.md rename docs/2-usage/{07-remuxing-reencoding-compression.md => 06-remuxing-reencoding-compression.md} (100%) rename docs/2-usage/{08-record.md => 07-record.md} (100%) rename docs/2-usage/{09-playback.md => 08-playback.md} (100%) rename docs/2-usage/{10-forward.md => 09-forward.md} (100%) rename docs/2-usage/{11-proxy.md => 10-proxy.md} (100%) rename docs/2-usage/{12-extract-snapshots.md => 11-extract-snapshots.md} (100%) rename docs/2-usage/{13-on-demand-publishing.md => 12-on-demand-publishing.md} (100%) rename docs/2-usage/{14-route-absolute-timestamps.md => 13-route-absolute-timestamps.md} (100%) rename docs/2-usage/{15-expose-the-server-in-a-subfolder.md => 14-expose-the-server-in-a-subfolder.md} (93%) rename docs/2-usage/{16-embed-streams-in-a-website.md => 15-embed-streams-in-a-website.md} (97%) rename docs/2-usage/{17-start-on-boot.md => 16-start-on-boot.md} (100%) rename docs/2-usage/{18-log-management.md => 17-log-management.md} (100%) rename docs/2-usage/{19-hooks.md => 18-hooks.md} (100%) rename docs/2-usage/{20-control-api.md => 19-control-api.md} (100%) rename docs/2-usage/{21-metrics.md => 20-metrics.md} (98%) rename docs/2-usage/{22-performance.md => 21-performance.md} (100%) rename docs/2-usage/{23-srt-specific-features.md => 22-srt-specific-features.md} (100%) rename docs/2-usage/{24-webrtc-specific-features.md => 23-webrtc-specific-features.md} (95%) rename docs/2-usage/{25-rtsp-specific-features.md => 24-rtsp-specific-features.md} (100%) rename docs/2-usage/{26-rtmp-specific-features.md => 25-rtmp-specific-features.md} (93%) rename docs/2-usage/{27-decrease-packet-loss.md => 26-decrease-packet-loss.md} (72%) diff --git a/docs/1-kickoff/1-introduction.md b/docs/1-kickoff/1-introduction.md index 5b610f8d..623ff2c7 100644 --- a/docs/1-kickoff/1-introduction.md +++ b/docs/1-kickoff/1-introduction.md @@ -2,7 +2,7 @@ Welcome to the MediaMTX documentation! -MediaMTX is a ready-to-use and zero-dependency live media server and media proxy. It has been conceived as a "media router" that routes media streams from one end to the other. +_MediaMTX_ is a ready-to-use and zero-dependency live media server and media proxy. It has been conceived as a "media router" that routes media streams from one end to the other. Main features: diff --git a/docs/1-kickoff/2-install.md b/docs/1-kickoff/2-install.md index 0e0bc48c..b13618ba 100644 --- a/docs/1-kickoff/2-install.md +++ b/docs/1-kickoff/2-install.md @@ -6,7 +6,7 @@ There are several installation methods available: standalone binary, Docker imag 1. Visit the [Releases page](https://github.com/bluenviron/mediamtx/releases) on GitHub, download and extract a standalone binary that corresponds to your operating system and architecture (example: `mediamtx_{version_tag}_linux_amd64.tar.gz`). -2. Start the server: +2. Start the server by double clicking on `mediamtx` (`mediamtx.exe` on Windows) or writing in the terminal: ```sh ./mediamtx diff --git a/docs/1-kickoff/3-upgrade.md b/docs/1-kickoff/3-upgrade.md index 092e421e..73eeaa66 100644 --- a/docs/1-kickoff/3-upgrade.md +++ b/docs/1-kickoff/3-upgrade.md @@ -1,6 +1,6 @@ # Upgrade -If you have an existing MediaMTX installation, you can upgrade it to the latest version. The procedure depends on how MediaMTX was installed. +If you have an existing _MediaMTX_ installation, you can upgrade it to the latest version. The procedure depends on how _MediaMTX_ was installed. ## Standalone binary @@ -10,7 +10,7 @@ The standalone binary comes with a upgrade utility that can be launched with: ./mediamtx --upgrade ``` -This will replace the MediaMTX executable with its latest version. Privileges to write to the executable location are required. +This will replace the _MediaMTX_ executable with its latest version. Privileges to write to the executable location are required. ## Docker image diff --git a/docs/2-usage/01-basic-usage.md b/docs/2-usage/01-basic-usage.md index c3bb156a..dd064520 100644 --- a/docs/2-usage/01-basic-usage.md +++ b/docs/2-usage/01-basic-usage.md @@ -13,7 +13,7 @@ ! qtdemux name=d d.video_0 ! queue ! s.sink_0 d.audio_0 ! queue ! s.sink_1 ``` -2. Open the stream. For instance, you can open the stream with _VLC_: +2. Read the stream. For instance, you can read the stream with _VLC_: ```sh vlc --network-caching=50 rtsp://localhost:8554/mystream diff --git a/docs/2-usage/02-publish.md b/docs/2-usage/02-publish.md index af9ea177..c949edad 100644 --- a/docs/2-usage/02-publish.md +++ b/docs/2-usage/02-publish.md @@ -94,7 +94,7 @@ paths: 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](read#webrtc): +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](read#webrtc): ```yml paths: @@ -452,7 +452,7 @@ ffmpeg -re -stream_loop -1 -i file.ts -c copy -f flv rtmp://localhost:1935/mystr #### FFmpeg and MPEG-TS over UDP -In MediaMTX configuration, add a path with `source: udp+mpegts://238.0.0.1:1234`. Then: +In _MediaMTX_ configuration, add a path with `source: udp+mpegts://238.0.0.1:1234`. Then: ```sh ffmpeg -re -stream_loop -1 -i file.ts -c copy -f mpegts 'udp://127.0.0.1:3356?pkt_size=1316' @@ -468,7 +468,7 @@ ffmpeg -re -f lavfi -i testsrc=size=1280x720:rate=30 \ #### 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: +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 \ diff --git a/docs/2-usage/04-configuration.md b/docs/2-usage/04-configuration.md index 083ac566..f9c104e0 100644 --- a/docs/2-usage/04-configuration.md +++ b/docs/2-usage/04-configuration.md @@ -2,6 +2,8 @@ All the configuration parameters are listed and commented in the [configuration file](/docs/references/configuration-file) (`mediamtx.yml`). +## Change the configuration + There are several ways to change the configuration: 1. By editing the configuration file, that is @@ -46,3 +48,13 @@ There are several ways to change the configuration: ``` 3. By using the [Control API](control-api). + +## Encrypt the configuration + +The configuration file can be entirely encrypted for security purposes by using the `crypto_secretbox` function of the NaCL function. An online tool for performing this operation is [available here](https://play.golang.org/p/rX29jwObNe4). + +After performing the encryption, put the base64-encoded result into the configuration file, and launch the server with the `MTX_CONFKEY` variable: + +``` +MTX_CONFKEY=mykey ./mediamtx +``` diff --git a/docs/2-usage/05-authentication.md b/docs/2-usage/05-authentication.md index 2beac485..d9d860b8 100644 --- a/docs/2-usage/05-authentication.md +++ b/docs/2-usage/05-authentication.md @@ -2,7 +2,7 @@ ## 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. +_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 @@ -306,6 +306,6 @@ Authorization: Bearer MY_JWT 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. +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, see [Embed streams in a website](embed-streams-in-a-website). diff --git a/docs/2-usage/06-encrypt-the-configuration.md b/docs/2-usage/06-encrypt-the-configuration.md deleted file mode 100644 index 6be4e630..00000000 --- a/docs/2-usage/06-encrypt-the-configuration.md +++ /dev/null @@ -1,9 +0,0 @@ -# Encrypt the configuration - -The configuration file can be entirely encrypted for security purposes by using the `crypto_secretbox` function of the NaCL function. An online tool for performing this operation is [available here](https://play.golang.org/p/rX29jwObNe4). - -After performing the encryption, put the base64-encoded result into the configuration file, and launch the server with the `MTX_CONFKEY` variable: - -``` -MTX_CONFKEY=mykey ./mediamtx -``` diff --git a/docs/2-usage/07-remuxing-reencoding-compression.md b/docs/2-usage/06-remuxing-reencoding-compression.md similarity index 100% rename from docs/2-usage/07-remuxing-reencoding-compression.md rename to docs/2-usage/06-remuxing-reencoding-compression.md diff --git a/docs/2-usage/08-record.md b/docs/2-usage/07-record.md similarity index 100% rename from docs/2-usage/08-record.md rename to docs/2-usage/07-record.md diff --git a/docs/2-usage/09-playback.md b/docs/2-usage/08-playback.md similarity index 100% rename from docs/2-usage/09-playback.md rename to docs/2-usage/08-playback.md diff --git a/docs/2-usage/10-forward.md b/docs/2-usage/09-forward.md similarity index 100% rename from docs/2-usage/10-forward.md rename to docs/2-usage/09-forward.md diff --git a/docs/2-usage/11-proxy.md b/docs/2-usage/10-proxy.md similarity index 100% rename from docs/2-usage/11-proxy.md rename to docs/2-usage/10-proxy.md diff --git a/docs/2-usage/12-extract-snapshots.md b/docs/2-usage/11-extract-snapshots.md similarity index 100% rename from docs/2-usage/12-extract-snapshots.md rename to docs/2-usage/11-extract-snapshots.md diff --git a/docs/2-usage/13-on-demand-publishing.md b/docs/2-usage/12-on-demand-publishing.md similarity index 100% rename from docs/2-usage/13-on-demand-publishing.md rename to docs/2-usage/12-on-demand-publishing.md diff --git a/docs/2-usage/14-route-absolute-timestamps.md b/docs/2-usage/13-route-absolute-timestamps.md similarity index 100% rename from docs/2-usage/14-route-absolute-timestamps.md rename to docs/2-usage/13-route-absolute-timestamps.md diff --git a/docs/2-usage/15-expose-the-server-in-a-subfolder.md b/docs/2-usage/14-expose-the-server-in-a-subfolder.md similarity index 93% rename from docs/2-usage/15-expose-the-server-in-a-subfolder.md rename to docs/2-usage/14-expose-the-server-in-a-subfolder.md index f8d5ad4e..06ceb8d1 100644 --- a/docs/2-usage/15-expose-the-server-in-a-subfolder.md +++ b/docs/2-usage/14-expose-the-server-in-a-subfolder.md @@ -1,6 +1,6 @@ # Expose the server in a subfolder -HTTP-based services (WebRTC, HLS, Control API, Playback Server, Metrics, pprof) can be exposed in a subfolder of an existing HTTP server or reverse proxy. The reverse proxy must be able to intercept HTTP requests addressed to MediaMTX and corresponding responses, and perform the following changes: +HTTP-based services (WebRTC, HLS, Control API, Playback Server, Metrics, pprof) can be exposed in a subfolder of an existing HTTP server or reverse proxy. The reverse proxy must be able to intercept HTTP requests addressed to _MediaMTX_ and corresponding responses, and perform the following changes: - The subfolder path must be stripped from request paths. For instance, if the server is exposed behind `/subpath` and the reverse proxy receives a request with path `/subpath/mystream/index.m3u8`, this has to be changed into `/mystream/index.m3u8`. diff --git a/docs/2-usage/16-embed-streams-in-a-website.md b/docs/2-usage/15-embed-streams-in-a-website.md similarity index 97% rename from docs/2-usage/16-embed-streams-in-a-website.md rename to docs/2-usage/15-embed-streams-in-a-website.md index 58517eb5..c8ee2656 100644 --- a/docs/2-usage/16-embed-streams-in-a-website.md +++ b/docs/2-usage/15-embed-streams-in-a-website.md @@ -20,7 +20,7 @@ The iframe can be controlled by adding query parameters to the URL (example: `ht The iframe method is fit for most use cases, but it has some limitations: -- it doesn't allow to pass credentials (username, password or token) from the website to MediaMTX; credentials are asked directly to users. +- it doesn't allow to pass credentials (username, password or token) from the website to _MediaMTX_; credentials are asked directly to users. - it doesn't allow to directly access the video tag, to extract data from it, or to perform dynamic actions. In order to overcome these limitations, it is possible to load the stream directly inside a `