DEV Community: Joy

I Recorded a Screen-Reader Walkthrough, Then Used Audio to Text to File the Issues

Joy — Fri, 13 Nov 2026 14:22:13 +0000

I do accessibility reviews for our own product, not as a specialist hired from outside, but as the engineer who was willing to keep a checklist and a copy of a screen reader on their laptop. For a long time my review notes were a mess of screenshots and half sentences I had typed with one hand while listening with both ears. I would hear a problem, reach for the keyboard, lose my place in the page, and then write “button, somewhere near checkout, unclear” — which is a terrible ticket. In May I started recording the walkthrough as I spoke, and I ran audio to text afterward so the ticket could quote the moment I was actually in, not the moment I thought I had been in. This is that workflow, including the parts that did not work.

I only record my own voice, plus the screen reader’s output if it is coming through the same headphones I have looped back on purpose. I do not record teammates who happen to be in the room, and I do not record users. If someone sits in on a review, the recorder stays off unless they agree, and even then I prefer they not sit in. This is a private engineering artifact, not a research session.

The walkthrough I actually run

I use the same route every time, because a random wander makes a worse transcript and a worse ticket. Mine is boring on purpose:

Land on the page with the screen reader running, and say the page title I hear
Move through the main landmarks, and say each one out loud if the software does not
Try the primary task (in this case, starting a checkout)
Try the error state (submit the form empty)
Stop, and say “end of walkthrough”

The last line is for me. It gives me a marker when I search the text later. I used to forget to say where I was on the page. The first transcript I got was a stream of complaints with no headings, and I had to play the audio back anyway. Now I announce the place: “I am on the shipping form. The field after postal code has no spoken label.” That sentence is already most of a ticket title.

I record with the in-browser recorder sometimes, and with a local m4a when I want the file next to the video I take of the session. Both have worked. The tool accepts thirty-plus audio and video formats, and it also accepts a public YouTube or TikTok or X link, which I do not use here; these reviews are not public videos. A typical walkthrough is fifteen or twenty minutes. In Standard mode that is 15 or 20 credits, against 240 free credits a day when I am signed in. I leave speaker identification off when it is only my voice. If the screen reader is in the same file and I want those lines marked separately, I will turn it on, at two credits a minute, and then I still relabel anything that looks off.

A one-hour file is described as often finishing in about two minutes, depending on quality and language. These short files are done before I have finished closing the extra tabs I opened for the review.

From transcript to tickets

I export SRT or VTT, not just a wall of TXT, because I want a timestamp I can paste into the ticket and, if needed, match to the video. I do not need a subtitle file for a public player. I need “at 06:12 I was on the shipping form.”

My issue template is small. I have pasted it at the bottom of this post. The only parts I take from the transcript are the spoken description and the timestamp. The rest — browser, screen reader version, expected result, actual result — I fill in by hand, looking at the page. I do not let the text invent an expected result. It is very willing, if I am not careful, to sound more precise than I was in the moment.

Accuracy is described as up to 99% on clear recordings. A headset mic in a quiet room is close to that. The screen reader’s voice can still be chopped, especially when I talk over it, which I try not to do and sometimes do. Control names, in particular, I check against the page. If I heard “continue” and the accessible name is “Continue to payment,” the ticket uses the name on the page.

I do not use an automatic summary for this. A summary of a walkthrough tends to smear three issues into one paragraph and drop the timestamp. I want three tickets, or one ticket with three numbered steps, and I want the clock on each.

When the tickets are filed, I delete the audio and the transcript from my machine and from the library in the tool. The tickets are the record. If a reviewer wants to hear the stretch, they can ask me to reproduce it; they should not need a copy of my voice sitting in a folder.

Here is the template I actually use:

## Title
[page] [control] [what I heard or didn’t hear]

## Environment
- Browser:
- Screen reader and version:
- URL (internal):

## Timestamp
- Walkthrough clock: (from the SRT cue)

## Steps
1.
2.

## Expected
## Actual
## Notes
- Quote from my spoken notes, checked against the page:

