Pronunciation dictionaries

[guilevi]

Adds user-editable pronunciation dictionaries to the emulator and to the NVDA
add-on: rules that rewrite text on its way to the card, matched by whole word,
by substring, or by regular expression, substituting a respelling, a phoneme
string, an embedded command, or nothing at all.

word		Sean	Shawn
word		arthritis	[AA R TH R AY DX IX S]
word	C	US	[Y UW EH S]
regex		\bv([0-9]+)\.([0-9]+)\b	version \1 point \2

In NVDA they are arranged from Preferences → Settings → DoubleTalk PC
dictionaries — a list in load order with Add, Remove, Move up, Move down and
Reload. Files are read where the user keeps them; Add records a path rather
than copying, so the file being edited is the file the card reads and Reload is
the whole round trip.

Nothing changes for anyone who does not create a dictionary. With no files
present, dtalk_say takes exactly the path it took before and allocates
nothing, and the driver's byte stream is unchanged.

Three commits: the .gitignore line, the emulator side, the NVDA side.

---

The part that needs your judgement: doubletalk/rcdict/ is vendored

The dictionary layer is not written for this repository. It is mirrored
byte-for-byte from an upstream project, where it serves RC Systems' later
RC8650 — a different package around the same synthesizer. The RC8650 datasheet
captions its phoneme table "DoubleTalk Phoneme Symbols", and in practice the
symbols, the Table 6 modifiers, the D/T/C mode commands and the Ctrl-A
command character are the same on both. What differs is carried by a per-card
profile (rcdict_doubletalk_pc), so the rules, the file format and the loaders
are genuinely one body of code.

That is seven files (rcdict.{c,h}, rcdict_regex.{c,h}, remimu.h,
example.dict, DICTIONARY-GUIDE.md), about 2.5k lines including the vendored
regex engine. A sync script on the upstream side copies them across, and its
--check mode exits non-zero if the two copies have drifted — worth a CI step
if this lands.

Licensing was the design constraint, not an afterthought. rcdict is
BSD-3-Clause and depends on nothing but libc. That is what lets the same
sources also be linked into the upstream project, which is GPL-3. The sharing
works in that direction only, so nothing under rcdict/ may acquire a GPL
header or a dependency on either host, and LICENSING.md says so. remimu.h
is a third-party regex engine (wareya) released under CC0; it imposes no
conditions on a redistributor and is listed for attribution rather than
obligation.

