Controller Client API

External API for applications to communicate with NVDA

Introduction

The NVDA Controller Client API allows external applications to communicate with NVDA, enabling them to:

• Speak text programmatically
• Display braille messages
• Cancel speech
• Check if NVDA is running
• Speak SSML (Speech Synthesis Markup Language)

The API is implemented as a DLL (Dynamic Link Library) that can be called from any programming language that supports loading and calling functions from DLLs.

The Controller Client API is primarily designed for applications that want to provide their own accessibility layer or need to communicate information directly to NVDA users.

Getting the API

Download Pre-built

Download the *controllerClient.zip from:

• Latest stable release
• GitHub Actions artifacts for development versions

Build from Source

Build the controller client yourself:

scons source client

Build output is available in ./build/[x86|x64|arm64]/client/

What’s Included

DLL Files

Platform-specific nvdaControllerClient.dll files for x86, x64, and ARM64

Header File

nvdaController.h with C declarations for all functions

Import Libraries

.lib and .exp files for C/C++ linking

Examples

Sample code in Python, C, C#, and Rust

API Versions

Version 2.0 (NVDA 2024.1+)

Added support for:

• nvdaController_getProcessId - Get NVDA’s process ID
• nvdaController_speakSsml - Speak SSML with markup support

These functions return error code 1717 (RPC_S_UNKNOWN_IF) on NVDA versions older than 2024.1.

Version 1.0

Core functions available in all NVDA versions:

• Test if NVDA is running
• Speak text
• Braille messages
• Cancel speech

Security Considerations

NVDA runs on the lock screen and secure screens. Before providing information to users via the Controller Client API, check if Windows is locked or on a secure screen to prevent leaking secure data.

Applications should implement security checks:

import ctypes

# Check if on secure desktop
def is_secure_desktop():
    # Implementation depends on your security requirements
    # Check for locked workstation or secure screen
    pass

# Only speak if not on secure desktop
if not is_secure_desktop():
    clientLib.nvdaController_speakText("Sensitive information")

Core Functions

nvdaController_testIfRunning()

Test if NVDA is running and accessible.

Return Value · int

0 on success, non-zero Windows error code on failure

import ctypes

clientLib = ctypes.windll.LoadLibrary("./nvdaControllerClient.dll")

res = clientLib.nvdaController_testIfRunning()
if res != 0:
    errorMessage = str(ctypes.WinError(res))
    print(f"NVDA not running: {errorMessage}")

nvdaController_speakText(text)

Speak the provided text through NVDA.

text · wchar_t* · required

The text to speak (wide character string)

Return Value · int

0 on success, non-zero error code on failure

# Speak a message
clientLib.nvdaController_speakText("Hello from my application!")

nvdaController_brailleMessage(message)

Display a message on the user’s braille display.

message · wchar_t* · required

The message to display in braille

Return Value · int

0 on success, non-zero error code on failure

# Show a braille message
clientLib.nvdaController_brailleMessage("Status: Connected")

nvdaController_cancelSpeech()

Cancel all currently queued speech.

Return Value · int

0 on success, non-zero error code on failure

# Stop speaking
clientLib.nvdaController_cancelSpeech()

nvdaController_getProcessId()

Get the process ID of the running NVDA instance.

processId · DWORD* · required

Pointer to receive the process ID

Return Value · int

0 on success, 1717 if not supported, other non-zero on failure

Available in NVDA 2024.1 and later

processId = ctypes.c_ulong()
res = clientLib.nvdaController_getProcessId(ctypes.byref(processId))
if res == 0:
    print(f"NVDA Process ID: {processId.value}")

nvdaController_speakSsml()

Speak SSML (Speech Synthesis Markup Language) with support for prosody, marks, and breaks.

ssml · wchar_t* · required

The SSML string to speak

symbolLevel · int

Symbol verbosity level (-1 for user’s setting)

priority · int

Speech priority (0 = normal)

asynchronous · bool

Whether to speak asynchronously

Return Value · int

0 on success, 1717 if not supported, other non-zero on failure

Available in NVDA 2024.1 and later

ssml = """<speak>
    This is one sentence.
    <mark name="test" />
    <prosody pitch="200%">This sentence is pronounced with higher pitch.</prosody>
    <break time="1000ms" />
    This is after a one second pause.
</speak>"""

clientLib.nvdaController_speakSsml(ssml, -1, 0, False)

nvdaController_setOnSsmlMarkReachedCallback()

Set a callback function to be called when SSML marks are reached.

callback · function pointer

Function with signature: int callback(wchar_t* markName)

Return Value · int

0 on success, non-zero error code on failure