The first week I used this, I filed four issues from a single checkout walkthrough, and two of them were things I would have written as “confusing form” and then never been able to reproduce. One was a heading level that I had felt, vaguely, and then could point to at 03:41. The other was an error message that was visible but never spoken. I had heard myself say “I submitted, and nothing was announced,” which is a better ticket than “error??” with a screenshot of a red box.

What I will not do with this

I will not attach the transcript to a public issue tracker. I will not record a customer. I will not treat this as a substitute for testing by people who use a screen reader every day. This is a way for me, as an engineer, to keep my place and to write a ticket that another engineer can follow. It is not a complete accessibility practice, and I do not want it read as one.

If you already do a spoken walkthrough and you already lose your notes, you can transcribe the walkthrough and file from the cues instead of from the mess on your second monitor. Try it on one route, one day, and compare the tickets to the last set you wrote from one-handed typing. Mine were shorter, and they were easier to reopen a month later.

I still keep the checklist. The recorder does not know the route. I do, and I still forget a step when I am annoyed at a dropdown. The difference is that when I say “end of walkthrough” and something is missing, I can see the gap in the text and go back, instead of discovering the gap in front of a reviewer.

If you try audio to text for this, start with your own voice, one route, and a template that already has a timestamp field. The file is a means to a ticket. The ticket is the thing that should last.

Disclosure: I'm involved with AudioToText, the tool linked in this post. The walkthrough route, the template, and the checkout examples are from my own reviews. I have not included product UI, customer data, or a real internal URL.

I Debugged a Timezone Bug by Talking to Myself, Then Ran the Audio to Text and Got a Bug Report

Joy — Thu, 12 Nov 2026 11:44:07 +0000

Rubber-duck debugging works for me, but I've always lost the useful part. I talk through the problem, I find the bug, and an hour later I can't explain to my team how I found it. Last month I tried recording the monologue and running the audio to text afterwards. The transcript turned into the first draft of my bug report.

This is what happened, what the script looks like, and where it fell short.

The bug: a test that failed only after 4 p.m.

We had a test in a Node service that checked "orders created today." It passed in CI every morning and failed for anyone who ran it after about 4 p.m. Pacific.

You can probably guess the cause. I couldn't, at the time, and I spent forty minutes going in circles.

Recording myself (and only myself)

I work from home, so the only voice on the recording was mine. That matters. If you try this while pairing, ask your pair first, and stop recording when someone else drops into the call without knowing.

I didn't bother with a separate app. The tool I used has in-browser recording, so I opened a tab, hit record, and started talking at my second monitor like a person who has been alone too long.

The one rule I gave myself: say a marker word out loud before anything worth keeping.

"Hypothesis:" when I had a theory
"Ruled out:" when a theory died
"Note:" for anything I'd want in the write-up
"Fix:" for the final change

It felt silly for about three minutes. Then I forgot I was doing it.

Forty minutes of talking, condensed

Here's a cleaned-up slice of the transcript, to give you the flavor:

Hypothesis: the fixture dates are hard-coded and drift. … Ruled out: fixtures use Date.now(). … Okay, so it fails at 4:10 and passes at 3:50. Note: that's suspiciously close to midnight UTC. Hypothesis: startOfDay is running in UTC on my machine but the query uses local time. … Fix: pass the tenant timezone into startOfDay instead of relying on the process TZ.

Pacific time is UTC−8 in winter, so 4 p.m. local is midnight UTC. Once I said that sentence out loud, the bug was obvious. The recording caught the exact moment, which is what I always lose.

The audio to text part

When I stopped the recording, I ran the transcription right there in the browser. The free guest run covers up to 60 minutes once, which was plenty for a 40-minute ramble. Since then I've signed in. In Standard mode without speaker identification, each minute costs one of the 240 daily free credits, and a solo monologue doesn't need speakers anyway.

If you want to try it on your own next debugging session, you can record and transcribe in the browser without installing anything, then export the transcript as a TXT file.

The transcript wasn't perfect. startOfDay came back as "start of day," and TZ as "tease." Accuracy is up to 99% on clear recordings, and me mumbling at a monitor with a fan running is not that. I fixed the code identifiers by hand with the editor's search before exporting. It took about three minutes.

The 35-line script

The export is plain text. I wrote a small Python script that splits it into sentences and groups anything that starts with a marker word. No dependencies.

