AiHummer обрабатывает речь на входе и на выходе «из коробки» — платный
речевой API не нужен. Входящий аудиофрагмент распознаётся (STT), текст запускает
обычный ход агента, а ответ озвучивается (TTS). Оба движка свободные и
локальные и работают как сайдкары:
faster-whisper для распознавания и edge-tts для синтеза.
Как проходит голосовой ход
Голосовой ход — это обычный ход агента с аудио на обоих концах:
Gateway отправляет входящее аудио в сайдкар STT (:8001, faster-whisper)
и получает текст.
Этот текст запускает обычный цикл вызова функций — те же роутер, оркестратор,
инструменты и память, что и для текстового сообщения.
Текст ответа отправляется в сайдкар TTS (:8002, edge-tts), и озвученное
аудио возвращается звонящему.
Всё это доступно через единый эндпоинт POST /v1/voice/turn: канал или клиент
передаёт аудио и получает аудио, не оркеструя шаги самостоятельно.
POST /v1/voice/turn HTTP/1.1Host: localhost:8765Content-Type: application/json{ "audio": "<клип в base64>", "format": "wav"}
[!NOTE]
Речевые возможности входят в ядро — они не привязаны к плагину SIP. Канал
SIP использует эти же движки STT/TTS для своего движка local, но речь
на входе/выходе работает для любого клиента, который вызывает /v1/voice/turn.
Голосовые сайдкары
Порт
Сайдкар
Движок
Роль
Подключается через
8001
STT
faster-whisper
речь → текст
AIHUMMER_STT_URL
8002
TTS
edge-tts
текст → речь
AIHUMMER_TTS_URL
Оба движка свободные и локальные: ничего не отправляется платному речевому
вендору. Как и любой сайдкар, gateway обращается к ним по URL, поэтому их
можно запустить рядом с gateway или указать на общий экземпляр.
Подключение
Host-native установщик прописывает URL STT и TTS за вас. Переменные:
# gateway.env — речь на входе/выходе (прописывается установщиком)AIHUMMER_STT_URL=http://127.0.0.1:8001AIHUMMER_TTS_URL=http://127.0.0.1:8002
[!TIP]
Поскольку каждый сайдкар — это просто URL, несколько gateway могут использовать
один экземпляр STT/TTS. Централизуйте более тяжёлые речевые сервисы вместо
копии на каждом хосте.
Настройка аудио-тракта
Ручки качества речи находятся в группе настроек «Media · Voice» и
конфигурируются из веб-админки — без передеплоя. Они охватывают real-time
аудио-тракт:
Ручка
Что регулирует
Duplex
Полный дуплекс (слушать во время речи) или полудуплекс
AiHummer обрабатывает **речь на входе и на выходе «из коробки»** — платный
речевой API не нужен. Входящий аудиофрагмент распознаётся (STT), текст запускает
обычный ход агента, а ответ озвучивается (TTS). Оба движка **свободные и
локальные** и работают как [сайдкары](/v1.0/architecture/sidecars):
faster-whisper для распознавания и edge-tts для синтеза.
## Как проходит голосовой ход
Голосовой ход — это обычный ход агента с аудио на обоих концах:
1. Gateway отправляет входящее аудио в **сайдкар STT** (`:8001`, faster-whisper)
и получает текст.
2. Этот текст запускает обычный цикл вызова функций — те же роутер, оркестратор,
инструменты и память, что и для текстового сообщения.
3. Текст ответа отправляется в **сайдкар TTS** (`:8002`, edge-tts), и озвученное
аудио возвращается звонящему.
Всё это доступно через единый эндпоинт `POST /v1/voice/turn`: канал или клиент
передаёт аудио и получает аудио, не оркеструя шаги самостоятельно.
## Эндпоинты
| Метод | Эндпоинт | Назначение |
|---|---|---|
| `POST` | `/v1/voice/turn` | Аудио на входе → ход агента → аудио на выходе |
| `GET` | `/v1/voice/config` | Текущая голосовая конфигурация (движки, настройки) |
```http
POST /v1/voice/turn HTTP/1.1
Host: localhost:8765
Content-Type: application/json
{
"audio": "<клип в base64>",
"format": "wav"
}
```
> [!NOTE]
> Речевые возможности входят в **ядро** — они не привязаны к плагину SIP. Канал
> SIP использует эти же движки STT/TTS для своего движка `local`, но речь
> на входе/выходе работает для любого клиента, который вызывает `/v1/voice/turn`.
## Голосовые сайдкары
| Порт | Сайдкар | Движок | Роль | Подключается через |
|---|---|---|---|---|
| 8001 | STT | faster-whisper | речь → текст | `AIHUMMER_STT_URL` |
| 8002 | TTS | edge-tts | текст → речь | `AIHUMMER_TTS_URL` |
Оба движка свободные и локальные: ничего не отправляется платному речевому
вендору. Как и любой сайдкар, gateway обращается к ним **по URL**, поэтому их
можно запустить рядом с gateway или указать на общий экземпляр.
## Подключение
Host-native установщик прописывает URL STT и TTS за вас. Переменные:
```ini
# gateway.env — речь на входе/выходе (прописывается установщиком)
AIHUMMER_STT_URL=http://127.0.0.1:8001
AIHUMMER_TTS_URL=http://127.0.0.1:8002
```
> [!TIP]
> Поскольку каждый сайдкар — это просто URL, несколько gateway могут использовать
> один экземпляр STT/TTS. Централизуйте более тяжёлые речевые сервисы вместо
> копии на каждом хосте.
## Настройка аудио-тракта
Ручки качества речи находятся в группе настроек **«Media · Voice»** и
конфигурируются из веб-админки — без передеплоя. Они охватывают real-time
аудио-тракт:
| Ручка | Что регулирует |
|---|---|
| Duplex | Полный дуплекс (слушать во время речи) или полудуплекс |
| AEC | Подавление акустического эха |
| Noise suppression | Фильтрация фонового шума до STT |
| AGC | Автоматическая регулировка усиления (нормализация уровня) |
| VAD threshold | Чувствительность детектора голосовой активности |
| Barge-in | Возможность перебить агента во время ответа |
`GET /v1/voice/config` возвращает действующую конфигурацию, чтобы клиент мог
узнать активные движки и эти настройки.
## Куда дальше
- Транспортная модель за этими сервисами:
[Сайдкары](/v1.0/architecture/sidecars).
- Диаризация, перевод, клонирование голоса и видео:
[Диаризация, перевод и клонирование](/v1.0/voice/diarization-translation-clone).
- Голос на телефонной линии:
[SIP-телефония](/v1.0/channels/sip).
AiHummer