Play without the theatre surround if SteamVR refuses it

Review (SWE-2 Max): a non-standby error creating the cosmetic surround
at startup still ended playback before the screen appeared. Theatre now
logs it and plays without the surround. close() treats any per-overlay
teardown error as best effort (signals are already ignored there).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

docs/evidence/linux-vr/2026-09-29.txt

@@ -0,0 +1,29 @@
+Locked real-Frame repeat, 2026-09-29
+SteamOS 0.4.1, BUILD_ID 20260925.6191901; aarch64.
+mkdir /tmp/frame-test.lock succeeded before installs/launches; rmdir issued after cleanup.
+Preflight battery 44%, charging; before WiVRn 46%, before ALVR 47%, cleanup 47%.
+Original Steam PID 49823 and vrserver PID 49571 present after cleanup.
+Same unmodified upstream release APKs and SHA-256s as 2026-09-28.txt.
+Installer functions loaded from a613735 before checkout was fast-forwarded to current main.
+No compatibility layer injected. Per-app immersive Lepton instances, Steam shortcut launches.
+Headset unworn. No Linux gaming host. No pairing or streaming session reached.
+
+WIVRN: selected journal lines (local +1000 prefix, Android timestamps UTC).
+Sep 29 11:03:15 frame lepton-steamlaunch-2817846116[1967]: 09-29 01:03:15.202  1153  1181 E OpenXR-Loader: Error [GENERAL | xrCreateInstance | OpenXR-Loader] : LoaderInstance::CreateInstance, no support found for requested extension: XR_KHR_convert_timespec_time
+Sep 29 11:03:15 frame lepton-steamlaunch-2817846116[1967]: 09-29 01:03:15.210  1153  1181 I WiVRn   : [2026-09-29 01:03:15.210] [WiVRn] [info] Failed to create OpenXR instance version 1.1.58: XR_ERROR_EXTENSION_NOT_PRESENT
+Sep 29 11:03:15 frame lepton-steamlaunch-2817846116[1967]: 09-29 01:03:15.248  1153  1181 E OpenXR-Loader: Error [GENERAL | xrCreateInstance | OpenXR-Loader] : LoaderInstance::CreateInstance, no support found for requested extension: XR_KHR_convert_timespec_time
+Sep 29 11:03:15 frame lepton-steamlaunch-2817846116[1967]: 09-29 01:03:15.256  1153  1181 I WiVRn   : [2026-09-29 01:03:15.256] [WiVRn] [info] Failed to create OpenXR instance version 1.0.58: XR_ERROR_EXTENSION_NOT_PRESENT
+Sep 29 11:03:15 frame lepton-steamlaunch-2817846116[1967]: 09-29 01:03:15.257  1153  1181 E WiVRn   : [2026-09-29 01:03:15.257] [WiVRn] [error] Error during initialization: Failed to create OpenXR instance: XR_ERROR_EXTENSION_NOT_PRESENT
+Screenshot API exit 0; 1920x1080 uniformly dark image; no client scene visible.
+
+ALVR: selected journal lines (local +1000 prefix, Android timestamps UTC).
+Sep 29 11:03:36 frame lepton-steamlaunch-2831623938[1967]: 09-29 01:03:35.553  1139  1167 E OpenXR-Loader: Error [GENERAL | xrCreateInstance | OpenXR-Loader] : LoaderInstance::CreateInstance, no support found for requested extension: XR_KHR_convert_timespec_time
+Sep 29 11:03:36 frame lepton-steamlaunch-2831623938[1967]: 09-29 01:03:35.553  1139  1165 I RustStdoutStderr: Error [GENERAL | xrCreateInstance | OpenXR-Loader] : LoaderInstance::CreateInstance, no support found for requested extension: XR_KHR_convert_timespec_time
+Sep 29 11:03:36 frame lepton-steamlaunch-2831623938[1967]: 09-29 01:03:35.611  1139  1167 E [ALVR NATIVE-RUST]: panicked at alvr/client_openxr/src/lib.rs:220:10:
+Sep 29 11:03:36 frame lepton-steamlaunch-2831623938[1967]: 09-29 01:03:35.611  1139  1167 E [ALVR NATIVE-RUST]: called `Result::unwrap()` on an `Err` value: ERROR_EXTENSION_NOT_PRESENT
+Screenshot API exit 0; 1920x1080 uniformly dark image; no client scene visible.
+
+Cleanup: both test app directories, compatdata, shadercache, containers and shortcuts absent.
+Capture output directory removed. No global settings changed; Steam/SteamVR not stopped.
+The shared lock was subsequently acquired by another thread (new directory timestamp 11:03:49 +1000).
+Native clients and Valve host streaming not exercised: no native build or Linux gaming host available.

docs/linux-vr-streaming.md

@@ -38,6 +38,33 @@ after its container exited. No headset was worn and no host was connected.
 All test app files, compatdata, shortcuts and containers were removed afterwards.
 SteamVR's original process remained running. No global settings changed.
 
