Repository navigation
Known Issues & Limitations
When streaming over wired Ethernet, video data sent by your host PC is not always transmitted at a perfectly constant rate. Larger video frames, particularly keyframes, can temporarily generate significantly more network traffic. While the host PC may be connected through a Gigabit or faster Ethernet connection, many Tizen TVs have a built-in Ethernet port limited to 100 Mbps. This difference in link speeds can cause temporary traffic bursts that exceed the capacity of the TV’s Ethernet connection, potentially resulting in packet loss. When this happens, Moonlight may experience an unstable connection, black screen, freezing, or frequent frame drops. These kinds of issues can be particularly noticeable at higher resolutions or bitrates, where larger amounts of video data need to be transmitted.
If the same stream works normally over 5 GHz Wi-Fi on the same TV, the issue is likely related to the wired network connection rather than Moonlight itself. A Wi-Fi connection can provide higher throughput than the TV’s 100 Mbps Ethernet interface, depending on the TV and network conditions, allowing the stream to remain stable even when the wired connection does not.
On Windows, open the Ethernet adapter’s properties and navigate to Configure → Advanced → Speed & Duplex. Change Auto Negotiation to 100 Mbps Full Duplex, click OK, and restart your stream.
Setting the host PC’s Ethernet adapter to 100 Mbps Full Duplex can help eliminate the speed mismatch between the PC and the TV. When using this solution, keep the Moonlight bitrate below approximately 80 Mbps to leave sufficient bandwidth for network overhead.
If you have a managed switch that supports Ethernet flow control, enabling Flow Control on the port connected to your TV may help the switch better handle traffic bursts between the faster host connection and the TV’s 100 Mbps connection.
- Log into your switch’s administration interface.
- Find Flow Control, which may be located under Port Settings, QoS, or a similar section.
- Enable Flow Control on the port connected to the TV.
- Save the configuration and restart your stream.
After enabling Flow Control, you can return the host PC’s Ethernet adapter to Auto Negotiation and test streaming again at your desired bitrate.
Using a reliable 5 GHz Wi-Fi connection can avoid the limitations of the TV’s 100 Mbps Ethernet interface and may provide a more stable streaming experience, particularly when using higher resolutions or bitrates.
H.264 (AVC) on Tizen TVs is generally limited to 1080p, because it is a legacy and less-efficient codec compared to H.265 (HEVC) or AV1. While the H.264 standard technically supports 4K at Level 5.1 and above, most Samsung TV hardware decoders are capped at H.264 Level 4.1 or 4.2 to maximize efficiency. This limitation exists due to the high bitrate requirements of H.264 at higher resolutions such as 4K, which can exceed the TV’s internal memory bandwidth and cause playback instability.
Switch from H.264 to a high-efficiency codec such as HEVC or AV1 (requires a supported host GPU). These modern codecs are specifically designed to stream high-resolution content with much lower bitrates while remaining compatible with the TV’s dedicated hardware decoders.
Probably you may have encountered video stuttering or “clunky” frames during streaming, despite the FPS stats reporting the correct value. This may occur due to a display synchronization issue at the Tizen system level, where TVs fail to initialize the maximum display refresh rate, resulting in frame skipping. On the other side, the Moonlight app simply renders within whatever refresh rate configuration the TV provides to the application. This behavior is related to how Tizen OS handles refresh rates at the system/application level and is not something that can be controlled or caused by Moonlight itself.
Based on user reports, the only reliable workaround is to switch to an external HDMI source (e.g., gaming console) before launching Moonlight. Powering on a device on the HDMI port appears to force the TV to reinitialize its display refresh rate, after which Moonlight runs smoothly. Be aware that simply switching to the HDMI input without powering on the console does not fix it, and the issue returns after the TV is powered off, since the state resets.
Starting with Tizen 9.0, Samsung introduced platform-level changes to the Game Mode pipeline that can negatively affect WASM-based internal applications, such as Moonlight. As a result, the TV fails to properly activate Game Mode during streaming, even when Game Mode (Ultra Low Latency) is enabled in Moonlight’s settings. These changes can lead to various streaming issues, including video freezing on the first rendered frame, black screens, corrupted output at higher resolutions, instability at higher frame rates or bitrates, codec initialization failures, choppy or crackling audio, and other unpredictable behavior.
Important Note: These issues are not caused by Moonlight, but are the result of breaking changes introduced by the Samsung Tizen platform.
Due to inconsistent behavior of Game Mode across TV models and firmware versions on this affected platform, there are only two workarounds available (neither guarantees a perfect experience in all cases).
To force Game Mode on affected Tizen TVs, install the Moonlight-ForceGM.wgt variant from the latest release. This build package already includes the required Game Mode metadata, allowing the Tizen platform to attempt enabling Game Mode and prioritize low-latency optimization for Moonlight. Once installed, keep Game Mode disabled in Moonlight’s settings to utilize Low Latency. This combination allows Game Mode to activate properly (depending on the TV model) and avoids streaming issues that occur when using Ultra Low Latency.
Warning
Be aware that Game Mode metadata is considered experimental. Its behavior varies significantly depending on TV model and firmware version. While some users report success, others may still experience known issues such as unstable performance, black screens, resolution corruption above 1080p, screen artifacts/flickering/glitches, forced HDR activation, and other unknown issues.
If the Game Mode metadata causes instability, install the standard Moonlight.wgt from the latest release, and keep Game Mode disabled in Moonlight’s settings to use Low Latency. While this results in slightly higher latency compared to Ultra Low Latency or Game Mode Metadata, it still avoids several streaming issues that occur specifically when Game Mode is enabled.
Tip
To further reduce latency in this mode, it’s highly recommended to open your TV’s Picture Settings menu and disable any post-processing features such as Picture Clarity, Contrast Enhancer, and other similar video enhancements.