fix(benchmark): read recording.db, the format the recorder writes

[abrichr]

load_real_capture_data opened <recording>/capture.db and ran SELECT * FROM capture LIMIT 1, then read started_at, ended_at, screen_width and screen_height. openadapt-capture PR #28 replaced that format on 2026-07-17. The current recorder writes recording.db, and the two schemas share no table and no column:

pre-#28	current
capture.started_at	recording.timestamp
capture.ended_at	gone; derive from the newest event
capture.screen_width / screen_height	recording.monitor_width / monitor_height
events	action_event
screenshots/*.png	screenshot rows holding png_data blobs

So the benchmark viewer raised FileNotFoundError on every recording anyone has made since. #17 fixed the same defect in the catalog scanner and left this file alone.

One reader, not two

src/openadapt_viewer/recording_db.py is new and owns the filename, the column names, the derived end time and the refusal to read a legacy capture. The scanner and the benchmark loader both read through it, so scanner.py loses about 90 lines and gains an import. A second translator living here would have put format knowledge in two places inside a repository that does not own the format.

Legacy support is absent on purpose. openadapt-capture ships scripts/migrate_legacy_capture.py and states that current code cannot load a legacy capture. A capture.db directory raises LegacyCaptureError carrying the conversion command, which is the same thing the scanner already prints.

The run's config gains frame_count, event_count and task_description, counted from the database. Those are what let a loaded run be checked against its source file rather than only against itself.

What the tests prove

tests/test_real_data_loader.py loads the two recordings openadapt-capture commits under examples/captures and asserts the values the loader reports, with every expectation queried here from the same file. CI already checks that repository out and sets $OPENADAPT_CAPTURE_EXAMPLES, so tests/capture_examples.py now holds the lookup that test_scanner_recording_db.py had inline.

Twenty of the twenty-one new tests fail on main. The one that passes asserts that an empty directory gains no recording.db, which was already true.

What the tests do not prove

The episodes half is not verified, and the test module says so in its own docstring rather than leaving a green run to imply otherwise.

load_real_capture_data also requires an episodes.json beside the recording. Neither committed recording carries one, and no producer writes the dialect this parser reads. The parser wants string steps, an episode_id like episode_001, and a screenshots.key_frames list. openadapt-ml's segmentation pipeline serialises EpisodeExtractionResult, whose steps are EpisodeStep objects, whose episode_id is a UUID, and which has no screenshots key at all. Writing a fixture to match the parser would only have proved that the parser agrees with whoever wrote the fixture, so the tests use test_episodes.json, which is already committed here, and assert against recording.db for everything that matters: start time, derived end time, duration, display geometry, platform, task description, frame count and event count.

That mismatch is a separate defect and is not fixed here. Guessing at a format with no sample in hand is how this one started.

Also

examples/capture.db is deleted. It is a zero-byte file, committed, named after the retired format, and read by nothing. sqlite3.connect creates a database at whatever path it is handed, which is how a file like that appears; both lookups in the new reader call is_file() before connecting.

[github-actions]

📸 Generated Screenshots Preview

Screenshots have been generated. Download the artifacts to preview them.

Generated Files:

• demo_new_controls.png (0.10 MB)
• demo_new_events.png (0.09 MB)
• demo_new_full.png (0.12 MB)
• turn-off-nightshift_controls.png (0.10 MB)
• turn-off-nightshift_events.png (0.10 MB)
• turn-off-nightshift_full.png (0.12 MB)

---

🔗 Download screenshots artifact