Supported screen readers
voiceover macOS. Records to a .mov path through native video capture. nvda Windows. Records to an .mp4 path. virtual Not supported. The simulated screen reader has no window to capture. It produces a transcript instead. On macOS a11ied captures video only. It does not request microphone access, so the file has no audio track.
Record a session
Pass --recording with an output path when you start the session. The file
closes when you stop the session.
a1 sr start --sr voiceover --recording ./recordings/checkout.mov http://localhost:3000/checkout --json
a1 sr next --json
a1 sr checkpoint "submitted the form" --json
a1 sr transcript --json
a1 sr stop --json
The recording covers the whole session, so keep each session short and limited to one
behavior. Add sr checkpoint calls to mark the moments you want a reviewer to
look for.
Stopping writes the Markdown transcript next to the recording. For
./recordings/checkout.mov that file is
./recordings/checkout.transcript.md. It has an ISO timestamp per
announcement, so a reviewer can match what the screen reader said to the point in the
video.
macOS Screen Recording permission
macOS grants screen capture to the application that runs the command, not to a11ied. If you
run a1 from Terminal, Terminal needs the permission. If your editor or agent
runs it, that app needs it.
a1 doctor --task reader --sr voiceover --recording
On macOS, doctor --recording captures a temporary screen video with
screencapture for the app that ran it, to confirm the permission works, and
reports the result under the VoiceOver checks. Run it from the same app you plan to
test from.
Troubleshooting
a1 setup, which runs the Guidepup steps doctor lists under Action items and re-checks afterward. sr stop. The recorder finishes the file when the session stops. Privacy
A recording captures the screen, which includes the page content, the browser window, system menus, and anything else visible during the run. Use test data, not real accounts, and check the file before attaching it to a ticket.
A recording documents one run against one build. Record the route, the browser, the screen reader, and the file path with it, so a reviewer can tell later which build it shows.