+### Locked repeat, 2026-09-29 (verified)
+
+Acquired `/tmp/frame-test.lock` before installing or launching anything and
+released it after cleanup. Battery was 44% and charging at preflight, 46–47%
+during the launches, and 47% at cleanup. The SteamOS version/build was unchanged.
+
+Reinstalled and launched both original APKs in immersive Lepton instances.
+WiVRn again failed at OpenXR 1.1 and 1.0 with the missing timespec extension;
+ALVR again panicked on `ERROR_EXTENSION_NOT_PRESENT`. This repeats the
+unmodified-client test, not the newer installer's automatic compatibility-layer
+path. Neither reached a session that could be paired or exercised further.
+Fresh [journal excerpts and cleanup evidence](evidence/linux-vr/2026-09-29.txt)
+record the failures.
+
+SteamVR's screenshot API returned a 1920×1080 headset capture after each
+launch. Both are uniformly dark: [WiVRn](evidence/linux-vr/2026-09-29-wivrn.png)
+and [ALVR](evidence/linux-vr/2026-09-29-alvr.png). These images do **not** prove
+rendering or a working client. The headset was unworn; visibility, controllers,
+frame rate and motion-to-photon latency could not be judged. The explicit
+OpenXR errors, rather than the dark captures, establish the client blocker.
+
+Both test installs, app data, shader caches, shortcuts, containers and temporary
+capture files were removed. The original Steam and SteamVR process IDs were
+unchanged. No reboot, power action or global setting change was used. Native
+clients remain untested, and no Linux gaming host was available for Valve's
+streaming path. The recommendation below is unchanged.
+
 ### Relation to the VR APK branch
 
 **Documented from source:** [PR #20](https://github.com/saphid/frame-control/pull/20)

tests/test_media.py

@@ -81,8 +81,12 @@ class Media(unittest.TestCase):
             write_status(path, **values)
 
         class FakeOverlay:
+            created = 0
+
             def create(self, *a, **k):
-                return len(calls)
+                # Handles in creation order: surround 0, then screen 1 (theatre).
+                FakeOverlay.created += 1
+                return FakeOverlay.created - 1
 
             def call(self, *a):
                 pass
@@ -131,6 +135,13 @@ class Media(unittest.TestCase):
         self.assertEqual(result['dropped'], 2)
         self.assertIn((0, 1, 1), calls[3:])
 
+    def test_theatre_surround_failure_does_not_stop_playback(self):
+        def fail_surround(n):
+            if n == 1:  # the surround's upload is the first pixels call
+                raise RuntimeError('OpenVR SetOverlayRaw failed: 11')
+        result, _ = self.play_with('clip_SBS.mp4', on_pixels=fail_surround)
+        self.assertEqual((result['state'], result['frames']), ('ended', 4))
+
     def test_stop_mid_video_reports_stopped(self):
         result, _ = self.play_with('clip_SBS.mp4', on_pixels=lambda n: n == 3 and stop_now())
         self.assertEqual(result['state'], 'stopped')

ui/frame_media_player.py

@@ -88,12 +88,14 @@ class Overlay:
     def close(self):
         # Best effort: SteamVR removes a disconnected client's overlays anyway,
         # and a teardown error must not overwrite a finished playback's status.
-        for h in reversed(self.handles):
-            try:
-                self.call('DestroyOverlay', h)
-            except RuntimeError:
-                pass
-        self.vr.VR_ShutdownInternal()
+        try:
+            for h in reversed(self.handles):
+                try:
+                    self.call('DestroyOverlay', h)
+                except Exception:  # signals are already ignored here, so Stop isn't lost
+                    pass
+        finally:
+            self.vr.VR_ShutdownInternal()
 
 
 def probe(path):
@@ -183,6 +185,8 @@ def play(args):
             except OverlayBusy:
                 pending.insert(0, item)
                 return
+            except RuntimeError:
+                pass  # the surround is cosmetic; never end playback over it
 
     def hold(handle, data, w, h):
         """Keep a still (photo or splat) up until Stop, retrying through standby."""
@@ -203,10 +207,14 @@ def play(args):
     try:
         vr = Overlay()
         if args.theatre:
-            surround = vr.create('framecontrol.media.surround', 40, 4, order=0)
-            vr.call('SetOverlayAlpha', surround, .85)
-            if not show(surround, b'\x00\x00\x00\xff', 1, 1):
-                pending.append((surround, b'\x00\x00\x00\xff', 1, 1))
+            try:
+                surround = vr.create('framecontrol.media.surround', 40, 4, order=0)
+                vr.call('SetOverlayAlpha', surround, .85)
+                if not show(surround, b'\x00\x00\x00\xff', 1, 1):
+                    pending.append((surround, b'\x00\x00\x00\xff', 1, 1))
+            except RuntimeError as e:
+                # Cosmetic: play without the dark surround rather than not at all.
+                print('Theatre surround unavailable: %s' % e, flush=True)
         screen = vr.create('framecontrol.media.screen', 3 if args.theatre else 1.6, 2,
                            plan['layout'] != 'mono', aspect)
         if splat: