Bump Frame Control to 0.4.21 (#173)

Co-authored-by: SAPHID <saphid@users.noreply.github.com>

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+- Add a source-checkout helper that sends the Frame's SteamVR mirror and
+  default-output audio to a local OBS Media Source. A real Frame supplied a
+  4.021-second H.264/AAC stream to a Linux receiver; OBS playback and sync
+  remain unverified. [Setup and limits](docs/obs-headset-source.md).
+
+- Link emulator setup guidance from Store → Emulators. Existing Steam library
+  shortcuts and artwork cover Android apps and sideloaded titles; Android ROM
+  transfer still needs a verified per-instance workflow.
+  [Guide](docs/emulators.md).
+
+- Record the current Frame OS mirror and charge-limit checks. Active
+  passthrough in the mirror is still unknown; this build has no supported
+  user-writable 80% charge-limit control.
+  [Headset evidence](docs/evidence/round3-headset-2026-10-25.md).
+
 - Add Windows Tools → Wireless Adapter doctor: an explicit read-only PC snapshot
   of distinct Wi-Fi Direct PnP instances, presence/link state, PC Wi-Fi and
   reported channels/bands, with possible 2.4 GHz overlap guidance. Unknowns stay

app/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "frame-control",
-  "version": "0.4.20",
+  "version": "0.4.21",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "frame-control",
-      "version": "0.4.20",
+      "version": "0.4.21",
       "license": "MIT",
       "devDependencies": {
         "electron": "^44.4.5",

app/package.json

@@ -1,7 +1,7 @@
 {
   "name": "frame-control",
   "productName": "Frame Control",
-  "version": "0.4.20",
+  "version": "0.4.21",
   "description": "Desktop app for managing a Valve Steam Frame over SSH",
   "private": true,
   "main": "main.js",

docs/charge-limit.md

@@ -9,6 +9,11 @@ only control the Frame has is a vendor charger attribute that Valve's own
 charging daemon also manages. Research as of 2026-10-23, confirmed with the
 read-only checks below on a Frame running SteamOS 0.5.6 (build 20261015.6141207):
 
+Rechecked read-only on build `20261022.6153909` on 2026-10-25: the
+`BatteryChargeLimit1` interface still returned `UnknownInterface`, no
+`charge_control_*` sysfs attribute existed, and the vendor charging switches
+were root-owned mode `644`. See [Round 3 headset evidence](evidence/round3-headset-2026-10-25.md).
+
 - `steamosctl get-max-charge-level` fails with `UnknownInterface: ...BatteryChargeLimit1`.
 - `/usr/share/steamos-manager/devices/` has `[battery_charge_limit]` only for
   the Steam Deck, ROG Ally, ROG Xbox Ally and MSI Claw, not the Frame.

docs/emulators.md

@@ -0,0 +1,54 @@
+# Emulators and your own games
+
+Frame Control's **Store → Emulators** lists Android emulators from its open
+app sources. Pick an app, read its compatibility result, and install it. An
+installed Android app gets its own Steam library shortcut and artwork; **Add
+artwork** in its library menu can fill missing images later. The artwork
+workflow also covers native Linux and Windows titles added through **Send to
+Frame**. An optional SteamGridDB key under **Settings → Library artwork**
+can supply exact-title community images; source images and generated art are
+fallbacks. See [VR APKs → In the Steam library](vr-apks.md#in-the-steam-library)
+for the limits and tested behavior.
+
+## Set up an emulator
+
+1. In **Store → Emulators**, choose an emulator that supports the console and
+   file format you want. Check its compatibility result before installing;
+   an app listed in the store is not automatically verified on the Frame.
+2. Launch the new shortcut from Steam. Open the emulator's own settings to
+   choose a gamepad layout, core or system, and game folder. These controls
+   differ by emulator; Frame Control does not change them.
+3. Use game files you own and any firmware that emulator's instructions
+   require. Frame Control does not provide ROMs or firmware.
+
+**Android apps run in separate Lepton instances.** Copying a ROM to the
+Frame's Linux `~/Downloads` through **Send to Frame** does not automatically
+put it in an Android app's `/sdcard/Download`. A one-click ROM transfer is
+deferred until an emulator and its file picker can be tested end to end on a
+real Frame. An app's own import or sync feature may be enough. Advanced users
+can use [Lepton's per-instance ADB port](apks.md)
+to copy into that instance, after confirming the correct container and port.
+Do not assume that port 5555 is the emulator: it is Lepton Development, while
+installed apps receive their own ports.
+
+For a native Linux emulator that can read the Frame's home directory, use
+**Send to Frame → Copy to ~/Downloads instead** for your files, then open them
+from the emulator. Whether a particular emulator has a Frame-compatible ARM64
+build, correct controller mapping and readable storage must be checked for
+that app. **Linux apps** in Frame Control lists Flatpak options; a Windows or
+native game archive can instead be added through
+[Send to Frame](sideloading.md#using-it), which registers a Steam title and
+artwork. Each ROM is usually opened *inside* its emulator; Frame Control does
+not create one Steam shortcut per ROM.
+
+## If something does not appear
+
+- Check that the emulator is running and is the same app instance to which
+  you sent the file. Android instances do not share `/sdcard` storage.
+- Check the emulator's supported extension and whether it expects an archive
+  or an extracted file. Some systems need firmware before games appear.
+- For an empty Steam tile, use **Add artwork** in the installed app or
+  sideloaded title menu. This changes artwork, not emulator data or ROMs.
+
+The Frame's microSD/USB path into Android apps remains unverified without an
+inserted medium and an app readback test; see [issue #169](https://github.com/saphid/frame-control/issues/169).

docs/evidence/round3-headset-2026-10-25.md

@@ -0,0 +1,19 @@
+# Round 3 headset checks, 25 October 2026
+
+These checks used the real Frame after the device hold ended. SteamOS was
+0.5.6, build `20261022.6153909`. Each device session acquired
+`/tmp/frame-test.lock` atomically and released only its own lock. The battery
+read 100% and Full in the first check and after the OBS session; Steam and
+SteamVR were left running.
+
+| Question | Observation | Conclusion |
+|---|---|---|
+| Does active passthrough appear in SteamVR's `/dev/video99` mirror? | The mirror service was active. One 1920×1080 RGB frame read from `/dev/video99` had a single pixel value, `(24, 28, 53)`, throughout. The headset was unworn; no active passthrough session or wearer-visible room view was established. Frame Control has no verified remote passthrough toggle. The temporary frame was removed. | **Still unknown.** A uniform standby frame cannot answer whether SteamVR composites active passthrough into its mirror. No headset setting was changed. |
+| Can Frame Control prompt when a headset text box opens? | No desktop `plasmashell` process was running during this check. There is no verified cross-app focus event from SteamVR, Lepton and the nested desktop; KDE Connect's `keyboardstate` packet describes keyboard support, not a focused text field. | **Not built.** A prompt triggered by an unverified signal would be misleading. The existing **Type on the headset** control remains available. |
+| Does reverse clipboard exist? | Frame Control already has **Copy the headset's clipboard here**. Its earlier real Frame test used a temporary nested desktop and confirmed that text copied through Klipper reached a Linux PC clipboard. No desktop panel was open during this session, so it was not rerun here. | **Shipped and previously verified**, text only. Windows/macOS backends and arbitrary headset apps remain unverified on a real Frame. |
+| Is an 80% charge limit available and writable? | `steamosctl get-max-charge-level` returned `UnknownInterface: ...BatteryChargeLimit1`. No `charge_control_*` attribute was found under `/sys/class/power_supply`. Only `pm8550b-charger/charging_pause` and `charging_enable` were present, each mode `644`, owner `root:root`. | **No supported user-writable control.** No battery attribute was written. |
+
+The separate OBS transport check on the same build sent the mirror and the
+default-output monitor to a Linux PC. A 4.021-second temporary capture had
+H.264 video and AAC audio according to `ffprobe`. It was removed; OBS itself
+and audible playback were not tested. See the OBS source PR and guide.

docs/obs-headset-source.md

@@ -0,0 +1,38 @@
+# Headset view in OBS
+
+Frame Control can send SteamVR's headset mirror and the Frame's output audio to
+OBS on a Linux or macOS computer. The helper uses the same `/dev/video99` video
+source and default-output monitor as **Capture & Live → Record**. It sends a
+local MPEG-TS stream; no port is opened to the LAN or internet.
+
+1. Connect to the Frame with `ssh frame` and start SteamVR. Install `python3`
+   on the computer; the Frame already has `ffmpeg`. OBS runs on the computer.
+2. From this repository, run:
+
+   ```sh
+   python3 scripts/obs-headset-source.py
+   ```
+
+3. In OBS, add a **Media Source**, clear **Local File**, set **Input** to
+   `udp://127.0.0.1:15099`, and set **Input Format** to `mpegts`. The source
+   carries video and AAC audio. Use OBS's audio mixer to choose monitoring and
+   recording levels. Leave the helper running while the source is in use;
+   Ctrl+C stops it.
+
+`--height 1080 --fps 60` increases quality and Frame CPU use. The default is
+720p30. `--port 15100` selects another loopback port; use the same port in
+OBS. If the Frame's PulseAudio monitor cannot be read, the helper exits with
+an error. Use `--no-audio` only when a silent view is useful. To inspect the
+stream without OBS, run `ffprobe -v error -show_streams
+udp://127.0.0.1:15099` in a second terminal while the helper is running.
+
+This is the composited, undistorted one-eye **SteamVR mirror**, not a raw
+passthrough camera feed. The mirror may be blank when the headset is idle or
+unworn. Whether active passthrough pixels appear in it is still unverified.
+The helper does not send a microphone. It is designed for one local OBS
+receiver. **Verified 2026-10-24:** against a real Frame running SteamOS 0.5.6,
+build 20261022.6153909, the receiver saved a 4.021-second MPEG-TS sample on
+the Linux PC; `ffprobe` found H.264 video and AAC audio. The temporary sample
+was removed. The headset was unworn, so visible content and audible sound were
+not checked. OBS itself was not installed on that PC; its Media Source setup,
+monitoring and sync are still unverified.

docs/recording.md

@@ -1,5 +1,8 @@
 # Recording and Steam clips
 
+For a live OBS Media Source with headset output audio, see
+[Headset view in OBS](obs-headset-source.md).
+
 Frame Control can record SteamVR's mirrored headset view, with its sound, and save it as
 an `.mp4` on your computer. It can also export the clips and background
 recordings from Steam's own game recording, at any length, as one `.mp4` each.

scripts/obs-headset-source.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""Send the Frame's SteamVR mirror and output audio to a local OBS Media Source.
+
+OBS opens udp://127.0.0.1:15099 with input format mpegts. Nothing is bound to
+the network: this process sends MPEG-TS packets to the computer's loopback.
+"""
+import argparse
+import shlex
+import signal
+import socket
+import subprocess
+import sys
+
+
+PACKET = 188
+DATAGRAM = PACKET * 7
+
+
+def remote_command(height=720, fps=30, audio=True):
+    if height not in (720, 1080) or fps not in (30, 60):
+        raise ValueError('height must be 720 or 1080; fps must be 30 or 60')
+    rate = 3 if height == 720 else 6
+    clock = '-thread_queue_size 1024 -use_wallclock_as_timestamps 1'
+    video = f'{clock} -f v4l2 -video_size 1920x1080 -i /dev/video99'
+    sound = f' {clock} -f pulse -i @DEFAULT_MONITOR@' if audio else ''
+    maps = '-map 0:v:0 -map 1:a:0' if audio else '-map 0:v:0'
+    encode = (f'-vf fps={fps},scale=-2:{height},format=yuv420p '
+              f'-c:v libx264 -preset ultrafast -tune zerolatency -g {fps * 2} -bf 0 '
+              f'-b:v {rate}M -maxrate {rate}M -bufsize {rate}M '
+              '-x264-params repeat-headers=1')
+    if audio:
+        encode += ' -af aresample=async=1 -c:a aac -b:a 160k'
+    return ("export XDG_RUNTIME_DIR=${XDG_RUNTIME_DIR:-/run/user/$(id -u)}; "
+            "test -e /dev/video99 || { echo 'SteamVR mirror /dev/video99 is missing' >&2; exit 3; }; "
+            f'ffmpeg -hide_banner -loglevel warning -nostdin {video}{sound} '
+            f'{maps} {encode} -f mpegts -flush_packets 1 -')
+
+
+def relay(source, destination):
+    """Preserve 188-byte MPEG-TS packet boundaries in loopback datagrams."""
+    pending = bytearray()
+    total = 0
+    while data := source.read(DATAGRAM):
+        pending.extend(data)
+        size = min(len(pending) // PACKET * PACKET, DATAGRAM)
+        if size:
+            destination.send(bytes(pending[:size]))
+            del pending[:size]
+            total += size
+    if pending:
+        raise RuntimeError('Frame stream ended with an incomplete MPEG-TS packet')
+    return total
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--frame', default='frame', help='SSH host or alias (default: frame)')
+    parser.add_argument('--port', type=int, default=15099, help='local OBS UDP port (default: 15099)')
+    parser.add_argument('--height', type=int, choices=(720, 1080), default=720)
+    parser.add_argument('--fps', type=int, choices=(30, 60), default=30)
+    parser.add_argument('--no-audio', action='store_true', help='video only when the Frame audio monitor is unavailable')
+    args = parser.parse_args(argv)
+    if not 1024 <= args.port <= 65535:
+        parser.error('port must be between 1024 and 65535')
+    if not args.frame or args.frame.startswith('-') or any(c.isspace() for c in args.frame):
+        parser.error('frame must be one SSH host or alias')
+    command = remote_command(args.height, args.fps, not args.no_audio)
+    ssh = ['ssh', '-T', '-o', 'BatchMode=yes', args.frame, 'bash', '-lc', shlex.quote(command)]
+    target = ('127.0.0.1', args.port)
+    print(f'Sending Frame view to udp://127.0.0.1:{args.port} for OBS; press Ctrl+C to stop.', file=sys.stderr)
+    signal.signal(signal.SIGTERM, lambda *_: sys.exit(0))
+    with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as udp:
+        proc = subprocess.Popen(ssh, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE)
+        try:
+            amount = relay(proc.stdout, _Sender(udp, target))
+            code = proc.wait(timeout=10)
+            if code or not amount:
+                raise RuntimeError(f'Frame stream stopped (SSH exit {code}; {amount} bytes). '
+                                   'Check SteamVR and the audio monitor; try --no-audio if needed.')
+            return 0
+        except KeyboardInterrupt:
+            return 0
+        finally:
+            proc.stdout.close()
+            if proc.poll() is None:
+                proc.terminate()
+                try:
+                    proc.wait(timeout=5)
+                except subprocess.TimeoutExpired:
+                    proc.kill()
+                    proc.wait()
+
+
+class _Sender:
+    def __init__(self, sock, target):
+        self.sock, self.target = sock, target
+
+    def send(self, data):
+        self.sock.sendto(data, self.target)
+
+
+if __name__ == '__main__':
+    try:
+        sys.exit(main())
+    except (OSError, RuntimeError) as error:
+        print(error, file=sys.stderr)
+        sys.exit(1)

tests/test_obs_headset_source.py

@@ -0,0 +1,45 @@
+"""The OBS relay must preserve transport packets and keep its output local."""
+import importlib.util
+import io
+from pathlib import Path
+import unittest
+
+
+SCRIPT = Path(__file__).resolve().parents[1] / 'scripts' / 'obs-headset-source.py'
+spec = importlib.util.spec_from_file_location('obs_headset_source', SCRIPT)
+obs = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(obs)
+
+
+class Receiver:
+    def __init__(self):
+        self.chunks = []
+
+    def send(self, data):
+        self.chunks.append(data)
+
+
+class ObsSourceTests(unittest.TestCase):
+    def test_relay_keeps_whole_transport_packets(self):
+        stream = bytes(range(188)) * 101
+        receiver = Receiver()
+        self.assertEqual(obs.relay(io.BytesIO(stream), receiver), len(stream))
+        self.assertEqual(b''.join(receiver.chunks), stream)
+        self.assertTrue(all(len(chunk) % 188 == 0 and len(chunk) <= 1316
+                            for chunk in receiver.chunks))
+
+    def test_incomplete_packet_fails(self):
+        with self.assertRaisesRegex(RuntimeError, 'incomplete'):
+            obs.relay(io.BytesIO(b'x' * 189), Receiver())
+
+    def test_remote_command_uses_recording_sources(self):
+        with_audio = obs.remote_command()
+        self.assertIn('/dev/video99', with_audio)
+        self.assertIn('@DEFAULT_MONITOR@', with_audio)
+        self.assertIn('-map 1:a:0', with_audio)
+        self.assertIn('-f mpegts', with_audio)
+        self.assertNotIn('@DEFAULT_MONITOR@', obs.remote_command(audio=False))
+
+
+if __name__ == '__main__':
+    unittest.main()

ui/index.html

@@ -1240,6 +1240,7 @@
       </div>
       <div class="hint" id="recStatus" role="status" hidden></div>
       <div class="hint" id="viewHint"></div>
+      <p class="sub"><a href="https://github.com/saphid/frame-control/blob/main/docs/obs-headset-source.md" target="_blank" rel="noopener noreferrer">Use the headset view and sound in OBS →</a></p>
     </section>
 
 
@@ -4388,7 +4389,7 @@ function renderCats() {
   $("storeCats").querySelectorAll("[data-cat]").forEach(b => b.setAttribute("aria-pressed", String(b.dataset.cat === sourceState.category)));
   const [, label, eyebrow, blurb] = storeCat(sourceState.category);
   $("storeHeading").hidden = !sourceState.category;
-  $("storeHeading").innerHTML = `<div class="store-eyebrow">${esc(sourceState.category ? eyebrow : "Android apps for your Frame")}</div><h1>${esc(sourceState.category ? label : "Apps & VR")}</h1><p>${esc(blurb)}</p>`;
+  $("storeHeading").innerHTML = `<div class="store-eyebrow">${esc(sourceState.category ? eyebrow : "Android apps for your Frame")}</div><h1>${esc(sourceState.category ? label : "Apps & VR")}</h1><p>${esc(blurb)}</p>${sourceState.category === "emulators" ? '<p><a href="https://github.com/saphid/frame-control/blob/main/docs/emulators.md" target="_blank" rel="noopener noreferrer">Set up an emulator and your own games →</a></p>' : ""}`;
 }
 function renderStore() {
   const apps=sourceState.apps, q=$("sourceQ").value.trim(), browsing=!q && !sourceState.category && !sourceState.installable && !sourceState.source;