Repository navigation
Settings and Models
Settings has ten sections: Appearance, Playback, Pronunciation, Engines & models, Storage, Phones and tablets, Audiobookshelf, Local speech API, Privacy and About. On wide screens, an index on the left jumps between them.
Choose the System, Light or Dark theme, Standard or High contrast, and the reading text's Text size, Line spacing, Typeface and Letter and word spacing (with a preview). These are saved on this device only, so each browser can have its own.
These preferences are saved by the local server and shared by every browser that opens the app.
| Setting | What it does |
|---|---|
| Default voice | The reading voice. Voices whose engine isn't installed are listed as "(not installed)". |
| Playback speed | How fast audio plays, from 0.75× to 2×; pitch is preserved. |
| Speaking pace | How quickly the voice itself speaks (Kokoro voices), 0.70× to 1.40×. New audio is generated when it changes. |
| Export format | MP3 (smaller) or WAV (lossless), the starting choice in the export dialog. |
| Follow along while listening | Keeps the sentence being spoken in view. |
Reading Documents explains speed and pace in more detail.
Teach every voice how to say a word: enter the Word or name as it is written and how to Say it as, written the way it sounds, with no phonetic symbols (gnocchi → NYOH-kee, quinoa → KEEN-wah, Nguyen → Win, "Dr." → "Doctor"). Join syllables with hyphens and put the stressed one in capitals; it is read as one word, never spelled out. Hear as written and Hear respelling play the word and the respelling side by side in the current reading voice before you save. Words match whole words in any letter case; tick Only when the letter case matches for words such as "US".
Your documents' text never changes, only what is spoken. Rules apply to reading and exports, and rules for all documents to voice previews and the local speech API too; only the sentences that contain a changed word are generated again. Words added here apply to All documents. To fix a word in one document only, select it in the reader and choose Fix pronunciation (see Reading Documents). The list shows each rule's scope, All documents or Only in a document; a document's rule wins over the one for all documents there, and Change can move it to all documents. A document's rules are deleted with it.
Up to 500 words for all documents, and up to 500 more for each document; rules are plain text, never patterns. Hearing a word before saving it is limited to 30 previews a minute, of up to 200 characters each.
Each speech engine has a panel with its status (Installed, Installing, Not installed, Optional or Needs attention), hardware advice, the disk space it uses or needs, and its licence. Model files are downloaded from pinned sources and verified with SHA-256 before use.
| Engine | Role | Licence |
|---|---|---|
| Kokoro | The default engine: the 54 built-in voices. CPU only; about 1 GB of RAM while speaking. | Apache-2.0 model weights; ONNX export MIT |
| Chatterbox Turbo | Optional voice cloning for Voice Studio. Several GB to download. | MIT (code and weights) |
- Install. The install button names the engine and its download size, for example Install Kokoro. For Chatterbox Turbo, first choose how to run it (see Voice Studio). A progress bar shows the download, with Cancel. If a model download is interrupted, retrying resumes it instead of starting again.
- Remove. Remove deletes the engine's model files and clears the audio cache. Your documents and voice recordings are kept, and you can reinstall at any time. Removing Chatterbox Turbo also removes its separate environment.
- Repair. Before an engine loads its model, every file is checked against its published SHA-256 checksum (once per file, and again whenever the file changes). If a file is missing, incomplete or doesn't match, the engine shows Needs repair, names the files, and offers Repair: only the damaged files are downloaded again, each is verified before it replaces anything, and your documents, recordings, voices and other models aren't touched.
You can also install (or repair) the Kokoro model from a terminal with npm run setup, and check the
installed Kokoro files against their checksums with:
node scripts/uv-run.mjs run --frozen --project apps/server ltts models verify kokoroStorage shows the path of your data folder (on the computer only; a phone sees the sizes) and how much space is used by Voice models, Audio cache, Voice recordings, Exports and the Library database, plus the free space on that disk.
The audio cache holds generated speech so that sentences you've heard play instantly next time. It has
a limit (2 GB by default, LTTS_AUDIO_CACHE_MAX_MB); older audio is removed automatically when it's
full. Clear audio cache deletes all generated audio after you confirm. Documents, voices and models
are kept, and audio is generated again as you listen.
LAN mode, off until you switch it on, lets phones and tablets on the same Wi-Fi read and listen. The section says what a paired device can and can't do before the switch, then shows the address to open, a QR code and a one-time pairing code, the paired devices (each can be removed) and Turn off LAN mode. It turns itself off when TTSNative restarts. See Other Devices.
For advanced users: an optional, OpenAI-compatible endpoint (/v1/audio/speech) that lets
scripts, screen readers and home automation on this computer read text aloud with TTSNative
voices. It is off until you open Speech API settings and switch it on, and programs need a
token, which is shown once (only a fingerprint of it is kept). Custom voices can't be used until
you allow each one, web pages can never call it, and other devices are refused unless you allow
them (which only matters while LAN mode or network mode is on). OpenAI's voice names (alloy,
nova…) work too, each reading with a built-in Kokoro voice. The section shows the exact address
programs use, http://127.0.0.1:<port>/v1 with TTSNative's own port (under npm run dev, not the
one in your browser's address bar), and warns you when TTSNative has moved to another port since a
program last used it, as it does when its usual port is busy at startup. It also shows when the API
was last used, and the sidebar shows Speech API in use while a program is using it. See the
local speech API guide
for examples (curl, Python, the OpenAI SDK), the voice names, limits and how it is protected.
A summary of how the app treats your data: no accounts, analytics or telemetry; documents, recordings and generated audio stay on this computer; the only network requests are model downloads you start yourself, web pages you choose to import, books you send to your own Audiobookshelf and, in the Windows app, a check for new TTSNative versions on GitHub (which you can turn off under About); everything works offline once models are installed. While LAN mode is on, a LAN mode is on warning appears here, and if the server was started in network mode, a Network access is on warning (see Other Devices).
About & diagnostics lists the app and server versions, the Python runtime, your system (platform, CPU count and RAM), the GPU (or "None detected (CPU mode)"), who made the app and its licence, with a link to the source code and how to credit the project.
Version shows whether this is a stable release or a development build. In the Windows app you can Check for updates, turn automatic checks on or off, and open the data folder, the log folder and the third-party notices. From source, it says that the app updates when you pull new code. What's new and Release history show the notes of every version, one version at a time with Older and Newer, also offline; the version at the bottom of the sidebar leads here.
Copy diagnostics copies a short report to the clipboard: versions, platform, memory, GPUs, ONNX Runtime providers, disk use and whether network access is on. It contains no documents or personal data. Paste it into bug reports.
The defaults work out of the box. Server settings can be changed with environment variables, or by
copying
.env.example to .env
in the project folder. Some commonly changed ones:
| Variable | Default | Purpose |
|---|---|---|
LTTS_DATA_DIR |
./data |
Library database, audio cache, recordings and exports |
LTTS_MODELS_DIR |
<data>/models |
Verified model files |
LTTS_AUDIO_CACHE_MAX_MB |
2048 | Audio cache size |
LTTS_MAX_UPLOAD_MB |
25 | Largest accepted document |
LTTS_MAX_DOCUMENTS |
500 | Library size |
LTTS_WARM_UP_ENGINES |
true | Load Kokoro at startup for a fast first sentence |
LTTS_CLONE_WORKER_IDLE_UNLOAD_S |
600 | Free GPU/CPU memory after this many idle seconds |
The startup scripts read a few more variables: LTTS_API_PORT and LTTS_WEB_PORT (ports for
npm run dev), LTTS_NO_OPEN=1 (don't open a browser) and LTTS_SKIP_MODEL_DOWNLOAD=1. These are
read from the environment of the terminal you start the app from, not from .env.
The full list is in the
configuration guide.
These variables apply to source installs. The Windows app sets its own settings and ignores LTTS_*
variables.