AAC Online Speak & Translate Plug-in for Windows ("AAC Speak Helper")

For Full Documentation see here https://docs.acecentre.org.uk/products/v/aac-speak-helper-tool/

Introduction

AAC Speak Helper is designed to enhance your ability to communicate. It leverages the copy-paste clipboard to offer translation services in various languages, transliteration between different scripts (e.g., Latin to Devanagari), and uses multiple providers' Text-to-Speech (TTS) technology to read aloud the processed text. You can easily configure all these functionalities through our Configure app and maintain numerous settings files for different tasks.

Use Case

Imagine you are a Ukrainian speaker with limited English skills residing in a care facility. AAC Speak Helper bridges you and your caregivers, translating Ukrainian text into English. Moreover, it supports people who need to speak languages less commonly supported by TTS technology.

Compatibility

AAC Speak Helper is a Windows executable. It can be called from any AAC app on Windows that can run external programs. To make it work you currently need to run the server and client separately - but also edit your pagesets and a speak button.

How it Works

AAC Speak Helper reads the text once the text is copied to the clipboard (using Ctrl+C). Depending on the configuration settings, it can:

1. Translate the text using the selected translation service
2. Transliterate the text between different scripts (e.g., convert Latin text to Devanagari script)
3. Speak the processed text aloud using Text-to-Speech technology

There are additional features, such as putting intonation (or style) onto some voices. We have a graphical application that can configure the app. The main application, though, has no interface.

Developer details

see this mermaid graph

See build details here.

To build the encryption key

1. Fill your .env (or github env vars) with the correct keys for google/azure

eg.

MICROSOFT_TOKEN="token-here"
MICROSOFT_REGION="uksouth"
GOOGLE_CREDS_JSON="jq -c '@json' ttsandtranslate-7dd2e2d80d42.json - contents here"
MICROSOFT_TOKEN_TRANS="token-for-trans"
CONFIG_ENCRYPTION_KEY="key"

To get config encryption key run the following command

from cryptography.fernet import Fernet
print(Fernet.generate_key().decode())

2. Once this is all filled up run the following command to encrypt the config file

uv run python prepare_config_enc.py

It will now have a config.enc file created. Our code will use that. If keys are in settings.cfg that overrides these keys

Prerequisites

1. Install Python 3.11 (or higher) for Windows from the official Python website.

2. Install uv if you don't have it already. You can install uv by running:

   python -m pip install uv

   Ensure that uv is available in your PATH. You can verify this by running:

   uv --version

Setting Up the Development Environment

1. Clone the Repository if you haven't already:

   git clone https://github.com/AceCentre/AACSpeakHelper.git
   cd AACSpeakHelper

2. Create a Virtual Environment and Install Dependencies:

   uv venv
   uv sync --all-extras  # Installs all dependencies including dev tools

   This command will:

   • Create a virtual environment in the .venv directory within your project.
   • Install all dependencies and development tools listed in pyproject.toml.

3. Activate the Virtual Environment (if needed):

   While uv handles this automatically with uv run, you can activate the virtual environment manually if required:

   .venv/Scripts/activate  # On Windows
   # or
   source .venv/bin/activate  # On Unix-like systems

Running the Application

1. Run the Server:

   With the virtual environment active, you can run the application directly:

   uv run python AACSpeakHelperServer.py

   This ensures that the Python interpreter and dependencies used are from the managed environment.

   to call the client now you do (in a different terminal/console)

   uv run python client.py

   CLI Configuration Tool (for development):

   uv run python cli_config_creator.py

   TTS Preview Tool:

   • Development: uv run python gui_config_tester.py
   • Installed: Run AACSpeakHelper TTS Preview.exe or use Start Menu shortcut

Configuration

AACSpeakHelper uses a modern, intuitive configuration system with positive boolean logic. Instead of confusing double-negative settings like no_translate = False, the new system uses clear, positive values like enabled = true.

New Configuration Format

The configuration now uses a modular processing pipeline with intuitive settings:

[processing]
pipeline = translate,transliterate,tts    # Define processing order

[translate]
enabled = true                           # Clear: true means translation is active
source_language = en
target_language = ps
replace_clipboard = true

[transliterate]
enabled = true                           # Clear: true means transliteration is active
language = hi
from_script = Latn
to_script = Deva
replace_clipboard = true

[tts]
enabled = true                           # Clear: true means TTS is active
engine = azureTTS
save_audio = true

Before using AACSpeakHelper, you need to configure it. There are three main approaches:

1. GUI Configuration & Testing Tool (Recommended)

For development:

uv run python gui_config_tester.py

For installed version: Run Configure AACSpeakHelper GUI.exe

The GUI tool provides a user-friendly interface to:

• Select and configure TTS engines with dropdown menus
• Enter credentials with password masking for security
• Select voices from predefined lists or enter custom voice IDs
• Test TTS playback with sample text
• Save audio output as WAV files
• Real-time configuration validation

2. CLI Configuration Tool

For development:

uv run python cli_config_creator.py

For installed versions, use the "Configure AACSpeakHelper CLI" application from your start menu.

The CLI tool provides an interactive menu with intuitive language:

• Configure TTS engines with clear enable/disable options
• Set up translation providers with positive boolean logic
• Configure transliteration settings with easy-to-understand prompts
• Configure processing pipeline order
• Save and manage multiple configuration files

Key Improvement: The CLI now uses positive language like "Enable translation?" instead of confusing double-negatives like "Disable translation?"

3. Manual Configuration

Edit the settings.cfg file directly:

• Development: Located in the project root directory
• Installed: Located in %AppData%\Ace Centre\AACSpeakHelper\settings.cfg

You can also create custom configuration files and use them with:

uv run python client.py --config path/to/your/settings.cfg

API Keys and Credentials

For cloud-based TTS and translation services, you'll need API keys:

• Azure TTS: Requires Azure Speech Services subscription
• Google TTS: Requires Google Cloud TTS API credentials
• Microsoft Translator: Requires Azure Translator subscription
• Other services: See individual provider documentation

Store credentials in your settings.cfg file or use environment variables during development.

Additional Tips

• Adding Dependencies: To add new dependencies:

  # Edit pyproject.toml to add dependencies, then run:
  uv sync

• Updating Dependencies: To update all dependencies:

  uv pip compile pyproject.toml -o requirements.txt
  uv sync

• Exiting the Virtual Environment: To exit the virtual environment:

  deactivate

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Ace Centre for funding and supporting this project.
• Will Wade (TTS-Wrapper is heavily dependent on this project. Will converted the MMS models to sherpa-onnx which is used in this project)
• Gavin Henderson and all of the Ace Centre team for their support and feedback.