feat(linux)!: use experimental renderer by default

This commit introduces an experimental offscreen renderer for Linux
that decouples UI rendering from video rendering as much as possible to
improve UI responsiveness. The new renderer is enabled by default on
Linux and can be toggled via the MPVQC_LINUX_EXPERIMENTAL_RENDERER
environment variable.

Updated Video Rendering:
- Windows:
    unchanged - mpvQC uses winId/HWND embedding as before
- Linux:
    Offscreen renderer (experimental) by default. Set
    MPVQC_LINUX_EXPERIMENTAL_RENDERER=false to use the old renderer

Technical Differences:
- Legacy renderer: Renders directly into the UI's framebuffer. Without
  tweaking other configuration parameters, this has the limitation that
  the UI is constrained to the framerate of the video file.
- Offscreen renderer: Uses two additional framebuffers and renders in a
  separate thread, independent of the screen's refresh rate:

  mpv → _render_fbo → _display_fbo → Qt Quick's FBO → screen

  _render_fbo → _display_fbo:    pointer swap
  _display_fbo → Qt Quick's FBO: blit in render()

Audio Delay Compensation:
The offscreen renderer decouples video rendering from UI framerate,
which means mpv renders frames independently of what's displayed on
screen. This can cause audio desynchronization as the audio continues
at real-time while video frames may be presented at the display's
refresh rate.

To address this, mpvQC now automatically adjusts the audio delay based
on the current monitor's refresh rate. The delay is calculated as the
frame time (1 / refresh_rate) rounded to millisecond precision. The
adjustment updates dynamically when the window moves to a different
monitor or when the refresh rate changes.

Breaking Change:
Users upgrading from previous versions of mpvQC on Linux must update
their mpv settings via Options -> Edit mpv.conf:

- When using the NEW offscreen renderer (default):
  Remove any video-timing-offset configuration. The new renderer handles
  timing automatically through audio delay compensation based on the
  monitor's refresh rate. Having video-timing-offset configured will
  cause timing issues.

