TTS configuration

Coming in 0.1.7 — not released yet. Not included in public 0.1.6. Use matching TTS-capable server and clients.

See Server TTS for Lua and TTS voices for reference samples.

Installation on Windows and Linux

Two package variants are prepared for the upcoming release on each OS; this page does not announce a public download. WITH TTS includes an application-local Python 3.12 interpreter, isolated CPU inference libraries, both engine models and language data. Extract the entire package and use the normal server launcher. No system Python, pip, Git or CUDA installation is required. WITHOUT TTS omits the Python/ML runtime and models; TTS defaults to disabled. To add it later, copy the complete tts/runtime from the matching full variant, then enable TTS. Never overwrite saved recordings, own voices or credentials during this operation.

All runtime paths are package-relative. Windows uses an isolated Python module path; Linux uses a relocatable standalone interpreter and private dependency directories. Startup checks bundled dependencies/model files without loading a speech model. Missing files produce a specific error with recovery instructions. System requirements and dependency details are in TTS-PACKAGES.txt; exact bundled package versions and file hashes are in tts/runtime/runtime-manifest.json. Game clients do not need any of these dependencies.

Start only Start-G1RServer.cmd on Windows or ./start-g1r-server.sh on Linux. Run as an unprivileged account. Ordinary restarts do not download anything, and models remain unloaded until needed. Model processes unload after the configured idle interval. The small package works with no Python present when TTS is disabled.

Advanced source/CUDA installation (not required by the complete CPU package)

Use Python 3.11 or 3.12 and Git. Run the explicit installer from the server directory containing serverconf.cfg; it creates a separate environment for each engine under tts/runtime and initially downloads several gigabytes. It does not start anything or modify a system Python installation. Only the server owner installs these dependencies; players do not.

Windows examples:

py -3.12 tts-service/install.py --engine chatterbox_v3 --root tts/runtime --device cpu
py -3.12 tts-service/install.py --engine styletts2_uk --root tts/runtime --device cpu

Linux examples:

python3.12 tts-service/install.py --engine chatterbox_v3 --root tts/runtime --device cpu
python3.12 tts-service/install.py --engine styletts2_uk --root tts/runtime --device cpu

Use --device cuda only on a compatible NVIDIA machine with a working driver. The GPU need not be on the game server: a separate worker can be reached over authenticated HTTPS. CPU generation is asynchronous but is not guaranteed to be fast enough for live conversations. Pre-render repeated lines before players need them.

Install the engine(s) once. Set workerInstallDirectory in serverconf.cfg to that installation directory, choose workerEngines, and change the single enabled switch to true. Start only Start-G1RServer.cmd on Windows or ./start-g1r-server.sh on Linux. The ordinary launcher starts the private workers automatically, waits for authenticated readiness, then starts the interactive dedicated server. No separate TTS console or start command is required. Run as an unprivileged account, not root/Administrator.

The default configuration stays workerInstallDirectory=tts/runtime on both platforms, resolved relative to serverconf.cfg, regardless of the shell's working directory. No developer-machine path belongs in a distributed configuration. The installer also records models inside that runtime using relative paths. A manually created Python venv is host-specific; it is not the relocatable runtime supplied in the complete CPU package. Do not redistribute developer venvs or generated tts/managed files.

The installer writes per-engine JSON metadata. Managed startup reuses the recorded model directories (including --reuse-model-directory); it never runs pip, installs software, downloads weights, or generates speech during startup. Models are loaded lazily. Missing installation/configuration produces a specific startup error instead of an implicit download. Starting g1rmp_server directly bypasses this process supervision: use the supplied launcher for managed TTS.

For another isolated environment on the same machine, --reuse-model-directory /path/to/prepared/engine reuses an existing model/frontend store without changing it or downloading the weights again. Both manifests must already exist. Runtime still checks the recorded hashes before loading.

Workers bind to 127.0.0.1 only. Do not expose their plain HTTP port publicly. Advanced deployments may use workerMode=external and separately managed authenticated HTTPS workers. This is not needed for normal single-launcher use. Never put the worker token or reference voices in downloadable resources.

Game server configuration

Add this section to serverconf.cfg, adjusting paths. Paths are relative to that configuration file unless absolute.

[tts]
enabled=false
workerInstallDirectory=tts/runtime
workerEngines=chatterbox_v3,styletts2_uk
voiceDirectory=tts/voices
device=cpu
cpuThreads=2
idleUnloadSeconds=120
chatterboxUrl=http://127.0.0.1:7792
ukrainianUrl=http://127.0.0.1:7793
tokenFile=tts/worker.token
dataDirectory=tts/data
timeoutSeconds=300
queueCapacity=128
pendingPerResource=16
cacheMiB=256
diskCacheMiB=2048

