feat(linux)!: decouple video rendering from UI thread

Replace the direct renderer with a threaded offscreen renderer that
decouples video rendering from UI rendering to improve UI
responsiveness.

Updated Video Rendering:
- Windows: unchanged - mpvQC uses winId/HWND embedding as before
- Linux: threaded offscreen renderer (replaces direct rendering)

Technical Implementation:
The new renderer uses double-buffered framebuffers with rendering in a
dedicated background thread. The UI thread blits the latest completed
frame during its render operations:

  ┌─────┐     ┌────────┐     ┌─────────┐     ┌────────┐     ┌────────┐
  │ mpv │  →  │ render │  →  │ display │  →  │   Qt   │  →  │ screen │
  │     │     │  fbo   │     │   fbo   │     │  fbo   │     │        │
  └─────┘     └────────┘     └─────────┘     └────────┘     └────────┘
                   └─ pointer swap ─┘             │
  └────────── Background thread ──────────┘       │
                                                  │
                                    └── UI thread ┘
                                          blit

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

Audio Delay Compensation:
The double-buffered design introduces variable latency as frames wait
in display fbo for the next Qt render cycle. Assuming Qt processes
the render request on the next vsync cycle, frames wait on average
half a display frame period before being blitted to screen.

  ┌─────────────────────────────────────────────────────────────────┐
  │ Consider a 60Hz display (16.67ms frame time):                   │
  │                                                                 │
  │   Display vsync:  |                                 |           │
  │   Time (ms):      0                                16.67        │
  │                                                                 │
  │   Frame arrives at t=5ms:                                       │
  │                   |         F                       |           │
  │                             ←------11.67ms wait-----→           │
  │                                                                 │
  │   Frame arrives at t=12ms:                                      │
  │                   |                       F         |           │
  │                                           ←-4.67ms--→           │
  │                                                                 │
  │   Average wait = 16.67ms / 2 ≈ 8.33ms                           │
  └─────────────────────────────────────────────────────────────────┘

To compensate, mpvQC automatically adjusts mpv's audio delay to half
the current monitor's frame time: (1 / refresh_rate) / 2. This value
updates dynamically when the window moves to a different monitor or
when the refresh rate changes.

  60Hz:  8.33ms
  120Hz: 4.17ms
  144Hz: 3.47ms
  240Hz: 2.08ms
  360Hz: 1.39ms

BREAKING CHANGE: Linux users must update their mpv.conf via Options ->
Edit mpv.conf by either restoring default values or removing the
video-timing-offset option. The new renderer handles timing
automatically through audio delay compensation.

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
 

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":
+            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,15 @@ 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 <= 0:
+            return
+
+        audio_delay = (1 / new_refresh_rate) / 2
+        logger.info("Setting mpv audio-delay to %.4f sec for %.2f Hz", audio_delay, new_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,6 +17,8 @@ def perform_startup():
 
 
 def configure_qt_application_data():
+    import platform
+
     from PySide6.QtCore import QCoreApplication
 
     from mpvqc.build import get_build_info
@@ -27,6 +29,11 @@ def configure_qt_application_data():
     QCoreApplication.setOrganizationDomain(app.domain)
     QCoreApplication.setApplicationVersion(app.version)
 
+    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,12 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 
 # ruff: noqa: F401
-from .player_framebuffer_object import MpvqcMpvFrameBufferObjectPyObject
-from .player_win_id import MpvWindowPyObject
+import logging
+import platform
+
+logger = logging.getLogger(__name__)
+
+if platform.system() == "Windows":
+    from .player_win_id import MpvWindowPyObject
+else:
+    from .player_framebuffer_object_offscreen import MpvqcMpvFrameBufferObjectPyObject