Piper-TTS-Manager-for-X-Plane

Piper TTS Manager is an adaption of the MaryTTS Manager utility for the FlyWithLua plugin for X-Plane 11/12 to the Piper TTS. Compared to MaryTTS Manager, the codebase has been slicked and cleaned up.

 

Table of Contents

1. Compatibility and Requirements
2. Installation
3. Uninstallation
4. Functionality
5. Usage
6. Known Issues
7. License

 

1 - Compatibility and Requirements

Compatibility:

• Confirmed working on Arch Linux, Fedora 39, Ubuntu 22.04, Windows 11 and MacOS so far.
• Does not support X-Plane's Steam release!
• X-Plane 11 is untested.
• Windows only: A console window will quickly pop up and close, momentarily taking focus from X-Plane when in full screen mode. This is Windows default behavior which I've tried for hours to work around with all kinds of command and PowerShell voodoo and failed miserably. For SimpleATC usage, it is recommended to simply use the default Windows SpeechAPI voices instead (see X-ATC-Chatter user guide).
• Also see "Known Issues" below.

Requirements:

• X-Plane, version 11.50, 12.00 or newer)
• FlyWithLua:
  • X-Plane 11: FlyWithLuaNG (version 2.7.28 or higher)
  • X-plane 12: FlyWithLuaNG+ (version 2.8.1 or higher)

Back to table of contents

 

2 - Installation

Because of the file sizes involved, PiperTTS Manager is dfelivered as a self-assmbly kit.
All paths are relative to the X-Plane 11/12 main installation folder.

• Click "Code" --> "Download ZIP" or use this link.
• Unzip the archive and copy the "Scripts" and "Modules" folders into "X-Plane 11/Resources/plugins/FlyWithLua/"
• Download Piper's latest release for your operating system from this Piper TTS fork:
  • Linux x86-64: piper_linux_x86_64.tar.gz
  • Windows: piper_windows_amd64.zip
  • Mac M1/2/3: piper_macos_aarch64.tar.gz
  • Mac (other): piper_macos_x64.tar.gz
• Unzip the downloaded file
• Move the content of the unzipped "piper" folder (not the folder itself!) to:
  • Linux: "Resources/plugins/FlyWithLua/Modules/PiperTTSManager/Resources/Piper_LIN"
  • Windows: "Resources/plugins/FlyWithLua/Modules/PiperTTSManager/Resources/Piper_WIN"
  • Mac: "Resources/plugins/FlyWithLua/Modules/PiperTTSManager/Resources/Piper_MAC"
• Go to the PiperTTS voice repository
• Pick any voice(s) you want from the "en" folder (at least download "en/en_US/lessac/medium" because the SimpleATC interface is preconfigured for it)
• The download and installation steps for each voice you pick are the same.
• In the folder of the voice in the repository, download the .onnx and .onnx.json files (download icon to the right of the file name)
• After the download, the onnx.json file may need to be renamed. It must(!) have the same(!!) filename as the voice, just with an .onnx.json extension (e.g. en_US-lessac-medium.onnx and en_US-lessac-medium.onnx.json)!
• Move both voice files into "Resources/plugins/FlyWithLua/Modules/PiperTTSManager/Resources/piper_voices".
• Repeat for any desired voice. (Note that PTTSM does not support subfolders in "piper_voices".)

Back to table of contents

 

3 - Uninstallation

All paths are relative to the X-Plane 11/12 main installation folder.

• Delete PiperTTSManager.lua from "Resources/plugins/FlyWithLua/Scripts"
• Delete "PiperTTSManager" from "Resources/plugins/FlyWithLua/Modules"

Back to table of contents

 

4 - Functionality

4.1 - Purpose

Piper TTS Manager is an interface and wrapper to call Piper TTS to generate an output audio file that can be played back. It is basically a bridge between an X-Plane plugin (or FlyWithLua or XLua or SASL script) and a local Piper TTS installation.

It was developed for use with the SimpleATC module of X-ATC-Chatter in close cooperation with Stick and Rudder studios to provide multiple pilot and controller voices.

 

4.2 - Interfaces

The bridging between plugin and Piper TTS is defined in interface files that can be created and edited directly in PTTSM's user interface in X-Plane. These interfaces define various aspects like input text file location, output WAV file location and optional voice mapping to assign a specific voice to a specific actor. Interface file structure is fixed and the user interface exposes all the required inputs for plugin or script developers.

 

4.3 - Input processing

