Troubleshooting

Cause: CineWindows forces the OpenGL RHI backend on Windows for mpv video rendering (QSG_RHI_BACKEND=opengl). Stats pages 2 (frame timings), 3 (cache), and 4 (key bindings) rely on Direct3D 11-specific mpv features and are not available under the OpenGL backend.

Solution: This is a known limitation of the current architecture. Pages 1 (default), 5 (tracks), and the keyboard shortcut reference (?) work correctly. Toggle stats with F1–F5 — non-functional pages will show a blank overlay.

Cause: Qt 6 defaults to the Direct3D 11 RHI backend on Windows, but mpv’s OpenGL render API is incompatible with D3D11. CineWindows forces QSG_RHI_BACKEND=opengl at startup, but this can fail on systems with broken or missing OpenGL drivers.

Solution: Ensure your GPU drivers are up to date. On systems with only D3D11 support, this may not work — consider a system with OpenGL 3.3+ support. Verify that QSG_RHI_BACKEND=opengl is being set by checking the application log for the RHI backend message.

# Check environment variable is set
echo $env:QSG_RHI_BACKEND
# Should output: opengl

Cause: Several possibilities: system audio device is not available, mpv audio output driver selection fails, or the volume is muted or set to zero.

Solution:

• Check that Mute is not enabled (press M to toggle)
• Increase volume with 0 or *
• Verify your system audio device is working with other applications
• Check the audio output device selection in your system sound settings
• Try a different audio track (# cycles tracks)

Cause: Subtitle files may not be auto-detected, the wrong track is selected, or the subtitle visibility is toggled off.

Solution:

• Press V to toggle subtitle visibility
• Cycle subtitle tracks with J (next) or Shift+J (previous)
• For external subtitle files, drag and drop the file onto the window
• Check that the subtitle file name matches the video file name for auto-loading
• Verify subtitle font and scale settings in Preferences

Cause: CineWindows requires yt-dlp to be in the application directory or on the system PATH for URL streaming (YouTube, etc.).

Solution:

• The official setup installer and portable releases fetch and place yt-dlp.exe automatically during installation or packaging
• If running from a portable ZIP, ensure yt-dlp.exe is present in the application directory next to CineWindows.exe
• Download official application updates and release packages from GitHub Releases
• Verify with yt-dlp --version in a terminal if custom pathing is used

Cause: The LAN companion remote service may not be running on the expected port, or firewall rules are blocking connections.

Solution:

• Open Preferences and verify the Remote Control service is enabled
• Default port is 32322 — check your firewall allows inbound connections on this port
• Ensure both devices are on the same local network
• Regenerate the pairing code from the Remote Control settings
• The companion remote web interface URL is displayed in the Remote Control settings panel

Cause: Typically a missing Qt runtime DLL, incompatible libmpv version, or corrupt configuration file.

Solution:

• Run from a command prompt to see any error messages before the crash
• Verify Qt 6.8+ runtime DLLs are available (windeployqt should have deployed them)
• Check that libmpv is version 2.x and compatible with MpvQt 1.2.0
• Delete or rename the configuration directory (%APPDATA%/gyrolet/CineWindows/) to reset settings
• Try the portable ZIP distribution instead of the installed version

# Backup and remove
Rename-Item "$env:APPDATA\gyrolet\CineWindows" "$env:APPDATA\gyrolet\CineWindows.backup"

Cause: Software decoding of high-resolution video, insufficient GPU capabilities, or missing hardware acceleration.

Solution:

• Open Preferences and enable Hardware Acceleration (auto-safe)
• Verify your GPU supports DXVA2 or D3D11VA decoding
• Close other GPU-intensive applications
• Reduce video quality or resolution in mpv.conf if needed
• Check CPU usage — if it’s near 100%, hardware decoding is not active