tokenFile must point to the same secret used by the workers. Protect it with filesystem permissions. The game server requires internal resource HTTP mode for live audio; a static external catalog alone cannot serve newly generated clips. The client resource transport currently uses HTTP. Audio integrity is protected by a session signature and SHA-256, but the audio transport is not confidential against network observers.

The shipped default is enabled=false; the launcher then does not even invoke Python. Set enabled=true after installation. workerEngines defaults to Chatterbox alone; add styletts2_uk after installing Ukrainian support. With TTS enabled, idle workers have small Python HTTP processes but no loaded models. Each model loads on its first cache miss and its entire subprocess exits after idleUnloadSeconds (default 120). The server launcher closes its workers when the server stops. A matching already-running worker is reused, not killed by a different server; a port occupied by a worker with different credentials/settings is rejected. Concurrent servers sharing a worker need a common token and identical worker/voice settings, but separate writable dataDirectory values.

Managed worker logs/configs live under tts/managed next to the server configuration. Do not edit those generated JSON files: change serverconf.cfg. Ordinary restarts preserve the secret, own voice files and stored recordings. A crashed generator reports an error; saved clips remain playable. Restart the server after correcting its worker log. Settings are read at server startup, not hot-reloaded.

Configuration reference (since 0.1.7)

Setting	Purpose
enabled	The master switch; default false. No TTS runtime is started when disabled.
workerInstallDirectory	Complete runtime for the current OS, normally tts/runtime; not a path to a single model file.
workerEngines	Comma-separated engines started by the launcher. PL needs chatterbox_v3; UK needs styletts2_uk and a reference voice.
voiceDirectory	Private operator-provisioned samples, shared by both managed engines.
device, cpuThreads	cpu in the bundled package; default two CPU threads per model process. More threads are not guaranteed to improve overall server performance.
idleUnloadSeconds	Unload an idle model subprocess; next cache miss must load it again. Saved clips do not require loading it.
chatterboxUrl, ukrainianUrl	Authenticated worker endpoints; defaults are loopback-only. Do not forward these ports to game players.
tokenFile	Private shared worker secret, generated on first managed startup. Preserve it, never put it in a resource or Lua event.
dataDirectory	Persistent generated recordings, their index and resource-private names. Back up the entire directory.
timeoutSeconds	Backend request timeout, not an audio duration or a server tick timeout.
queueCapacity, pendingPerResource	Bounded pending work globally / per resource. Reject excessive submissions instead of allocating unbounded inference work.
cacheMiB, diskCacheMiB	Compressed memory cache / persistent disk budget, not model RAM limits. Disk exhaustion is reported, not resolved by silently deleting saved dialogue.

The optional advanced workerMode=external skips managed local workers. It requires an operator-managed compatible worker; it is not needed for the supplied all-in-one packages. Server configuration is not editable by game clients. Keep test commands out of a public gamemode, or protect them with permissions and per-player quotas.

CPU package requirements and dependencies

Windows x64: a current supported Windows/Windows Server installation; system
  Universal C Runtime must be available. Python/ML libraries and Microsoft
  VC143 runtime DLLs are bundled app-locally; no separate VC installer needed.
  Linux x86_64: glibc-based Linux (not Alpine/musl), glibc >= 2.28, libstdc++6,
  libgcc-s1, libgomp1, libatomic1. Tested on Debian 13/WSL. If a shared library is
  missing, install the named OS library with your distribution's package manager.
  RAM: 8 GiB is a practical starting point for one CPU engine, 16 GiB recommended
  when both engines can render alongside a populated game server. These are
  planning recommendations, not a measured guarantee for every workload.
  Disk: several GiB for the full runtime, plus growing saved recordings.
  GPU is not required in this CPU package. CUDA is an advanced separate setup.

Bundled software:
  Python 3.12; CPU PyTorch 2.6.0 and torchaudio 2.6.0; NumPy 1.26.4;
  librosa 0.11.0; soundfile/libsndfile (OGG codec); transformers 5.2.0;
  Chatterbox V3, Perth watermark, tokenizer dependencies and weights;
  Ukrainian StyleTTS2, Stanza, accent/stress dictionaries and model weights.
  All resolved package versions and SHA-256 checksums are recorded in
  tts/runtime/runtime-manifest.json. No OmniVoice is included.