From 7ecbe736c6b707f44f3995971a2bd74cb9ed3758 Mon Sep 17 00:00:00 2001
From: Alessandro Ros <aler9.dev@gmail.com>
Date: Sun, 5 Oct 2025 18:07:39 +0200
Subject: [PATCH] docs: update (#5061)

---
 docs/2-usage/03-read.md                       |  16 +-
 docs/2-usage/05-authentication.md             |   6 +-
 docs/2-usage/16-embed-streams-in-a-website.md | 152 ++++++++++++++++++
 ...6-start-on-boot.md => 17-start-on-boot.md} |   0
 docs/2-usage/{17-hooks.md => 18-hooks.md}     |   0
 .../{18-control-api.md => 19-control-api.md}  |   0
 docs/2-usage/{19-metrics.md => 20-metrics.md} |   0
 .../{20-performance.md => 21-performance.md}  |   0
 ...eatures.md => 22-srt-specific-features.md} |   0
 ...ures.md => 23-webrtc-specific-features.md} |   0
 ...atures.md => 24-rtsp-specific-features.md} |   4 +-
 ...atures.md => 25-rtmp-specific-features.md} |   0
 12 files changed, 160 insertions(+), 18 deletions(-)
 create mode 100644 docs/2-usage/16-embed-streams-in-a-website.md
 rename docs/2-usage/{16-start-on-boot.md => 17-start-on-boot.md} (100%)
 rename docs/2-usage/{17-hooks.md => 18-hooks.md} (100%)
 rename docs/2-usage/{18-control-api.md => 19-control-api.md} (100%)
 rename docs/2-usage/{19-metrics.md => 20-metrics.md} (100%)
 rename docs/2-usage/{20-performance.md => 21-performance.md} (100%)
 rename docs/2-usage/{21-srt-specific-features.md => 22-srt-specific-features.md} (100%)
 rename docs/2-usage/{22-webrtc-specific-features.md => 23-webrtc-specific-features.md} (100%)
 rename docs/2-usage/{23-rtsp-specific-features.md => 24-rtsp-specific-features.md} (97%)
 rename docs/2-usage/{24-rtmp-specific-features.md => 25-rtmp-specific-features.md} (100%)

