leonardder/rdaccess

Remote Desktop Accessibility for the NVDA screen reader

RDAccess: Remote Desktop Accessibility

• Authors: Leonard de Ruijter
• Download latest stable version
• NVDA compatibility: 2023.2 and later

The RDAccess add-on (Remote Desktop Accessibility) adds support for Microsoft Remote Desktop, Citrix, or VMware Horizon remote sessions to NVDA. When installed on both the client and the server in NVDA, speech and braille generated on the server will be spoken and displayed in braille on the client machine. This enables a user experience where managing a remote system feels as seamless as operating the local system.

Features

• Support for Microsoft Remote Desktop, Citrix, and VMware Horizon
• Speech and braille output
• Automatic detection of remote braille using NVDA's automatic braille display detection
• Automatic detection of remote speech using a dedicated detection process that can be disabled in NVDA's settings dialog
• Support for portable copies of NVDA running on a server (additional configuration required for Citrix)
• Full support for portable copies of NVDA running on a client (no additional administrative privileges required to install the add-on)
• Multiple active client sessions simultaneously
• Remote desktop instantly available after NVDA start
• Ability to control specific synthesizer and braille display settings without leaving the remote session
• Ability to use speech and braille from the user session when accessing secure desktops

Changelog

Version 1.3

• Fixed broken braille display gestures.

Version 1.2

• Use Ruff as a formatter and linter. #13
• Fixed an issue where NVDA on the client generates an error when pausing speech on the server.
• Fixed support for winAPI.secureDesktop.post_secureDesktopStateChange.
• Improved driver initialization on the server.

Version 1.1

• Added support for NVDA 2023.3 style device registration for automatic detection of braille displays. #11
• Added support for NVDA 2024.1 Alpha winAPI.secureDesktop.post_secureDesktopStateChange extension point. #12

Version 1.0

Initial stable release.

Getting Started

1. Install RDAccess on both a client and server copy of NVDA.
2. The remote system should automatically start speaking using the local speech synthesizer. If not, in the NVDA instance on the server, select the remote speech synthesizer from NVDA's synthesizer selection dialog.
3. To use braille, enable automatic braille display detection using the braille display selection dialog.

Configuration

After installation, the RDAccess add-on can be configured using NVDA's settings dialog, accessible from the NVDA Menu by choosing Preferences > Settings... Then, choose the Remote Desktop category.

This dialog contains the following settings:

Enable Remote Desktop Accessibility for

This list of checkboxes controls the operating mode of the add-on. Choose between:

• Incoming connections (Remote Desktop Server): Choose this option if the current instance of NVDA is running on a remote desktop server.
• Outgoing connections (Remote Desktop Client): Choose this option if the current instance of NVDA is running on a remote desktop client that connects to one or more servers.
• Secure Desktop pass-through: Choose this option if you want to use braille and speech from the user instance of NVDA when accessing the secure desktop. Note that for this to work, you need to make the RDAccess add-on available on the secure desktop copy of NVDA. For this, choose "Use currently saved settings during sign-in and on secure screens (requires administrator privileges)" in NVDA's general settings.

To ensure a smooth start with the add-on, all options are enabled by default. However, you are encouraged to disable server or client mode as appropriate.

Automatically Recover Remote Speech after Connection Loss

This option is only available in server mode. It ensures that the connection will automatically be re-established when the Remote Speech synthesizer is active and the connection is lost, similar to braille display auto-detection.

This option is enabled by default. It is strongly encouraged to leave this option enabled if the Remote Desktop server has no audio output.

Allow Remote System to Control Driver Settings

When enabled in the client, this option allows you to control driver settings (such as synthesizer voice and pitch) from the remote system. Changes made on the remote system will automatically reflect locally.

Persist Client Support When Exiting NVDA

This client option, available on installed copies of NVDA, ensures that the client portion of NVDA is loaded in your remote desktop client even when NVDA is not running.

To use the client portion of RDAccess, changes need to be made in the Windows Registry. The add-on ensures that these changes are made under the profile of the current user, requiring no administrative privileges. Therefore, NVDA can automatically apply the necessary changes when loaded and undo these changes when exiting NVDA, ensuring compatibility with portable versions of NVDA.

This option is disabled by default. However, if you are running an installed copy and you are the only user of the system, it is advised to enable this option for smooth operation when connecting to a remote system after NVDA starts.

Enable Microsoft Remote Desktop Support

This option, enabled by default, ensures that the client portion of RDAccess is loaded in the Microsoft Remote Desktop client (mstsc) when starting NVDA. Changes made through this option will be automatically undone when exiting NVDA unless persistent client support is enabled.

Enable Citrix Workspace Support

