roseeast/PawnTTS

---

Pawn TTS brings real-time, clientless text-to-speech (TTS) and spatial audio streaming to SA-MP and open.mp Pawn servers. Players on standard PC (GTA: San Andreas) and Android mobile launchers do not require any client modifications, ASI plugins, or external software. Audio is streamed natively through the GTA audio engine via PlayAudioStreamForPlayer with full 3D spatial sound (distance attenuation and stereo panning).

Overview

Features

Release Files

Prebuilt release packages are available in release/.

Package layout:

pawn-tts-v0.2.0/
  plugins/
    pawn_tts.so
    pawn_tts.dll
  components/
    pawn_tts.so
    pawn_tts.dll
  pawno/include/
    pawn_tts.inc
  examples/
    example.pwn
    commands.pwn
  pawn_tts.json
  README.md
  LICENSE

Compatibility

Pawn TTS does not hook RakNet, patch memory, or depend on internal server offsets. It registers standard Pawn natives and runs a high-performance HTTP stream listener to deliver audio directly to GTA game clients.

Installation

1. Install Files

For SA-MP (Legacy Plugin)

Copy the files into your server directory:

plugins/pawn_tts.so        -> Linux server plugins folder (use x86 32-bit for classic SA-MP)
plugins/pawn_tts.dll       -> Windows server plugins folder
pawno/include/pawn_tts.inc -> Pawn compiler include folder
pawn_tts.json              -> Server root folder

For open.mp (Native Component - Recommended)

Copy the files into your server directory:

components/pawn_tts.so     -> Linux server components folder
components/pawn_tts.dll    -> Windows server components folder
pawno/include/pawn_tts.inc -> Pawn compiler include folder
pawn_tts.json              -> Server root folder

For Qawno or custom build systems, place pawn_tts.inc in the include path used by your compiler.

2. Load The Plugin / Component

For SA-MP server.cfg:

plugins pawn_tts

On Linux setups where explicit extensions are required:

plugins pawn_tts.so

For open.mp config.json (Native Component Mode - Recommended):

{
  "components": [
    "pawn_tts"
  ]
}

For open.mp config.json (Legacy Plugin Mode):

{
  "pawn": {
    "legacy_plugins": ["pawn_tts"]
  }
}

3. Include In Pawn

#include <pawn_tts>

Quick Start

#include <a_samp>
#include <pawn_tts>

public OnGameModeInit()
{
    // Pre-cache frequent phrases for instant 0 ms playback
    TTS_SetProvider(TTS_PROVIDER_EDGE);
    TTS_SetVoice("en-US-GuyNeural");
    TTS_Precache("Welcome to the server!");
    return 1;
}

public OnPlayerConnect(playerid)
{
    // Private 2D stereo welcome greeting
    new requestid = TTS_Speak(playerid, "Welcome to Los Santos.");
    printf("[TTS] queued request %d", requestid);
    return 1;
}

// 3D Proximity Voice Chat: speech originates from the player character in world space
public OnPlayerText(playerid, text[])
{
    TTS_SpeakFromPlayer(playerid, text, "id", 25.0);
    return 1;
}

Native API

Callbacks

forward OnTTSGenerated(const hash[], const text[], const voice[], bool:success);
forward OnTTSRequestQueued(requestid, playerid, provider);
forward OnTTSGeneratedEx(requestid, playerid, provider, const audio_url[]);
forward OnTTSError(requestid, playerid, provider, error_code, const error_message[]);
forward OnTTSCacheHit(requestid, playerid, const cache_key[]);
forward OnTTSFallback(requestid, playerid, old_provider, new_provider);
forward OnTTSReady(playerid, const hash[], const url[], Float:x, Float:y, Float:z, Float:distance, usepos);

OnTTSGenerated

Called asynchronously when a speech synthesis request finishes:

public OnTTSGenerated(const hash[], const text[], const voice[], bool:success)
{
    if (success) {
        printf("[TTS] Audio generated: hash=%s voice=%s", hash, voice);
    }
    return 1;
}

OnTTSReady

Dispatched automatically by the include hook to play audio via PlayAudioStreamForPlayer. If you define TTS_OnTTSReady, you can customize or filter stream playback before dispatch.

Configuration

Configuration is managed via pawn_tts.json in the server root folder:

{
  "port": 7788,
  "bind_ip": "0.0.0.0",
  "public_url": "",
  "provider": "edge",
  "default_voice": "en-US-GuyNeural",
  "default_model": "",
  "default_speed": 1.0,
  "default_pitch": 0.0,
  "default_volume": 1.0,
  "worker_threads": 2,
  "cache_dir": "cache/tts",
  "cache_memory_limit": 256,
  "edge_enabled": true,
  "edge_command": "",
  "elevenlabs_enabled": false,
  "elevenlabs_api_key_env": "ELEVENLABS_API_KEY",
  "elevenlabs_command": "",
  "kokoro_enabled": false,
  "kokoro_command": "",
  "piper_enabled": false,
  "piper_command": "",
  "custom_enabled": false,
  "custom_http_url": "http://127.0.0.1:5000/tts",
  "google_legacy_enabled": true
}

The C++ core now uses a provider interface internally. Edge, Kokoro, Piper, and ElevenLabs are isolated provider modules; this repository currently exposes them through command/config adapters unless you wire a native backend in the provider module. ElevenLabs API keys must come from an environment variable such as ELEVENLABS_API_KEY and are never exposed to Pawn.

3D Spatial Audio Mechanics

When using TTS_SpeakAtPos or TTS_SpeakFromPlayer, audio streams leverage GTA San Andreas's built-in BASS audio engine:

• Distance Falloff: Audio volume decreases smoothly from the center coordinate out to the configured radius (distance).
• Stereo Panning: Audio dynamically pans between the player's left and right audio channels based on their camera and character orientation relative to the sound source.
• Client Compatibility: Fully operational on standard PC GTA:SA clients and official Android mobile launchers without any custom .asi or APK modifications.

Build From Source

This repository uses CMake (version 3.20+).

Requirements

Linux (Native x86_64)

cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

Output:

• build/plugins/pawn_tts.so (Legacy SA-MP plugin)
• build/components/pawn_tts.so (Native open.mp component)

Linux (32-bit x86 for Classic SA-MP)

cmake -B build-linux-x86 -S . \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_CXX_FLAGS="-m32" \
  -DCMAKE_SHARED_LINKER_FLAGS="-m32"
cmake --build build-linux-x86 --config Release

Output:

• build-linux-x86/plugins/pawn_tts.so (Legacy SA-MP plugin)
• build-linux-x86/components/pawn_tts.so (Native open.mp component)

Windows (Cross-compile with MinGW)

cmake -B build-win -S . \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_SYSTEM_NAME=Windows \
  -DCMAKE_C_COMPILER=i686-w64-mingw32-gcc-posix \
  -DCMAKE_CXX_COMPILER=i686-w64-mingw32-g++-posix
cmake --build build-win --config Release

Output:

• build-win/plugins/pawn_tts.dll (Legacy SA-MP plugin)
• build-win/components/pawn_tts.dll (Native open.mp component)

Troubleshooting

License

Pawn TTS is released under the MIT License.