- When using the OLD legacy renderer
  (MPVQC_LINUX_EXPERIMENTAL_RENDERER=false):
  Keep or add video-timing-offset=0.016 (or adjust based on your
  monitor's refresh rate). The legacy renderer requires this setting
  for proper synchronization.

Author: trin94

data/config/mpv-linux.conf

@@ -5,10 +5,6 @@
 # HQ preset, uses Spline36 for upscaling and Mitchell-Netravali for downscaling
 profile=gpu-hq
 
-# Configure offset to match a frame rate of 60 fps; default 0.050
-# More info: https://github.com/mpvqc/mpvQC/issues/26
-video-timing-offset=0.016
-
 # Debanding is disabled because we don't want to alter the video while doing quality control
 deband=no
 

docs/configuration.md

@@ -21,3 +21,10 @@ mpvQC can be configured using the following environment variables:
   - **Operating System:** All
   - **Description:** Enables mpv player logging
   - **Possible Values:** *not set* or *any value*
+
+- **`MPVQC_LINUX_EXPERIMENTAL_RENDERER`**
+
+  - **Default Value:** true
+  - **Operating System:** Linux
+  - **Description:** Enables rendering in background thread
+  - **Possible Values:** *false* to revert back to stable renderer, unset to enable

mpvqc/services/host_integration/__init__.py

@@ -2,10 +2,17 @@
 #
 # SPDX-License-Identifier: GPL-3.0-or-later
 
+from __future__ import annotations
+
 import platform
 from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QEvent, QObject, Signal, Slot
+from PySide6.QtGui import QScreen
 
-from PySide6.QtCore import QEvent, QObject, Signal
+if TYPE_CHECKING:
+    from PySide6.QtGui import QWindow
 
 
 @dataclass(frozen=True)
@@ -28,27 +35,51 @@ class HostIntegrationService(QObject):
     DEFAULT_WINDOW_BUTTON_PREFERENCE = WindowButtonPreference(minimize=True, maximize=True, close=True)
 
     display_zoom_factor_changed = Signal(float)
+    refresh_rate_changed = Signal(float)
 
     def __init__(self):
         super().__init__()
         self._zoom_factor = get_display_zoom_factor()
+        self._refresh_rate = get_refresh_rate()
 
         self._zoom_factor_change_listener = ZoomFactorChangeEventListener()
         self._zoom_factor_change_listener.device_pixel_ratio_changed.connect(self._invalidate_zoom_factor)
 
         from mpvqc.utility import get_main_window
 
-        self._window = get_main_window()
+        self._window: QWindow = get_main_window()
         self._window.installEventFilter(self._zoom_factor_change_listener)
+        self._window.screenChanged.connect(self._on_screen_changed)
+
+        self._screen: QScreen = self._window.screen()
+        self._screen.refreshRateChanged.connect(self._invalidate_refresh_rate)
+
+    @property
+    def display_zoom_factor(self) -> float:
+        return self._zoom_factor
 
+    @Slot(float)
     def _invalidate_zoom_factor(self, *_) -> None:
         if (zoom_factor := get_display_zoom_factor()) != self._zoom_factor:
             self._zoom_factor = zoom_factor
             self.display_zoom_factor_changed.emit(zoom_factor)
 
     @property
-    def display_zoom_factor(self) -> float:
-        return self._zoom_factor
+    def refresh_rate(self) -> float:
+        return self._refresh_rate
+
+    @Slot(QScreen)
+    def _on_screen_changed(self, screen: QScreen) -> None:
+        self._screen.refreshRateChanged.disconnect(self._invalidate_refresh_rate)
+        self._screen = screen
+        self._screen.refreshRateChanged.connect(self._invalidate_refresh_rate)
+        self._invalidate_refresh_rate()
+
+    @Slot(float)
+    def _invalidate_refresh_rate(self, *_) -> None:
+        if (refresh_rate := get_refresh_rate()) != self._refresh_rate:
+            self._refresh_rate = refresh_rate
+            self.refresh_rate_changed.emit(refresh_rate)
 
     def get_window_button_preference(self) -> WindowButtonPreference:
         match platform.system():
@@ -66,6 +97,12 @@ def get_display_zoom_factor() -> float:
     return get_main_window().devicePixelRatio()
 
 
+def get_refresh_rate() -> float:
+    from mpvqc.utility import get_main_window
+
+    return get_main_window().screen().refreshRate()
+
+
 def read_linux_window_button_preference() -> WindowButtonPreference:
     from mpvqc.services.host_integration.portals import SettingsPortal
 

mpvqc/services/player.py

@@ -6,12 +6,13 @@
 
 import logging
 import os
+import platform
 from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING
 
 import inject
-from PySide6.QtCore import QObject, Qt, Signal
+from PySide6.QtCore import QObject, Qt, Signal, Slot
 
 from .application_paths import ApplicationPathsService
 from .host_integration import HostIntegrationService
@@ -106,6 +107,10 @@ def init(self, win_id: int | None = None):
         self._mpv.observe_property("height", self._on_player_height_changed)
         self._mpv.observe_property("width", self._on_player_width_changed)
 
+        if platform.system() == "Linux" and os.getenv("MPVQC_LINUX_EXPERIMENTAL_RENDERER", "").lower() != "false":
+            self._host_integration.refresh_rate_changed.connect(self._on_refresh_rate_changed)
+            self._on_refresh_rate_changed(self._host_integration.refresh_rate)
+
     @property
     def mpv(self) -> MPV | None:
         return self._mpv
@@ -115,6 +120,11 @@ def _get_mpv_attr(self, attr: str) -> Any | None:
             return None
         return getattr(self._mpv, attr, None)
 
+    def _set_mpv_attr(self, attr: str, value: Any) -> None:
+        if self._mpv is None:
+            return
+        setattr(self._mpv, attr, value)
+
     @property
     def mpv_version(self) -> str:
         return self._get_mpv_attr("mpv_version") or ""
@@ -173,6 +183,14 @@ def current_time(self) -> int:
     def duration(self) -> float:
         return self._get_mpv_attr("duration") or 0.0
 
+    @property
+    def is_paused(self) -> bool:
+        return not self.is_playing
+
+    @property
+    def is_playing(self) -> bool:
+        return not self._mpv.pause and not self._mpv.idle_active if self._mpv else False
+
     @property
     def _track_list(self) -> list[TrackListEntry]:
         if self._mpv is None:
@@ -230,6 +248,17 @@ def _on_player_width_changed(self, _, value: int) -> None:
         if value is not None:
             self.width_changed.emit(value)
 
+    @Slot(float)
+    def _on_refresh_rate_changed(self, new_refresh_rate: float) -> None:
+        if new_refresh_rate is None:
+            return
+
+        refresh_rate = round(new_refresh_rate, 4)
+        audio_delay = round(1 / refresh_rate, 4)
+
+        logger.info("Adjusting audio_delay to %s due to updated refresh rate %s", audio_delay, refresh_rate)
+        self._set_mpv_attr("audio_delay", audio_delay)
+
     def move_mouse(self, x: int, y: int) -> None:
         zoom_factor = self._host_integration.display_zoom_factor
         x = int(x * zoom_factor)

mpvqc/startup.py

@@ -17,12 +17,19 @@ def perform_startup():
 
 
 def configure_qt_application_data():
+    import platform
+
     from PySide6.QtCore import QCoreApplication
 
     QCoreApplication.setApplicationName("mpvQC")
     QCoreApplication.setOrganizationName("mpvQC")
     QCoreApplication.setApplicationVersion(">>>tag<<<")
 
+    if platform.system() == "Linux":
+        from PySide6.QtGui import QGuiApplication, Qt
+
+        QGuiApplication.setAttribute(Qt.ApplicationAttribute.AA_ShareOpenGLContexts)
+
 
 def configure_qt_style():
     from PySide6.QtQuickControls2 import QQuickStyle

mpvqc/views/__init__.py

@@ -3,5 +3,21 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 
 # ruff: noqa: F401
-from .player_framebuffer_object import MpvqcMpvFrameBufferObjectPyObject
+
+import logging
+import os
+import platform
+
+logger = logging.getLogger(__name__)
+
+if platform.system() == "Linux":
+    if os.getenv("MPVQC_LINUX_EXPERIMENTAL_RENDERER", "").lower() == "false":
+        logger.info("Using default renderer. Unset MPVQC_LINUX_EXPERIMENTAL_RENDERER to enable experimental renderer")
+        from .player_framebuffer_object import MpvqcMpvFrameBufferObjectPyObject
+    else:
+        logger.info("Using experimental renderer. Set MPVQC_LINUX_EXPERIMENTAL_RENDERER=false to disable")
+        from .player_framebuffer_object_offscreen import MpvqcMpvFrameBufferObjectPyObject
+else:
+    from .player_framebuffer_object import MpvqcMpvFrameBufferObjectPyObject
+
 from .player_win_id import MpvWindowPyObject