YouTube Caption Reader for NVDA

YouTube Caption Reader is an NVDA add-on that reads captions currently shown in YouTube videos.

Version 1.0.2

Version 1.0.2 keeps caption speech closer to the current video position when captions update faster than NVDA can speak. It limits stale queued speech, treats the first visible caption as a baseline, and replaces revised live-caption text before it is spoken. Very rapid updates may skip intermediate fragments to avoid falling further behind.

• NVDA compatibility: 2026.1.1
• Tested browser: Microsoft Edge
• Supported pages: YouTube video and Shorts pages
• Source code: https://github.com/sheldon-im/nvda-youtube-caption-reader
• Release downloads: https://github.com/sheldon-im/nvda-youtube-caption-reader/releases

Install

1. Download youtubeCaptionReader-1.0.2.nvda-addon from the 1.0.2 release.
2. Open the downloaded file and confirm installation in NVDA.
3. Restart NVDA when it asks you to do so.
4. Open a YouTube video, turn captions on, and start playback.

The add-on starts with automatic caption reading enabled.

Use with translated captions

YouTube's Auto-translate feature can display Korean captions for a video with captions in another language. Enable captions and choose Korean from YouTube's subtitle settings. The add-on reads the text that YouTube exposes through the Windows accessibility APIs; it does not translate captions itself.

Commands

• NVDA+Shift+Y: Turn automatic caption reading on or off.
• NVDA+Shift+U: Read the caption currently visible on screen.
• NVDA+Shift+D: Open a diagnostic report of the YouTube caption accessibility tree. This command is intended for troubleshooting.

How it works

YouTube updates captions without reliably sending a screen-reader event. The add-on finds the player caption area in NVDA's accessibility tree and turns the newest visible text into a speech stream.

• The first visible caption after activation, caption discovery, or a video seek is used as a baseline instead of being read as new speech.
• Completed sentence and clause boundaries are spoken as they appear.
• Long automatic captions without punctuation can release a word-boundary prefix after up to 0.9 seconds.
• A short unfinished suffix waits for text to stabilize. The delay adapts to recent caption updates, from 450 to 1,200 milliseconds.
• At most one add-on caption is sent to NVDA at a time. While it is speaking, only the newest pending caption is retained, and pending text older than 1.5 seconds is discarded.
• A revised live-caption suffix replaces its unspoken earlier version instead of forcing the earlier recognition result to speak.
• A detected video seek clears caption assembly and pending state before the new position is used as a baseline.
• When YouTube rolls an older line off screen, the add-on compares only the current and immediately previous caption views. This prevents a shortened view from blocking later captions.

To avoid slowing other browsing, caption polling runs only when NVDA identifies the focused document as a YouTube video or Shorts page.

Limitations and troubleshooting

• The add-on depends on YouTube, the browser, and NVDA exposing captions through the Windows accessibility APIs. Changes to any of them can require an update.
• YouTube's own automatic captions and Auto-translate can already lag behind the original audio. The add-on cannot remove that upstream delay.
• The first caption already visible when automatic reading starts or resumes is not spoken automatically. NVDA+Shift+U can read it on demand.
• Very fast captions may be coalesced so the speech stays closer to the current video position. Some intermediate caption fragments may therefore be skipped.
• Speech already handed to NVDA is allowed to finish unless NVDA itself cancels speech; the add-on does not globally cancel unrelated speech to catch up.
• If captions are visible but are not read, press NVDA+Shift+U. If it still cannot find a caption, press NVDA+Shift+D and include the diagnostic report when reporting the issue.
• Before reporting a shortcut problem, disable any other YouTube caption-reading add-on that might use the same NVDA gesture.

Please report reproducible problems in the issue tracker. Include your NVDA version, browser, YouTube URL if shareable, selected caption language, and the output of NVDA+Shift+D when available.

Development

This project uses the official NVDA Add-on Template.

text scons python -m unittest discover -s tests -v

The build creates youtubeCaptionReader-1.0.2.nvda-addon in the repository root.

Continuous integration runs on Windows and checks formatting, unit tests, and add-on packaging.

License

GPL-2.0-or-later. See COPYING.txt.