OpenEVVWindows - GitLite

KO | EN

gitlite — search

#database #dotnet #open-source #html #linux #ios #electron #python #terminal #nextjs

OpenEVVWindows

(★ 9)

Eloquence (IBM Embedded ViaVoice) for NVDA, built on OpenEVV. Engine included, both bitnesses, no eci.dll to hunt down.

File Explorer

ZIP Download

- - build.yml
- build.py
- buildVars.py
- comment-punctuation-localised.md
- comment-samplerate.md
- issue-32bit-abi.md
- issue-body.md
- issue-punctuation.md
- issue-rules-perf.md
- README.md
- repro_abort_hang.py
- repro_samplerate.py
- repro_synthmode_crash.py
- stopbug.c
- stopstress.c
- - main.cpp
- - openevv.iss
  - stage.ps1
- - dialog.cpp
  - dialog.h
  - eci.cpp
  - eci.h
  - guids.cpp
  - guids.h
  - openevv_sapi5.def
  - resource.h
  - server.cpp
  - settings.cpp
  - settings.h
  - settings.rc
  - text.cpp
  - text.h
  - text_parity.cpp
  - tokenui.cpp
  - tokenui.h
  - voice.cpp
  - voice.h
  - voice_test.cpp
- .gitignore
- CMakeLists.txt
- analyse_trace.py
- build_engine.sh
- check_eci.py
- compare_ibmtts_audio.py
- compare_ibmtts_text.py
- compare_ibmtts_utterance.py
- compare_sapi_text.py
- engine_probe.c
- fetch_eci.py
- latency_check.py
- test_driver.py
.gitignore
LICENSE
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Eloquence — IBM's Embedded ViaVoice — for NVDA and for SAPI 5, built on
[OpenEVV](https://github.com/Mudb0y/openevv), which is that engine rebuilt as
portable C.

The engine ships inside the packages, in both word sizes. There is no
synthesiser to find, no `eci.dll` to hunt down and no path to configure, and
nothing here asks the user to supply one.

## What is here

| | |
|---|---|
| `nvda-addon/` | The NVDA synthesiser driver. Loads the engine in process. |
| `sapi5/` | A SAPI 5 voice: eight tokens, a settings dialog, an installer. |
| `tools/` | Fetching an engine, and driving one without NVDA to check it. |
| `openevv-bugs/` | Minimal reproductions of three faults found in the engine. |

## The NVDA add-on

Install it, pick **OpenEVV (Eloquence)** in the synthesiser dialog, and it
speaks. Eight voices, the usual sliders, plus head size, roughness,
breathiness and the pause style Eloquence users expect.

**In process, no bridge.** This is the part that is new. NVDA became 64-bit in
2026, and the existing IBMTTS driver reaches a 32-bit `eci.dll` by hosting it
in a separate 32-bit process and talking to it over a named pipe. OpenEVV
builds 64-bit, so the engine is simply loaded into NVDA and called.

64-bit only, for now — see below.

### Building

The engine is not committed. Continuous integration builds it from OpenEVV's
source with the rules compiled; to work on the driver, take the libraries from
a release instead:

```
python tools/fetch_eci.py        # puts eci.dll in place for x86 and x86_64
python nvda-addon/build.py       # writes nvda-addon/dist/openevv-<version>.nvda-addon
```

Those releases are the interpreted build and are about five times slower to
start speaking than they need to be, which is fine for working on the driver
and not what you want to use. `tools/build_engine.sh` builds the engine
properly from a checkout of OpenEVV, on Windows, under MSYS2.

### Checking it without NVDA

`tools/check_eci.py` drives the bundled library on its own — loads it, reads
the eight voices back, synthesises with index marks — and is what CI runs on
Windows against a freshly built engine.

`tools/test_driver.py` goes further: it stands up stubs for the NVDA modules
the driver imports and exercises the real driver against the real engine, so
the speech sequence, the text substitutions, the worker thread, the index
marks, cancelling and recovering from a cancel are all covered by something
that can be run from an ordinary command line.

Both want a Python whose word size matches the library being checked.

## The SAPI 5 voice

Install it and eight Eloquence voices appear to anything that speaks through
SAPI — Narrator, the speech control panel, and every program that asks Windows
for a voice list. Each preset is its own token, so a program that remembers
"Reed" gets Reed back rather than a default with parameters applied to it.

`dist/OpenEVV-Eloquence-<version>-setup.exe`, built by CI on every tag, wants
administrator: SAPI reads its voice tokens from `HKEY_LOCAL_MACHINE`. The
settings a person changes while listening are in `HKEY_CURRENT_USER`, so
changing them never asks for anything, and an uninstall offers to leave them
in place for whatever is installed next.

### Settings

Abbreviation expansion, phrase prediction, whether backquote tags in the text
are obeyed, and how much punctuation is paused at. The same dialog opens two
ways, because a person will look in either place: on its own, from
**OpenEVV Eloquence Settings** in the Start menu, and from the **Settings**
button a SAPI host shows beside the voice it has selected.

### Building

```
cmake -B sapi5/build/x64 -A x64 -S sapi5
cmake --build sapi5/build/x64 --config Release
powershell -ExecutionPolicy Bypass -File sapi5/installer/stage.ps1
iscc sapi5/installer/openevv.iss
```

The engine is not built here; `stage.ps1` takes the one the add-on uses and
puts it beside the voice, which is where the voice looks for it.

### Checking it without installing it

`voice_test.exe` loads the DLL by hand, asks it for a class through
`DllGetClassObject` and drives it with a site of its own, so whether the voice
speaks is answerable without putting anything in the registry — which is worth
keeping separate from whether the installer works. It checks the format, the
audio, the rate, spelling, bookmarks and their positions in the stream.

`tools/compare_sapi_text.py` holds this voice's text handling against the NVDA
driver's. They are separate implementations of the same rules in different
languages, and only the Python one was compared input by input against the
IBMTTS driver, so that one is the reference. CI runs both.

## The engine is built with its rules compiled

OpenEVV runs the Eloquence language rules through a bytecode interpreter
unless it is told otherwise, and that is what its released binaries are. It
costs more than it looks:

| | first audio | whole utterance |
|---|---|---|
| rules interpreted (the default) | 5.8 ms | 11.4 ms |
| rules compiled (`RULES=c`) | 1.8 ms | 4.3 ms |

Measured inside NVDA against the original IBMTTS library on the same machine
and the same list, the interpreted build took **9.5 ms** to produce the first
audio of an utterance where IBM's own library took **1.7 ms** — and produced a
third as much of it. That is the whole of the difference in how quickly the
two start speaking; the driver either side of it costs 0.13 ms.

Compiled, it is 1.8 ms. The audio is byte for byte identical: same SHA-256
over three voices and seven texts, including annotations, numbers and
spelling.

So the sixty-four bit engine is built with `RULES=c`. The thirty-two bit one
is not: the rules come to nearly thirteen megabytes of C in a single file and
a thirty-two bit compiler runs out of address space on it, even at `-O1`.
Teaching `tools/delta-decompile.py` to write several files would fix that and
is worth doing upstream.

## Notes on the engine

Three faults were found in OpenEVV v0.3 while writing the driver. Each has a
minimal reproduction in `openevv-bugs/`; the driver is built to avoid all
three.

1. **`eciStop` faults while synthesis is in flight.** The calling thread
   resets the Delta machine that the synthesis thread is interpreting. This
   is what a screen reader does to cancel speech, and it is why the driver
   never calls it: it lets the synthesis finish on its worker and throws the
   audio away, which costs nothing, because the engine synthesises about two
   hundred times faster than the audio plays.
2. **A callback returning `eciDataAbort` wedges the engine.** IBM published
   that value as 2; returning it makes `eciSynchronize` never return. The
   only safe answer is `eciDataProcessed`.
3. **`eciSynthMode = 1` faults** on an utterance carrying three index marks
   across two pieces of text — the ordinary shape of a screen reader's
   output. The driver leaves the mode at its default.

There is also a build note: the tree only links at `-O2`. Two dead stores in
`sti_indexQueueCtor` name vtables that exist solely in IBM's objects, and at
`-O0` they survive to the link and fail it, so there is no debug build.

## Thirty-two bit is not usable yet

The engine's thirty-two bit build exports its functions as cdecl, where the
ECI interface is stdcall and IBM's own library is stdcall. NVDA reaches a
library through `ctypes.windll`, which is stdcall, so every call into it
leaks four bytes of stack; a stdcall client that registers a callback faults
outright. Upstream issue: <https://github.com/Mudb0y/openevv/issues/7>.

Thirty-two bit NVDA is therefore not supported in practice, whatever the
add-on ships, and the SAPI 5 installer is sixty-four bit only for the same
reason: a thirty-two bit SAPI application loads a thirty-two bit voice or
none, and a thirty-two bit voice here could not call the engine. Sixty-four
bit is what has been used and measured. Both will be built the day the
upstream issue is fixed; the thirty-two bit engine is built by CI already,
so that the artifact is there when it is.

## Licence

The driver is GPL v2. The OpenEVV engine is MIT.

The language data the engine reads is neither: it is transcribed from IBM's
Embedded ViaVoice objects and remains IBM's work. `NOTICE`, shipped beside
the library, says what it is. Neither OpenEVV nor this project is in a
position to license it to anyone, and packaging it here does not change that.

## Credits

The engine is the work of the OpenEVV project. The text substitutions that
keep Eloquence from mispronouncing — and in a few cases from falling over —
come from the [NVDA IBMTTS driver](https://github.com/davidacm/NVDA-IBMTTS-Driver)
by David CM and contributors, which collected them over many years; the break
timing comes from eloquence_threshold.