# Orpheus Native Driver

Orpheus Native is an NVDA 2026 add-on for Orpheus by Dolphin. It keeps the Orpheus speech engine available in 64-bit NVDA without using the old external 32-bit NVDA synth wrapper path.

This add-on includes the Orpheus speech files it needs. It does not require the older Orpheus NVDA add-on or a separate Orpheus installation.

## What changed from the old Orpheus add-on?

Area | Old Orpheus add-on | Orpheus Native
--- | --- | ---
NVDA 2026 support | Used a compatibility wrapper to bridge NVDA 64-bit to the older Orpheus path. | Uses a smaller native host shipped with the add-on for the Orpheus speech calls needed by NVDA.
Configuration | Most advanced options lived in the old Orpheus configuration tools. | Adds an Orpheus Native panel inside NVDA Settings and an Orpheus Native settings item in NVDA's Tools menu.
Dictionary and exceptions | Used old Orpheus exception and dictionary files. | Uses a new editable dictionary stored as JSON under NVDA's configuration folder, with import and export for old Orpheus formats.
Voice settings | Voice, language, and some extra parameters were handled through the old driver and tools. | Exposes voice, variant, pitch, intonation, head size, voicing, skim reading level, word pause, and phrase pause through NVDA's normal synth settings ring where practical.
Updates | Updated manually. | Can check Andre's private update feed manually or daily in the background.

## Selecting Orpheus Native

1. Open NVDA's Synthesizer dialog.
2. Choose Orpheus Native.
3. Choose the language and voice you want through NVDA's normal voice and variant settings.
4. Save NVDA's configuration if you want Orpheus Native to remain selected after restart.

During an Orpheus Native update, the Orpheus voice may stop briefly while the native host executable is replaced. When the update has completed, NVDA restarts automatically.

## Synth settings

Orpheus Native uses NVDA's normal synth settings ring for the settings most users change while listening.

Setting | Purpose
--- | ---
Rate | Controls speech speed.
Volume | Controls speech volume.
Pitch | Controls pitch using NVDA's 0 to 100 scale. Pitch 50 is treated as the selected Orpheus voice's normal pitch.
Intonation | Controls the current Orpheus voice's intonation value.
Head size | Controls the current Orpheus voice's head-size attribute. 50 is neutral.
Voicing | Controls the current Orpheus voice's voicing attribute.
Voice | Selects the Orpheus language or voice group exposed to NVDA.
Variant | Selects a voice within the current Orpheus language or voice group, such as Synthetic Dave or Synthetic Andy.
Skim reading level | Controls Orpheus skim-reading behavior where supported by the engine.
Word pause | Adds or removes a pause between words on a 0 to 100 scale.
Phrase pause | Adds or removes a pause between phrases on a 0 to 100 scale.

## Orpheus Native settings panel

Open NVDA Settings and choose Orpheus Native, or use NVDA's Tools menu and choose Orpheus Native settings.

The panel contains the native dictionary editor, registry setting save/restore controls, and the manual update checker.

## Dictionary editor

Orpheus Native applies dictionary replacements before sending text to Orpheus. The active dictionary is stored here:

`%APPDATA%\nvda\orpheusNative\dictionary.json`

Keeping the dictionary outside `nvda.ini` avoids filling NVDA's main configuration file with many pronunciation entries. If this file does not exist yet, Orpheus Native starts with a bundled baseline dictionary containing useful entries from Andre and Derek. Once you save changes, your personal dictionary is stored in the external JSON file above.

### Dictionary entry fields

Field | Meaning
--- | ---
Text | The text Orpheus Native should look for.
Replacement | The replacement text or Orpheus pronunciation text to send to the engine.
Match type | Whole word, Anywhere, Starts with, Ends with, or Regular expression.
Case sensitive | When enabled, the entry only matches the exact upper/lowercase form.

### Import and export

- Import old .exc: imports entries from the old Orpheus exception file when available.
- Import dictionary file: imports Orpheus Native JSON or old Orpheus text dictionaries.
- Export: exports either full Orpheus Native JSON or old Orpheus-compatible text dictionary format.

Old Orpheus text dictionaries use a third column for match type. Orpheus Native maps those values as follows:

Old flag | Orpheus Native match type
--- | ---
A | Anywhere
B | Starts with
E | Ends with
W | Whole word

When importing, exact duplicates are skipped. If the import contains entries for words that already exist with different pronunciations or match types, Orpheus Native asks whether to import only new words or all non-duplicate entries.

## Registry settings snapshot

Some Orpheus settings still live in Dolphin's original registry area. The Orpheus Native settings panel can save those registry settings into the NVDA profile and restore them later. This is useful when moving a configured NVDA profile to another machine.

## Updates

Use Check for updates in the Orpheus Native settings panel to check Andre's private update feed. The add-on also performs a daily background check.

Updates are downloaded from `https://onj.me/nvda` and are verified by file size and SHA-256 hash before NVDA installs them.

## Known notes

- This add-on is for NVDA 2026 and later. NVDA 2025 used 32-bit add-on code and does not need this native path.
- The add-on ships the Orpheus speech files needed by Orpheus Native.
- Some old Orpheus configuration options, such as sound-card routing, are left to NVDA or Windows rather than duplicated in the add-on.
- Balance, bass lift, and high lift are not exposed because testing showed unsafe values could make speech disappear.

## Changes

- 1.1.7: Updated the bundled baseline dictionary with additional pronunciation corrections.
- 1.1.6: Restored the full bundled Orpheus runtime files after testing showed the slimmer package could stop speaking intermittently on some systems. Keeps the self-update race fixes from 1.1.4 and 1.1.5.
- 1.1.5: Fixed a second Orpheus Native self-update race where startup cleanup could delete the staged update folder before the external apply helper moved it into place.
- 1.1.4: Fixed the Orpheus Native self-update helper so it no longer deletes the staged update folder before the external apply step can replace the running add-on.
- 1.1.3: Slimmed the bundled Orpheus runtime by removing unused legacy SAM files, old help files, old document files, and the old external configuration tool from the add-on package. Switched the private update feed to a stable package filename, with version, size, and SHA-256 carried by the JSON update manifest.
- 1.1.2: Added startup cleanup for stale Orpheus Native updater helper scripts, so a helper left behind by an older updater build cannot trigger a later clean NVDA restart. Added updater-helper tracing so any future unexpected restart can be tied to an exact update-helper action.
- 1.1.1: Hardened the private update helper so update scripts are unique, one-shot, clean up stale helper files, and remove themselves after restarting NVDA. This prevents a delayed second clean restart after an update has already completed.
- 1.1.0: Added Head size and Voicing controls for the current Orpheus voice, using the same voice record block as Intonation. Fixed Word pause and Phrase pause so the synth ring and NVDA settings dialog report matching 0 to 100 values while Orpheus still receives the correct internal pause values.
- 1.0.0: First stable private Orpheus Native build. Added the native host driver, NVDA settings panel, external JSON dictionary, old dictionary import/export, registry settings save/restore, intonation support, conservative Orpheus pause settings, bundled baseline dictionary, and private self-hosted updates.

## Source code

The source archive for this add-on and its native host is available from onj.me/nvda/orpheusNative-source.zip.