diff --git a/docs/2-usage/03-read.md b/docs/2-usage/03-read.md
index 979f5000..61be0d54 100644
--- a/docs/2-usage/03-read.md
+++ b/docs/2-usage/03-read.md
@@ -412,13 +412,7 @@ You can read a stream by using the [WebRTC protocol](#webrtc) by visiting the we
 http://localhost:8889/mystream
 ```
 
-This web page can be embedded into another web page by using an iframe:
-
-```html
-<iframe src="http://mediamtx-ip:8889/mystream" 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 read page](https://github.com/bluenviron/mediamtx/blob/{version_tag}/internal/servers/webrtc/read_index.html). In particular, there's a ready-to-use, standalone JavaScript class for reading streams with WebRTC, available in [reader.js](https://github.com/bluenviron/mediamtx/blob/{version_tag}/internal/servers/webrtc/reader.js).
+See [Embed streams in a website](embed-streams-in-a-website) for instructions on how to embed the stream into an external website.
 
 #### Web browsers and HLS
 
@@ -428,10 +422,4 @@ Web browsers can also read a stream with the [HLS protocol](#hls). Latency is hi
 http://localhost:8888/mystream
 ```
 
-This web page can be embedded into another web page by using an iframe:
-
-```html
-<iframe src="http://mediamtx-ip:8888/mystream" scrolling="no"></iframe>
-```
-
-For more advanced setups, you can create and serve a custom web page by starting from the [source code of the HLS read page](https://github.com/bluenviron/mediamtx/blob/{version_tag}/internal/servers/hls/index.html).
+See [Embed streams in a website](embed-streams-in-a-website) for instructions on how to embed the stream into an external website.
diff --git a/docs/2-usage/05-authentication.md b/docs/2-usage/05-authentication.md
index 249cdf29..2beac485 100644
--- a/docs/2-usage/05-authentication.md
+++ b/docs/2-usage/05-authentication.md
@@ -256,7 +256,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.
+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](embed-streams-in-a-website).
 
 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:
 
@@ -306,4 +306,6 @@ Authorization: Bearer MY_JWT
 
 In OBS Studio, this is the "Bearer Token" field.
 
-If the `Authorization: Bearer` token cannot be provided (for instance, with web browsers that directly access MediaMTX and show a credential dialog), credentials can be passed through the `Authorization: Basic` header, by using the token as password and 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/16-embed-streams-in-a-website.md b/docs/2-usage/16-embed-streams-in-a-website.md
new file mode 100644
index 00000000..27818a1b
--- /dev/null
+++ b/docs/2-usage/16-embed-streams-in-a-website.md
@@ -0,0 +1,152 @@
+# 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](#read).
+
+## WebRTC
+
+The simplest way to embed a live stream in a web page, using the WebRTC protocol, consists in adding an `<iframe>` tag to the body section of the HTML:
+
+```html
+<iframe src="http://mediamtx-ip:8889/mystream" scrolling="no"></iframe>
+```
+
+The iframe can be controlled by adding query parameters to the URL (example: `http://mediamtx-ip:8889/mystream?muted=false`). The following parameters are available:
+
+- `controls` (boolean): whether to show controls. Default is true.
+- `muted` (boolean): whether to start the stream muted. Default is true.
+- `autoplay` (boolean): whether to autoplay the stream. Default is true.
+- `playsInline` (boolean): whether to play the stream without using the entire window of mobile devices. Default is true.
+- `disablepictureinpicture` (boolean): whether to disable the ability to open the stream in a dedicated window. Default is false.
+
+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 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 `<video>` tag in the web page, through a JavaScript library.
+
+Download [reader.js](https://github.com/bluenviron/mediamtx/blob/{version_tag}/internal/servers/webrtc/reader.js) from the repository and serve it together with the other assets of the website.
+
+If you are using a JavaScript bundler, you can import it by using:
+
+```js
+import "./reader.js";
+```
+
+Otherwise, you can add a `<script>` tag to the `<head>` section of the page:
+
+```html
+<script defer src="./reader.js"></script>
+```
+
+Add a `<video>` tag:
+
+```html
+<video id="myvideo" controls muted autoplay width="640" height="480"></video>
+```
+
+After the video tag, add a script that initializes the stream when the page is fully loaded:
+
+```html
+<script>
+  let reader = null;
+
+  window.addEventListener("load", () => {
+    reader = new MediaMTXWebRTCReader({
+      url: "http://mediamtx-ip:8889/mystream/whep",
+      user: "", // fill if needed
+      pass: "", // fill if needed
+      token: "", // fill if needed
+      onError: (err) => {
+        console.error(err);
+      },
+      onTrack: (evt) => {
+        document.getElementById("myvideo").srcObject = evt.streams[0];
+      },
+    });
+  });
+
+  window.addEventListener("beforeunload", () => {
+    if (reader !== null) {
+      reader.close();
+    }
+  });
+</script>
+```
+
+## HLS
+
+Reading a stream with the HLS protocol introduces some latency, but is usually easier to setup since it doesn't involve managing additional ports that in WebRTC are used to transmit the stream.
+
+The simplest way to embed a live stream in a web page, using the HLS protocol, consists in adding an `<iframe>` tag to the body section of the HTML:
+
+```html
+<iframe src="http://mediamtx-ip:8888/mystream" scrolling="no"></iframe>
+```
+
+The iframe can be controlled by adding query parameters to the URL (example: `http://mediamtx-ip:8888/mystream?muted=false`). The following parameters are available:
+
+- `controls` (boolean): whether to show controls. Default is true.
+- `muted` (boolean): whether to start the stream muted. Default is true.
+- `autoplay` (boolean): whether to autoplay the stream. Default is true.
+- `playsInline` (boolean): whether to play the stream without using the entire window of mobile devices. Default is true.
+- `disablepictureinpicture` (boolean): whether to disable the ability to open the stream in a dedicated window. Default is false.
+
+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 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 `<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:
+
+```js
+import Hls from "hls.js";
+```
+
+Otherwise, you can use a `<script>` tag inside the `<head>` section that points to a CDN:
+
+```html
+<script
+  defer
+  src="https://cdnjs.cloudflare.com/ajax/libs/hls.js/1.6.13/hls.min.js"
+></script>
+```
+
+Add a `<video>` tag:
+
+```html
+<video id="myvideo" controls muted autoplay width="640" height="480"></video>
+```
+
+After the video tag, add a script that initializes the stream when the page is fully loaded:
+
+```html
+<script>
+  window.addEventListener("load", () => {
+    if (Hls.isSupported()) {
+      const hls = new Hls({
+        xhrSetup: function (xhr, url) {
+          let user = ""; // fill if needed
+          let pass = ""; // fill if needed
+          let token = ""; // fil if needed
+
+          if (user !== "") {
+            const credentials = btoa(`${user}:${pass}`);
+            xhr.setRequestHeader("Authorization", `Basic ${credentials}`);
+          } else if (token !== "") {
+            xhr.setRequestHeader("Authorization", `Bearer ${token}`);
+          }
+        },
+      });
+
+      hls.on(Hls.Events.MEDIA_ATTACHED, () => {
+        hls.loadSource("http://mediamtx-ip:8888/mystream/index.m3u8");
+      });
+
+      hls.attachMedia(document.getElementById("myvideo"));
+    }
+  });
+</script>
+```
diff --git a/docs/2-usage/16-start-on-boot.md b/docs/2-usage/17-start-on-boot.md
similarity index 100%
rename from docs/2-usage/16-start-on-boot.md
rename to docs/2-usage/17-start-on-boot.md
diff --git a/docs/2-usage/17-hooks.md b/docs/2-usage/18-hooks.md
similarity index 100%
rename from docs/2-usage/17-hooks.md
rename to docs/2-usage/18-hooks.md
diff --git a/docs/2-usage/18-control-api.md b/docs/2-usage/19-control-api.md
similarity index 100%
rename from docs/2-usage/18-control-api.md
rename to docs/2-usage/19-control-api.md
diff --git a/docs/2-usage/19-metrics.md b/docs/2-usage/20-metrics.md
similarity index 100%
rename from docs/2-usage/19-metrics.md
rename to docs/2-usage/20-metrics.md
diff --git a/docs/2-usage/20-performance.md b/docs/2-usage/21-performance.md
similarity index 100%
rename from docs/2-usage/20-performance.md
rename to docs/2-usage/21-performance.md
diff --git a/docs/2-usage/21-srt-specific-features.md b/docs/2-usage/22-srt-specific-features.md
similarity index 100%
rename from docs/2-usage/21-srt-specific-features.md
rename to docs/2-usage/22-srt-specific-features.md
diff --git a/docs/2-usage/22-webrtc-specific-features.md b/docs/2-usage/23-webrtc-specific-features.md
similarity index 100%
rename from docs/2-usage/22-webrtc-specific-features.md
rename to docs/2-usage/23-webrtc-specific-features.md
diff --git a/docs/2-usage/23-rtsp-specific-features.md b/docs/2-usage/24-rtsp-specific-features.md
similarity index 97%
rename from docs/2-usage/23-rtsp-specific-features.md
rename to docs/2-usage/24-rtsp-specific-features.md
index ce919415..03f0767b 100644
--- a/docs/2-usage/23-rtsp-specific-features.md
+++ b/docs/2-usage/24-rtsp-specific-features.md
@@ -25,7 +25,7 @@ gst-launch-1.0 filesrc location=file.mp4 ! qtdemux name=d \
 d.video_0 ! rtspclientsink location=rtsp://localhost:8554/mystream protocols=tcp
 ```
 
-VLC allows to use the TCP transport protocol, use the `--rtsp_tcp` flag:
+VLC allows to use the TCP transport protocol through the `--rtsp_tcp` flag:
 
 ```sh
 vlc --network-caching=50 --rtsp-tcp rtsp://localhost:8554/mystream
@@ -39,7 +39,7 @@ vlc --network-caching=50 rtsp://localhost:8554/mystream?vlcmulticast
 
 ## Encryption
 
-Incoming and outgoing RTSP streams can be encrypted by using a secure protocol variant, called RTSPS, that replaces all the subprotocols that are normally used in RTSP with their secure variant (TLS, MIKEY, SRTP). A TLS certificate is needed and can be generated with OpenSSL:
+Incoming and outgoing RTSP streams can be encrypted by using a secure protocol variant, called RTSPS, that replaces all the subprotocols that are normally used in RTSP with their secure variant (TLS, SRTP, SRTCP). A TLS certificate is needed and can be generated with OpenSSL:
 
 ```sh
 openssl genrsa -out server.key 2048
diff --git a/docs/2-usage/24-rtmp-specific-features.md b/docs/2-usage/25-rtmp-specific-features.md
similarity index 100%
rename from docs/2-usage/24-rtmp-specific-features.md
rename to docs/2-usage/25-rtmp-specific-features.md