@ctypes.WINFUNCTYPE(ctypes.c_ulong, ctypes.c_wchar_p)
def onMarkReached(name: str) -> int:
    print(f"Reached SSML mark: {name}")
    return 0

clientLib.nvdaController_setOnSsmlMarkReachedCallback(onMarkReached)
# Speak SSML with marks
clientLib.nvdaController_speakSsml(ssml, -1, 0, False)
# Clear callback when done
clientLib.nvdaController_setOnSsmlMarkReachedCallback(None)

Complete Examples

Python Example

Basic Usage

import ctypes
import time

# Load the library
clientLib = ctypes.windll.LoadLibrary("./nvdaControllerClient.dll")

# Test if NVDA is running
res = clientLib.nvdaController_testIfRunning()
if res != 0:
    errorMessage = str(ctypes.WinError(res))
    print(f"Error: {errorMessage}")
    exit(1)

# Speak and braille messages
clientLib.nvdaController_speakText("Application started successfully")
clientLib.nvdaController_brailleMessage("Ready")

# Cancel speech if needed
time.sleep(2)
clientLib.nvdaController_cancelSpeech()

C Example

example_c.c

#include "nvdaController.h"
#include <windows.h>

int main(int argc, char **argv) {
    // Test if NVDA is running
    long res = nvdaController_testIfRunning();
    if (res != 0) {
        MessageBoxA(NULL, "Error communicating with NVDA", "Error", MB_OK);
        return 1;
    }
    
    // Speak text
    nvdaController_speakText(L"Hello from C application!");
    
    // Display braille message
    nvdaController_brailleMessage(L"C App Running");
    
    // Cancel speech
    Sleep(2000);
    nvdaController_cancelSpeech();
    
    return 0;
}

C# Example

Program.cs

using System;
using System.Runtime.InteropServices;
using System.Threading;

class Program
{
    [DllImport("nvdaControllerClient.dll")]
    static extern int nvdaController_testIfRunning();
    
    [DllImport("nvdaControllerClient.dll")]
    static extern int nvdaController_speakText([MarshalAs(UnmanagedType.LPWStr)] string text);
    
    [DllImport("nvdaControllerClient.dll")]
    static extern int nvdaController_brailleMessage([MarshalAs(UnmanagedType.LPWStr)] string message);
    
    [DllImport("nvdaControllerClient.dll")]
    static extern int nvdaController_cancelSpeech();
    
    static void Main(string[] args)
    {
        // Test if NVDA is running
        int res = nvdaController_testIfRunning();
        if (res != 0)
        {
            Console.WriteLine("NVDA is not running");
            return;
        }
        
        // Speak and braille
        nvdaController_speakText("Hello from C# application!");
        nvdaController_brailleMessage("C# App");
        
        Thread.Sleep(2000);
        nvdaController_cancelSpeech();
    }
}

Error Handling

All functions return 0 on success and a non-zero Windows error code on failure. Common error codes:

Error Code	Meaning
0	Success
1717	RPC_S_UNKNOWN_IF - Function not supported in this NVDA version
Other	Standard Windows error codes (use WinError or equivalent to decode)

Always check the return value of controller client functions and handle errors gracefully. NVDA might not be running, or the user might have disabled it temporarily.

Best Practices

Test Availability

Always call nvdaController_testIfRunning() before other operations

Security First

Check for secure desktops before speaking sensitive information

Graceful Degradation

Handle errors gracefully - user might not have NVDA installed

Version Detection

Check return codes to detect unsupported functions on older NVDA versions

Use Cases

Progress Notifications

def report_progress(percent):
    clientLib.nvdaController_brailleMessage(f"Progress: {percent}%")
    if percent == 100:
        clientLib.nvdaController_speakText("Operation complete")

Form Validation

def announce_error(field_name, error_message):
    message = f"{field_name}: {error_message}"
    clientLib.nvdaController_speakText(message)
    clientLib.nvdaController_brailleMessage(f"Error: {field_name}")

Status Updates

def announce_connection_status(status):
    ssml = f"""<speak>
        Connection status:
        <mark name="status_start" />
        <prosody rate="slow">{status}</prosody>
        <mark name="status_end" />
    </speak>"""
    clientLib.nvdaController_speakSsml(ssml, -1, 0, False)

License

The NVDA Controller Client API is licensed under the GNU Lesser General Public License (LGPL), version 2.1.

This means:

• ✅ You can use this library in any application (commercial or open source)
• ✅ You can distribute the DLL with your application
• ⚠️ If you modify the library, you must contribute changes back under LGPL 2.1

View Full License

Read the complete LGPL 2.1 license text

Additional Resources

Example Code

Complete working examples in multiple languages

Header File

nvdaController.h with full API documentation

Download Client

Download pre-built controller client DLLs

GitHub Issues

Report issues or request features