moonlight-stream/moonlight-docs
1
0
Fork 0
mirror of https://github.com/moonlight-stream/moonlight-docs.git synced 2025-07-01 15:26:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: two way sync repo and wiki

Browse Source
This commit is contained in:
ReenigneArcher 2025-04-20 09:22:22 -04:00
parent 1694161a67
commit 204e499099
No known key found for this signature in database
GPG Key ID: 362B4EC0ADC98755
23 changed files with 1593 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
.github/workflows/publish-wiki.yml vendored Normal file
View File

@ -0,0 +1,29 @@
---
name: "Publish wiki"
on:
push:
branches:
- master
paths:
- wiki/**
- .github/workflows/publish-wiki.yml
concurrency:
group: "${{ github.workflow }}-${{ github.ref }}"
cancel-in-progress: true
permissions:
contents: write
jobs:
publish:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Publish wiki
uses: Andrew-Chen-Wang/github-wiki-action@v4
with:
path: wiki/

76
.github/workflows/pull-wiki.yml vendored Normal file
View File

@ -0,0 +1,76 @@
---
name: "Pull wiki"
on:
gollum # When wiki is updated
concurrency:
group: "${{ github.workflow }}"
cancel-in-progress: true
jobs:
publish:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Clean wiki
run: rm -rf wiki
- name: Checkout wiki
run: git clone https://github.com/${{ github.repository }}.wiki.git wiki --depth 1
- name: Remove wiki git
run: rm -rf wiki/.git
- name: git diff
id: diff
run: |
git add ./wiki/*
git diff --staged
git diff --color
# multi-line output
echo "diff<<EOF" >> $GITHUB_OUTPUT
git diff >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT
if [[ -n "$(git diff --staged)" ]]; then
echo "Changes detected"
echo "diff<<EOF" >> $GITHUB_OUTPUT
git diff --staged >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT
echo "has_changes=true" >> $GITHUB_OUTPUT
else
echo "No changes detected"
echo "has_changes=false" >> $GITHUB_OUTPUT
fi
- name: Create/Update Pull Request
id: create-pr
if: steps.diff.outputs.has_changes == 'true'
uses: peter-evans/create-pull-request@v7
with:
add-paths: |
wiki/**
token: ${{ secrets.GITHUB_TOKEN }}
commit-message: "chore: sync wiki"
branch: bot/sync-wiki
delete-branch: true
title: "chore: sync wiki"
body: |
This PR syncs the wiki with the main repository.
- name: Automerge PR
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
if: steps.create-pr.outputs.pull-request-number != ''
run: |
gh \
pr \
merge \
--auto \
--delete-branch \
--squash \
"${{ steps.create-pr.outputs.pull-request-number }}"

52
wiki/Fixing-Hardware-Decoding-Problems.md Normal file
View File

@ -0,0 +1,52 @@
<a href="https://moonlight-stream.org/discord"><img src="https://moonlight-stream.org/images/discord.png" height="70" alt="Join our Discord"></a>
# Windows
Moonlight uses either DXVA2 or D3D11VA for hardware acceleration on Windows, depending on hardware support and OS version. All modern GPUs from AMD, NVIDIA, and Intel should support hardware decoding of H.264 via DXVA2 or D3D11VA with the proper drivers installed.
If you have issues with hardware decoding:
* Ensure your client PC GPU drivers are properly installed and up-to-date from the GPU manufacturer or PC vendor's website.
* If your client PC supports NVIDIA Optimus, try switching Moonlight to run on the integrated Intel GPU.
* Ensure you're not using Remote Desktop to access your PC. This can prevent your GPU from being usable for rendering.
# Mac
Moonlight uses VideoToolbox for hardware acceleration on macOS. All Macs capable of running the latest release of macOS should support hardware H.264 decoding without any work required.
If you are using Hackintosh machine, you'll need to find a GPU driver (if available) that correctly implements VideoToolbox decoding for H.264 video.
# Linux
Moonlight uses VAAPI, VDPAU, and NVDEC for hardware acceleration on Linux. One of those APIs should be compatible with any modern desktop GPU. The most common issue preventing it from working properly is a missing driver package for your GPU or if your distro doesn't include H.264 and HEVC decoding support in their Mesa package for AMD GPUs (openSUSE and Fedora don't).
* Hardware acceleration support may differ between included libraries within the Flatpak, Snap, and AppImage packages. If you have hardware acceleration issues, trying a different Moonlight package may resolve the issue.
* If you are running Moonlight via AppImage, you will need to ensure the appropriate video acceleration drivers are installed on your system. On Debian-based distros like Ubuntu, run `apt-get install va-driver-all vdpau-driver-all`. On newer Intel hardware, you may need to also run `apt install intel-media-va-driver-non-free`.
* If you installed Moonlight via Flatpak, you may need extra packages to utilize hardware video decoding in Flatpak applications.
* For AMD GPUs, run `flatpak install flathub org.freedesktop.Platform.GL.default//22.08-extra` to install the required Mesa video codecs.
* For Intel and Nvidia GPUs, run `flatpak update` to ensure the appropriate packages are installed and up-to-date.
* If you are running Wayland on GNOME, you may need to launch Moonlight with the `-platform wayland` option to ensure hardware acceleration works.
* If you installed Moonlight via Snap, run `moonlight -platform wayland`.
* If you installed Moonlight via Flatpak, it runs under Wayland by default.
* Decoding performance under Wayland may not be as good as X11, so try X11 if you experience performance issues.
* For AMD GPU users on Fedora 37 or later, you will need to configure [RPM Fusion Free repositories](https://rpmfusion.org/Configuration) and follow the setup instructions in the "Hardware codecs with AMD" section in [this documentation](https://rpmfusion.org/Howto/Multimedia) to install drivers capable of hardware H.264 and HEVC decoding.
# Steam Deck
The current Steam OS Preview v3.4 disables H.264 and HEVC hardware decoding functionality. This affects both Moonlight and native Steam Link streaming.
See https://github.com/ValveSoftware/SteamOS/issues/903 for details.
If you are willing to risk modifying your OS, you can try the workaround in https://steamcommunity.com/app/1675200/discussions/0/3541546590709961979/
# Raspberry Pi
Moonlight uses the Raspberry Pi's H.264 hardware decoder using the MMAL decoder library. It can also use the HEVC decoder in the Raspberry Pi 4 and later hardware, as long as you've [followed the steps to enable it](https://github.com/moonlight-stream/moonlight-docs/wiki/Installing-Moonlight-Qt-on-Raspberry-Pi-4#hevc-support) and you're running Moonlight outside of the desktop environment.
**First, ensure you have [followed the instructions here](https://github.com/moonlight-stream/moonlight-docs/wiki/Installing-Moonlight-Qt-on-Raspberry-Pi-4#raspbian-bullseye) to ensure you're using the correct display driver for streaming.** Without this step, the H.264 decoder will not work!
If the H.264 decoder still fails to initialize after following the above steps, this usually means that the amount of reserved GPU memory is insufficient.
To increase the reserved GPU memory, run the following commands:
```
echo "gpu_mem=128" | sudo tee -a /boot/config.txt
sudo reboot
```

238
wiki/Frequently-Asked-Questions.md Normal file
View File

@ -0,0 +1,238 @@
## Information on NVIDIA's GameStream End of Service Notification
See the dedicated [GameStream End of Service Notification FAQ](https://github.com/moonlight-stream/moonlight-docs/wiki/NVIDIA-GameStream-End-Of-Service-Announcement-FAQ) page.
We recommend switching to [Sunshine](https://app.lizardbyte.dev/Sunshine/) for hosting, particularly if you experience issues with stream reliability from GeForce Experience. Unlike GeForce Experience, Sunshine is still receiving new features and bugfixes.
## What is Moonlight?
Moonlight is an unofficial third-party open-source client for the NVIDIA SHIELD streaming software that comes included with GeForce Experience. GeForce Experience uses the NVENC hardware on NVIDIA GPUs and custom tuned software to provide low-latency high-quality PC streaming.
## What do I need for my host PC?
The recommended hosting software [Sunshine](https://app.lizardbyte.dev/Sunshine/), which is fully open-source, supports more platforms and GPUs, and has more features, and lacks most of the annoying bugs in the older GeForce Experience hosting software.
If you want to use GeForce Experience to host instead of Sunshine, your host needs:
- Windows 10 or later
- NVIDIA GeForce GTX/RTX GPU 600-series or later
- NVIDIA GeForce Experience
## What devices can I run Moonlight on?
We have official clients for [Windows, macOS, Linux, Raspberry Pi 4, Steam Link hardware](https://github.com/moonlight-stream/moonlight-qt/releases/), [Android](https://play.google.com/store/apps/details?id=com.limelight), [Amazon Fire tablets and TVs](https://www.amazon.com/gp/product/B00JK4MFN2), [iOS, Apple TV](https://apps.apple.com/us/app/moonlight-game-streaming/id1000551566), [and ChromeOS devices](https://chrome.google.com/webstore/detail/moonlight-game-streaming/gemamigbbenahjlfnmlfdjhdnkpbkfjj).
The community has created unofficial ports for [PS Vita](https://github.com/xyzz/vita-moonlight/releases/), [Xbox consoles](https://apps.microsoft.com/detail/9MW1BS08ZBTH), [LG webOS TVs](https://github.com/mariotaku/moonlight-tv), and many [embedded Linux devices](https://github.com/irtimmer/moonlight-embedded/wiki/Packages).
## Is there a Moonlight web client?
No, while there is a ChromeOS app that runs on Chromebooks, there is not a pure web-based Moonlight client. The GameStream protocol requires us to use raw TCP and UDP sockets which is not currently supported in web browsers. Fortunately, there is a proposed [Direct Sockets web standard](https://github.com/WICG/raw-sockets/blob/master/docs/explainer.md) in development that could make it possible to implement a web-based Moonlight client in the future.
While we would like to offer a web-based client as an option, we believe that native apps currently provide the most feature-rich and performant clients. Optimizations like changing the display refresh rate to match the stream frame rate, communicating with gamepads that aren't natively supported by the OS or browser, and using full-screen exclusive mode for lower latency are not currently available to web apps. Web browsers are also often forced to make tradeoffs to cater to the most common use-cases at the expense of others. For example, a design tradeoff for better battery life for video playback or smoother web animations might result in an increase to rendering latency.
## Can I stream from my PC while outside my house?
Yes, for many ISPs, it's as simple as [installing the Moonlight Internet Hosting Tool on your PC](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#automatic-configuration-recommended-for-most-users).
If your ISP doesn't provide dedicated public IP addresses, you can still [stream using ZeroTier](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#zerotier) but the setup is slightly more complicated.
When you are streaming outside your home, we recommend that you choose a bitrate in Moonlight that is at least 1 Mbps lower than your Internet connection's upload speed. This will leave room for other upload traffic from your network to avoid disturbing your Moonlight streaming performance.
## Can I wake up my PC for streaming if it's asleep?
If you're connected to the same network as your host, it is usually possible to wake your PC with Moonlight. If it's not working, check your NIC driver and BIOS settings to ensure Wake-on-LAN is enabled.
If you're streaming from outside your home network, it is not always possible to wake your PC. Certain routers may support it, but many don't. We recommend that you leave your computer awake if you want to stream outside your home.
## Can I stream my entire desktop with Moonlight?
Yes, many Moonlight users use it as a high performance remote desktop client.
If you're using Sunshine on your host PC, you should see a "Desktop" option included out of the box. If you're using GeForce Experience, you can add an option to stream your full desktop [using these steps](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#using-moonlight-to-stream-your-entire-desktop).
If you're using the PC client, you can also enable remote desktop mouse mode in the Moonlight settings for a seamless mouse experience when using other apps along with Moonlight.
## Can I use special input hardware like flight sticks, steering wheels, gyros, etc?
Yes, but not with Moonlight itself. GameStream only supports passing gamepad input via virtual Xbox 360 controllers to the host PC. This means special input devices connected to the Moonlight client like flight sticks, steering wheels, etc. cannot be directly passed through to the host PC.
To pass through those special devices to your host PC, we recommend [VirtualHere](https://virtualhere.com/) which can pass through 1 USB device for free, or more with the paid version.
## Is Moonlight secure?
NVIDIA GameStream uses a secure pairing process to establish trust between clients and hosts. Each Moonlight client generates a unique key which is exchanged directly with the host PC during the pairing process. This process authorizes the Moonlight client to launch games, view installed apps, etc.
Moonlight client keys are generated and stored locally on each client. We never receive your unique client keys, so there is no online account system that could possibly be compromised to gain access to your PC.
Keyboard, mouse, and gamepad data is sent back to the host PC over an encrypted connection to prevent the possibility of this data being intercepted when travelling over an insecure network. For even more security, you can use Moonlight over a VPN connection [like ZeroTier](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#zerotier) which encrypts all traffic.
Beginning in Sunshine v0.22, full end-to-end encryption is supported. This includes all video, audio, control, and connection setup traffic. By default, full encryption is enabled for capable devices when streaming over the Internet. Encryption can be disabled or made mandatory for LAN and WAN connections independently in the Sunshine configuration.
## Where can I get help with streaming issues?
[Our Discord server](https://moonlight-stream.org/discord) is the best place to find help from Moonlight developers and the community.
## Where can I make suggestions for improvements to Moonlight?
You can [suggest improvements here](https://ideas.moonlight-stream.org). Please upvote suggestions to show your support. Only comment if you have something to add to the conversation.
Some new features will require the use of [Sunshine](https://github.com/LizardByte/Sunshine) for hosting, instead of GeForce Experience, since the latter is out of support from NVIDIA and is not receiving new feature work.
## Where can I find the Moonlight source code?
The Moonlight source code is on our [GitHub page](https://github.com/moonlight-stream).
We welcome pull requests. If you'd like to port Moonlight to a new platform, please [join our Discord server](https://moonlight-stream.org/discord). We would be happy to share our knowledge with you to help you bring Moonlight to a new platform.
## Why doesn't my audio work after I stop streaming?
This is almost always because you haven't truly ended your streaming session; you've just disconnected from it.
When you just exit the stream or close Moonlight, the session remains running on your host PC to ensure you don't lose progress in the game or application that you're streaming. This behavior also allows you to seamlessly pick up your streaming session from a totally different device without having to restart your game.
If you select your PC in Moonlight, you will see that the app you were streaming still has the Play button icon on it, which indicates the session for that app is still active.
To end your streaming session, select the running game and choose Quit App. Keep in mind that this will forcefully terminate the app on your host PC, so ensure you've saved your progress first!
## Why does my host PC resolution change to 720p when I start streaming?
GeForce Experience only officially supports 720p, 1080p, and 4K streaming resolutions. Moonlight allows users to pick resolutions to stream that aren't on that officially supported list, but these will cause GeForce Experience to set the host PC resolution to 720p when streaming starts.
This is usually not a problem, since you can configure your resolution in game to whatever you want and that will kick in when the game launches. If changing resolution in game isn't working, make sure your game is configured to use full-screen exclusive mode instead of borderless windowed mode.
You can also [stream your full desktop](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#using-moonlight-to-stream-your-entire-desktop) which will not adjust your host PC resolution at all.
Note: This issue doesn't affect hosts using [Sunshine](https://github.com/LizardByte/Sunshine) instead of GeForce Experience.
## Why doesn't Moonlight show all of my games?
NVIDIA GeForce Experience only reports games that NVIDIA has manually validated to work correctly with GameStream, even if they otherwise appear in GeForce Experience's game list.
You can add any game manually [using these steps](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#adding-custom-programs-that-are-not-automatically-found).
## Why doesn't Steam show up on my Apple TV or iOS device?
To comply with [Apple App Store Review Guideline 4.2.7d](https://developer.apple.com/app-store/review/guidelines/#minimum-functionality), we cannot show the Steam app out of the box, because it features a third-party store for purchasing games.
You can manually add Steam if you would like [using these steps](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#adding-custom-programs-that-are-not-automatically-found).
## Why can't I add a PC that isn't on my local network on my Apple TV or iOS device?
To comply with [Apple App Store Review Guideline 4.2.7a](https://developer.apple.com/app-store/review/guidelines/#minimum-functionality), we cannot allow computers to be added that aren't connected to your local network. You must add them while connected to the same network.
## Why doesn't my mouse work properly in FPS games on Android 7.1 or earlier?
Android 8.0 is the first version of Android that contains support for mouse pointer capture. Without this, mouse support is limited to games that don't utilize relative mouse motion, like RTS or simulation games.
If your device is rooted, you may try the APK named 'app-root-release.apk' on the [Moonlight Android releases page](https://github.com/moonlight-stream/moonlight-android/releases). This version of Moonlight uses root access to capture the mouse pointer on older Android devices.
## Why does my mouse move very fast on Android?
Android's mouse capture API does not allow apps to opt-out of mouse acceleration. The result is that your mouse may be accelerated twice, once by Android and once by Windows, leading to difficulty controlling the mouse.
If possible, you can disable mouse acceleration in your game as a workaround.
NVIDIA has implemented a custom method for disabling mouse acceleration on their own SHIELD Android devices. Moonlight uses this support to provide proper non-accelerated mouse support on NVIDIA Shield Android devices. Unfortunately, there is no generic solution for other Android devices.
## Why does my host's mouse acceleration change while streaming?
When GeForce Experience starts a GameStream session, it adjusts the Windows mouse acceleration and pointer speed options to some predefined settings. We don't know exactly why NVIDIA's software does this, but there is nothing Moonlight can do to opt out of it.
The adjusted mouse acceleration is not generally a problem in games, because most games disable Windows' mouse acceleration or implement their own custom mouse acceleration internally. If your mouse is misbehaving in game, look for an option to enable "raw input", disable "mouse acceleration", or similar options.
For remote desktop usage, Moonlight has a remote desktop optimized mouse mode that can be enabled in the Moonlight's input settings. In remote desktop mouse mode, your host's mouse cursor will directly track at the same position as your client's cursor. Not only does this avoid host mouse acceleration problems, but it also allows your cursor to seamlessly enter and exit the Moonlight window without having to bind and unbind your mouse. In this configuration, Moonlight behaves very similarly to Microsoft Remote Desktop or Chrome Remote Desktop.
Note: This issue doesn't affect hosts using [Sunshine](https://github.com/LizardByte/Sunshine) instead of GeForce Experience.
## Why do I see periodic stutters on macOS when streaming over WiFi?
macOS performs periodic background WiFi scans for Location and AirDrop. While the WiFi radio is scanning, it cannot send or receive traffic. The result is that video and audio data is delayed or dropped during these scans. The result is perceived as stuttering video and audio.
To minimize background scans that lead to stuttering, try disabling AirDrop and Location Services.
Other video applications like Netflix or YouTube keep a buffer of some data which smooths over these small glitches. Real-time streaming apps like Moonlight can't buffer data because it would introduce significant latency. As a result, Moonlight and other game streaming apps are much more sensitive to small glitches in your network performance.
## Why is my frame rate low when streaming my desktop on a laptop with NVIDIA Optimus?
There is extra overhead to stream the desktop when Optimus is enabled, because each frame must be copied back from the iGPU to the NVIDIA GPU for NVENC to encode it. This extra copying overhead usually results in frame rates between 25 and 40 FPS while streaming the desktop.
Once you start a full-screen game, the streaming performance should go back to normal. If it doesn't, make sure your game is set to run on the NVIDIA GPU and that your game is set to use full-screen exclusive mode instead of borderless windowed mode.
Note: This issue doesn't affect hosts using [Sunshine](https://github.com/LizardByte/Sunshine) instead of GeForce Experience.
## Why is my frame rate low when streaming static content from Sunshine?
Unlike GeForce Experience which produces a fixed frame rate encode, Sunshine uses variable frame rate encoding to match the rate of content updates on the host. That means you'll see a low frame rate (typically around 10 FPS) when streaming static content. When content on the screen starts changing, the frame rate will increase to match the frame rate of the content displayed on the host PC, up to the maximum FPS set in Moonlight.
Note: On some Android devices, this may cause the reported decoding latency numbers to be higher when content is static than it will be when actually gaming.
## Why doesn't the bitrate slider go beyond 150 Mbps?
There are a few hardware and software limitations at play.
The hardware video decoder on the client must have the capability to actually handle the video bitrate you specify. Since almost no content is produced at a bitrate above 100 Mbps, it's unlikely that the hardware decoder and driver could handle a 1 Gbps video stream even if you have a 1 Gbps network connection.
Encoders also have limitations regarding the amount of data they can encode from the source video. NVIDIA's GameStream tuning for NVENC is optimized for very fast encode times to ensure low latency. While this ensures frames are delivered to the client as fast as possible, it also limits the encoding hardware in terms of how much encoding it can do in the time window.
Finally, GeForce Experience itself also caps the bitrate that it will use for encoding, regardless of what Moonlight asks for. This is likely due to the encoding limitations above.
## How can I see on-screen statistics about my streaming performance?
On the PC client, you can press Ctrl+Alt+Shift+S to enable the stats overlay while streaming. Raspberry Pi and Steam Link do not current have overlay support, but you can see the same stats in the log file after you end your stream.
On Android and iOS, you can enable the on-screen overlay in the Moonlight settings.
## What do the numbers mean in the on-screen connection statistics?
Notes about these numbers:
- Due to limitations of the various decoding APIs available on each platform, not all latency and frame drop numbers will be available on all Moonlight clients.
- Client performance can vary significantly depending on the selected frame rate, resolution, client hardware, etc. You can tweak these settings to improve your performance.
- These numbers can't be used to compare to other non-Moonlight clients, since each value may not be measuring the same thing, despite potentially having the same name.
- There is additional system latency that can't be measured by apps (compositor latency, display latency, input device latency, etc). For the most accurate results, you should always measure using external testing hardware.
### Latency numbers
- Network latency
- This is your "ping" time to your host - the time it takes for one packet to be sent from client -> host -> client.
- In more concrete terms, this is the amount of network delay for user input (like a key press) to reach the host, then for the resulting video and audio from the host to reach the client.
- Network latency usually increases as the geographic distance from your host increases.
- Network latency can also increase if your bitrate is set higher than your connection can handle well.
- Many cellular networks (3G, 4G/LTE, 5G) tend to have higher network latency than traditional Internet connections.
- Network latency variance
- This measures the amount of variance between the network latency of each packet (also known as: jitter).
- Latency variance/jitter depends on how well the connection to your host is handling the network load from streaming.
- If this value is very high or jumps around a lot, try lowering the bitrate in Moonlight or streaming from a more stable connection.
- Decode latency
- This is the average amount of time it takes for a frame to be decoded and ready for rendering.
- This number varies widely depending on your client hardware, bitrate, stream frame rate, and stream resolution.
- Increasing the frame rate to 90 or 120 FPS may decrease decode latency on some devices.
- Frame queue latency
- This is the average amount of time that frames wait to be rendered after decoding. The wait is usually because the previous frame is still being rendered or waiting for V-Sync.
- It should usually stay under a frame interval (16 ms for 60 FPS), but in rare cases, driver issues can cause it to rise significantly if rendering is not progressing at the normal rate.
- Render latency
- This is the average amount of time it takes for a decoded frame to be rendered to the display.
- If you have V-Sync enabled, this will typically include a V-sync period (16 ms for a 60 Hz display) in addition to the actual render latency. This is because Moonlight must wait for V-Sync to render.
### Frame drop numbers
- Frames dropped by network connection
- This indicates the percentage of frames that are sent from the host and don't successfully reach the client. It should stay very close to 0% most of the time.
- High values indicate an unreliable network connection (like 2.4 GHz WiFi or powerline networking) or that your connection is not capable of streaming at the bitrate settings you've chosen.
- Frames dropped due to network jitter
- This indicates the percentage of frames dropped because they are too early or too late to render.
- Rather than coming at a smooth 16ms-16ms-16ms-16ms... for each frame, network variance may cause patterns like 20ms-12ms-18ms-14ms... which forces Moonlight to skip or drop frames to stay in sync with the client display.
- It is typically caused by high network jitter but it can also be caused by hardware limitations or software issues (especially if very high).
## What do the frame pacing options on the Android client mean?
- Prefer lowest latency
- Renders a frame immediately after it has been decoded (dropping the last frame if it hasn't been displayed yet)
- Keeps the display refresh rate as high as possible
- Balanced (recommended)
- Uses a [Choreographer frame callback](https://developer.android.com/reference/android/view/Choreographer.FrameCallback) to render when the next frame is due
- Up to 1 frame is buffered to smooth over network jitter and v-sync drift between host and client
- Balanced with FPS limit
- Limits the FPS value to the display refresh rate - 1 and never drops frames
- If FPS > display refresh rate, it will behave like Balanced
- Devices with variable refresh rate displays may have issues with this pacing method due to fluctuations in display refresh rate
- This was the default frame pacing behavior before v10.0
- Prefer smoothest video
- Never drops frames, even if the frame rate is equal or higher than the display
- Frames queue up until they hit an OS-defined limit, potentially leading to very high latency

9
wiki/Gamepad-Mapping.md Normal file
View File

@ -0,0 +1,9 @@
The [Moonlight PC client](https://github.com/moonlight-stream/moonlight-qt) contains built-in mappings for most popular game controllers courtesy of SDL2 and the community maintained [list of SDL gamepad mappings](https://github.com/gabomdq/SDL_GameControllerDB).
If your gamepad mapping isn't included in Moonlight or SDL, you will need to map it in order to use it in Moonlight.
### Mapping Instructions
1. Run this [SDL gamepad mapping tool](https://generalarcade.com/gamepadtool/)
2. Select the controller without a mapping, then click "Create a new mapping"
3. After mapping, click "Set Mapping As Environment Variable" and start Moonlight

18
wiki/Get-In-Touch.md Normal file
View File

@ -0,0 +1,18 @@
**Talk to Us!**
<a href="https://moonlight-stream.org/discord"><img src="https://moonlight-stream.org/images/discord.png" height="70" alt="Join our Discord"></a>
**[Discord](https://moonlight-stream.org/discord)**: Keep up with Moonlight developments and get in touch with the developers and other users. This is the recommended way to get the fastest help, since many people can answer your questions.
**Email**: info@moonlight-stream.org
We receive a lot of mail and can't respond to all of it, so please research your question on this wiki first. If we don't respond in a few days and you still haven't been able to sort out your issue, feel free to send a follow-up email to remind us - sometimes we miss things in our inboxes.
If you do email us, please include the troubleshooting steps you've already tried and the version of Moonlight you're having issues with.
**Report bugs**: If you have a Github account, please open issues on the Issues page of the corresponding project. Please do not create issues on this project.
- [Report Moonlight Android Issues](https://github.com/moonlight-stream/moonlight-android/issues)
- [Report Moonlight iOS Issues](https://github.com/moonlight-stream/moonlight-ios/issues)
- [Report Moonlight PC Issues](https://github.com/moonlight-stream/moonlight-qt/issues)
- [Report Moonlight Chrome Issues](https://github.com/moonlight-stream/moonlight-chrome/issues)
![](https://github.com/moonlight-stream/moonlight-android/blob/master/app/src/main/res/drawable-xhdpi/ic_launcher.png)

18
wiki/Home.md Normal file
View File

@ -0,0 +1,18 @@
<a href="https://moonlight-stream.org/discord"><img src="https://moonlight-stream.org/images/discord.png" height="70" alt="Join our Discord"></a>
## Introduction
Welcome to **Moonlight** - the open source client implementation of NVIDIA GameStream that allows you to to stream your collection of games and apps from your GameStream-compatible PC to another device.
**Disclaimer: This app is not affiliated with NVIDIA Corporation. Please do not contact them for support.**
This wiki is open to contributions from our community. Thanks for making Moonlight easier to use!
## Navigation
| **[Moonlight Overview](https://github.com/moonlight-stream/moonlight-docs/wiki/Moonlight-Overview)** | **[Setup Guide](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide)** | **[Troubleshooting](https://github.com/moonlight-stream/moonlight-docs/wiki/Troubleshooting)**|**[Project and Community](https://github.com/moonlight-stream/moonlight-docs/wiki/Project-and-Community)**|
|:-----:|:-----:|:-----:|:-----:|
| Introducing Moonlight - what it does and where it came from. | Step-by-step guide on how to get started with Moonlight. | Guide to troubleshooting Moonlight issues. | About the developers, community, and how to contribute. |
## Questions? Comments? Bugs?
If you can't find your answer in any of the other wiki pages, check out our [Get In Touch](https://github.com/moonlight-stream/moonlight-docs/wiki/Get-In-Touch) page.
***

83
wiki/Installing-Moonlight-Qt-on-ARM‐based-Single-Board-Computers.md Normal file
View File

@ -0,0 +1,83 @@
Beginning with Moonlight Qt v5.0.0, we are now publishing generic armhf and aarch64 Debian packages for use on single-board computers or other embedded devices. This packages are designed for devices that have standards-compliant V4L2 H.264 and/or HEVC decoders and working DRI drivers. Devices that use non-standard video decoding interfaces should use [Moonlight Embedded](https://github.com/moonlight-stream/moonlight-embedded) instead.
ARM SBCs often have notoriously bad video and graphics drivers (sometimes requiring special patches to work), so your experience may vary depending on your hardware and which distro you choose.
These packages are designed to be used directly from the console (not inside a desktop environment) for best performance. Newer devices with more powerful GPUs may perform fine within a desktop environment, though certain features like HDR will not work.
Supported distros:
- Debian/Armbian Bullseye
- Debian/Armbian Bookworm
- Ubuntu 22.04 (Jammy)
- Ubuntu 24.04 (Noble)
Other requirements:
- 32-bit ARMv7 or 64-bit ARMv8 (armhf or aarch64)
- Working V4L2 H.264 or HEVC decoder (stateful or stateless)
- Linux kernel v5.8 or later
Tested working devices:
- Asus Tinkerboard (RK3388) - Armbian Bookworm
- Orange Pi 4 LTS (RK3399) - Armbian Bookworm
Tested non-working devices:
- **Raspberry Pi - [Use this build instead](https://github.com/moonlight-stream/moonlight-docs/wiki/Installing-Moonlight-Qt-on-Raspberry-Pi-4)**
- NanoPi R6S (RK3588 currently lacks V4L2 drivers)
[![Hosted By: Cloudsmith](https://img.shields.io/badge/OSS%20hosting%20by-cloudsmith-blue?logo=cloudsmith&style=for-the-badge)](https://cloudsmith.com)
## Installation
Run the following commands to install Moonlight Qt to your device:
```
curl -1sLf 'https://dl.cloudsmith.io/public/moonlight-game-streaming/moonlight-qt/setup.deb.sh' | sudo -E bash
sudo apt install moonlight-qt
```
### Updates
To update Moonlight Qt after you've installed it, run:
```
sudo apt update
sudo apt upgrade
```
### Running Moonlight
Start Moonlight by running the `moonlight-qt` command.
For best performance, run Moonlight directly from a console/TTY. If you are currently in a desktop environment, you should be able to switch using Ctrl+Alt+(F1-F7). Usually your desktop will be at Ctrl+Alt+F1 or Ctrl+Alt+F7, so you can pick a different TTY that's not being used.
## Support
For the most part, these packages are provided without official support. We can fix bugs in Moonlight itself, but if it doesn't start or stream at all, odds are that it's related to your hardware or OS and won't be fixable by us.
### GUI doesn't start
This most likely means your device lacks either a working DRI driver (check if a `/dev/dri/card*` device exists) or an OpenGL ES 2.0 driver (even a software one) or that your user account lacks permission to open /dev/dri devices.
The error message from Qt may give you a hint as to what the problem is. You may try adding `-platform linuxfb` to the end of the `moonlight-qt` command (which will somewhat break the UI, but may allow you to get far enough to stream) or try creating a EGLFS configuration json file [as detailed here](https://doc.qt.io/qt-5/embedded-linux.html#eglfs-with-the-eglfs-kms-backend).
If you see an error like `Could not open DRM device /dev/dri/card0 (Permission denied)`, it's probably your account is not a member of the `video` group. To fix this, run `sudo usermod -a -G video $USER` and reboot.
### Input devices aren't working
This is probably because you're not a member of the `input` group, so Moonlight lacks permission to open input devices to receive input.
To fix this, run `sudo usermod -a -G input $USER` and reboot.
### GUI is very slow/unresponsive
This is usually because your device or distro lacks an hardware accelerated OpenGL ES driver and is using software rendering instead. Unfortunately, this is quite common on many ARM devices due to the lack of open-source drivers. You may try to find a distro that contains proper OpenGL ES drivers, or you can try adding `-platform linuxfb` to the `moonlight-qt` command (which will cause some UI issues, but should make it slightly faster).
Note: Only Moonlight's UI is actually using OpenGL, so the slowness of the GUI will not impact performance while streaming.
### Video decoder error dialog when starting Moonlight
This means your device or distro doesn't have working V4L2 decoders for H.264 or HEVC. Generally this is a show-stopper for Moonlight Qt
on your device, but you may also try [Moonlight Embedded](https://github.com/moonlight-stream/moonlight-embedded) which supports some vendor-specific decoding APIs.
You may try searching the Internet for any special distro builds, newer kernels, or patches that might enable V4L2 decoding on your device's SoC.
### Display doesn't switch to HDR mode or HDR content is not displayed correctly
This usually means that your hardware is probably not exposing the standard properties used for HDR (`COLOR_ENCODING`, `HDR_OUTPUT_METADATA`, and `Colorspace`). You may see an error message from Moonlight referring to one or more of those properties.
If so, there is probably nothing you (or we) can do. You may be able to find a distro or kernel for your device that properly implements HDR modesetting support if you search around.

24
wiki/Installing-Moonlight-Qt-on-Linux4Tegra-(L4T)-Ubuntu.md Normal file
View File

@ -0,0 +1,24 @@
Beginning with Moonlight Qt v2.0.0, support for L4T devices such as the [Nintendo Switch](https://wiki.switchroot.org/en/Linux/Ubuntu-Install-Guide) and NVIDIA Jetson development boards is in beta. As is typical with beta releases, the usual caveats apply: this may not perform well for you; it may crash/hang or just not work at all. Please [report bugs](https://github.com/moonlight-stream/moonlight-qt/issues) if you encounter issues.
NOTE: If you installed an earlier preview version of Moonlight Qt prior to v2.0.0, you must switch to the official repository to receive the update to v2.0.0 and future updates. To do so, you must first run `sudo apt remove moonlight` then run the commands listed in the installation section to install the new `moonlight-qt` package.
[![Hosted By: Cloudsmith](https://img.shields.io/badge/OSS%20hosting%20by-cloudsmith-blue?logo=cloudsmith&style=for-the-badge)](https://cloudsmith.com)
Requirements:
* Linux4Tegra OS based on Ubuntu 18.04, Ubuntu 22.04, or Ubuntu 24.04
### Installation
Run the following commands to install Moonlight Qt to your L4T device:
```
curl -1sLf 'https://dl.cloudsmith.io/public/moonlight-game-streaming/moonlight-l4t/setup.deb.sh' | sudo -E bash
sudo apt install moonlight-qt
```
You can then launch Moonlight from your desktop or via the `moonlight-qt` command in the terminal.
### Updates
To update Moonlight Qt after you've installed it, run:
```
sudo apt update
sudo apt upgrade
```

126
wiki/Installing-Moonlight-Qt-on-RISC‐V-Single-Board-Computers.md Normal file
View File

@ -0,0 +1,126 @@
Beginning with Moonlight Qt v5.0.0, we are now publishing experimental Debian Sid packages for use on single-board computers or other embedded devices. This packages are designed for devices that have standards-compliant V4L2 H.264 and/or HEVC decoders and working DRI drivers.
SBCs often have notoriously bad video and graphics drivers (sometimes requiring special patches to work), so your experience may vary depending on your hardware and which distro you choose.
These packages are designed to be used directly from the console (not inside a desktop environment) for best performance.
Requirements:
- RISC-V board
- Debian/Armbian Sid
- Working V4L2 H.264 or HEVC decoder (stateful or stateless)
- Linux kernel v5.8 or later
Tested working devices:
- VisionFive 2 (JH7110) using the [Debian image provided by StarFive](https://rvspace.org/en/project/VisionFive2_Debian_User_Guide)
Tested non-working devices:
- TH1520-based devices such as the LicheePi 4a (due to lack of V4L2 drivers for the VPU)
[![Hosted By: Cloudsmith](https://img.shields.io/badge/OSS%20hosting%20by-cloudsmith-blue?logo=cloudsmith&style=for-the-badge)](https://cloudsmith.com)
## Installation
Run the following commands to install Moonlight Qt to your device:
```
curl -1sLf 'https://dl.cloudsmith.io/public/moonlight-game-streaming/moonlight-qt/setup.deb.sh' | codename=sid sudo -E bash
sudo apt install moonlight-qt
```
### Updates
To update Moonlight Qt after you've installed it, run:
```
sudo apt update
sudo apt upgrade
```
### Running Moonlight
First, make sure to **complete any relevant device-specific steps in the section below**, then start Moonlight by running the `moonlight-qt` command.
For best performance, run Moonlight directly from a console/TTY. If you are currently in a desktop environment, you should be able to switch using Ctrl+Alt+(F1-F7). Usually your desktop will be at Ctrl+Alt+F1 or Ctrl+Alt+F7, so you can pick a different TTY that's not being used.
## Device-Specific Steps
### VisionFive 2
**Recommendations**
When using the [Debian image provided by StarFive](https://rvspace.org/en/project/VisionFive2_Debian_User_Guide), don't install their patched Qt package because it has a broken TLS implementation. Instead, you can simply use the Qt packages already provided by the existing APT repo from upstream Debian.
**Initial Setup**
First, you will need to add your local user account to the `video` and `input` groups in order for Moonlight to be able to directly open video devices and read input devices, then logoff or reboot for the changes to take effect. You can do so using the following commands
```
sudo usermod -a -G video $USER
sudo usermod -a -G input $USER
sudo reboot
```
Note: Since `video` and `input` groups are used to enforce multi-user separation, adding unprivileged users to these groups is not recommended.
**Setup Required After Reboots**
The current Debian image for the VisionFive 2 board from StarFive defaults to OMX-based video decoding drivers rather than V4L2. This Moonlight build only supports V4L2 decoding, so leaving the OMX drivers loaded will lead to a video decoding warning in Moonlight.
You can switch to the V4L2 driver using the following commands:
```
sudo modprobe -r vdec
sudo modprobe wave5
```
You will need to reactivate the Wave5 driver using these commands each time you restart your VisionFive board.
**Launching Moonlight**
Finally, to launch Moonlight, you should use the `-platform linuxfb` option since EGLFS UI performance is poor anyway due to non-functional OpenGL ES support on current Debian images.
In short, to launch Moonlight on the VisionFive board _after following the above steps_, switch to a different TTY with Ctrl+Alt+F2 then run:
```
moonlight-qt -platform linuxfb
```
If everything worked, you should get a GUI and no video decoder warning dialogs.
Note: Due to the use of the LinuxFB Qt backend, you may see minor to moderate UI rendering issues. These will not impact the stream itself.
**Other Notes**
The default kernel used in the StarFive Debian images lacks the built-in drivers for most gamepads. You may have more success using a HID-compliant game controller, such as PS4/5 controllers (though extended features like motion sensors, LED control, and touchpad support will not be available due to the lack of the `hid-playstation` driver in the StarFive kernel.
## Support
For the most part, these packages are provided without official support. We can fix bugs in Moonlight itself, but if it doesn't start or stream at all, odds are that it's related to your hardware or OS and won't be fixable by us.
### GUI doesn't start
This most likely means your device lacks either a working DRI driver (check if a `/dev/dri/card*` device exists) or an OpenGL ES 2.0 driver (even a software one) or that your user account lacks permission to open /dev/dri devices.
The error message from Qt may give you a hint as to what the problem is. You may try adding `-platform linuxfb` to the end of the `moonlight-qt` command (which will somewhat break the UI, but may allow you to get far enough to stream).
If you see an error like `Could not open DRM device /dev/dri/card0 (Permission denied)`, it's probably because your account is not a member of the `video` group. To fix this, run `sudo usermod -a -G video $USER` and reboot.
### Input devices aren't working
This is probably because you're not a member of the `input` group, so Moonlight lacks permission to open input devices to receive input.
To fix this, run `sudo usermod -a -G input $USER` and reboot.
### GUI is very slow/unresponsive
This is usually because your device or distro lacks an hardware accelerated OpenGL ES driver and is using software rendering instead. Unfortunately, this is quite common on many devices due to the lack of open-source drivers. You may try to find a distro that contains proper OpenGL ES drivers, or you can try adding `-platform linuxfb` to the `moonlight-qt` command (which will cause some UI issues, but should make it slightly faster).
Note: Only Moonlight's UI is actually using OpenGL, so the slowness of the GUI will not impact performance while streaming.
### Video decoder error dialog when starting Moonlight
First, make sure you've followed any steps under the "Device-Specific Steps" section above.
If that doesn't work, This means your device or distro doesn't have working V4L2 decoders for H.264 or HEVC. Generally this is a show-stopper for Moonlight Qt on your device, but you may also try [Moonlight Embedded](https://github.com/moonlight-stream/moonlight-embedded) which supports some vendor-specific decoding APIs.
You may try searching the Internet for any special distro builds, newer kernels, or patches that might enable V4L2 decoding on your device's SoC.
### Display doesn't switch to HDR mode or HDR content is not displayed correctly
This usually means that your hardware is probably not exposing the standard properties used for HDR (`COLOR_ENCODING`, `HDR_OUTPUT_METADATA`, and `Colorspace`). You may see an error message from Moonlight referring to one or more of those properties.
If so, there is probably nothing you (or we) can do. You may be able to find a distro or kernel for your device that properly implements HDR modesetting support if you search around.

127
wiki/Installing-Moonlight-Qt-on-Raspberry-Pi-4.md Normal file
View File

@ -0,0 +1,127 @@
NOTE: If you installed an earlier preview version of Moonlight Qt prior to v2.0.0, you must switch to the official repository to receive the update to v2.0.0 and future updates. To do so, run the the commands listed in the installation section and then those listed in the updates section.
Requirements:
- Raspberry Pi 4 or later (earlier Raspberry Pi models may not perform well)
- Raspberry Pi OS Buster or later (**see special Bullseye instructions below**)
[![Hosted By: Cloudsmith](https://img.shields.io/badge/OSS%20hosting%20by-cloudsmith-blue?logo=cloudsmith&style=for-the-badge)](https://cloudsmith.com)
## Installation
Run the following commands to install Moonlight Qt to your Raspberry Pi:
```
curl -1sLf 'https://dl.cloudsmith.io/public/moonlight-game-streaming/moonlight-qt/setup.deb.sh' | distro=raspbian codename=$(lsb_release -cs) sudo -E bash
sudo apt install moonlight-qt
```
You can then launch Moonlight from your Raspberry Pi's desktop or via the `moonlight-qt` command in the terminal.
For best performance, run Moonlight directly from a console/TTY. If you are currently in a desktop environment, you should be able to switch using Ctrl+Alt+(F1-F7). Usually your desktop will be at Ctrl+Alt+F1 or Ctrl+Alt+F7, so you can pick a different TTY that's not being used.
**NOTE**: If you run Moonlight from a desktop environment with the Raspberry Pi 4, we recommend keeping your Raspberry Pi's display resolution set to 1080p or below. Due to GPU performance limitations on the Pi 4, streaming performance decreases significantly when the Moonlight window is scaled larger than 1080p, even if the stream resolution is 1080p or below. These restrictions do not apply when streaming directly from a console/TTY using the steps above.
### Audio on Raspberry Pi OS Lite
Raspberry Pi OS Lite doesn't come with any audio daemon by default, so you should install PulseAudio otherwise audio over HDMI may not work.
Perform the following steps to install and configure PulseAudio:
1. `sudo apt install pulseaudio`
2. `sudo raspi-config`
3. Navigate to Advanced Settings -> Audio Config and select "PulseAudio"
4. Reboot your Pi (`sudo reboot`)
5. `sudo raspi-config`
6. Navigate to System Settings -> Audio and select the audio output you want to use
If you want to switch audio outputs, simply follow steps 5 and 6 again.
### Updates
To update Moonlight Qt after you've installed it, run:
```
sudo apt update
sudo apt upgrade
```
### HEVC and HDR support
Beginning with Moonlight Qt v3.1.2, the Raspberry Pi builds have support for streaming HEVC video using hardware decoding. If you're running Raspberry Pi OS Buster or Bullseye, you may need to perform the steps below to enable this functionality. These steps are not required on the Raspberry Pi 5, Raspberry Pi OS Bookworm, or later OS versions.
To enable HEVC support (only required on older Raspberry Pi OS versions):
- Add `dtoverlay=rpivid-v4l2` to your `/boot/config.txt` and reboot your Pi.
- You must run Moonlight directly from the console for HEVC support to be enabled. If you have your Pi set to boot to GUI, you can press Ctrl+Alt+F1 to switch to TTY 1 and run moonlight-qt from there.
If you would also like to stream HDR, perform these additional steps (only required on older Raspberry Pi OS versions):
- Open `/boot/config.txt`, change `dtoverlay=vc4-fkms-v3d` to `dtoverlay=vc4-kms-v3d`, then reboot your Pi
NOTE: Performing the HDR setup steps will prevent Moonlight from working normally when run within your Pi's desktop environment. You will need to launch Moonlight directly from the console for the video renderer to work properly.
### OSMC
OSMC uses a different permission group for input devices than Raspberry Pi OS does. Input devices work, but you will not have any of the extended DS4/DS5 controller features by default.
To fix this, run the following command and reboot:
```
sudo usermod -a -G input $USER
```
### Raspberry Pi OS Bullseye
Raspberry Pi OS Bullseye defaults to a display driver that doesn't support Moonlight's low-latency H.264 decoder. Unless you have incompatible software on your Pi (like Kodi v19) or need HDR support, we recommend enabling the alternate driver as detailed below.
**Do NOT perform these steps on the Raspberry Pi 5 or Raspberry Pi OS Bookworm! They are no longer required and may render your Pi unbootable!**
To fix this issue, you can edit the `/boot/config.txt` file:
1. Run `sudo nano /boot/config.txt`
2. Scroll down using the arrow keys until you see the line that says `dtoverlay=vc4-kms-v3d`
3. Change that line to `dtoverlay=vc4-fkms-v3d`
4. Press Ctrl+X, press Y, then press Enter
5. Reboot your Pi
**Workarounds for incompatible software (Kodi v19+)**
If you are using software that requires `vc4-kms-v3d` (such as Kodi v19 or later), you can force Moonlight to use the slower V4L2M2M decoder to enable it to function in this scenario. V4L2M2M adds between 1 and 2 frames of additional latency at 1080p compared to the optimal solution above (using `vc4-fkms-v3d`). This workaround is no longer required on Raspberry Pi 5 or Raspberry Pi OS Bookworm and later.
To enable the V4L2M2M decoder, launch Moonlight with the following command:
```
H264_DECODER_HINT=h264_v4l2m2m DRM_FORCE_DIRECT=1 moonlight-qt
```
It is _highly_ recommended that you enable the HEVC decoder (see "HEVC support" above) to avoid the performance cost of V4L2M2M for host PCs that support HEVC encoding (GTX 900 series and newer).
## Common problems and solutions
### Video decoder error dialog when starting Moonlight or black screen when streaming
This is most likely because you're running Raspberry Pi OS Bullseye or another Linux distro that enables the Full KMS display driver by default.
To fix this, you can follow the steps above in the Raspberry Pi OS Bullseye section.
### HDR option cannot be enabled or display doesn't switch to HDR mode
This is most likely because you have not correctly followed all the steps in the [HEVC and HDR support](https://github.com/moonlight-stream/moonlight-docs/wiki/Installing-Moonlight-Qt-on-Raspberry-Pi-4#hevc-and-hdr-support) section.
If the HDR option cannot be enabled, you have either not enabled the HEVC decoder properly or are running Moonlight from within the desktop environment. Moonlight must be run directly from the console for HDR to be available.
If you can stream HDR but it doesn't switch your TV to HDR mode, you are probably not using the Full KMS driver (`vc4-kms-v3d`) that is required for HDR metadata to be sent to your TV. Ensure your `/boot/config.txt` is updated to use `vc4-kms-v3d` (not `vc4-fkms-v3d`) and try again.
### PS4/PS5 controller features aren't working
This is likely caused by Moonlight not having permission to open `/dev/hidraw` devices on your Pi. This is a common issue on OSMC, which doesn't use the `input` group in the same way that Raspberry Pi OS does.
To fix this, run the following command and reboot:
```
sudo usermod -a -G input $USER
```
### No audio output
If you are on _Raspberry Pi OS Lite_, make sure you've followed the steps [here](https://github.com/moonlight-stream/moonlight-docs/wiki/Installing-Moonlight-Qt-on-Raspberry-Pi-4/#audio-on-raspberry-pi-os-lite) first!
The most common issue is simply failing to configure the default audio device properly. Use the `raspi-config` tool, navigate to System Settings -> Audio, then select the audio device you want to use.
If you've set your audio device and Moonlight still cannot output audio, you can try an alternate SDL audio driver using the following commands:
- `SDL_AUDIODRIVER=alsa moonlight-qt`
- `SDL_AUDIODRIVER=pulseaudio moonlight-qt`
### Decoder Errors with a 4K 60 Hz Monitor
If your Raspberry Pi is configured for 4K 60 Hz output, you will need to increase the amount of GPU memory for the hardware video decoder to work.
Run the following commands:
```
echo "gpu_mem=128" | sudo tee -a /boot/config.txt
sudo reboot
```

63
wiki/Internet-Streaming-Errors.md Normal file
View File

@ -0,0 +1,63 @@
<a href="https://moonlight-stream.org/discord"><img src="https://moonlight-stream.org/images/discord.png" height="70" alt="Join our Discord"></a>
# Multiple connections error
If you get this warning, your host PC is probably connected to your home network via both WiFi and Ethernet. This can cause connection issues with NVIDIA GameStream. Disconnect one of the connections (preferably the WiFi connection), then try again.
# Connected through another router error
If you get this error, it usually means you have two routers plugged into each other. This is usually caused by having your own wireless router plugged into a router already provided by your ISP. This setup prevents many applications from working optimally, like hosting games, P2P applications, etc.
You can fix this by switching one of your two routers into bridged or Access Point mode. The steps to do this vary by router, but you should be able to find them by Googling around a bit.
If you're sure that you don't have more than one router running on your network, try restarting your router. If that doesn't work, the error may be caused by a Carrier-Grade NAT running on the ISP's network. You can try the steps in the section below to resolve that.
If you can't fix this, you can try using the [ZeroTier setup steps](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#zerotier) instead.
# Carrier-Grade NAT error
If you get this error, your ISP hasn't given you a public IP address which allows you to host services like Moonlight on the Internet. In many cases, your ISP will be happy to give one to you for free if you just ask.
If your ISP won't give you a public IP address, you can try using the [ZeroTier setup steps](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#zerotier) instead.
# Limited connectivity for hosting error
If you get this error, your ISP hasn't given you a public IP address which allows you to host services like Moonlight on the Internet. In many cases, your ISP will be happy to give one to you for free if you just ask.
Despite the lack of a public IP address, your connection does offer IPv6 support which will work for hosting over the Internet but streaming will only work natively from networks that also support IPv6. You can check a network's IPv6 support by [running this test](http://test-ipv6.com/) while connected to the network you want to test. If it scores a 10/10, it should be good to go. If not, you may try the [Cloudflare 1.1.1.1 app for iOS and Android](https://1.1.1.1/) with the free 'WARP' feature to gain IPv6 connectivity on networks that don't natively support it.
If your ISP won't give you a public IP address, you can try using the [ZeroTier setup steps](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#zerotier) instead.
# Internet GameStream connectivity check error
This error usually means your router doesn't have UPnP enabled. Some routers have bugs where UPnP doesn't work properly, so you may check your router manufacturer's website for a firmware update for your router that could fix it. You can also try restarting your router.
This error may also be caused by a firewall product on your host PC blocking the Internet Hosting Tool from talking to your router. Try disabling your host PC's firewall temporarily to see if that's the cause.
If you can't fix this error, you can try using the [ZeroTier setup steps](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#zerotier) instead or you can [forward the ports manually](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#manual-port-forwarding-advanced) if you feel comfortable making changes to your router settings.
# Display locked error
This error means that your PC is currently sitting at the lock screen. This may seem counter-intuitive since you've obviously managed to run the tester, but you are probably doing that over Microsoft Remote Desktop.
In order for GameStream to work, your PC's "console session" (physical monitor, keyboard, and mouse) must be logged in. Microsoft Remote Desktop locks the console session until you sign in again, making GameStream unavailable.
You can use a GameStream-compatible remote desktop solution like Chrome Remote Desktop, TeamViewer, or VNC to connect to your PC's console session and sign in again. You will need to use one of these compatible remote desktop apps if you want to use GameStream.
# Local network access blocked error
This error means that something on your PC is blocking access to other devices on your local network. Without access to devices on your network, the Internet Hosting Tool cannot configure your router to allow streaming over the Internet. Depending on how the blocking is implemented, you may not be able to stream at all, even on your home network.
This is most commonly caused by VPN software which contains a feature to disable access to the local network. You will need to disable this in order to stream successfully. Check the documentation for the VPN software if you are unsure of how to disable local network blocking.
Here are links to instructions on unblocking the local network for some commonly used VPN software:
* [Private Internet Access (PIA)](https://www.privateinternetaccess.com/helpdesk/kb/articles/i-cannot-access-devices-on-my-local-network) - enable "Allow LAN traffic"
* [NordVPN](https://support.nordvpn.com/FAQ/Setup-tutorials/1047409642/Installing-and-using-NordVPN-on-Windows-7-and-later-versions.htm#Advanced%20settings) - disable "Invisibility on LAN" and "Internet Killswitch" options
* [ExpressVPN](https://www.expressvpn.com/support/troubleshooting/restore-lan-access/) - enable "Allow access to local network devices such as network shares or printers"
# Sleep mode enabled warning
This warning means your PC is configured to go to sleep after a period of inactivity. This will almost always make the PC unusable for streaming over the Internet until it is manually woken up.
In most cases, you should disable sleep in the Power Settings on your host PC to address this warning. You can leave the monitor power-off option enabled if you wish.
If you have configured a Wake-on-LAN relay device on your network, you can safely ignore this warning. If you don't know what this is, you probably don't have one :)
# Hibernation enabled warning
This warning means your PC is configured to hibernate after a period of inactivity. This will almost always make the PC unusable for streaming over the Internet until it is manually powered back on.
In most cases, you should disable hibernation in the Advanced Power Options on your host PC to address this warning.
If you have configured a Wake-on-LAN relay device on your network and your PC can wake from hibernation via Wake-on-LAN, you can safely ignore this warning. If you don't know what this is, you probably don't have one :)

10
wiki/Moonlight-Overview.md Normal file
View File

@ -0,0 +1,10 @@
## App Description
**Introducing Moonlight:** Moonlight allows you to stream your apps and games to another client device on your network or the Internet. You can play your favorite games on your PC, phone, tablet, or TV with Moonlight.
**What it does** This app streams games from a GameStream-compatible PC on your local network or the Internet. After initial pairing, Moonlight will show a list of apps to stream from your PC. You can add any other apps to this list through GeForce Experience. Mouse, keyboard, and controller input is sent from the Moonlight client to the PC.
To have a good experience, you need a mid to high-end wireless router with a good wireless connection to your Moonlight client device (5 GHz highly recommended) and a good connection from your PC to your router (Ethernet highly recommended).
***
This page under construction

54
wiki/NVIDIA-GameStream-End-Of-Service-Announcement-FAQ.md Normal file
View File

@ -0,0 +1,54 @@
This FAQ page covers frequently asked questions about [NVIDIA's GameStream End of Service Notification](https://nvidia.custhelp.com/app/answers/detail/a_id/5436).
# What is happening?
In late 2022, NVIDIA announced that they have chosen to discontinue their NVIDIA GameStream technology.
You can read NVIDIA's official announcement [here](https://nvidia.custhelp.com/app/answers/detail/a_id/5436).
# Why does NVIDIA's announcement impact Moonlight?
The Moonlight project implements unofficial open-source clients for NVIDIA GameStream. The host software that Moonlight connects to is part of NVIDIA GeForce Experience, so it is under NVIDIA's control and depends on their ongoing effort to fix bugs and implement new host-side features.
While NVIDIA's announcement is primarily centered around the removal of GameStream support from their official NVIDIA Games client, it's highly unlikely that they would continue to invest maintenance resources in the host software when no official clients exist.
**2024 Update:** NVIDIA has announced that GeForce Experience itself will be discontinued in favor of their new [NVIDIA app](https://www.nvidia.com/en-us/software/nvidia-app/) which is currently in beta. This new NVIDIA app does not support GameStream and installing it will remove GeForce Experience.
# What does this mean for Moonlight?
In the short term, nothing. Moonlight will continue to be usable with host PCs running the latest version of GeForce Experience until at least mid-Feburary 2023, according to NVIDIA's announcement.
Inline with our long-term goal of providing an excellent open-source game streaming solution, we have increased our efforts to improve [the Sunshine project](https://github.com/LizardByte/Sunshine), which acts as an a free open-source host for Moonlight.
Sunshine now supports many features that were never possible with GeForce Experience, including:
- Support for AMD, Intel, and NVIDIA GPUs
- Full DualShock controller emulation, including motion sensors, touchpad, and light bar control
- AV1 encoding for higher quality than HEVC or H.264 codecs
- Built-in support for hosting on the Internet without requiring [a separate tool](https://github.com/moonlight-stream/Internet-Hosting-Tool)
- Built-in support for IPv6 without requiring [a separate tool](https://github.com/moonlight-stream/GS-IPv6-Forwarder)
- Host capture/encoding latency reporting that appears in Moonlight's on-screen performance overlay
By investing our time in making Sunshine a top-tier game streaming host, we can ensure that the whims of a single company cannot unilaterally impact the game streaming community again.
# What will happen to Moonlight in mid-February?
Past mid-February 2023, the status of the hosting GeForce Experience is unclear. It's likely that the GameStream functionality will be present in GeForce Experience for a little longer, since major GeForce Experience updates don't arrive very often.
Even when the functionality is removed in GeForce Experience, it is likely that GameStream can still be used by running older versions of GeForce Experience (and blocking the automatic update mechanism). This might also require older GPU drivers, but historically older GeForce Experience versions and GameStream have been compatible with newer drivers without issue.
Because GeForce Experience contains a list of GameStream-supported GPUs, it is likely that GPUs launched after mid-February will not be usable for GameStream, even running older versions of GeForce Experience.
**2024 Update:** NVIDIA has announced that GeForce Experience will be discontinued in favor of their new [NVIDIA app](https://www.nvidia.com/en-us/software/nvidia-app/) which is currently in beta. This new NVIDIA app does not support GameStream and installing it will remove GeForce Experience.
# How will Moonlight change after GameStream support is removed from GeForce Experience?
That will depend on how the removal works in practice and what our users want.
While the performance and capabilities of GameStream in GeForce Experience was excellent, it did limit our capabilities in some ways. For example, microphone support was implemented for GeForce Now but never for GameStream. Similarly, major features like PS4 or Xbox One controller emulation, trigger rumble support, client-side cursor rendering, and AV1 encoding support were not possible due to host and GameStream protocol limitations. Now that we no longer have to worry about introducing compatibility issues with future versions of GameStream, we can implement features like these in Sunshine.
In any case, it is unlikely that we will remove support for streaming from GeForce Experience for the foreseeable future.
# Was the Moonlight team given advance notice of this?
No, we found out when the public announcement was made.
While it would have been nice to know in advance, it's completely understandable that NVIDIA did not do so. We have no official relationship or agreement with NVIDIA, so there is no NDA in place or anything that would provide legal protection for them that we wouldn't leak the news to the media (though we would certainly not have done so, even in the absence of such an agreement).

23
wiki/Project-and-Community.md Normal file
View File

@ -0,0 +1,23 @@
<a href="https://moonlight-stream.org/discord"><img src="https://moonlight-stream.org/images/discord.png" height="70" alt="Join our Discord"></a>
## Meet the Developers
Moonlight was created by [Case Western Reserve University](https://case.edu) students as a project at the [MHacks](https://mhacks.org) hackathon in 2013 and further developed at MHacks and HackCWRU in 2014. It's hard to put a cool project down after a hackathon, so we continue to develop Moonlight today.
Who we are:
* [Cameron Gutman](https://github.com/cgutman)
* [Diego Waxemberg](https://github.com/dwaxemberg)
* [Aidan Campbell](https://github.com/raidancampbell)
* [Aaron Neyer](https://github.com/aaronneyer)
* [Michelle Bergeron](https://github.com/mrb113)
* [Andrew Hennessy](https://github.com/yetanothername)
Email any of us at `<our first name>@moonlight-stream.org` or all of us at info@moonlight-stream.org. We do receive a lot of mail, so please check if your answer is described in this wiki first.
## Contribute
Project developers are often available on [our Discord server](https://moonlight-stream.org/discord) in the `dev` channels. Feel free to drop by with questions or to get feedback on your pull requests.
We welcome code contributions - here's how in three easy steps.
1. Fork us
2. Write code
3. Send Pull Requests

423
wiki/Setup-Guide.md Normal file
View File

@ -0,0 +1,423 @@
<a href="https://moonlight-stream.org/discord">Join our Discord</a>
* [Quick Setup Instructions](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#quick-setup-instructions)
* [Streaming over the Internet](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#streaming-over-the-internet)
* [Moonlight Client Setup Instructions](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#moonlight-client-setup-instructions)
* [Additional Requirements for HDR Streaming](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#additional-requirements-for-hdr-streaming)
* [Keyboard/Mouse/Gamepad Input Options](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#keyboardmousegamepad-input-options)
* [Adding custom programs that are not automatically found](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#adding-custom-programs-that-are-not-automatically-found)
* [Using Moonlight to stream your entire desktop](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#using-moonlight-to-stream-your-entire-desktop)
* [Frequently Asked Questions](https://github.com/moonlight-stream/moonlight-docs/wiki/Frequently-Asked-Questions)
* [Troubleshooting](https://github.com/moonlight-stream/moonlight-docs/wiki/Troubleshooting)
***
**Host Gaming PC Requirements**
For Sunshine:
* Any modern GPU from AMD, NVIDIA and Intel
* Windows 10 or 11 (Windows 7 and 8 are *not* supported)
* macOS 12 and newer (experimental)
* Linux (Debian 11, Ubuntu 22.04, Fedora 38 and newer)
For GeForce Experience:
* Windows 10 or 11 (Windows 7 and 8 *may* be supported)
* NVIDIA GeForce GTX/RTX 600+ series GPU, or NVIDIA Quadro GPU (Kepler series or later)
* NVIDIA GeForce Experience (GFE) 2.1.1 or higher, or NVIDIA Quadro Experience
* 720p or higher display (or headless display dongle) connected to the NVIDIA GPU
* 5 Mbps or higher upload speed (only required for streaming outside your house)
There are [additional host PC requirements](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#additional-requirements-for-hdr-streaming) for streaming HDR content.
## Quick Setup Instructions
### Using Sunshine
Detailed instructions for installing and configuring Sunshine can be found on the [Sunshine documentation](https://docs.lizardbyte.dev/projects/sunshine).
1. On your gaming PC, install the latest version of Sunshine from the [setup page](https://docs.lizardbyte.dev/projects/sunshine/latest/md_docs_2getting__started.html). Your PC may need a reboot after installation to finish setup and for controller emulation to work.
2. Start Sunshine and wait for the configuration page to open in your web browser. Your browser will show a "this page is not secure" error that you can safely ignore. You can access this interface manually by using the "Open Sunshine" option of the tray menu or by opening https://localhost:47990/ directly in your web browser.
3. The first time Sunshine starts, it will ask you to create an account to secure access to the configuration interface. This is important, as anyone with access to this interface can add new clients to access your computer remotely.
![Screenshot of the Sunshine account setup page](https://github.com/user-attachments/assets/e86ca34d-d102-44c2-b445-e3c1e0a90e63)
4. Start Moonlight and make sure your client is connected to the same network as your PC. In most cases, your gaming PC should show up automatically in the PC list after a few seconds. You can also add a computer manually by entering its IP address if it doesn't show up automatically or you're trying to pair over the Internet.
5. Click the entry in the PC list to start pairing. Sunshine should send a pairing notification on your host PC, redirecting you to the Pin page. There, enter the PIN displayed in Moonlight and submit the pairing dialog. If you get an error after submitting the PIN form, try the [troubleshooting steps here](https://github.com/moonlight-stream/moonlight-docs/wiki/Troubleshooting).
![Screenshot of the Sunshine PIN pairing page](https://github.com/user-attachments/assets/70d082d4-ee40-485d-ba41-444633642202)
6. Try streaming a game or app to make sure everything is working. If you encounter issues, try the [troubleshooting steps here](https://github.com/moonlight-stream/moonlight-docs/wiki/Troubleshooting).
7. Sunshine comes pre-loaded with Steam and the Remote Desktop. You can manually add other games and apps by following Sunshine's [guide to adding apps](https://docs.lizardbyte.dev/projects/sunshine/latest/md_docs_2app__examples.html).
### Using GeForce Experience
1. On your gaming PC, install the [GeForce Experience software](https://www.nvidia.com/en-us/geforce/geforce-experience/) from NVIDIA. Your PC may need a reboot after installation to finish setup.
* If your PC has a Quadro GPU, install the [Quadro Experience software](https://www.nvidia.com/en-us/design-visualization/software/quadro-experience/) instead.
2. To work around a [GPU driver bug](https://github.com/moonlight-stream/nvidia-gamestream-issues/issues/27) that impacts NVIDIA GameStream hosts running Windows 11, you will need to disable Hardware-accelerated GPU Scheduling on your host PC. Open "Graphics Settings" using the Start Menu, then click "Change default graphics settings", and set the "Hardware-accelerated GPU scheduling" option to Off.
<p align="center">
<img src="https://github.com/moonlight-stream/moonlight-docs/wiki/images/hw-gpu-sched-small.png"/>
</p>
3. Start GeForce/Quadro Experience and click on the **Settings "gear" button**. Then choose the **SHIELD** option. Make sure the GameStream switch is in the **"on" position (green)**. If the SHIELD tab is not present, see the [troubleshooting steps here](https://github.com/moonlight-stream/moonlight-docs/wiki/Troubleshooting).
<p align="center">
<img src="https://github.com/moonlight-stream/moonlight-docs/wiki/images/gfe-gamestream-enable-small.png"/>
</p>
4. Start Moonlight and make sure your client is connected to the same network as your PC. In most cases, your gaming PC will show up automatically in the PC list after a few seconds. Click the entry in the PC list to start pairing.
5. On your PC, enter the PIN displayed in Moonlight and accept the pairing dialog. If you don't see a pairing dialog, try the [troubleshooting steps here](https://github.com/moonlight-stream/moonlight-docs/wiki/Troubleshooting).
6. Try streaming a game or app to make sure everything is working. If you encounter issues, try the [troubleshooting steps here](https://github.com/moonlight-stream/moonlight-docs/wiki/Troubleshooting).
7. If you don't see the game you want to stream in Moonlight, you can [add it manually](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#adding-custom-programs-that-are-not-automatically-found). You can also [stream your desktop](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#using-moonlight-to-stream-your-entire-desktop) and launch anything you want.
## Streaming over the Internet
### Automatic configuration (Sunshine)
Sunshine comes with a built-in UPnP option that can be enabled in the Network section of the settings inside the web UI. It will automatically forward the required ports for streaming over the Internet.
For the easiest possible setup process, we highly recommend that you **first pair Moonlight with your gaming PC while connected to your home network** before trying to use Moonlight over the Internet. For iOS and tvOS users, [you _must_ pair while connected to the same network](https://github.com/moonlight-stream/moonlight-ios/issues/417) to comply with Apple guidelines.
### Automatic configuration (GeForce Experience)
For the easiest possible setup process, we highly recommend that you **first pair Moonlight with your gaming PC while connected to your home network** before trying to use Moonlight over the Internet. For iOS and tvOS users, [you _must_ pair while connected to the same network](https://github.com/moonlight-stream/moonlight-ios/issues/417) to comply with Apple guidelines.
Moonlight Internet Hosting Tool must remain installed on your host PC to maintain the ability to stream over the Internet.
#### If your gaming PC is already paired with Moonlight:
1. Install the [Moonlight Internet Hosting Tool](https://github.com/moonlight-stream/Internet-Streaming-Helper/releases) on your gaming PC.
2. Run "Moonlight Internet Streaming Tester" via the Start Menu to confirm it's working properly.
3. Do not uninstall Moonlight Internet Hosting Tool, unless you no longer want to stream over the Internet. It needs to remain installed on your PC to maintain the port forwarding entries on your router.
#### If your gaming PC is _not_ already paired with Moonlight:
1. Install the [Moonlight Internet Hosting Tool](https://github.com/moonlight-stream/Internet-Streaming-Helper/releases) on your gaming PC.
2. Run "Moonlight Internet Streaming Tester" via the Start Menu.
3. Type the IP address that is displayed on the tester's success dialog into the Add PC dialog of Moonlight.
* You must ensure your Moonlight client is **not connected to the same network as your gaming PC** during this step or the connection may not be successful.
4. Do not uninstall Moonlight Internet Hosting Tool, unless you no longer want to stream over the Internet. It needs to remain installed on your PC to maintain the port forwarding entries on your router.
#### Having trouble?
* Ensure UPnP is enabled in your router settings and delete any older Moonlight port forwarding entries.
* Try streaming from a different network. Some corporate or public WiFi networks block streaming applications like Moonlight. If that happens, you may have success with the ZeroTier, Tailscale, or NordVPN Meshnet setup steps below.
* Run the "Moonlight Internet Streaming Tester" found in the [Moonlight Internet Hosting Tool](https://github.com/moonlight-stream/Internet-Streaming-Helper/releases) and ask for help on our [Discord server](https://moonlight-stream.org/discord). Be sure to have the tester log handy.
### ZeroTier
[ZeroTier](https://www.zerotier.com/) which is a service that acts similar to a VPN, but with better performance in most cases.
This option also gives you the ability to stream from multiple PCs that are all connected via a single Internet connection. However, it requires software on your hosts and clients that must be running and connected in order to stream over the Internet, unlike the other Internet streaming options.
You should use ZeroTier if you are in one of the following situations:
* The automatic tool above says you're behind a Carrier-Grade NAT, that you have two routers connected together, or otherwise doesn't work and you can't resolve it yourself.
* You are still using GeForce Experience and you have multiple gaming PCs on your network that you'd like to stream from over the Internet.
* Moonlight is blocked on the network you want to use for streaming.
To set it up:
1. [Create an account](https://my.zerotier.com/login) on the ZeroTier website. The free service is perfectly fine for Moonlight.
2. Download the Windows version for your PC from the [Downloads page](https://www.zerotier.com/download/) and install it on your host gaming PC.
3. Install ZeroTier on your client device.
* If using Moonlight on a PC or Mac, download and install the appropriate version from the [Downloads page](https://www.zerotier.com/download/).
* If using Moonlight on Android or iOS, the apps are available on the [Google Play Store](https://play.google.com/store/apps/details?id=com.zerotier.one) and [Apple App Store](https://itunes.apple.com/us/app/zerotier-one/id1084101492).
4. Go to the [Networks tab](https://my.zerotier.com/network) then create a new network.
* Uncheck all checkboxes in the "IPv6 Auto-Assign" section (if checked)
* Under the "IPv4 Auto-Assign" section, ensure "Auto-Assign from Range" is checked, click the "Easy" button, then choose "10.147.17.*"
5. Copy the Network ID from that page and type it into the ZeroTier app's Join Network dialog (or use the e-mail invite system).
* If you get a prompt from Windows about asking for the network type/location, choose Private or Home network to avoid firewall issues.
6. After joining the network on each device (_including your client running Moonlight!_), go back to the ZeroTier Network page and **check the Auth checkbox for each member of your network** to allow the devices to connect with each other. ZeroTier should show up as connected on all devices.
7. With ZeroTier connected on your client and host PC, open Moonlight and click/tap the Add PC button, then type the "Managed IP" of your host PC as shown on the ZeroTier Network page.
To connect additional clients or host PCs, just download ZeroTier on the device, then complete steps 5-7.
Don't forget to connect to your ZeroTier network when you want to stream over the Internet!
### Tailscale
[Tailscale](https://tailscale.com) is a tool that helps you connect all your devices to a private network called a Tailnet. Once a device is logged into your Tailscale account, it automatically discovers the most efficient way to connect with other devices on the network using advanced [NAT traversal techniques](https://tailscale.com/blog/how-nat-traversal-works). Once a connection is established, a secure WireGuard tunnel is created between the devices, allowing them to talk directly without extra latency.
1. **Create a Free Account:**
[Sign up](https://login.tailscale.com/start) using an email address from a public service like Gmail, Microsoft, GitHub, or Apple. By doing this, you’ll be set up as a [personal user](https://tailscale.com/pricing?plan=personal), allowing you to use Tailscale for free on up to 100 devices. Using other email domains may cause your account to be categorized as a corporate account with more restrictions.
2. **Install Tailscale on Your Devices:**
[Download](https://tailscale.com/download) and install the Tailscale app on both your host (e.g., PC) and client (e.g., phone) devices. Log in to the same account on each device. Once logged in, your devices should show up on the [Machines page in the Dashboard](https://login.tailscale.com/admin/machines). Here, you can view details about each device and its network connection. Every device gets a unique `100.x.x.x` IP address, an IPv6 address, and a DNS name.
3. **Test the Connection:**
On your host machine, open a command prompt or shell and type `tailscale status` to see a list of all devices in your Tailnet. For example, let’s say you have “my-pc” and “my-phone.” Initially, since your devices haven’t communicated yet, the status will show a dash (-) in the last column.
```sh
> tailscale status
100.xx.xx.xx my-pc email.account@ windows -
100.xx.xx.xx my-phone email.account@ iOS -
```
Next, type `tailscale ping my-phone` (or whatever name your device has). You’ll see some ping responses. Pay attention to both the ping times and whether the connection is a direct connection or going through a relay (DERP server). The first few pings may go through the DERP server while Tailscale works on establishing a direct connection. Ideally, after a few seconds, the devices will connect directly, and ping times should be faster. If you only receive a single ping response, the connection is already in direct mode. In the Tailscale mobile app, long press on an entry in the list of devices to find the ping function.
Example of a successful direct connection:
```sh
> tailscale ping my-phone
pong from my-phone (100.xx.xx.xx) via DERP(nyc) in 28ms
pong from my-phone (100.xx.xx.xx) via DERP(nyc) in 25ms
pong from my-phone (100.xx.xx.xx) via 192.168.2.93:57324 in 0ms
```
Rarely, a direct connection isn’t possible, and Tailscale will continue to use a relay server to help the devices communicate. If this happens, you will not be able to stream with Moonlight between these devices. Tailscale's relay servers are shared with other users and are rate-limited to prevent abuse. Don't attempt to stream lots of traffic through them; this is quite rude and will likely result in your device or account being blocked or banned.
4. **Connect Using Moonlight:**
Once the devices are connected directly, you’re ready to use Moonlight. You may need to manually add the Tailscale `100.x.x.x` IP address or the ts.net hostname (`my-phone.tail12345.ts.net`) to Moonlight. If you’re using iOS, you may need to do this step on your local LAN before trying it over the Internet. Moonlight should link this IP address to the host's existing entry and it should appear as online. If you’re streaming over a mobile network, you may want to lower the resolution and bitrate settings for smoother performance, but Tailscale won’t add any additional delay.
5. **Stay Connected Anywhere:**
Now you can securely connect to your devices from almost anywhere. However, some mobile networks may block or interfere with the WireGuard UDP packets. For instance, T-Mobile in the US has been known to cause connection issues. The developers continue to work on solutions to this problem.
6. **Explore Other Features:**
Tailscale offers many other useful features. You can set up a custom subdomain, use exit nodes (to route all your internet traffic through a specific device), or enable subnet routing. In particular, subnet routing is an option for advanced users, where another Tailscale node on your home network routes the packets between a non-Tailscale PC and an external client.
### NordVPN Meshnet
[Meshnet](https://nordvpn.com/meshnet/) is a feature of the NordVPN app that allows linking devices from remote networks into secure, private virtual device networks. Once the devices are linked, they connect as if they were on the same LAN.
Using Meshnet for Moonlight allows you to circumvent port forwarding, overcome CGNAT limitations, and stream over the Internet from multiple gaming PCs sharing the same Internet connection.
First, you need to install and enable Meshnet on your host gaming PC:
1. Visit the [Nord Account sign-up page](https://nordaccount.com/signup) and create a free account. An active NordVPN subscription is not required.
2. On your gaming PC, download and install the [NordVPN app](https://support.nordvpn.com/hc/en-us/articles/19472023025169-Installing-and-using-NordVPN-on-Windows-10-and-11).
3. Log in to NordVPN using your Nord account.
4. On the left sidebar, select the "Devices in Meshnet" tab.
5. Turn on Meshnet using the toggle.
You should now see your gaming PC's unique Nord name and Meshnet IP address. You can use either to connect to the server with Moonlight.
Now, you can link your client device(s) that will connect to the host over Meshnet:
1. Download the NordVPN app for your client device.
- On Android, you can download NordVPN from the [Play Store](https://play.google.com/store/apps/details?id=com.nordvpn.android).
- On iOS, you can download NordVPN from the [App Store](https://apps.apple.com/us/app/nordvpn-vpn-fast-secure/id905953485).
2. Log in to your Nord Account.
3. [Enable Meshnet](https://meshnet.nordvpn.com/getting-started/how-to-start-using-meshnet).
Upon enabling Meshnet, you should see your gaming PC in the peer device list.
Finally, you can pair your gaming PC with the client device(s) inside Moonlight:
1. From the NordVPN app, copy the Nord name of your game server.
2. Open Moonlight.
3. Select "Add PC manually".
4. Paste the copied Nord name and choose "OK".
You should now be able to pair and connect to the host gaming PC over the Internet. Meshnet must be active for streaming over the Internet to work!
### Manual port forwarding (advanced)
If the automatic tool doesn't work, you can try manually forwarding the following ports through your router to your host gaming PC's IP address for streaming to work over the Internet:
* **TCP** 47984, 47989, 48010
* **UDP** 47998, 47999, 48000, 48002, 48010
If your router has separate options for "internal port" and "external port", you should set them to the same values. For example, your port forward for TCP 47989 would be set as internal port 47989 and external port 47989.
To verify the basic port forwarding was done correctly, visit https://www.canyouseeme.org/ and test port 47984 and 47989. If port forwarding is working, they should both report "Success" when you test them. The other ports are only active during streaming, so the only way to test them is via Moonlight.
If Moonlight already found your gaming PC automatically while on the same network, it should connect to your PC over the Internet without any additional steps. If you're not on the same network as your PC, go to https://www.whatsmyip.org/ from your gaming PC, then enter the IP address you get there into Moonlight. If you don't get an error, you should be all set.
Also see [DHCP leasing](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#static-dhcp-reservation).
### Static DHCP reservation
On many routers it will also be necessary to make a static DHCP reservation to ensure the host always has the same network IP address. This makes sure the ports you have forwarded remain forwarded to the correct machine. Some routers will do this automatically when port forwarding is done. But many do not and it must be done manually. Router makers also try to make there routers “user friendly” and call this function differently such as static IP, Reservations, fixed IP and so on. They also like to put the setting in different places. Common places are DHCP settings, Client lists, and NAT/LAN settings. What your looking for is the ability to set a client to have a certain IP whether that be via MAC address or client list.
### IPv6 (advanced - certain ISPs only)
If you are lucky enough to have native IPv6 connectivity to your host gaming PC, you may opt to use IPv6 for Internet streaming. This option is only recommended for those very familiar with network administration. You may combine these steps with the Moonlight Internet Hosting Tool above to stream over IPv4 or IPv6, depending on your client's connectivity.
1. Navigate to http://test-ipv6.com/ on both your host gaming PC and client device/PC to check their IPv6 test scores. You may need to disable Chrome's Data Compression option to get accurate results on mobile.
* If your host PC scores 0/10, check your router settings for an IPv6 option. Make sure it's enabled and set to "Native", "Automatic", "DHCPv6", or similar. Avoid "6to4" or "Teredo" options. Restart your router and try the IPv6 test again. If you can't find an IPv6 option or it's not working, contact your ISP and ask whether they support IPv6.
* If you can't get your host gaming PC to 10/10, you won't be able to use this method for streaming over the Internet with your ISP.
* If your client device doesn't score 10/10 but your host PC does, you can try the [Cloudflare 1.1.1.1 app for Windows, macOS, iOS, and Android](https://1.1.1.1/) with the free 'WARP' feature to gain IPv6 connectivity on networks that don't natively support it.
2. Install the [GameStream IPv6 Forwarder](https://github.com/moonlight-stream/GS-IPv6-Forwarder#instructions) on your host gaming PC (same PC that runs GeForce Experience). This step is only required if you do not have the [Moonlight Internet Hosting Tool](https://github.com/moonlight-stream/Internet-Streaming-Helper/releases) already installed.
3. If your router has an IPv6 firewall, you may need to create IPv6 firewall rules on your router to allow TCP ports 47984-48010 and UDP ports 47998-48010 through the firewall. The GameStream IPv6 Forwarder will create the rules for you if possible, but not many routers support this feature. If your IPv6 Moonlight connection is failing, this is most likely the reason.
4. If Moonlight already found your gaming PC automatically while on the same network, it should connect to your PC over IPv6 without any additional steps. If you haven't already paired to your gaming PC while on the same network, click Add PC and type the IPv6 address of your host gaming PC.
All officially supported Moonlight clients (iOS/tvOS, PC, Android) support streaming from servers over IPv6. Unofficial clients (Embedded, Vita) may not.
## Firewall setup
If you are not able to stream when connected to the same network as your gaming PC, you may need to add firewall rules to stream successfully. First, try disabling the firewall software on your gaming PC (usually Windows Firewall or a firewall integrated into your anti-virus software) to confirm it's a firewall-related problem.
### Windows Firewall
Sunshine and GeForce Experience should create rules for Windows Firewall automatically, but in the event that they don't work, you can create the rules required to host streaming by using the following steps:
1. Open a Command Prompt or PowerShell window as administrator
2. Run the following 2 commands:
```
netsh advfirewall firewall add rule name="GameStream UDP" dir=in protocol=udp localport=5353,47998-48010 action=allow
netsh advfirewall firewall add rule name="GameStream TCP" dir=in protocol=tcp localport=47984,47989,48010 action=allow
```
3. Ensure your PC now appears online in Moonlight
### Other firewall software
For other firewall products, you should follow their instructions to create exceptions for the following ports:
* **TCP** 47984, 47989, 48010
* **UDP** 5353, 47998, 47999, 48000, 48002, 48010
## Moonlight Client Setup Instructions
**Client Requirements**
* Android: An Android device running Android 4.1 (Jelly Bean) or newer. Newer and "flagship" devices with higher processor speeds are more likely to be able to handle Moonlight well by using the hardware video system on the device to produce smooth streaming without video stuttering or freezing.
* iOS: An iOS device running iOS 9.3 or later.
* tvOS: An Apple TV device running tvOS 12.0 or later.
* PC: Windows 7+, macOS 10.13+, or Linux. Your PC should be new enough that it supports hardware-accelerated H.264 video decoding, otherwise it will have to use CPU decoding. Most PCs made since around 2010 should work fine, though older PCs may not be able to stream at 60 FPS without lag.
* ChromeOS: All ChromeOS devices should have the required hardware.
**Internet and Network Requirements**
To have a good experience, you need a mid to high-end wireless router with a good wireless connection to your client device (5 GHz WiFi 5 (802.11ac) or WiFi 6 (802.11ax) strongly recommended) and a good connection from your PC server to your router (Ethernet/wired connections highly recommended).
## Additional Requirements for HDR Streaming
HDR10 video streaming (beta) is supported on certain Moonlight clients as long as some hardware and software requirements are met.
If the HDR requirements are not met, the HDR option in Moonlight may appear grayed out or not appear at all.
Known issues with GameStream HDR:
- Running some games and applications may cause flashing color artifacts when HDR streaming is enabled
- The video stream may not start until you move or click the mouse when HDR streaming is enabled
- You may see video scaling artifacts if the stream resolution doesn't match the host display resolution when HDR streaming is enabled
- If HDR is already enabled on your host PC when streaming starts, you may need to toggle HDR off and back on for the stream to enter HDR mode properly
**Host PC requirements for HDR streaming**
For a host using Sunshine:
- A Windows host with NVIDIA, AMD, or Intel GPUs that support encoding HEVC Main 10
- An HDR-capable display or EDID emulator dongle connected to your host PC
For a host using GeForce Experience:
- NVIDIA GeForce GTX/RTX 1000-series or later
- Some newer games may require an HDR display or HDR10-compatible EDID emulator dongle connected to your host PC for HDR options to be available
- The stream resolution in Moonlight should be set to match the host PC's display resolution to prevent video scaling artifacts
**iOS and Apple TV client requirements for HDR streaming**
- iOS/tvOS 11.3 or later
- HDR10-compatible display
- For iOS devices, this means devices with "XDR" displays
- For Apple TV devices, the connected TV must support HDR10
**Android client requirements for HDR streaming**
- Android 7.0 or later
- HEVC Main10 hardware decoder
- HDR10-compatible display
**Windows client requirements for HDR streaming**
- Windows 10 1703 (Creators Update) or later
- HDR10-compatible display
- Client GPU must support both HEVC Main10 decoding and HDR10 output
- For Intel GPUs, this is 7th-generation (Kaby Lake) iGPUs and later
- For NVIDIA GPUs, this is 1000-series (Pascal) GPUs and later
- For AMD GPUs, this is RX 400-series (Polaris) GPUs and later
- HDR toggle in Windows must be enabled for streaming in windowed mode
**macOS client requirements for HDR streaming**
- macOS Catalina or later
- See [Apple's documentation](https://support.apple.com/en-us/HT210980) for additional requirements and recommendations
**Linux client requirements for HDR streaming**
- Moonlight must be launched directly from the console, rather than within a desktop environment
- This is required to allow Moonlight to directly configure the display for HDR
- Intel GPU (other vendors may work but are untested)
- HDR10-compatible display
**Raspberry Pi 4 requirements for HDR streaming**
- Moonlight must be launched directly from the console, rather than within a desktop environment
- This is required to allow Moonlight to directly configure the display for HDR
- HDR10-compatible display
- See [HDR and HEVC support on the Raspberry Pi 4](https://github.com/moonlight-stream/moonlight-docs/wiki/Installing-Moonlight-Qt-on-Raspberry-Pi-4#hevc-and-hdr-support) for configuration steps
## Keyboard/Mouse/Gamepad Input Options
**PC client**
PC clients support keyboard, mouse, and touchscreen input and up to 4 game controllers (with mappings for most common gamepads included).
* Ctrl+Alt+Shift+Q - Quit the streaming session (leaving the game running on the host PC)
* Ctrl+Alt+Shift+Z - Toggle mouse and keyboard capture
* Ctrl+Alt+Shift+X - Toggle between full-screen and windowed mode
* Ctrl+Alt+Shift+S - Open performance stats overlay (not supported on Steam Link or Raspberry Pi)
* Ctrl+Alt+Shift+M - Toggle mouse mode (pointer capture or direct control)
* Ctrl+Alt+Shift+V - Type clipboard text on the host
* Ctrl+Alt+Shift+D - Minimize the stream window
* Ctrl+Alt+Shift+C - Toggle local cursor display in remote desktop mouse mode (remote cursor will always show up due to GameStream limitations)
* Ctrl+Alt+Shift+L - Toggle locking the mouse pointer to the video area (requires "Optimize mouse for remote desktop instead of games" checkbox enabled)
**Touchscreen controls**
Moonlight for Android, iOS, and PC use the touch screen as a way of controlling the mouse cursor. Multi-touch devices can emulate more mouse functions than single-touch devices. There are two modes of touchscreen operation that you can choose between in Moonlight - one uses the touchscreen as a trackpad and the other emulates direct touchscreen input.
Trackpad mode:
* Move cursor: Swiping across the screen moves the mouse cursor in the direction of the swipe.
* Left click: Tap with one finger.
* Right click: While holding one finger down, tap a second finger.
* Click and drag: Long press with one finger, then start to drag after holding for about half a second.
* Scroll: Drag 2 fingers vertically.
* Show Keyboard: Tap with three fingers (Android and iOS only).
Touchscreen mode:
* Move cursor and left click: Tap the location where you would like to left click.
* Right click: Long press the location where you would like to right click.
* Click and drag: Tap a location and drag your finger across the screen.
* Show Keyboard: Tap with three fingers (Android and iOS only).
* Zoom: Pinch with 2 fingers (iOS only).
* Pan: Drag with 2 fingers (iOS only).
**Android client**
Moonlight supports gamepads that use the standard Android button mapping. It also supports some popular non-Android controllers like the Xbox 360, Xbox One, PS3, and PS4 controllers. However, we recommend testing these with your specific Android device first, because some controllers have latency or disconnection issues (particularly with PlayStation controllers over Bluetooth).
For gamepads that are missing Select or Mode buttons, the following special button combos are available to emulate them:
- Start+Select (for gamepads with a Select button) or R1+Start (for gamepads without a Select button) = Mode
- L1+Start = Select
For non-SHIELD devices and devices running Android 7.1 (Nougat) or earlier, using an external mouse with proper mouse capture on Android requires a rooted device. If you want to use an external mouse on your rooted device, you should download `app-root-release.apk` from the [GitHub releases page](https://github.com/moonlight-stream/moonlight-android/releases). NVIDIA SHIELD devices and Android 8.0 (Oreo) have mouse capturing built-in that Moonlight uses without needing root. Moonlight for Rooted Devices is not available for Android 8.0, since the non-root version contains all features that required root using the new Android Oreo APIs.
To toggle capturing the mouse cursor on Moonlight for Rooted Devices, press Ctrl+Alt+Shift+Z.
If you don't have a mouse connected to your Android device, you can emulate one using a game controller. Press and hold the Start button to toggle mouse emulation. When mouse emulation is on, you can use either analog stick to move the cursor. The A button left clicks and the B button right clicks.
**iOS/tvOS client**
If your device is running iOS/tvOS 13 or later, you can use Xbox One S and PS4 controllers with your device over Bluetooth. Moonlight supports all physical buttons on these controllers, including Select, L3, and R3. Moonlight also supports controller vibration on these controllers with iOS/tvOS 14. You can also still use MFi controllers if you want, but they may not have all of the buttons that an Xbox or PS4 controller has and won't support vibration.
Devices running iOS/tvOS 12 or earlier are limited to MFi controllers. We recommend the "extended layout" controllers which have most buttons present on a typical Xbox controller. Notably lacking on most MFi controllers are the L3 and R3 buttons and the Select button. When using the Auto setting for on-screen controls on iOS, an overlay will be displayed containing the buttons that your physical controller is missing.
iPadOS 13.4 adds support for mouse input, though it is limited by the OS such that it doesn't work with games that capture the mouse pointer (like most FPS games) and you can't hold more than one mouse button down at a time. iPadOS 14 solves both of these limitations, however not all mice are compatible with the new enhanced iPadOS 14 mouse support. Compatibility for non-Apple mice seems to be best when connected via USB (with a USB-C to USB-A or Lightning to USB-A adapter) instead of Bluetooth.
You can use the Apple TV remote as a touchpad to move the mouse cursor and click.
To disconnect from your PC while streaming on iOS, swipe from the left edge of the screen. To disconnect on tvOS, double-tap the Menu button on your Apple TV Remote.
iCade gamepads (old iOS gamepads that fake a Bluetooth keyboard) are not supported by Moonlight.
## Adding custom programs that are not automatically found
You can stream almost any game or app by adding the EXE file manually to Sunshine or GeForce Experience (if it's not found by the automatic app scan).
If you're using Sunshine, you can add new apps via the configuration interface, under the "Applications" page.
If you're using GeForce Experience, open GeForce/Quadro Experience, click the **Settings (gear) button**, click **SHIELD** on the sidebar, then click the **Add button** on the right. Browse to the app or file you want to add and click OK. You can rename the app using the **Edit button**.
The next time the client opens and displays the App List, the newly added programs and games should be displayed and ready to stream.
If quitting an application doesn't stop Moonlight, press *Ctrl+Shift+Alt+Q* on Moonlight PC to quit the streaming session. On Moonlight Android and iOS, pressing the home key will switch out of the streaming session. Choose the **Quit Session** option from the App List to fully quit the streaming session.
## Using Moonlight to stream your entire desktop
If you're using Sunshine, you'll already have a built-in "Desktop" app. This only applies for hosts using GeForce Experience.
Follow the steps above for adding a custom program, but for the path use: **C:\windows\system32\mstsc.exe**
You can rename the remote desktop entry using the Edit button. When you click this entry, you will see your full desktop where you can run whatever you want.
Even though the mstsc.exe executable is typically used for Microsoft Remote Desktop, this is only an indicator to GeForce/Quadro Experience that you want to stream your desktop. It does not actually launch mstsc.exe or use RDP to stream.
***

159
wiki/Troubleshooting.md Normal file
View File

@ -0,0 +1,159 @@
_These troubleshooting checklists contain various suggestions to solve each potential issue. They are generally meant to be done in the order the steps are listed, however the list doesn't need to be fully completed if issue goes away during the process of troubleshooting._
You can chat with Moonlight developers and other users to help you resolve streaming issues on our Discord server.
<a href="https://moonlight-stream.org/discord"><img src="https://moonlight-stream.org/images/discord.png" height="70" alt="Join our Discord"></a>
Look at the troubleshooting steps for each of the following issues:
* [Unable to stream at all on the same network as the PC](https://github.com/moonlight-stream/moonlight-docs/wiki/Troubleshooting#unable-to-stream-at-all-on-the-same-network-as-the-pc)
* [Unable to stream at all over the Internet](https://github.com/moonlight-stream/moonlight-docs/wiki/Troubleshooting#unable-to-stream-at-all-over-the-internet)
* [Video is choppy or laggy](https://github.com/moonlight-stream/moonlight-docs/wiki/Troubleshooting#video-is-choppy-or-laggy)
* [No video (black screen)](https://github.com/moonlight-stream/moonlight-docs/wiki/Troubleshooting#no-video-black-screen)
* [Missing mouse cursor](https://github.com/moonlight-stream/moonlight-docs/wiki/Troubleshooting#missing-mouse-cursor)
* [Video only displays in the top left corner of the stream](https://github.com/moonlight-stream/moonlight-docs/wiki/Troubleshooting#video-only-displays-in-the-top-left-corner-of-the-stream)
* [Known application compatibility issues](https://github.com/moonlight-stream/moonlight-docs/wiki/Troubleshooting#known-application-compatibility-issues)
* [Pairing dialog won't show up on PC](https://github.com/moonlight-stream/moonlight-docs/wiki/Troubleshooting#pairing-dialog-wont-show-up-on-pc)
* [SHIELD tab is missing in GeForce Experience](https://github.com/moonlight-stream/moonlight-docs/wiki/Troubleshooting#shield-tab-is-missing-in-geforce-experience)
* [Games are missing from Moonlight](https://github.com/moonlight-stream/moonlight-docs/wiki/Troubleshooting#games-are-missing-from-moonlight)
* [Controller input doesn't work when streaming](https://github.com/moonlight-stream/moonlight-docs/wiki/Troubleshooting#controller-input-doesnt-work-when-streaming)
* [Bluetooth-related streaming issues](https://github.com/moonlight-stream/moonlight-docs/wiki/Troubleshooting#bluetooth-related-streaming-issues)
### Known bugs in GeForce Experience that _don't_ affect hosts using [Sunshine](https://app.lizardbyte.dev/Sunshine/)
* [Streamed picture is stuck in the top-left corner](https://github.com/moonlight-stream/nvidia-gamestream-issues/issues/48)
* [Pairing may fail if there are non-ASCII characters in your user name](https://github.com/moonlight-stream/nvidia-gamestream-issues/issues/30)
* [Video freezes with hardware-accelerated GPU scheduling on the host](https://github.com/moonlight-stream/nvidia-gamestream-issues/issues/27)
* [Host mouse cursor is invisible when a UAC dialog is displayed on Win10+](https://github.com/moonlight-stream/nvidia-gamestream-issues/issues/2)
* [Windows OS HDR state is not properly identified when starting a stream](https://github.com/moonlight-stream/nvidia-gamestream-issues/issues/29)
* [Rumble stops working until host PC reboot if nvstreamer.exe terminates unexpectedly](https://github.com/moonlight-stream/nvidia-gamestream-issues/issues/28)
### Unable to stream at all on the same network as the PC
* Ensure you've enabled GameStream in GeForce Experience per the [setup guide](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide)
* Reboot your PC and client device.
* If your gaming PC is connected to your home network via multiple connections (like both Ethernet and WiFi), disconnect all connections except for the fastest one (usually Ethernet).
* Check the list of [known application compatibility issues](https://github.com/moonlight-stream/moonlight-docs/wiki/Troubleshooting#known-application-compatibility-issues). Try uninstalling any programs on that list one to see if one of them is interfering.
* Make sure your primary monitor is connected to your NVIDIA GPU and turned on, and you are logged in.
* If you use a VPN for Internet access on your gaming PC, disable it to ensure your local network is accessible. You may also need to [disable the setting to block local network access](https://github.com/moonlight-stream/moonlight-docs/wiki/Internet-Streaming-Errors#local-network-access-blocked-error).
* Disable your PC's firewall and anti-virus, and reboot again. If this works, you can create a firewall exception using [the steps here](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#firewall-setup).
* Uninstall GeForce Experience, reboot, clean install GeForce Experience, and reboot again.
* In an administrator command prompt, run `netsh winsock reset` and reboot your computer.
* If your PC is running Windows Server, install the qWave service and ensure the Windows Audio service is enabled and running.
* If you had used Microsoft Remote Desktop you will need to follow the instructions in the [Known Compatibility Issues](https://github.com/moonlight-stream/moonlight-docs/wiki/Troubleshooting#known-application-compatibility-issues) in order to stream again.
* Ask for help on our [Discord server](https://moonlight-stream.org/discord)
### Unable to stream at all over the Internet
* First, ensure you can stream successfully from your home network to ensure it's an issue specific to streaming over the Internet. If you can't, follow the instructions in the section above for general streaming issues.
* Make sure your gaming PC is running the [Moonlight Internet Hosting Tool](https://github.com/moonlight-stream/Internet-Hosting-Tool/releases) to automatically manage your port forwarding rules.
* Ensure UPnP is enabled in your router settings and delete any older Moonlight port forwarding entries.
* If you use a VPN for Internet access on your gaming PC, disable it to ensure your local network is accessible. You may also need to [disable the setting to block local network access](https://github.com/moonlight-stream/moonlight-docs/wiki/Internet-Streaming-Errors#local-network-access-blocked-error).
* Run the "Moonlight Internet Streaming Tester" found in the [Moonlight Internet Hosting Tool](https://github.com/moonlight-stream/Internet-Hosting-Tool/releases) and ask for help on our [Discord server](https://moonlight-stream.org/discord). Be sure to have the tester log handy.
* If the Moonlight Internet Streaming Tester says your ISP is running a [Carrier-grade NAT](https://en.wikipedia.org/wiki/Carrier-grade_NAT) that blocks hosting services like Moonlight, try these steps:
* Ask your ISP for a public IP address. Many users have reported that their ISP is happy to provide one free of charge upon request.
* Many users have reported good streaming performance using the [ZeroTier](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#zerotier) setup steps.
* You can try using the [IPv6 setup steps](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#ipv6-certain-isps-only) if your home ISP and client network both support IPv6. You can check this by seeing if you score a 10/10 on [this web IPv6 test](http://test-ipv6.com/).
* Ask for help on our [Discord server](https://moonlight-stream.org/discord)
### Video is choppy or laggy
* If you have issues with the video getting stuck while streaming, disable hardware-accelerated GPU scheduling on your host PC.
* Try streaming with Bluetooth disabled to see if your device has the Bluetooth issue detailed below.
* Make sure your client device is connected on 5 GHz WiFi or Ethernet, and your PC is wired to your router if possible.
* If you're streaming to a Mac over WiFi, try [disabling Location Services and AirDrop](https://github.com/moonlight-stream/moonlight-qt/issues/159#issuecomment-452675992).
* If you're streaming to a Windows PC with an Intel WiFi adapter, try setting "Global BG scan blocking" to "On Good RSSI" in the Device Manager Properties for the WiFi adapter. If "On Good RSSI" does not show up, try using "Always" instead.
* Ensure your Nvidia GPU is not being underclocked (which can impact NVENC performance). You may also try a modest overclock or raising the GPU power limit if you are comfortable with that.
* Lower the bitrate slider to determine if it's a bandwidth issue.
* Try using 720p30 which has the lowest requirements.
* Ask for help on our [Discord server](https://moonlight-stream.org/discord)
### No video (black screen)
* Ensure your monitor is powered on and connected to your NVIDIA GPU
* If you want to stream without a monitor connected, you can buy a cheap headless HDMI dongle like [this one](https://www.amazon.com/fit-Headless-GS-resolution-emulator-game-streaming/dp/B01EK05WTY)
* Try a different game or stream Steam to see if it's game-specific. You may be able to work around the game-specific issues by [streaming your whole desktop](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#using-moonlight-to-stream-your-entire-desktop) and starting the game from there.
* Ask for help on our [Discord server](https://moonlight-stream.org/discord)
### Missing mouse cursor
* Ensure a mouse is connected to your host gaming PC
* If unable to physically connect a mouse, enable Mouse Keys on the host gaming PC to force Windows to display a mouse cursor.
* If you just type "Mouse key" into the Start Menu search dialog, it should take you to the correct settings page.
* Ask for help on our [Discord server](https://moonlight-stream.org/discord)
### Video only displays in the top left corner of the stream
* Use the NVIDIA Control Panel to set your desired display resolution, not Windows Display Settings
* If your resolution is already set to the desired value, change it to something else and back again using NVIDIA Control Panel.
### Known application compatibility issues
Some installed applications and security products can interfere with GeForce Experience or GameStream. Depending on the configuration of these incompatible applications, you may or may not experience issues streaming.
Special-case issues:
* Parsec/Rainway/Steam In-Home Streaming
* Disconnect your stream before using Moonlight to avoid encoder conflicts with other streaming apps
* NordVPN, TunnelBear, PIA, and other VPNs
* Disable the VPN if Moonlight cannot discover your gaming PC or stream over the Internet
* You may also need to [disable the setting to block local network access](https://github.com/moonlight-stream/moonlight-docs/wiki/Internet-Streaming-Errors#local-network-access-blocked-error).
* Safing Portmaster
* Streaming may not work until the program is fully uninstalled
* Microsoft Remote Desktop
* When using RDP, your computer is technically locked, causing streaming issues even after disconnecting. This lock prevents starting programs with Moonlight.
* Sunshine Hosts
* Log back into the computer via the "Desktop" app in Moonlight, then you can end and start another stream with the application you wanted originally.
* Geforce Experience Hosts
* Log into the computer physically or you may use the following script commands in a PowerShell terminal while in an RDP session:
```powershell
$session = (query session | Select-String $env:USERNAME) -split " " | Where-Object { $_ } | Select-Object -Index 2
& tscon $session /dest:console
```
This will terminate your RDP session but leave it unlocked, allowing you to stream again.
* Chrome Remote Desktop, TeamViewer, or VNC can be used for remote access without breaking Moonlight
* Teamspeak Gamepad Plugin
* The gamepad plugin may cause [extra gamepads to appear in Device Manager](https://github.com/moonlight-stream/moonlight-qt/issues/304), but streaming works normally
* Password managers (KeePass, iCloud Keychain, and potentially others)
* In order to improve security, some password managers report themselves as protected content (like DRM) to Windows. This can interfere with streaming.
* If you have trouble streaming while a password manager is running, check the password manager's settings to see if it's possible to turn this protection off.
* Valorant (The kernel level DRM. A full Windows reinstall may be required to allow Gamestream to function.)
If you have one of the following, try disabling or uninstalling it:
* 3rd-party Firewalls and Anti-virus
* Kaspersky in particular may only [stop breaking Moonlight when it is fully uninstalled](https://www.reddit.com/r/theNvidiaShield/comments/4g5fft/gamestreaming_vs_kaspersky_resolved/).
* Malwarebytes (specifically the Web Protection module)
* DisplayLink dock/display software
* Razer Synapse
* Razer Kraken software (APO Helper)
* ASUS Sonic Studio
* ASUS SonicRadar
* ASUS KeyBot
* ASUS GameFirst
* NVIDIA RTX Voice
* Lenovo Vantage
### Pairing dialog won't show up on PC
* Check the list of known application compatibility issues above. Uninstall any programs on that list, and reboot.
* Reboot your PC
* Delete the following registry value (if present): HKEY_LOCAL_MACHINE\SOFTWARE\NVIDIA Corporation\NvTray\ShowInSedona
* Open the NVIDIA Control Panel, select the "Desktop" menu at the top, and check "Show Notification Tray Icon".
* Uninstall GeForce Experience, reboot, clean install GeForce Experience, and reboot again.
* Ask for help on our [Discord server](https://moonlight-stream.org/discord)
### SHIELD tab is missing in GeForce Experience
* Check the list of known application compatibility issues above. Uninstall any programs on that list, and reboot.
* Reboot your PC
* Install the latest GPU driver from NVIDIA's website
* Uninstall and reinstall GeForce Experience
### Games are missing from Moonlight
* Make sure the folder where your games are installed is listed in GeForce Experience.
* You can add a games folder by opening GeForce Experience, clicking on the Settings button, then clicking the + button and navigating to the correct folder.
* You can add games manually that aren't detected as streamable by GeForce Experience [using this guide](https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#adding-custom-programs-that-are-not-automatically-found)
### Controller input doesn't work when streaming
* Ensure you're running GeForce Experience 3.15.0 or later
* In Steam Big Picture, go to Settings > Controller Settings, then uncheck all gamepad "Configuration Support" checkboxes
* Check if input works in Steam Big Picture to see if it's a game-specific compatibility issue
* If your host is running Windows Server 2016/2019, you may need to install the [Xbox 360 drivers for Windows 7 64-bit](https://www.microsoft.com/accessories/en-gb/d/xbox-360-controller-for-windows)
* Ask for help on our [Discord server](https://moonlight-stream.org/discord)
### Bluetooth-related streaming issues
Depending on your streaming device, you may have a bad experience if Bluetooth is active while streaming. This is a hardware limitation due to the antenna wiring. If you experience this and are streaming from within your home, you can try connecting the gamepad directly to your PC using a wireless adapter or Bluetooth.
Still having issues? Ask for help on our [Discord server](https://moonlight-stream.org/discord)

60
wiki/WOL-(Wake-On-LAN).md Normal file
View File

@ -0,0 +1,60 @@
## Overview
WOL (Wake On LAN) allows the waking of a suspended or shutdown system over LAN.
Note that not every system (especially laptops) supports WOL and or waking from shutdown.
A static DHCP lease (also known as a static Local IP) for your host in your router is recommended to improve reliability and is required for WOL over the Internet. See: https://github.com/moonlight-stream/moonlight-docs/wiki/Setup-Guide#static-dhcp-reservation
WOL over Wi-Fi is usually unstable. It is always recommended to have a wired connection for the host when possible.
WOL has to be enabled both in the UEFI/BIOS and OS in order to function.
## UEFI/BIOS Setup
*These steps may differ depending on your system*
First, enter the UEFI/BIOS. Pressing the __delete__ key during boot usually works, you can also try __F2__ or __F12__. Alternatively on Windows 8+ you can hold the __Shift key while Rebooting__ Then navigate to Troubleshooting>Boot to UEFI.
Look for a setting usually found in "Power" or "PCI sub system" called "Power On By PCI Device" or "Wake-on-LAN" or similar. These need to be enabled.
## Windows Setup
Open Device Manager, You can do this by right-clicking the Windows Icon. Then navigate to "Network Adapters", Right-click your Adapter, and go to its properties. Then go to the Advanced tab. In the list look for "Wake on Magic Packet" and enable it, it is usually towards the bottom. "Wake on Magic Packet from system shutdown" allows for Waking from shutdown. __Wake on pattern should remain Disabled!__ Having it Enabled can result in random system wakes from normal network scans and such.
![Wake on Magic Packet 1](https://github.com/moonlight-stream/moonlight-docs/assets/48956874/e4f331c9-5fc3-48ab-91d0-4b8aee09bac1)
If you do not see the options listed above then the NIC (Network Interface Card) either does not support WOL, or the drivers for the NIC are out of date or broken.
Also in the adapter properties under the "Power Management" tab enable "Allow this device to wake the computer" and its sub option.
![Wake on Magic Packet 2](https://github.com/moonlight-stream/moonlight-docs/assets/48956874/d5e5cfb5-9718-4564-a878-a5f418e17880)
## Linux Setup
In the Terminal run `ifconfig -a` and note the desired eth#.
Install "ethtool" if not already installed, run `sudo ethtool eth#` and replace eth# with noted. Check the output, if there is a "G" next to "Supports Wake-on" then the NIC supports WOL. Run `sudo ethtool -s eth# wol g` again replace eth# with noted.
## Internet WOL
WOL is not designed to work over WAN. (Wide Area Network, AKA Internet) But it can be done in a few ways, some safer than others. The list below is in the order of recommended methods. Most methods require some other device that is always online and connected you your __Host's__ local network.
DDNS or a static Public IP is a requirement for most options. see https://www.noip.com/ a DDNS service.
- Host a VPN server. You will need some other device that is always online and connected to the Host's network to act as a VPN server. You also need the ability to port forward on your router. The WOL packet can be sent from the Moonlight client to the sleeping host via a VPN tunnel. Also see the WOL Tailscale container in the next section. Such devices include but are not limited to;
- Routers, many can run a VPN server and even have a baked-in utility for hosting a VPN.
- A RPI (Raspberry PI) or other similar SBC.
- A NAS. (Network Attached Storage) Basically a Server, a NAS can host a variety of servers including VPN servers. Many customer NAS devices have a baked-in VPN utility.
- Have another device wake the system. You will need some other device that is always online and connected to the Hosts network to act as in essence a WOL relay. Depending on the device used you may need to port forward. Such devices include but are not limited to;
- Router WOL utility. Many routers offer a WOL utility either usable with just a router app or by port forwarding the router GUI. (If you do the latter be sure to have an EXTREMELY robust login for the router. Not recommended)
- WOL Tailscale container. This option is great if you are behind a __CGNAT__ or are __unable to port forward__. https://github.com/andygrundman/tailscale-wakeonlan
- A RPI. https://www.instructables.com/id/Raspberry-Pi-As-Wake-on-LAN-Server/
- A remotely accessible system such as a NAS, or similar.
- An Arduino with a network connection. https://github.com/TullyE/ArduinoWOL/
- Use Home Assistant. https://www.home-assistant.io/integrations/wake_on_lan/
- Forward and allow through the router firewall port 9 to the Host. This will only work for ~2 hours due to the way IPs work. after such time you __Will__ need to use one of the other methods mentioned above.
## WOL Alternatives
If your system either does not have the ability to use WOL, or you can not use the Internet WOL methods mentioned above you may be able to use the following tactics to achieve a similar effect.
- Use a smart plug. You can set the system UEFI/BIOS to power on the system when power is lost and then restored. When you want to start the system you just turn the smart plug off and on.
- Use an in-system KVM/Remote management board to interact with the system and it's internal power switch header such as: https://geekworm.com/products/pikvm-a8?_pos=1&_sid=333b48621&_ss=r
- Set the UEFI/BIOS to wake the system at a certain time.
## Tips and Tricks
- WOL has a tendency to break when a system is asleep for a prolonged period of time usually due to a very small network hiccup (usually not even noticeable). This is particularly annoying when abroad. One way to get around this is to set the UEFI of the host to wake the system every day at say 1:00 AM, then have a scheduled task in Windows to sleep the system at say 1:05 AM. This will allow the system to re-establish a network connection at least once a day if it happened to break.

1
wiki/_Footer.md Normal file
View File

@ -0,0 +1 @@
Have a question or problem that isn't addressed here? Try asking on [our Discord server](https://moonlight-stream.org/discord)!

BIN
wiki/images/gfe-gamestream-enable-small.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 77 KiB

BIN
wiki/images/gfe-gamestream-enable.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 175 KiB

BIN
wiki/images/hw-gpu-sched-small.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 77 KiB

BIN
wiki/images/hw-gpu-sched.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 231 KiB