14.4.1 Using a Windows Setup Build ¶

Run the development Setup executable to install Emacsvox Windows for your account. The wizard identifies Emacsvox and its included Emacs/Omnivox versions. No administrator privileges or network connection are required. A desktop shortcut is optional; a Start menu group is created unless disabled for an unattended installation. The final page explains startup/removal and offers Test speech for two announcements and Start Emacsvox. Finish runs selected actions and closes Setup.

The default directory is %LOCALAPPDATA%\Emacsvox\Desktop Dev. Launch through Start or its shortcut. Rerun Setup to repair missing files or upgrade a development build. First close the Emacsvox session using that installation; Setup does not close it. Locally edited application files prevent replacement so they can be preserved.

Windows Settings or the Start uninstall entry removes the application while retaining personal data by default. Optional cleanup separately lists sizes for logs/cache, this Emacs profile (including welcome preference), and unused downloads in the shared Omnivox library. Leave choices unchecked for reinstallation. Shared palettes/settings outside the profile stay. Unattended removal always preserves personal data.

Active voices, voices referenced by another profile, and files retained by a speech session stay with an explanation. Disable and Apply active downloads, then close the sessions using them before cleanup. Imported originals and system voices are never removed, and directory links are not followed. Development Setup builds are test artifacts; these instructions do not imply that a stable release installer includes this branch’s interface.

14.4.2 Guided Windows x64 Installation ¶

You need PowerShell 5.1 or newer, Git, network access, and working Windows audio with a speech voice. Put the checkout on a local Windows drive, not a WSL or network path. To follow this development manual, select its branch:

git clone --branch ui-experiments https://github.com/bartbunting/emacsvox.git
Set-Location emacsvox
.\bin\emacsvox-install.ps1 -Role Desktop -Check
.\bin\emacsvox-install.ps1 -Role Desktop

Skip cloning for an existing checkout and inspect its branch/local changes before updating it. The check reports selected Emacs and paths without downloads, configuration writes, or audio.

The installer reuses native Emacs 30.2 or newer. For a checksum-verified complete GNU Emacs 31.1 Windows release, use:

.\bin\emacsvox-install.ps1 -DownloadEmacs -Check
.\bin\emacsvox-install.ps1 -DownloadEmacs

This includes runtime libraries without a compiler/MSYS2. Alternatively select a separately installed prebuilt Windows Emacs with -Emacs and its bin/emacs.exe. -BuildEmacs explicitly builds 31.1 through a private MSYS2 UCRT64 toolchain; it can require several gigabytes and substantial downloading. No source build begins without that choice. The installer then prepares the pinned Omnivox core and Emacsvox, reusing installed components and verified cache on later runs.

-Emacs "C:\path\to\Emacs\bin\emacs.exe" selects an existing executable. Explicit -Emacs, environment EMACS, and local.mk must agree and require native 30.2 or newer. -DownloadEmacs and -BuildEmacs choose their managed Emacs instead of saved/PATH selections, reuse a matching complete installation, and cannot replace an explicit choice. Choose only one.

Per-user defaults are:

• Emacs, Omnivox, isolated profile, and logs under %LOCALAPPDATA%\Emacsvox\Native.
• Private build tools under %LOCALAPPDATA%\Emacsvox\Toolchains\msys2-20260611.
• Verified archives under %LOCALAPPDATA%\Emacsvox\Downloads.
• Data-only native-install.json in the checkout, ignored by Git.

-InstallRoot, -ToolchainRoot, and -CacheDirectory choose other local paths. The MSYS2 tool path must have no spaces; set -ToolchainRoot if needed. Checkout and Emacs paths may contain spaces. Personal initialisation, system PATH, Windows services, and JAWS settings remain unchanged.

-Offline -CacheDirectory "C:\path\to\archives" forbids downloads and verifies required cached archives before changes. Missing/damaged archives stop it. Offline supports prebuilt/existing Emacs, not -BuildEmacs. Read-only -Check reports the plan without testing cached archives or playing audio.

Source archives are checksum-pinned. MSYS2 compiler packages use signed rolling repositories, and installed versions are recorded. Managed source builds disable Lisp native compilation and include runtime DLLs, so launch needs no MSYS2 on PATH.

The final test opens a temporary native Emacs, verifies both streams, speaks two announcements, and closes that test. Confirm both by listening. After -NoAudioCheck, perform the explicit check before acceptance:

.\bin\emacsvox.ps1 -Diagnose
.\bin\emacsvox.ps1 -Check
.\bin\emacsvox.ps1

The last command opens the isolated desktop with Windows speech by default. OMNIVOX_ENGINE remains an explicit selection for separately configured engines. Native optional-engine installation, ARM64, and other native roles are not supplied by this guided installer.

After source updates, rerun it before launching. It preserves source edits and refreshes compiled files. Missing/stale compilation stops launch with that instruction. Keep named build logs after failure. Inspect incomplete installations before moving or choosing another directory; unknown partial trees are not overwritten.

Muting JAWS speech does not disable its shortcuts. If M-< or M-> is intercepted, try JAWSKey+3 before the key. Bart’s workstation-config repository supplies the separate Emacs-specific JAWS override used on the test workstation.

14.4.3 Manual Native Installation ¶

This route requires native Emacs 30.2 or newer already installed. It does not acquire Emacs or replace the guided x64 checks. Set $Emacsvox to the absolute checkout path and continue in one PowerShell window.

14.4.4 Download And Verify Omnivox ¶

Set $Platform for the host. The normal Intel/AMD x64 example is:

$Version = "1.18.0"
$Platform = "windows-x64" # Use windows-arm64 only on Windows on ARM.
$DownloadDir = Join-Path $env:USERPROFILE "Downloads\omnivox-$Version"
$Archive = "omnivox-$Version-$Platform.zip"
$ReleaseUrl = "https://github.com/bartbunting/omnivox/releases/download/v$Version"

New-Item -ItemType Directory -Force $DownloadDir | Out-Null
$ArchivePath = Join-Path $DownloadDir $Archive
$ChecksumPath = Join-Path $DownloadDir "sha256sums.txt"
Invoke-WebRequest -UseBasicParsing "$ReleaseUrl/$Archive" -OutFile $ArchivePath
Invoke-WebRequest -UseBasicParsing "$ReleaseUrl/sha256sums.txt" -OutFile $ChecksumPath

$Pattern = '\s+\*?' + [regex]::Escape($Archive) + '$'
$ChecksumLine = Get-Content $ChecksumPath |
  Where-Object { $_ -match $Pattern } |
  Select-Object -First 1
if (-not $ChecksumLine) { throw "No published checksum for $Archive" }
$Expected = ($ChecksumLine -split '\s+')[0].ToLowerInvariant()
$Actual = (Get-FileHash -Algorithm SHA256 $ArchivePath).Hash.ToLowerInvariant()
if ($Actual -ne $Expected) { throw "Checksum mismatch for $Archive" }
Write-Host "Checksum OK: $Archive"

Do not extract/run unless the final line reports Checksum OK. This unsigned Windows release may be rejected by policy; stop rather than weakening security. The existence of an ARM64 Omnivox archive does not extend Emacsvox’s supported native desktop beyond x64.

14.4.5 Install And Check The Native Server ¶

In the same PowerShell, extract everything beneath per-user LocalAppData:

$InstallDir = Join-Path $env:LOCALAPPDATA "Emacsvox\Omnivox\releases\$Version-$Platform"
New-Item -ItemType Directory -Force $InstallDir | Out-Null
Expand-Archive -LiteralPath $ArchivePath -DestinationPath $InstallDir -Force
$Omnivox = Join-Path $InstallDir "omnivox.exe"

foreach ($Required in @(
  $Omnivox,
  (Join-Path $InstallDir "espeak-ng-data\phontab"),
  (Join-Path $InstallDir "third-party-licenses\THIRD-PARTY-NOTICES.md")
)) {
  if (-not (Test-Path -LiteralPath $Required -PathType Leaf)) {
    throw "Incomplete Omnivox installation: $Required"
  }
}

& $Omnivox --version
if ($LASTEXITCODE -ne 0) { throw "Omnivox version check failed" }
& $Omnivox --list-voices
if ($LASTEXITCODE -ne 0) { throw "Omnivox voice discovery failed" }
& $Omnivox --check
if ($LASTEXITCODE -ne 0) { throw "Omnivox audio check failed" }

Require version 1.18.0 or newer, at least one Windows voice, and both tone and speech. Keep executable, espeak-ng-data, and third-party-licenses together. Do not copy/load omnivox-voices.el from the archive; that is the upstream Emacspeak adapter, not Emacsvox’s bundled one.

14.4.6 Start Native Emacsvox ¶

Keep the window so $Omnivox still identifies the verified binary. Set $Emacs to native emacs.exe and $Emacsvox if the checkout was not set above:

$Emacs = "C:\path\to\emacs\bin\emacs.exe"
# If not set above, uncomment and edit the next line:
# $Emacsvox = "C:\path\to\emacsvox"

& $Emacs --version
if ($LASTEXITCODE -ne 0) { throw "Could not run native Emacs" }
$env:TTS_PROGRAM = $Omnivox
& $Emacs -Q --no-splash --load "$Emacsvox\lisp\emacsvox-setup.el"

Require Emacs 30.2 or newer. Use emacs.exe instead of runemacs.exe for first launch so startup errors remain in PowerShell. Direct setup loading is intentional: bin/emacsvox is POSIX; bin/emacsvox.ps1 is the guided native entry.

14.4.7 Verify Speech And Report Problems ¶

Check the isolated native session:

1. Confirm the startup introduction/ready checkpoint is audible. Note the working buffer’s name with C-e m.
2. C-h v tts-program RET should identify the verified executable’s absolute path. Leave Help and return to the working buffer by name with C-x b.
3. M-x tts-speak-version RET speaks the version; M-x omnivox-list-voices RET displays Windows voices. Finish inspecting that list, then return to the working buffer and confirm its name and mode.
4. C-n and C-p should speak the lines reached. Press C-e s to stop, then C-e l to read again: stopping does not disable later speech. To test restarting separately, run M-x tts-restart RET and confirm that speech returns without process errors. Restarting is not needed after every Stop.
5. Toggle icons twice with M-x emacsvox-toggle-icons RET. In a session starting with icons enabled, the second toggle restores them and plays an icon in addition to speech. Preserve the initial preference when testing a customised session.

If direct --check fails, diagnose Omnivox/Windows audio first. If it passes but the server cannot be found in Emacs, confirm the same PowerShell’s $env:TTS_PROGRAM is absolute and Test-Path $env:TTS_PROGRAM returns True. For a process that exits, retain PowerShell errors, *Messages*, Windows version/architecture, and full emacs.exe --version and omnivox.exe --version.

After acceptance, put the same selection before setup in your init file:

(setenv "TTS_PROGRAM"
        "C:/Users/NAME/AppData/Local/Emacsvox/Omnivox/releases/1.18.0-windows-x64/omnivox.exe")
(load-file "C:/path/to/emacsvox/lisp/emacsvox-setup.el")

Replace both paths. This deliberately starts with an absolute executable. Adding its directory to exec-path is optional until selecting omnivox by short name. Native desktop support remains x64; remote speech is a separate preview.