Terminal Access for NVDA

An NVDA add-on that provides enhanced terminal accessibility for various Windows Terminals like PowerShell, WSL2, and others. Inspired by TDSR (Terminal Data Structure Reader), this add-on incorporates functionality from both TDSR and Speakup. Advanced features inspired by community suggestions and discussions.

Overview

Terminal Access enables screen reader users to efficiently navigate and interact with command-line interfaces on Windows. The add-on integrates seamlessly with NVDA's built-in speech synthesis and provides comprehensive navigation and reading commands specifically designed for terminal usage.

Features

Command Layer (New)

• Single-key command mode - Press NVDA+' to enter the command layer; all commands become simple single-key presses (e.g. i for current line, f for search, a for say all)
• No modifier conflicts - The command layer avoids conflicts with other NVDA add-ons since all keys are unmodified while in the layer
• Easy exit - Press Escape or NVDA+' to leave the layer
• Auto-exit on focus loss - Layer deactivates automatically when you switch away from the terminal
• Customizable - All gestures appear in NVDA's Input Gestures dialog under "Terminal Access" for remapping

Core Navigation

• Line-by-line navigation through terminal output
• Word and character navigation with phonetic spelling support
• Continuous reading (Say All) - Read from cursor to end of buffer
• Screen edge navigation - Jump to line/buffer boundaries quickly
• Directional reading - Read from cursor to any edge (left/right/top/bottom)

Text Processing & Reading

• Punctuation level system - 4 levels of punctuation verbosity (None/Some/Most/All)
• Line indentation detection - Essential for Python and YAML code
• Position announcement - Report row and column coordinates
• Character code announcement - Display ASCII/Unicode values

Advanced Selection & Copy

• Enhanced selection system - Linear and rectangular (column-based) selections
• Mark-based selection - Set start/end marks for precise text selection
• Unicode/CJK support - Proper column alignment for international text
• ANSI-aware column extraction - Accurate rectangular selection with color codes

Color & Formatting (v1.0.18)

• Enhanced ANSI parser - Full support for terminal colors and formatting
  • Standard 8 colors + bright colors (16 total)
  • 256-color palette support
  • RGB/TrueColor (24-bit color) support
• Format detection - Bold, dim, italic, underline, blink, inverse, strikethrough
• Attribute reading - Announce colors and formatting at cursor (NVDA+Shift+A)

Cursor Tracking & Windowing

• Multiple cursor tracking modes - Standard, Highlight, Window, or Off
• Highlight tracking - Detect and announce highlighted/inverse video text
• Screen windowing - Define and monitor specific screen regions
• Multiple window definitions - Support for split panes and complex layouts

Application Profiles (v1.0.18)

Automatic detection and optimized settings for popular terminal applications:

• Vim/Neovim - Silences status line, enhanced punctuation for code
• tmux - Suppresses status bar for cleaner navigation
• htop - Separate regions for header and process list
• less/more - Quiet mode optimized for reading documents
• Git - Enhanced punctuation for diffs and logs
• GNU nano - Silences keyboard shortcuts area
• irssi - Chat-optimized settings for IRC
• WSL (v1.0.27+) - Linux command-line optimized with enhanced punctuation for paths and operators

Tab Management (v1.0.39+)

• Multi-tab terminal support - Work seamlessly with Windows Terminal tabs
• Tab-aware state management - Bookmarks, searches, and command history automatically isolated per tab
• Tab creation and navigation - Keyboard shortcuts for creating and switching between tabs
• Automatic tab detection - Identifies when you switch tabs and updates context accordingly

URL List

