diff --git a/docs/audio.md b/docs/audio.md index a37e6a5e..e831a921 100644 --- a/docs/audio.md +++ b/docs/audio.md @@ -10,7 +10,7 @@ This brings the user experience of working with voice applications on the remote * Audio does not work with DIY devices, either CSI or USB video dongles. - * [VNC](vnc.md) does not support audio, it only works in the Web UI in [WebRTC](webrtc.md) mode. + * [VNC](vnc.md) does not support audio, it only works in the Web UI in [WebRTC](video.md) mode. ----- diff --git a/docs/faq.md b/docs/faq.md index a603256b..09d59730 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -359,7 +359,9 @@ As a first step, we recommend carefully reading our documentation on [GitHub](ht ??? question "How do I disable the web terminal?" ``` + # rw # systemctl disable --now kvmd-webterm + # ro ``` @@ -379,8 +381,9 @@ As a first step, we recommend carefully reading our documentation on [GitHub](ht ## Video problems -??? question "I can see the video but I can't see the WebRTC switch" - WebRTC is an alternative mode for the default MJPEG and it's only supported on V2+ platforms with the CSI video capture device. See [this](webrtc.md) page to solve any problems with WebRTC. +??? question "I can see the video but I can't see the WebRTC / video mode switch" + [WebRTC and Direct H.264](video.md) modes are only available on V2+ platforms with HDMI-CSI capture device, + including PiKVM [V3](v3.md) or [V4 Plus/Mini](v4.md). See the [modes guide](video.md) to solve any problems. ??? question "PiKVM does not show the video from the computer at all" diff --git a/docs/video.md b/docs/video.md index 2ff29109..d2b2c9c3 100644 --- a/docs/video.md +++ b/docs/video.md @@ -1,44 +1,151 @@ -# Working with video +# Video modes +PiKVM [V3](v3.md), [V4 Plus/Mini](v4.md) and all DIY devices based on HDMI-CSI bridge provides three video streaming modes. +This page explains the key differences between them and helps you to achieve optimal video performance. + +The video mode can be switched in the **System** menu in the Web UI. +If you don't see the switch, probably your browser does not support H.264 video. + + + + +!!! tip "Quick tips" + + * Good network: use `WebRTC` or `Direct` mode, set `H.264 gop = 0`. + + * Bad network and `WebRTC` mode: Set `H.264 gop = 30`. + + * Bad network and `Direct` mode: Set `H.264 gop = 0`. + + * If the `WebRTC` mode is not working, try the `Direct`. + + * The `Direct` mode doesn't support audio yet. If you need audio, but `WebRTC` is not working, follow [this guide](webrtc_config.md). + + +----- +## Settings + +* **H.264 kbps** *(Bitrate)* - with a large value, the video quality will be better, but the network traffic will increase. + +* **H.264 gop** *(Group of Pictures)* - the number of frames between which a reference frame must be forcibly added. + The recommended values are described above. + + +----- +## WebRTC H.264 mode + +This is the default mode. It'is using the efficient H.264 encoding to save traffic. +The video is streamed over WebRTC protocol which you may have encountered when you used video calls in Discord or Google Chat. +Since WebRTC does not use HTTP for video, establishing a connection is quite tricky (but PiKVM automates 99% of cases). +If you have problems with the WebRTC mode, please [check this guide](webrtc_config.md). + +!!! info "Advantages / Disadvantages" + + * ✅ Supported by all modern browsers. + + * ✅ Provides [two-way audio](audio.md) on PikVM [V3](v3.md) and [V4 Plus/Mini](v4.md). + + * ❌ The video may be lost due to a poor connection (like mobile internet, bad Wi-Fi, etc.), + or because of the router settings, when WebRTC is given low priority. + + * ❌ It may be blocked at all in some networks. + + * ❌ Sometimes the latency may increase slightly due to the peculiarities of WebRTC processing in all browsers. + + +----- +## Direct H.264 mode + +The new experimental mode for real-time streaming, introduced by PiKVM. +It also uses H.264 encoding, but streams the video over regular HTTP (WebSocket). + +!!! info "Advantages / Disadvantages" + + * ✅ Very stable on poor networks, better than WebRTC (based on our tests and user reviews). + + * ✅ It is not blocked by firewalls because it appears to be regular HTTPS traffic. + + * ✅ The latency is low and stable too. + + * ❌ No audio support right now (but it will). + + * ❌ Some [older browsers](https://caniuse.com/webcodecs) doesn't have the WebCodes support needed for this mode. + + +----- +## Legacy MJPEG mode + +Good old Motion JPEG. This is the way IP cameras have been streaming videos to browsers since ancient times. +The stream is just infinite queue of JPEGs that replace each other in `` HTML tag. +There is no point in using it now if one of the previous modes is working. + +!!! info "Advantages / Disadvantages" + + * ✅ Sometimes the H.264 is disabled in a browser by OS license limitations (for example, in Red Had Linux or Debian). + But MJPEG is working always. + + * ✅ It is not blocked by firewalls because it appears to be regular HTTPS traffic. + + * ✅ Low latency if you have a good network. + + * ❌ No audio support. + + * ❌❌❌ Consumes a HUGE amount of traffic. No Wi-Fi, no mobile, nothing but cable connection will work. + + +----- +## What if H.264 is not supported by browser at all + +There are some Linux distro's that require more work to be able to use H.264, +this may include any RedHat or Debian variant. Here some examples: + + * In case of Chromium on Fedora, you can connect the [RPM Fusion](https://rpmfusion.org) repo + and then install the `chromium-freeworld` package instead of `chromium`. + + * On Debian GNU/Linux and Firefox, make sure the OpenH264 Plugin both exists and is enabled. + Press `Ctrl+Shift+A` to open the `Add-on Manager`, then press `Plugins`. There you should see + *OpenH264 Video Codec provided by Cisco Systems, Inc.* + Make sure it is enabled by pressing the "more options" button (tree dots), then pressing `Always Activate`. + + +----- ## Video recording -!!! info - H.264 is available on Pi 3 and Pi 4. Older boards won't handle it. Best of all this feature only works for HDMI to CSI bridge. For the USB HDMI dongle, there will be a decrease in FPS to 10-15 for 1080p. +At the moment, it is not possible to record videos in a convenient way from the Web UI, +but a small trick in the console can be used to record videos without sound. +It's only available on same PiKVM models which support H.264 video. -1. Update OS: +??? example "Recording video from terminal" - {!_update_os.md!} + 1. Update OS: -2. Install ffmpeg: + {!_update_os.md!} + 2. Install `ffmpeg` package and reboot: + + ```console + [root@pikvm ~]# rw + [root@pikvm ~]# pacman -S ffmpeg + [root@pikvm ~]# reboot + ``` + + 3. After reboot, switch filesystem to RW-mode again using the `rw` command + + 4. To record a video, open the Web UI (i.e. stream should be running) or connect via VNC. + Next, run the recording process in the current directory: + + ```console + [root@pikvm ~]# ustreamer-dump --sink kvmd::ustreamer::h264 --output - | ffmpeg -use_wallclock_as_timestamps 1 -i pipe: -c:v copy my_video.mp4 + ``` + + 5. Press `Ctrl+C` to stop the recording, and don't forget to switch filesystem to read-only mode using the `ro` command. + +??? example "Take a screenshot from terminal" + + To take a screenshot, switch filesystem to RW-mode like in previous example and run the stream. + + Next, take a screenshot: + + ```console + [root@pikvm ~]# curl --unix-socket /run/kvmd/ustreamer.sock http://localhost/snapshot -o /tmp/screen.jpg ``` - # rw - # pacman -S ffmpeg - ``` - -3. For USB dongle only: Add line `gpu_mem=256` to `/boot/config.txt`. - -4. Perform `reboot` command. - -5. Run `rw` after the reboot. - -6. To record a video, you need to enable the stream (open the web interface or connect via VNC). Then run something like this in the console: - - ``` - # rw - # ustreamer-dump --sink kvmd::ustreamer::h264 --output - | ffmpeg -use_wallclock_as_timestamps 1 -i pipe: -c:v copy test.mp4 - ``` - -7. Press `Ctrl+C` to stop recording. Your video will be in the file `test.mp4`. - -8. After finishing work, do not forget to switch the file system to read-only mode using `ro` command. - - -## Take a screenshot via console on PiKVM - -!!! note - You must have a stream running - -``` -# curl --unix-socket /run/kvmd/ustreamer.sock http://localhost/snapshot -o /tmp/screen.jpg -``` diff --git a/docs/video/menu.png b/docs/video/menu.png new file mode 100644 index 00000000..f0a0def8 Binary files /dev/null and b/docs/video/menu.png differ diff --git a/docs/webrtc.md b/docs/webrtc.md deleted file mode 100644 index f1c6b037..00000000 --- a/docs/webrtc.md +++ /dev/null @@ -1,91 +0,0 @@ -# H.264 / WebRTC - -This is a main video streaming mode available on PiKVM V3+ devices and DIY builds based on CSI bridge (USB capture devices are not supported). -With the efficient H.264 encoding, a significant reduction in traffic is achieved compared to old MJPEG mode. - -!!! note - The video modes can be switched in the **System** menu in the Web UI. - If you don't see the switch, probably your browser does not support H.264, - or Janus Gateway (the WebRTC server) is not running on PiKVM. - - See the [troubleshooting](#troubleshooting) section below. - - ------ -## H.264 parameters - -The main parameters available for configuration in the Web UI are **bitrate** and **gop**. - -* **Bitrate (H.264 kbps)** - with a large value, the quality will be better, but the network consumption will increase. -* **Group of pictures (H.264 gop)** - the number of frames between which a reference frame must be forcibly added. - The recommended value is 0 for low-loss networks, this will also reduce latency. Use a value of 30 or so for unreliable networks if the image flickers frequently. - - ------ -## How it's working - -The MJPEG video stream uses the same HTTP connection that you use to get the web interface. -This means that for remote access, you just need to forward ports 80 and 443 on your router. -Please review the [Port Foward doc](port_forwarding.md) for proper usage. - -In contrast, WebRTC is a completely different way of transmitting video. -It uses a P2P connection and UDP. This reduces network load, but makes it difficult to configure - -the server needs to know your network configuration in order to use it correctly. - -To implement this, the PiKVM checks which of the network interfaces is used for the default gateway, -and also tries to find out your external address using the Google [STUN](https://en.wikipedia.org/wiki/STUN) server. -This is necessary when using [Tailscale](tailscale.md) or so that you can connect to your PiKVM from the external Internet. - -If you don't like using Google (it was chosen as the default for reliability reasons) for this purpose, -you can choose [any other STUN server](https://www.voip-info.org/stun/) at your discretion, or set up your own. - -Edit `/etc/kvmd/override.yaml`: - -```yaml -janus: - stun: - host: stun.stunprotocol.org - port: 3478 -``` - -... and restart `kvmd-janus` service using `systemctl restart kvmd-janus`. - - ------ -## Custom Janus config - -[Janus](https://janus.conf.meetecho.com) is a WebRTC gateway that is used to transmit the [uStreamer](https://github.com/pikvm/ustreamer) video. -KVMD-Janus is a wrapper around it, configuring and monitoring changes in the network configuration. This is suitable for most users. -However, if your PiKVM is not connected to the Internet and/or you want to use a custom Janus configuration, -then you should use the `kvmd-janus-static` service instead. You should first change the Janus configuration yourself. -You can find it in `/etc/kvmd/janus/janus.jcfg`. - -``` -# systemctl disable --now kvmd-janus -... -# systemctl enable --now kvmd-janus-static -``` - - ------ -## Troubleshooting - -In rare cases, WebRTC may not work. Here some common tips: - -* Clear the browser cache. - -* Try other browsers, incognito or private window without any extensions. - -* Tricky IPv6 configuration on the network can be a problem. IPv6 support for WebRTC in PiKVM is still in its infancy, so if your network has IPv4, it will be easiest to disable IPv6 on PiKVM. To do this, switch the file system to write mode using `rw` command, add option `ipv6.disable_ipv6=1` to `/boot/cmdline.txt` and perform `reboot`. Also see [here](https://wiki.archlinux.org/title/IPv6#Disable_IPv6). - -* A paranoid firewall when you try to connect to the PiKVM by forwarding port 443 to the Internet from the internal network. WebRTC is not enough of this, it uses UDP on ports 20000-40000 for a P2P connection. Make sure that the Firewall does not block them. - -* If nothing helps, open the browser's JS console and look at the log, and contact our community via [Discord](https://discord.gg/bpmXfz5). Developers and/or experienced users will definitely help you. - -* Another option to try is if you have both wifi and eth connected, disable wifi `rfkill list wifi` then `rfkill block X` where is a number that shows in the output. Reason: Arch Linux will choose to route all outgoing packets out wifi by default. - -* There are some Linux distro's that require more work to be able to use H.264 (WEBRTC MODE), this may include any RedHat or Debian variant. - - * On Fedora you can install the rpmfusion repos, then use the `chromium-freeworld` package instead of `chromium` - - * If on Firefox, make sure the OpenH264 Plugin both exists and is enabled (known issue on Debian GNU/Linux). Press `Ctrl+Shift+A` to open the Add-ons Manager, then press `Plugins`. You should see *OpenH264 Video Codec provided by Cisco Systems, Inc.*. Make sure it is enabled by pressing the "more options" button (3 horizontal dots), then pressing `Always Activate`. diff --git a/docs/webrtc_config.md b/docs/webrtc_config.md new file mode 100644 index 00000000..b10f2a7a --- /dev/null +++ b/docs/webrtc_config.md @@ -0,0 +1,75 @@ +# WebRTC H.264 + +This is the default mode. It'is using the efficient H.264 encoding to save traffic. +The video is streamed over WebRTC protocol which you may have encountered when you used video calls in Discord or Google Chat. + +It is available on PiKVM [V3](v3.md), [V4 Plus/Mini](v4.md) and all DIYdevices based on HDMI-CSI bridge. + +The video mode can be switched in the **System** menu in the Web UI. +If you don't see the switch, probably your browser does not support H.264 video. + + +----- +## How it's working + +The [Direct H.264 or MJPEG video](video.md) is streaming video using the similar HTTP connection like to get the Web UI. +This means that for remote access, you just need to [forward](port_forwarding.md) only ports `80` and `443` on your router it has public external IP address. + +In contrast, WebRTC is a completely different way of transmitting video. +It uses a P2P connection and UDP. This reduces network load, but makes it difficult to connect - +the PiKVM needs to know your network configuration in order to use it correctly: public IP, NAT type and so on. + +To achieve this, the PiKVM checks which of the network interfaces is used for the default gateway, +and tries to find out your external IP address using the Google [STUN](https://en.wikipedia.org/wiki/STUN) server. + +!!! tip + Google STUN servers was choosen for reliability reasons. + + If you don't want to use it, you can choose [any other public STUN server](https://www.voip-info.org/stun) + you like, or set up your own. + + To change the STUN server, edit `/etc/kvmd/override.yaml` (an example): + + ```yaml + janus: + stun: + host: stun.stunprotocol.org + port: 3478 + ``` + + ... and restart `kvmd-janus` service using `systemctl restart kvmd-janus`. + + +----- +## Custom Janus config + +[Janus](https://janus.conf.meetecho.com) is a WebRTC gateway that is used to transmit the video from [PiKVM uStreamer](https://github.com/pikvm/ustreamer). +PiKVM has a special service named `kvmd-janus` which is a wrapper for Janus that monitors the network configuration and applies changes. + +However, if your PiKVM is not connected to the Internet and/or you want to use a custom Janus configuration, +you should run the `kvmd-janus-static` service instead. + +The configuration is located in `/etc/kvmd/janus/janus.jcfg`. +You can change all you need according to the [Janus Documentation](https://janus.conf.meetecho.com/docs/index.html), +stop the `kvmd-janus` and start the `kvmd-janus-static` service: + +``` +[root@pikvm ~]# systemctl disable --now kvmd-janus +[root@pikvm ~]# systemctl enable --now kvmd-janus-static +``` + + +----- +## Troubleshooting + +In some cases, WebRTC may not work. Here some common tips: + +* Clear the browser cache. + +* Try any other browser, incognito or private window without any extensions. + +* Tricky IPv6 configuration on the network can be a problem. IPv6 support for WebRTC in PiKVM is still in its infancy, so if your network has IPv4, it will be easiest to disable IPv6 on PiKVM. To do this, switch the file system to write mode using `rw` command, add option `ipv6.disable_ipv6=1` to `/boot/cmdline.txt` and perform `reboot`. Also see [here](https://wiki.archlinux.org/title/IPv6#Disable_IPv6). + +* A paranoid firewall can interfere too when you try to connect to the PiKVM by forwarding port 443 to the Internet from the internal network. WebRTC is not enough of this, it uses UDP on ports 20000-40000 for a P2P connection. Make sure that the Firewall does not block them. + +* If nothing helps, open the browser's JavaScript console, look at the log and contact our community via [Discord](https://discord.gg/bpmXfz5). Developers and/or experienced users will definitely help you. diff --git a/mkdocs.yml b/mkdocs.yml index 4151e84a..90b63075 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,7 +4,7 @@ site_name: PiKVM Handbook -site_description: Open and cheap DIY IP-KVM on Raspberry Pi +site_description: KVM over IP on Raspberry Pi site_author: Maxim Devaev site_url: https://pikvm.github.io/pikvm @@ -12,7 +12,7 @@ repo_name: pikvm/pikvm repo_url: https://github.com/pikvm/pikvm edit_uri: "" -copyright: "Copyright © 2018-2022 Maxim Devaev" +copyright: "Copyright © 2018-2025 Maxim Devaev" docs_dir: docs @@ -64,6 +64,7 @@ plugins: "3g.md": "modem.md" "4g.md": "modem.md" "usb_dynamic.md": "usb.md" + "webrtc.md": "video.md" nav: - "Device guides": @@ -87,13 +88,13 @@ nav: - "Setting up 3G/4G/LTE modem": modem.md - "Let's Encrypt certificates": letsencrypt.md - "Video": + - "Video modes (WebRTC, Direct)": video.md + - "WebRTC configuration": webrtc_config.md - "Tuning HDMI EDID": edid.md - "HDMI passthrough": pass.md - - "H.264 / WebRTC": webrtc.md - - "Working with video": video.md - "Peripheral devices": - "USB configuration": usb.md - - "Audio / microphone": audio.md + - "Audio / Microphone": audio.md - "Keyboard & mouse": - "Mouse modes": mouse.md - "Mouse jiggler": mouse_jiggler.md