The core element is a watchdog loop that runs in one second intervals and monitors a text input file. If a string is written to said input file, PTTSM will read it from file, split it into actor and string to be spoken based on a delimiter defined in the interface file.
The actor is then further matched to a present Piper TTS voice by means of a voice mappping defined in the interface file or - if none is found - by a random voice selection. There is a small degree of memory for actors, so that e.g. an ATC ground controller will have a consistent voice for all interactions until a switchover to another actor (e.g. ATC tower controller), at which point another (unmapped) voice is randomly chosen.
Piper TTS is then called with the voice and string to be spoken to output a WAV file to a location specified in the interface file. Playback of the output WAV file is either done by the plugin itself or by FlyWithLua. After playback, the WAV file is deleted.

Back to table of contents

 

5 - Usage

Call the PTTSM user interface... ...from X-Plane's "Plugins" menu with "PiperTTS Manager" --> "Open Window"
or
...from the FlyWithLua menu with "FlyWithLua" --> "FlyWithLua Macros" --> "PiperTTS Manager: Toggle Window"
or
...by assigning a keyboard shortcut to "PiperTTS Manager/Window/Toggle Window" in X-Plane's keyboard settings window.

General hints:

• Most, if not all, items have tooltips!
• After having typed a value into any text/number input box, click anywhere in PTTSM's window to leave it, otherwise it will keep focus, eating up all keyboard inputs (see "Known Issues" section below).
• Undesired values in text/number input boxes that were just entered can be discarded by pressing the "ESC" key.
• Window visibility, size and position are automatically saved when exiting X-Plane.

All paths stated below are relative to the FlyWithLua installation folder within X-Plane's installation folder.

 

UI: Interface selector

The interface selector lists all the available MTTSM interfaces found in "FlyWithLua/Modules/PiperTTSManager/Interfaces" at script startup. Pressing the "Rescan" button rescans that folder and rebuilds the list of available interfaces.
Selecting an interface is only necessary for reviewing its settings or for editing it. All plugin interfaces stored in the interface folder are automatically processed at X-Plane session start and continuously monitored as long as X-Plane is running!

 

UI: Interface settings (non-edit mode)

This is a multifunction menu which displays various interface information and interaction settings.
All changes made to the text input and selector boxes only apply until the next interface rescan or script reload. For permanent changes to an interface, use "Edit" mode (see below).
Text input boxes additionally will lose any changes unless in "Edit" mode.

 

UI: Interface settings (edit mode)

The edit mode for the interface can be enabled with the "Enable Edit Mode" button. Picking "Create New Interface" from the interface selector will automatically enter edit mode.
When in edit mode, the watchdog that scans for input text files for text-to-speech processing is disabled.
Changes made in edit mode may be saved to the interface configuration file (existing or new) by pressing the "Save Interface Configuration File" button.
Disabling edit mode for an existing interface after having made changes will retain these new values until the "Rescan" button next to the interface selector is pressed. This will trigger a complete reload of all available interfaces.

 

UI: Testing area

This interface element is only visible when the "None/Testing" interface is selected.
The main purpose of this element is to provide a quick method to check that PTTSM is working properly.
Enter a string that should be spoken, pick a voice and hit the "Speak" button. You should hear the spoken string a few seconds later.

 

Settings File

The path to PTTSM's settings file is: "FlyWithLua/Modules/PiperTTSManager/settings.cfg". You can edit or delete it when X-Plane is not running.

 

Troubleshooting

These are generic troubleshooting hints:

• After having installed PTTSM, use the "Testing" interface with FlyWithLua output to check if PTTSM is working properly.
• PTTSM writes its log to: "FlyWithLua/Modules/PiperTTSManager/PTTSM_Log.txt". The log is regenerated at every script start.
• Enabling "Debug Mode" from the menu will provide extra log output.
• On Linux, Piper prints to stdout, so launching X-Plane from a terminal will provide more debug realted output.

Back to table of contents

 

6 - Known issues

• There is a delay between sending a string to the server and hearing it due to the required processing from text to speech.
• There may be a short stutter in X-Plane while an output audio file is generated.
• Voice quality may be too low for some people, but this is as good as it gets with MaryTTS.
• Text input boxes will not automatically unfocus. Click anywhere inside the UI to unfocus them.
• Checking for an input file or playing back an output wave file may slightly degrade simulator performance.

Back to table of contents

 

7 - License

Piper TTS Manager is licensed under the European Union Public License v1.2 (see EUPL-1.2-license.txt). Compatible licenses (e.g. GPLv3) are listed in the section "Appendix" in the license file.

Back to table of contents