> For the complete documentation index, see [llms.txt](https://docs.itranslator.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.itranslator.app/amazing-features/voice-features.md).

# Voice Features

{% hint style="info" %}
All Voice Features require [iTranslator PRO](https://itranslator.app/premium) and the **Manage Server** permission.
{% endhint %}

## Overview

The Voice system bundles two related capabilities under a single `/voice` command:

* **Text-To-Speech (TTS)** — turn any text into spoken audio, either played live in your voice channel or delivered as an audio file.
* **Speech-To-Text (Transcription)** — let iTranslator join your voice channel and produce a live transcript in a dedicated thread, with pause/resume controls and exportable files.

All subcommands live under the same base command:

| Command             | What it does                                                             |
| ------------------- | ------------------------------------------------------------------------ |
| `/voice help`       | Display your remaining TTS/transcription quotas and the next reset date. |
| `/voice tts`        | Generate speech from text and play it live in your voice channel.        |
| `/voice tts-file`   | Generate speech from text and upload it as an audio file.                |
| `/voice transcribe` | Start a live transcription session in your voice channel.                |

## Monthly Quotas

Every Pro user is billed against two pooled monthly quotas, shared across all servers where they activate Pro:

| Resource           | Monthly allowance      |
| ------------------ | ---------------------- |
| TTS characters     | **100,000 characters** |
| Transcription time | **24 hours** of audio  |

`/voice help` shows your current remaining balance and the exact reset timestamp. **Quotas reset automatically on the 1st of each month.**

***

## Text-To-Speech (Live) — `/voice tts`

iTranslator joins your current voice channel and plays the synthesized audio.

**How to use it:**

1. Join a voice channel iTranslator has access to.
2. Run `/voice tts` with a voice and your text.
3. iTranslator connects, plays the generated audio, then disconnects when finished.

**Parameters**

| Parameter | Description                                                                       |
| --------- | --------------------------------------------------------------------------------- |
| `voice`   | The voice used to read the text. See [Available Voices](#available-voices) below. |
| `text`    | The text to convert to speech (up to 4,096 characters per call).                  |

{% hint style="warning" %}
iTranslator can only handle one voice session at a time per server. If it is already connected (e.g. running a transcription, or playing another TTS), the command will be rejected.
{% endhint %}

## Text-To-Speech (File) — `/voice tts-file`

Same as the live version, except the audio is uploaded as a file in the format you choose — no voice channel needed.

**Parameters**

| Parameter         | Description                                                                 |
| ----------------- | --------------------------------------------------------------------------- |
| `voice`           | The voice used to read the text. See [Available Voices](#available-voices). |
| `response-format` | Output audio format: `mp3`, `opus`, `aac`, `flac`, `wav`, or `pcm`.         |
| `text`            | The text to convert to speech (up to 4,096 characters per call).            |

### Available Voices

iTranslator currently supports the following voices:

* `alloy`
* `echo`
* `fable`
* `nova`
* `onyx`
* `shimmer`

***

## Live Transcription — `/voice transcribe`

iTranslator joins your voice channel and writes everything spoken into a dedicated **thread** attached to the channel where you ran the command. The transcript updates in near real-time and can be paused, resumed, stopped, or exported.

**How to use it:**

1. Join a voice channel iTranslator has access to.
2. Run `/voice transcribe` from a text channel where the bot can create public threads.
3. A status embed and a transcription thread are created — speak normally and watch the transcript flow in.

**Parameters**

| Parameter     | Required | Description                                                                                                                       |
| ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `language`    | No       | Forces the transcription language. If omitted, the language is auto-detected per chunk.                                           |
| `combined`    | No       | If `true`, all speakers are merged into a single feed. If `false` (default), each speaker gets their own webhook-styled messages. |
| `ignore-bots` | No       | If `true` (default), audio coming from other bots is skipped.                                                                     |

### How the session looks

After running the command, iTranslator posts a status embed with:

* The current **state**: 🔴 Recording / ⏸️ Paused / ✅ Ended
* The **initiator** of the session
* The active **duration** versus the session limit
* Three control buttons:
  * **Pause / Resume** — temporarily stop or resume recording.
  * **Stop** — end the session immediately.
  * **Generate file** — export the transcript as a `TXT` or `SRT` file.

Transcribed messages are then delivered into the thread, either with each speaker’s name and avatar (per-user mode) or as a single timestamped feed (combined mode).

{% hint style="info" %}
Only the **initiator** of the session, or members with the **Manage Server** permission, can use the Pause / Stop / Generate-file buttons.
{% endhint %}

### Session limits

| Limit                         | Value                                      |
| ----------------------------- | ------------------------------------------ |
| Maximum session duration      | **30 minutes** of active recording         |
| Simultaneous speakers tracked | **5 users** per session                    |
| Update interval               | New transcript chunks every **10 seconds** |

If more than 5 users speak at the same time, iTranslator transcribes the first 5 it heard and posts a one-time notice in the thread for each user it had to skip.

### Why does iTranslator stop on its own?

A transcription session can end for several reasons:

* **Manual** — someone pressed the **Stop** button.
* **Automatic** — the 30-minute duration limit was reached.
* **Quota** — the Pro user’s monthly transcription time ran out mid-session.
* **Disconnected** — the bot was kicked, lost permissions, or the voice channel was deleted.

In every case, a status message is posted in the thread to explain what happened, and the embed is updated to `✅ Ended`.

### Exporting the transcript

Click **Generate file** at any time during or after the session to download the transcript:

| Format | Content                                                                     |
| ------ | --------------------------------------------------------------------------- |
| `TXT`  | Plain text with timestamps and speaker names.                               |
| `SRT`  | Subtitle file (timestamps + text) ready to be loaded by most video players. |

The file is generated from the current state of the session, so you can export at any point — not only at the end.

### Combined vs Per-User mode

|              | Per-User (default)                                                            | Combined (`combined: true`)                                                    |
| ------------ | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| **Delivery** | One message per speaker, with their name & avatar (via webhook).              | A single stream of messages where each line is prefixed with the speaker name. |
| **Best for** | Multi-speaker conversations where you want to clearly identify who said what. | Note-taking, meeting summaries, or single-speaker sessions.                    |

{% hint style="warning" %}
Per-user mode uses Discord **webhooks** to keep each speaker’s identity. If iTranslator cannot create or use a webhook in the parent channel (e.g. missing permissions), it falls back to plain messages and posts a warning in the thread.
{% endhint %}

### Required permissions for transcription

For `/voice transcribe` to succeed, iTranslator needs to be able to:

* **Connect** to the voice channel you’re in.
* **Send messages** in the text channel where you ran the command.
* **Create public threads** in that text channel.
* **Manage webhooks** in the parent channel (optional — needed for per-user mode; otherwise the bot falls back to plain messages).

***

## Tips

* Run `/voice help` first to make sure you still have quota for the month.
* Want a quick voice memo without joining a channel? Use `/voice tts-file` and pick `mp3` or `opus`.
* For meetings, run `/voice transcribe` from a dedicated text channel — the thread keeps everything organized and easy to export at the end.
* The **language** parameter is optional but recommended for multilingual servers — it locks the transcription language and prevents auto-detect from switching mid-conversation.