#!/usr/bin/env python3
"""Pull marker sentences out of a spoken debugging transcript."""
import re
import sys
from pathlib import Path

MARKERS = ["hypothesis", "ruled out", "note", "fix"]

def sentences(text: str):
    # Split on ., ?, ! followed by whitespace. Good enough for speech.
    return [s.strip() for s in re.split(r"(?<=[.?!])\s+", text) if s.strip()]

def extract(text: str):
    found = {m: [] for m in MARKERS}
    pattern = re.compile(r"^(hypothesis|ruled out|note|fix)\s*[:,-]?\s*(.+)", re.I)
    for s in sentences(text):
        m = pattern.match(s)
        if m:
            found[m.group(1).lower()].append(m.group(2))
    return found

def to_markdown(found):
    titles = {"hypothesis": "Hypotheses tried", "ruled out": "Ruled out",
              "note": "Notes", "fix": "Fix"}
    out = ["# Bug report (draft)", ""]
    for key in MARKERS:
        out.append(f"## {titles[key]}")
        out += [f"- {line}" for line in found[key]] or ["- (none)"]
        out.append("")
    return "\n".join(out)

if __name__ == "__main__":
    text = Path(sys.argv[1]).read_text(encoding="utf-8")
    print(to_markdown(extract(text)))

Run it like this:

python3 duck.py debugging-2026-10-14.txt > bug-report-draft.md

The output for my timezone bug looked like this (trimmed):

## Hypotheses tried
- the fixture dates are hard-coded and drift.
- startOfDay is running in UTC on my machine but the query uses local time.

## Ruled out
- fixtures use Date.now().

## Notes
- that's suspiciously close to midnight UTC.

## Fix
- pass the tenant timezone into startOfDay instead of relying on the process TZ.

That went into the PR description almost unchanged. My reviewer said it was the first bug write-up of mine she'd actually enjoyed reading.

Where it fell short

A few honest caveats after doing this about a dozen times:

Markers get mangled. "Ruled out" occasionally became "rule doubt." I added a fuzzy match for that one, then gave up and just fix it by hand in the editor.
Speech doesn't punctuate like writing. Some "sentences" run for 80 words. The regex split is crude. It's fine for a draft and useless for anything you'd publish as-is.
Code doesn't survive speech. Never trust a transcribed identifier. I read every backticked name against the actual code.
Not every session is worth it. For a five-minute bug, this is overkill. I use it when I've been stuck for 20 minutes and can feel myself starting to loop.

Why I kept doing it

The script isn't the point, and neither is the audio to text step on its own. The point is that speaking a hypothesis out loud forces me to finish the thought, and the recording means I don't lose it.

I also noticed a pattern in my own transcripts: I say "Ruled out" far less often than "Hypothesis." I jump to the next theory without killing the last one. Seeing that on paper has made me a slightly more disciplined debugger.

If you try it, I'd love to know what marker words you end up using. Mine have grown to include "Weird:", which so far has preceded every real bug I've found.

Disclosure: I'm involved with AudioToText, the transcription tool used in this post. The bug, the script and the opinions are my own.

Captions for Your Product Demo in One Afternoon: Audio to Text, WebVTT and the HTML `` Element

Joy — Wed, 11 Nov 2026 10:43:37 +0000

Our landing page had a three-minute product demo video. It autoplayed muted, like most demo videos do. Which meant that for most visitors, it was a silent movie of a cursor clicking things.

A teammate who is hard of hearing pointed it out first, kindly. Then our analytics confirmed it: almost nobody unmuted.

So I spent an afternoon adding real captions and chapter markers. No video platform, no paid captioning service, just a file, a text editor and the HTML <track> element. Here is the whole process.

What we are building

A captions.vtt file with accurate, readable cues
A chapters.vtt file so users can jump to sections
A <video> element that loads both, with captions on by default when the video starts muted

Step 1: Get a timestamped transcript

You need text with timings, which is exactly what audio to text output gives you. I uploaded the MP4 export of the demo to an audio to text tool and exported VTT directly. It accepts 30+ audio and video formats, so I did not need to strip the audio track first. If your demo is already on YouTube, a public link works too.

