Validate frame-accurate seeking with python-mpv (build order step 1)

Confirms single-frame stepping is reliable: monotonic frame counter
across steps, and the synthetic clip's 1-frame flash event lands on
exactly one frame with clean neighbors. Also documents/works around
three environment quirks hit along the way: locally-built libmpv not
in ldconfig's cache, QApplication resetting LC_NUMERIC and breaking
libmpv's locale requirement, and the playback-restart event not firing
reliably after frame-step (switched to polling estimated_frame_number).

player_widget.py

@@ -0,0 +1,110 @@
+import locale
+import os
+import time
+
+# The dev machine has a locally-built libmpv in /usr/local/lib that isn't
+# registered with ldconfig. LD_LIBRARY_PATH must be set in the environment
+# *before this process starts* (dlopen reads it at exec time) -- see run
+# scripts / README for the wrapper that does this.
+
+import mpv
+from PyQt6.QtWidgets import QWidget
+from PyQt6.QtCore import Qt
+
+
+class PlayerWidget(QWidget):
+    """Embeds an mpv render surface in a Qt widget.
+
+    Frame-accurate seeking relies on mpv's hr-seek (decode-and-discard to the
+    exact target instead of snapping to the nearest keyframe), which is why
+    this exists instead of a QMediaPlayer/HTML5-video-style backend.
+    """
+
+    def __init__(self, parent=None):
+        super().__init__(parent)
+        self.setAttribute(Qt.WidgetAttribute.WA_DontCreateNativeAncestors)
+        self.setAttribute(Qt.WidgetAttribute.WA_NativeWindow)
+
+        # QApplication resets LC_NUMERIC to the system locale on construction,
+        # which undoes python-mpv's own import-time fix and makes libmpv abort
+        # with "Non-C locale detected" -- reset it again right before libmpv
+        # actually gets instantiated.
+        locale.setlocale(locale.LC_NUMERIC, "C")
+
+        self.mpv = mpv.MPV(
+            wid=str(int(self.winId())),
+            vo="gpu",
+            hr_seek="yes",
+            hr_seek_framedrop="no",
+            keep_open="yes",
+            pause=True,
+        )
+        self._fps = None
+
+    def load(self, path: str):
+        # NOTE: we start the MPV instance with pause=True, so `core-idle`
+        # never flips to False and mpv.wait_until_playing() would block
+        # forever. Wait for `duration` to populate instead, which happens
+        # once the file is loaded regardless of pause state.
+        self.mpv.play(path)
+        self.mpv.wait_for_property("duration", timeout=10)
+        self.mpv.pause = True
+        self._fps = self.mpv.container_fps or self.mpv.estimated_vf_fps
+
+    def play(self):
+        self.mpv.pause = False
+
+    def pause(self):
+        self.mpv.pause = True
+
+    def seek(self, seconds: float):
+        before = self.mpv.estimated_frame_number
+        self.mpv.seek(seconds, reference="absolute", precision="exact")
+        self._wait_for_frame_change(before)
+
+    def step_frame(self, n: int = 1):
+        # frame-step is async: the command returns immediately and the
+        # actual decode/seek happens on mpv's internal thread. Without
+        # waiting for confirmation, rapid-fire commands get coalesced or
+        # dropped (observed: some steps silently no-op, others jump 2-3
+        # frames at once when driven by a fixed sleep guess).
+        #
+        # `playback-restart` -- the event mpv's own docs point to for this --
+        # turned out to never fire with our vo=gpu Qt-embedded surface (nor
+        # with vo=null in an isolated test), even though the underlying
+        # decode/seek completes correctly and quickly. So instead we poll
+        # `estimated_frame_number` directly until it changes, which was
+        # confirmed reliable in isolated testing (see scripts/mpv_bare_test.py).
+        cmd = "frame-step" if n >= 0 else "frame-back-step"
+        for _ in range(abs(n)):
+            before = self.mpv.estimated_frame_number
+            self.mpv.command(cmd)
+            self._wait_for_frame_change(before)
+
+    def _wait_for_frame_change(self, before, timeout=1.0):
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            current = self.mpv.estimated_frame_number
+            if current is not None and current != before:
+                return
+            time.sleep(0.005)
+
+    def get_position(self) -> float:
+        return self.mpv.time_pos or 0.0
+
+    def get_estimated_frame(self) -> int:
+        return self.mpv.estimated_frame_number or 0
+
+    def fps(self) -> float:
+        return self._fps or 0.0
+
+    def screenshot(self, path: str):
+        # `estimated_frame_number` updates as soon as the demuxer/decoder
+        # reports the new position, slightly ahead of the vo=gpu surface
+        # actually finishing its render -- give it a couple frames' worth
+        # of slack so the screenshot doesn't grab the previous frame.
+        time.sleep(0.05)
+        self.mpv.screenshot_to_file(path, includes="video")
+
+    def shutdown(self):
+        self.mpv.terminate()