I have used SPDX identifiers in rcdict/** rather than the MAME-style
// license: headers the rest of the tree uses, because those files have to
read identically in both repositories. LICENSING.md notes the exception. Say
the word if you would rather they matched the house style and I will take it up
on the other side.

If vendoring is not what you want, the alternatives are a submodule (awkward:
an NVDA add-on build has to zip a working tree), or dropping the regex
matcher and writing something smaller from scratch here.

---

Emulator side

• dtalk_set_dictionary(dt, d, inline_phonemes) attaches a dictionary.
  It is borrowed, not owned — it must outlive the instance or be replaced
  with NULL first, so a host can swap dictionaries without tearing the card
  down. inline_phonemes enables the [[K AE T]] escape in ordinary text and
  is off by default, because [[ is wiki link syntax and someone reading a
  wiki must not silently lose text to it.

• dtalk_expand() runs the rules without queueing. Callers that split long
  text into utterances themselves need this and it is not optional for them:
  one word can become forty characters of phonemes plus the mode switches, so
  splitting first and expanding after can push a piece past what the card will
  accept. Expand, then split.

• dtalk_dict_new/_free/_add_file/_rule_count are four forwarding calls that
  exist only for the DLL. dtalk.h marks its entry points
  __declspec(dllexport), which turns off mingw's export-everything default —
  so rcdict's own symbols are absent from the export table and a ctypes
  caller cannot reach them. Re-exporting the four calls a host actually needs
  seemed better than exporting every symbol in the image, and it keeps the
  export marker out of rcdict, which has to stay free of anything Windows- or
  project-specific to go on being shared.

Build change worth a look: rcdict is C and has to be compiled as C —
handed to g++, its designated initializers and implicit void * conversions
are errors. Each DLL is therefore two compilers' output linked together, the
C++ emulator plus rcdict built by the matching gcc. Warnings are disabled
for rcdict_regex.c alone, because vendored remimu.h is not clean under
-Wall.

Leaving rcdict out of the mingw rules is a silent failure worth naming, since
I made it first: the DLL links, dtalk_set_dictionary is exported, and the
caller simply has no way to build a dictionary to hand it.

Two behaviours that are decisions, not accidents

First match in load order wins — never longest match, and the output is never
rescanned. This is the card's own convention for its exception dictionaries;
the datasheet warns that (RAT) placed before (RATING) means (RATING) is
never reached. It is also what makes "load this file first" a usable way to
override, which is what the NVDA panel is for.

A phoneme span breaks the letter-to-sound stage's context on both sides of
itself. So a trailing . or , is moved inside the span, and a preceding
article "a" is absorbed into it. Measured on the RC8650, with both rules
applied the rendered audio is byte-identical to what text mode produces; without
them it is audibly not. That measurement is what the substitution shape is built
on rather than on reading the datasheet's prose.

NVDA side

Expansion happens in speak(), not in dtalk_say. This driver queues its own
bytes with dtalk_queue because it interleaves index marks and settings — the
raw path, which deliberately bypasses dtalk_say — so the driver applies the
dictionary itself, before _split.

The settings panel is a global plugin rather than part of the driver
package, because a driver module comes and goes with the synthesizer and a
settings category cannot. That means globalPlugins/ is a second directory in
the add-on; build_addon.sh now packages it, prints the resulting package
listing, and refreshes the DLLs from the build tree, since shipping the previous
library is the kind of bug that builds, installs and runs.

Dictionaries are referenced, not copied. The configuration holds a path to
the file where the user keeps it, so the file they edit is the file the card
reads. A copy would have made every dictionary two files, one of them stale
from the first edit onwards, and "why did my change do nothing" the commonest
question about the panel. A reference whose file is not reachable today — an
unplugged drive, a share not mounted yet — stays in the list marked not
found and is skipped at load time, rather than being dropped: the add-on does
not own that file, so discarding the reference is not its call to make.

%APPDATA%\nvda\doubletalkpc\ is still scanned as a second source, so a
.dict dropped in there works with no configuration at all — anything the
saved order has not seen is appended in sorted order. That is the one place
Remove has to delete rather than unlist, since a scanned file would come
straight back; the panel says so and asks first, and Remove on anything else
touches nothing on disk. The order lives in NVDA's configuration, not in the
filenames.

Failures are contained. The ctypes bindings are guarded, so an add-on running
against a DLL built before this change loses dictionaries rather than the
synthesizer; each file is loaded in its own try, so one unencodable path costs
one file; the new dictionary is attached before the old one is freed, so a
reload cannot leave the card pointing at freed memory.

Testing

doubletalk/nvda/tests/ stubs NVDA's API and drives the real speak() against
the host's shared library, so it runs without NVDA and without Windows:

make -C doubletalk            # tests load libdtalk in place of dtalk.dll
sh doubletalk/nvda/tests/run.sh

It covers the load-order rules on their own — including references to files
outside the add-on's folder, and what happens when one of them is missing —
that a substitution reaches the queued bytes, that expansion happens before the
split so no piece can overrun the card, that reload swaps and detaches cleanly,
and — the check the others rest on — that the card really renders different
audio with a dictionary loaded than without.

Verified before opening this:

• native make and both mingw cross-builds are clean, and all six new entry
  points appear in the export tables of dtalk.dll and dtalk64.dll;
• the NVDA test suite passes;
• the upstream rcdict suite passes (102 unit checks, plus 12 that render both
  sides through a chip emulator and compare the audio);
• the add-on has been run under NVDA on Windows, installed from a package built
  from this branch, with the DLLs rebuilt from these sources.

Left for you

• No version bump. manifest.ini is still 0.1.12 — bumps look like your
  own commits in this history, and it is a predictable conflict. Say what you
  want and I will add it.
• The prebuilt DLLs are gitignored, so anyone building the add-on from this
  branch needs make -C doubletalk win32 win64 first.

🤖 Generated with Claude Code