A few settings that mattered:

Language set explicitly instead of auto, because our voiceover drops product terms that confuse detection.
Speaker recognition off. One narrator, so there was nothing to separate, and Standard mode without speakers uses the fewest credits.
Clean Up Speech on for this job. It removes filler words and repetitions, which is what you want in captions for a scripted demo. For interviews I would keep the verbatim text.

The site says up to 99% accuracy on clear recordings. Our voiceover was recorded in a closet with a decent mic, so the draft was close, but it still spelled our product name three different ways. Budget ten minutes for proofreading.

Step 2: Tidy the cues

Raw transcript cues are often too long for comfortable reading. My rules of thumb:

Max two lines per cue, about 42 characters per line
Each cue on screen at least one second
Break lines at natural phrase boundaries, not mid-noun

A tiny Node script flags anything too long:

// check-vtt.mjs
import { readFileSync } from "node:fs";

const file = process.argv[2] ?? "captions.vtt";
const blocks = readFileSync(file, "utf8").split(/\r?\n\r?\n/);

for (const block of blocks) {
  const lines = block.split(/\r?\n/);
  const timing = lines.find((l) => l.includes("-->"));
  if (!timing) continue;
  const text = lines.slice(lines.indexOf(timing) + 1);
  const tooLong = text.filter((l) => l.length > 42);
  if (text.length > 2 || tooLong.length) {
    console.log(`${timing}\n  ${text.join("\n  ")}\n`);
  }
}

Run it with node check-vtt.mjs captions.vtt and fix whatever it prints. On a three-minute video this took me two passes.

Step 3: Write chapters by hand

Chapters are just another VTT file with kind="chapters". I skimmed the transcript to find where each section started. This was the moment the transcript paid off: searching for "dashboard" or "export" gave me exact timestamps without scrubbing the video.

WEBVTT

00:00:00.000 --> 00:00:21.000
Intro

00:00:21.000 --> 00:01:10.000
Importing a file

00:01:10.000 --> 00:02:15.000
Reviewing results

00:02:15.000 --> 00:03:02.000
Sharing and export

Step 4: Wire it up

<video id="demo" controls muted autoplay playsinline
       poster="/img/demo-poster.jpg" width="960">
  <source src="/video/demo.mp4" type="video/mp4" />
  <track kind="captions" src="/video/captions.vtt"
         srclang="en" label="English" default />
  <track kind="chapters" src="/video/chapters.vtt" srclang="en" />
</video>

The default attribute turns captions on. Browsers render chapter tracks inconsistently, so I also built a simple chapter list from the same file:

const video = document.getElementById("demo");
const track = video.textTracks[1]; // chapters
track.mode = "hidden";

video.addEventListener("loadedmetadata", () => {
  const list = document.getElementById("chapters");
  for (const cue of track.cues) {
    const btn = document.createElement("button");
    btn.textContent = cue.text;
    btn.onclick = () => { video.currentTime = cue.startTime; video.play(); };
    list.append(btn);
  }
});

Step 5: Serve VTT correctly

Two gotchas I hit:

The file must be served as text/vtt. Our static host defaulted to text/plain, and Safari silently ignored the track.
If the VTT lives on a different origin than the page, add crossorigin="anonymous" to the <video> and send CORS headers. Same origin is simpler.

What it cost

Roughly an afternoon, most of it on proofreading and line breaks. The transcription step itself took a couple of minutes. A one-hour file typically finishes in about two minutes, and our three-minute demo was nearly instant. As a guest you can try up to 60 minutes once; signed in, the daily 240 credits cover up to 240 minutes in Standard mode without speaker recognition (other modes use more credits per minute).

Checklist

[ ] Transcript proofread against the audio, especially product names
[ ] Cues under two lines and about 42 characters
[ ] Captions default when video autoplays muted
[ ] Chapters derived from transcript timestamps
[ ] VTT served as text/vtt

Captions built from audio to text output are one of those accessibility fixes that also help everyone watching in an open-plan office. If your demo video is still a silent movie, get a timestamped transcript and give it a voice on screen.

Disclosure: I'm involved with AudioToText, the transcription tool used in step 1.