This option, enabled by default, ensures that the client portion of RDAccess is loaded in the Citrix Workspace app when starting NVDA. Changes made through this option will be automatically undone when exiting NVDA unless persistent client support is enabled.

This option is available only under the following conditions:

• Citrix Workspace is installed. Note that the Windows Store version of the app is not supported due to limitations in the app itself.
• It is possible to register RDAccess under the current user context. After installing the app, you have to start a remote session once to enable this.

Citrix Specific Instructions

There are important points to note when using RDAccess with the Citrix Workspace app:

Client-Side Requirements

1. The Windows Store variant of the app is not supported.
2. After installing Citrix Workspace, you need to start a remote session once to let RDAccess register itself. This occurs because the application copies system settings to user settings during the initial session setup. Following this, RDAccess can register itself under the current user context.

Server-Side Requirement

In Citrix Virtual Apps and Desktops 2109, Citrix enabled the so-called virtual channel allow list, restricting third-party virtual channels, including the channel required by RDAccess, by default. For more information, see this Citrix blog post.

Explicitly allowing the RdPipe channel required by RDAccess is not yet tested. For now, it is best to disable the allow list altogether. If your system administrator has concerns, feel free to address the issue here.

Issues and Contributing

To report an issue or contribute, refer to the issues page on Github.

External Components

This add-on relies on RD Pipe, a library written in Rust backing the remote desktop client support. RD Pipe is redistributed as part of this add-on under the terms of version 3 of the GNU Affero General Public License.

[[!tag dev beta]]

rdaccess's Issues

Document explicitly allowing the RdPipe channel in the Citrix Virtual Channel Allow List

This is not yet tested. There is some information from Citrix on how to find out the appropriate channel name by inspecting the event log, but I was unable to dig this up for RdPipe.

"Capital pitch change" doesn't always work

Steps to reproduce:

1. Make sure the "Capital pitch change percentage" is set to 30 on both the server and the client.
2. On the server, open notepad and try typing uppercase letters and then try typing lowercase letters.

Actual performance

NVDA can't distinguish capital letters by pitch change

Expected performance

NVDA should use speech synthesizer pitch changes to indicate capital letters.

Checkbox state changes are sometimes not reported

Steps to reproduce

1. The following operations are completed on the remote server.
2. Select remote speech speech synthesizer;
3. Try changing the state of the options checkbox in NVDA Documentation Settings with a space.

Expected performance

It should always be possible to consistently report state changes.

Feature request: support playing audio feedback.

On the server, using nvda+space to switch browse mode or focus mode has no sound.

Steps to reproduce

1. Open a browser and load any web page.
2. After the web page is loaded, press NVDA +Space to switch focus or browse mode.

actual performance

NVDA has no audio feedback and the user does not know which mode is currently in.

expected performance

NVDA provides audio feedback as expected.

Add support for dictionary sync

I think that Voice dictionaries aren't coming through (whether local or remote) because the remote side sees the remote synth as its own synth and so generates a different speech dictionary for those, but I can copy over the file as desired.

Originally posted by @tmthywynn8 in #2 (comment)

Test client side support for Vmware Horizon

VMware Horizon works in theory, but I have no environment to test it.

The VMware SDK says that every appliance has the vdp_rdpvcbridge.dll bundled with it. Therefore when it is available, it should replace twsapi32 calls. This is implemented properly and I tested that on a non-VMware VM by simply adding vdp_rdpvcbridge.dll to C:\Windows\SysWOW64. However we need to test a real situation for sure.

NVDA freezes upon loading in a Windows ARM VM running on Parallels if the add-on is installed.

To reproduce the problem, run a portable version of NVDA with this add-on installed in a Parallels VM running windows 11 ARM. I hear NVDA's startup sound and sometimes the message please wait. NVDA doesn't crash, it keeps running, but there is no speech or braille. I have reviewed the log in debug mode and there is no error message generated by the add-on.

NVDA version: I have tried 2023.1 and latest alpha.

Windows version: Windows 11 Pro ARM Version 22H2

Braille gestures don't seem to work when local system uses BRLTTY

There's a problem with braille we can read braille on braille display but we can't use the command thumb braille key etc to use to be able to move the braille display around the screen.

On the server, some options of the settings panel were not reported.

As the title says, I use mstsc to connect to the remote desktop, open the NVDA settings panel located on the server, and I find that the options in the 'server' group under the 'Remote Desktop' category are not displayed correctly.

Implement support for secure desktops

There is a long standing NVDA issue about braille on secure screens, see nvaccess/nvda#2315
With the protocol in this add-on, it should be pretty trivial to implement this. As soon as the user session enters a secure desktop, it should start a Named Pipe Server (the basics for named pipe servers are already implemented in addon/lib/namedPipe.py). The NVDA instance on the secure screen should connect to that pipe. The rest should be the same as for Remote Desktop.