docs: update (#5061)

2025-10-05 18:07:39 +02:00
parent 6415285427
commit 7ecbe736c6
12 changed files with 160 additions and 18 deletions
@@ -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.
@@ -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).
@@ -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>
+```
@@ -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