feat(linux)!: use experimental renderer by default

This commit introduces an experimental offscreen renderer for Linux
that decouples video rendering from UI rendering 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, blocking
  the UI thread during video rendering operations. This constrains the
  entire UI to the video's framerate.
- Offscreen renderer: Uses two framebuffers and renders video frames in
  a dedicated background thread. Qt Quick blits the latest completed
  frame whenever a new video frame is ready:

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

  Background thread:
    _render_fbo → _display_fbo: pointer swap after mpv completes rendering
  UI thread:
    _display_fbo → Qt Quick's FBO: blit when new frame signal arrives

  This allows the UI to remain responsive at the display's refresh rate
  while video frames render independently in the background at the
  content's native framerate.

Audio Delay Compensation:
The offscreen renderer presents video frames as they become available
rather than being tightly coupled to the display's vsync. This can
cause audio desynchronization as video frame presentation timing
differs from the legacy renderer.

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.

- 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
+
+if TYPE_CHECKING:
+    from PySide6.QtGui import QWindow
 
 
 @dataclass(frozen=True)
@@ -28,18 +35,28 @@ 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()
     def _invalidate_zoom_factor(self, *_) -> None:
@@ -48,8 +65,21 @@ def _invalidate_zoom_factor(self, *_) -> None:
             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():
@@ -67,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,6 +6,7 @@
 
 import logging
 import os
+import sys
 from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING
@@ -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 sys.platform == "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