• Extract URLs from terminal output - Press NVDA+Alt+U (or E in command layer) to scan the buffer for URLs
• Interactive dialog - Filterable list showing URL, line number, and context
• Actions - Open in browser, copy to clipboard, or navigate to the line
• Broad URL support - HTTP/HTTPS, FTP, www-prefixed, and OSC 8 hyperlinks (file:// URLs are detected but blocked from opening for security)

System Features

• Key echo to hear characters as you type
• Quiet mode to temporarily disable automatic announcements
• Copy functionality for terminal content with flexible selection
• Configurable settings through NVDA's settings dialog
• Per-gesture unbinding - Disable individual direct shortcuts to resolve conflicts with other add-ons
• Native acceleration - CPU-bound text processing offloaded to a native Rust DLL for improved responsiveness, with automatic fallback to pure Python
• 17 languages - Arabic, Chinese (Simplified/Traditional), Czech, Dutch, French, German, Hungarian, Italian, Japanese, Korean, Polish, Portuguese, Russian, Spanish, Turkish, Ukrainian

Supported Terminals

Built-in Windows Terminals (5):

• Windows Terminal
• Windows PowerShell
• PowerShell Core (pwsh)
• Command Prompt (cmd.exe)
• Console Host (conhost.exe)

Windows Subsystem for Linux (WSL):

• WSL1 and WSL2 (all distributions)
• Automatic detection and optimized profile
• Full support for Linux commands and tools

Third-Party Terminal Emulators (23):

• Cmder - Portable console emulator
• ConEmu - Console emulator with tabs (32-bit and 64-bit)
• mintty - Git Bash and Cygwin terminal
• PuTTY - SSH and telnet client
• KiTTY - PuTTY fork with enhancements
• Terminus - Modern, highly configurable terminal
• Hyper - Electron-based terminal
• Alacritty - GPU-accelerated terminal
• WezTerm - GPU-accelerated with multiplexing
• Tabby - Modern terminal with SSH support
• FluentTerminal - UWP-based terminal
• Ghostty - Fast, native terminal emulator
• Rio - Hardware-accelerated terminal built with Rust
• Wave Terminal - Modern terminal with inline rendering
• Contour - GPU-accelerated terminal with VT extensions
• Cool Retro Term - Retro CRT terminal emulator
• MobaXterm - Enhanced terminal with X11 server and SSH
• SecureCRT - Professional SSH and terminal emulation
• Tera Term - Open-source terminal emulator
• mRemoteNG - Multi-remote connection manager
• Royal TS - Cross-platform remote management

Total: 30 supported terminal applications (including WSL)

For detailed information about each terminal and third-party terminal support, see the User Guide. For WSL-specific information, see WSL_TESTING_GUIDE.md.

System Requirements

• Operating Systems: Windows 10, Windows 11
• NVDA Versions: 2025.1 and later
• Python: 3.11+ (included with NVDA 2025.1+)

Installation

1. Download the latest release (.nvda-addon file)
2. Press Enter on the downloaded file to install
3. Confirm installation when NVDA prompts
4. Restart NVDA when prompted

Quick Start

When you open a supported terminal application, NVDA will announce:

"Terminal Access support active. Press NVDA+shift+f1 for help."

Press NVDA+Shift+F1 to open the comprehensive user guide.

Key Gestures

Terminal Access provides keyboard shortcuts for efficient terminal navigation. For the complete list of gestures and detailed usage instructions, see:

• Press NVDA+Shift+F1 while using the add-on to view the built-in guide
• View the User Guide for detailed documentation
• Refer to addon/doc/en/readme.html file

Quickest Start — Command Layer:

• NVDA+' — Enter the command layer (single-key mode)
• Then press: i (current line), o/u (next/prev line), k (current word), a (say all), f (search), Escape (exit layer)

Direct Gestures (alternative):

• NVDA+U/I/O - Read previous/current/next line
• NVDA+J/K/L - Read previous/current/next word
• NVDA+F - Search terminal output
• NVDA+[/] - Adjust punctuation level
• NVDA+Shift+Q - Toggle quiet mode

All gestures can be remapped in NVDA's Input Gestures dialog under "Terminal Access". For the complete list, see the User Guide.

Configuration

Access Terminal Access settings through:

• NVDA menu > Preferences > Settings > Terminal Settings

Available Settings

Cursor Tracking - Automatically announces the character at cursor position when it moves. Essential for monitoring position while navigating with arrow keys. Works with Cursor Delay to control timing.

Cursor Tracking Mode - Choose between four tracking modes:

• Off: No cursor tracking
• Standard: Announce character at cursor position (default)
• Highlight: Track and announce highlighted/inverse video text
• Window: Only track cursor within defined screen window

Key Echo - Announces each character as you type it. Provides immediate feedback for every keystroke. Works with Process Symbols and Condense Repeated Symbols for intelligent announcements.

Line Pause - Reserved for future continuous reading functionality. Currently preserved but not actively used.

Announce Indentation When Reading Lines - When enabled, automatically announces the indentation level (spaces and/or tabs) after reading each line with NVDA+U, I, or O. Essential for Python, YAML, and other indentation-sensitive code. Use NVDA+F5 to toggle quickly, or NVDA+I twice to query indentation of current line. Can be customized per application profile.

Punctuation Level - Controls how many symbols are announced (0-3):

• Level 0 (None): No punctuation announced
• Level 1 (Some): Basic punctuation (.,?!;:)
• Level 2 (Most): Most punctuation (adds @#$%^&*()_+=[]{}\|<>/)
• Level 3 (All): All punctuation and symbols
• Applies to typing echo, cursor tracking, and character navigation. Essential for developers who need to hear punctuation in code and commands without overwhelming verbosity in prose.

Condense Repeated Symbols - Counts repeated symbols and announces them as a group (e.g., "3 equals" instead of "equals equals equals"). Only works with symbols specified in "Repeated Symbols to Condense".

Repeated Symbols to Condense - Specifies which symbols to condense (default: -_=!). Customize for your workflow (e.g., -=# for Markdown users).

Cursor Delay - Delay in milliseconds (0-1000) before announcing cursor position changes. Lower values provide instant feedback but may overwhelm during rapid movement. Default: 20ms.

Default Profile - Select a profile to use when no application-specific profile is detected. Allows you to have custom settings apply by default rather than global settings. Use NVDA+F10 to check which profile is currently active and which is set as default.

Direct Gesture Bindings - A checklist of all direct keyboard shortcuts (e.g., NVDA+I, NVDA+K). Uncheck any gesture to disable it, useful for resolving conflicts with other NVDA add-ons or built-in commands. Unchecked gestures remain accessible through the command layer (NVDA+'). The command layer and help gestures are always available and cannot be disabled.

Settings Interactions

• Quiet Mode (NVDA+Shift+Q) temporarily disables cursor tracking and key echo
• Indentation Announcement (NVDA+F5) toggles indentation reading on line navigation
• Process Symbols affects cursor tracking, key echo, and character navigation
• Condense Repeated Symbols requires Key Echo to be enabled
• Cursor Delay only affects cursor tracking, not key echo or manual navigation

Troubleshooting

For troubleshooting common issues, please refer to the FAQ.md which provides comprehensive solutions for common problems.

Releases

Latest Release

Download the latest version from the GitHub Releases page.

Version History

See CHANGELOG.md for detailed information about all releases, including:

• New features and enhancements
• Bug fixes
• Breaking changes
• Migration guides

Contributing

Contributions are welcome! Please feel free to:

• Report bugs or issues
• Suggest new features
• Submit pull requests
• Improve documentation

For detailed contribution guidelines, development setup, coding standards, and testing procedures, please see:

• CONTRIBUTING.md - Complete contribution guide
• docs/README.md - Documentation organization and structure

Credits

Terminal Access is inspired by:

• TDSR (Terminal Data Structure Reader) by Tyler Spivey - Original terminal accessibility project that laid the foundation for terminal screen reader support
• Speakup - Linux kernel screen reader, which inspired the advanced cursor tracking modes, screen windowing system, and attribute reading features

Community contributions and discussions from various accessibility forums and social media have shaped the advanced features in Terminal Access.

License

Copyright (C) 2024 Pratik Patel

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

See the LICENSE file for the complete license text.

Links

• Project Repository
• NVDA Official Website
• Original TDSR Project
• Speakup Screen Reader
• NVDA Add-on Development Guide
• NVDA Developer Guide