Speechfony

Beta. This project is under active development. Expect rough edges.

Known gaps (tracked in Issues): multi-column PDFs, tables/code/equations, footnotes and citations, scanned PDFs (OCR), TOC/index pages, captions and sidebars, URLs/DOIs, non-English/RTL, voice & rate controls, and the entity/document map UI.

Speech uses a custom Kokoro Rust binding. Its pronunciation lexicon does not cover every company name or technical term - if something is missing or wrong, please open an issue there.

Speechfony is a desktop PDF reader with offline text-to-speech and audiobook export. Open a PDF, listen with sentence-level playback and highlighting, or export selected pages to MP3 - all powered by the Kokoro TTS model running locally on your machine.

Built with Tauri 2, React, TypeScript, and Rust.

Features

• PDF reading - scroll through pages with PDF.js, adjustable reading margins, and resume where you left off
• Listen while you read - sentence-by-sentence playback with live highlight sync
• Audiobook export - batch synthesize selected pages to MP3 (desktop app only)
• Offline TTS - Kokoro runs on-device; models download on first launch
• Hardware acceleration - CoreML on macOS, DirectML/CUDA on Windows, CUDA on Linux (when available)
• Recent documents - quick access to previously opened PDFs

Downloads

Pre-built installers are published on GitHub Releases. See Supported platforms for which builds are available.

On first launch, the app downloads the Kokoro voice model (~130 MB from Hugging Face). An internet connection is required for that one-time setup.

Supported platforms

Platform	Arch	Status	Installer
macOS	Apple Silicon (arm64)	Supported	.dmg
Windows	x64	Supported	.exe (NSIS); .msi also published
Linux	x64	Supported	.AppImage, .deb (.rpm also published)

Not supported: macOS Intel (x86_64) - ONNX Runtime 2.x has no prebuilt binaries for that target. There are also no ARM Linux or ARM Windows prebuilds. Linux installers require glibc ≥ 2.38 (e.g. Ubuntu 24.04+).

Development

Prerequisites

• Node.js (LTS)
• Rust (stable)
• Platform dependencies for Tauri - see the Tauri prerequisites for your OS

On Linux (Debian/Ubuntu):

sudo apt update
sudo apt install libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf

Setup

git clone https://github.com/pguso/speechfony.git
cd speechfony
npm install

Kokoro models (optional for dev)

End users get models automatically on first run. For local development you can pre-place files under src-tauri/resources/kokoro/:

Path	Contents
src-tauri/resources/kokoro/models/	One ONNX model (model.onnx recommended on macOS for CoreML)
src-tauri/resources/kokoro/voices/	Voice files, e.g. af_heart.bin

Download from Hugging Face. See src-tauri/resources/kokoro/MODELS.txt for model variants and performance notes.

Run

# Web UI only (no TTS / audiobook)
npm run dev

# Full desktop app
npm run tauri:dev

Scripts

Command	Description
npm run dev	Vite dev server (browser)
npm run tauri:dev	Tauri desktop app in dev mode
npm run dev:debug	Tauri dev with extra debug UI
npm run build	Build frontend
npm run tauri build	Production desktop build
npm run test:cache	Run unit tests
npm run version:sync -- <semver>	Sync version across package.json, Cargo.toml, and tauri.conf.json
npm run tag -- <semver>	Sync version, commit, push to main, create tag, and push tag (full release prep)

Environment variables

Optional tuning for synthesis (see MODELS.txt for details):

Variable	Values	Purpose
KOKORO_ORT_PROVIDER	auto, cpu, coreml, cuda, directml	ONNX Runtime execution provider (Windows auto: CUDA→DirectML→CPU)
KOKORO_COREML_COMPUTE_UNITS	all, ane, gpu, cpu_only	macOS CoreML device selection
SPEECHFONY_SYNTH_WORKERS	1–4	Parallel workers for audiobook export
SPEECHFONY_STREAM_WORKERS	1–4	Parallel workers for read-aloud stream (default 2)

Project layout

speechfony/
├── src/                    # React frontend (PDF UI, playback, export)
├── src-tauri/              # Rust backend (Kokoro TTS, PDF synth, IPC)
│   └── resources/kokoro/   # Optional bundled ONNX models and voices
├── .github/workflows/      # CI: build checks and release pipeline
├── docs/release.md         # Signing secrets and release setup reference
└── scripts/                # Release helpers (sync-version, tag-release)

Releases

Releases are automated via GitHub Actions. Pushing a version tag builds signed installers for all major platforms and uploads them to a draft GitHub Release.

One-time setup (maintainers)

Before the first release, configure the repository:

1. Workflow permissions - GitHub Settings → Actions → General → Workflow permissions → enable Read and write permissions.
2. Signing secrets - add macOS and Windows code-signing secrets under Settings → Secrets and variables → Actions.
3. Tauri config - set real values in src-tauri/tauri.conf.json under bundle.macOS and bundle.windows (replace the placeholders).

Full secret names, certificate export steps, and signing references are documented in docs/release.md.

Cutting a release

npm run tag -- 0.2.0

That syncs the version across package.json, Cargo.toml, and tauri.conf.json, commits with chore: release v0.2.0, pushes to main, creates tag v0.2.0, and pushes the tag. The tag must be v plus the semver from tauri.conf.json - the script handles that automatically.

To sync the version only (without committing or tagging), use:

npm run version:sync -- 0.2.0

After pushing the tag:

1. Open the Release workflow on the Actions tab and wait for all matrix jobs to finish.
2. Go to Releases - a draft release named Speechfony v0.2.0 will appear with assets attached.
3. Download and smoke-test installers on each platform.
4. Click Publish release when ready.

What gets built

Platform	Artifacts
macOS Apple Silicon	.dmg
Windows	NSIS .exe installer
Linux	.deb, .AppImage, and related bundles

CI workflows

Workflow	Trigger	Purpose
release.yml	Push tag v*	Build, sign, and upload release assets
build.yml	Push / PR to main	Linux build check without creating a release

Recommended IDE setup

• VS Code + Tauri + rust-analyzer