---
name: local-tts-voice-skill
description: >
  Generate voice messages using the local Chatterbox TTS server with voice cloning.
  Sends audio as Telegram voice notes.
---

# Local TTS Voice Skill

Generate voice messages locally using the Chatterbox TTS server and send them as Telegram voice notes.

## How to use

When you want to send a voice message, follow these steps:

### 0. (One-time) Upload your reference voice

Before generating any audio, upload the voice file you want to clone. You only need to do this once — the file stays on the server.

curl -s -X POST "http://<SERVER_IP>:<PORT>/upload_reference" \
  -F "files=@/path/to/your-voice-file.mp3"


The response will confirm the upload and list all available reference files on the server. Note the filename — you will use it in the reference_audio_filename field of your TTS requests.

To check what files are already uploaded:

curl -s "http://<SERVER_IP>:<PORT>/get_reference_files"

### 1. Generate the audio

Use the Chatterbox TTS server at `http://<SERVER_IP>:<PORT>`.

**Endpoint:** POST `/tts`

**English (use defaults):**
```json
{
  "text": "Your text here",
  "voice_mode": "clone",
  "reference_audio_filename": "voice-to-clone.mp3",
  "language": "en",
  "output_format": "opus",
  "split_text": false,
  "temperature": 0.8,
  "exaggeration": 0.3,
  "cfg_weight": 0.3
}
```

**Non-English languages (French, Japanese, etc.):**
```json
{
  "text": "Your text here",
  "voice_mode": "clone",
  "reference_audio_filename": "voice-to-clone.mp3",
  "language": "fr",
  "output_format": "opus",
  "split_text": false,
  "temperature": 1.0,
  "exaggeration": 0.5,
  "cfg_weight": 0.7
}
```

**Supported languages:** ar, da, de, el, en, es, fi, fr, he, hi, it, ja, ko, ms, nl, no, pl, pt, ru, sv, sw, tr, zh

Save the response to a `.ogg` file (e.g., `/tmp/output_voice.ogg`).

### 2. Send via Telegram

Use `sendVoice` with your bot token:

```bash
curl -s -X POST "https://api.telegram.org/bot{TOKEN}/sendVoice" \
  -F chat_id={CHAT_ID} \
  -F voice=@/tmp/output_voice.ogg
```

- The voice file must be in `.ogg` opus format for Telegram voice notes.

### 3. Clean up

Delete the temporary `.ogg` file after sending.

## Getting help



## Reference audio

- **Primary:** Your cloned voice file (e.g., `voice-to-clone.mp3`)
- Upload it to the Chatterbox server's reference_audio directory via the `/upload_reference` endpoint
- List available references via `/get_reference_files`

## Generation parameters

| Param | English | Non-English | Notes |
|-------|---------|-------------|-------|
| temperature | 0.8 | 1.0 | Higher = more expressive |
| exaggeration | 0.3 | 0.5 | Controls expressiveness |
| cfg_weight | 0.3 | 0.7 | Higher = more adherence to voice |
| split_text | false | false | Keep as single chunk |
| output_format | opus | opus | Required for Telegram voice |

## Style / emotion control

The Chatterbox server does not support mood instructions like the Xiaomi TTS did.
Adjust `exaggeration` and `temperature` to control expressiveness. For emotional
delivery, write the text itself to convey the tone.

## Gotchas

- Do NOT attach captions or other content to voice note messages. Voice only.