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

[abrichr]

What was broken

openadapt-viewer catalog scan found zero recordings on a machine full of them.

The scanner globbed capture.db and queried a capture table and an events table. openadapt-capture PR #28 replaced that bespoke format on 2026-07-17 with a SQLAlchemy database named recording.db. Nothing the current recorder writes matched the glob.

Against the two recordings openadapt-capture commits under examples/captures, on main:

FOUND: 0 []
--- pointing it straight at a real recording directory ---
Warning: Could not read capture.db: no such table: capture
created_at= 1787888945.5  duration= None  frames= None  events= None  task= None  meta= {}

It was not a one-word fix

Renaming the glob would have registered directories with no date, no duration and no counts, which is the second line above. The formats share no table and no column:

pre-#28 capture.db	current recording.db
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

What changed

scanner.py reads the current schema:

• recording for the start timestamp, task description, platform and display geometry, matching what CaptureSession.load selects
• action_event rows for the event count, which is what events counted
• screenshot rows for the frame count, falling back to screenshots/*.png only when the database cannot answer
• the newest timestamp across the event tables for the duration, because there is no ended_at column

It reads with sqlite3 rather than importing CaptureSession. Indexing needs two row counts and a few scalars; installing openadapt-capture for them would pull mss, sounddevice, soundfile, matplotlib, sqlalchemy, alembic, numpy and the platform accessibility stack into an HTML generator. Anything that needs decoded frames should import CaptureSession instead of extending the scanner.

cli.py also fixes catalog register, which raised TypeError for every directory that got past the path check. Recording names the field id, register_recording takes recording_id, and TypeError is not in the except clause there, so the command ended in a traceback.

Legacy captures are not supported, on purpose

openadapt-capture's own scripts/migrate_legacy_capture.py says it plainly: "CaptureSession.load reads only recording.db. Legacy captures are therefore unloadable by current code." The migration exists, and screenshots.yml already reports a capture.db directory as unusable rather than missing.

So a legacy directory now prints the conversion command and is skipped, and _extract_recording_info raises rather than returning a shell:

Warning: /tmp/.../old-rec holds the legacy capture.db format, which the current
viewer cannot read. Convert it with openadapt-capture:
python scripts/migrate_legacy_capture.py <src> <dest>

A directory holding both is indexed from recording.db with no warning, so converting in place works.

Proof against the real recordings

Not a fixture written here. openadapt-viewer catalog scan --capture-dir <openadapt-capture>/examples/captures, then catalog list --json:

[
  {"id": "turn-off-nightshift", "created_at": 1767229200.0, "duration_seconds": 19.0,
   "frame_count": 20, "event_count": 20,
   "task_description": "Synthetic display-setting documentation fixture",
   "metadata": {"platform": "synthetic", "screen_width": 960, "screen_height": 540,
                "pixel_ratio": 1.0}},
  {"id": "demo_new", "created_at": 1767225600.0, "duration_seconds": 13.0,
   "frame_count": 14, "event_count": 14,
   "task_description": "Synthetic calculator documentation fixture",
   "metadata": {"platform": "synthetic", "screen_width": 960, "screen_height": 540,
                "pixel_ratio": 1.0}}
]

The counts match the table in that repository's examples/captures/README.md: 20 frames and 20 actions for turn-off-nightshift, 14 and 14 for demo_new.

Tests

tests/test_scanner_recording_db.py reads those two committed recordings. 17 of its 21 tests fail against the scanner on main and all 21 pass here. Every expectation is queried from the recording.db the scanner read, written out in the test rather than shared with the scanner, so it asserts the catalog reports what the file says.

test.yml now sparse-checks out openadapt-capture/examples/captures and points the suite at it, the way screenshots.yml already does. Without that the whole module would skip and verify nothing, so one test fails under GITHUB_ACTIONS when the recordings are absent. Tonight a PR with 197 passing tests shipped a real break because every test stubbed the boundary under test; a recording.db built here to match this repository's idea of the schema would have proved only that the reader agrees with the test author.

tests/test_screenshot_generation.py::test_captures_exist asserted on capture.db at the checkout root. Both halves were stale: the captures live under examples/captures, and the file is recording.db.

Not fixed here

viewers/benchmark/real_data_loader.py reads the same legacy schema. It also needs an episodes.json that no committed recording carries, so there is no real input to verify a fix against. Left alone rather than changed blind.

🤖 Generated with Claude Code

[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