YouTube Caption Reader for NVDA

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

Version 1.0.1

Version 1.0.1 updates the documentation and prepares the add-on for NVDA Add-on Store submission. There are no functional changes from version 1.0.0.

• 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.1.nvda-addon from the 1.0.1 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.

• Completed sentence and clause boundaries are spoken as they appear.
• Long automatic captions without punctuation can release a word-boundary prefix after up to 1.5 seconds.
• A short unfinished suffix waits for text to stabilize. The delay adapts to recent caption updates, from 450 to 1,200 milliseconds.
• Rapid updates are held for 450 milliseconds before entering NVDA's shared speech queue. Only the newest pending caption is sent, and the add-on never cancels unrelated NVDA speech.
• A detected video seek clears caption assembly and pending state before processing the new position.
• 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.
• Very fast captions may be coalesced so the speech stays closer to the current video position. Some intermediate caption fragments may therefore be skipped.
• 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.1.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.