TTS (Text-to-Speech) Сервис

Автоматически сгенерировано: 2026-02-19 11:02:19

⚠️ ВАЖНО: Документация генерируется из РЕАЛЬНОГО кода (tts_service.py), а не из .env

Обзор

TTS сервис используется для генерации голосовых приветствий в CallBox. Преобразует текстовые шаблоны приветствий в WAV аудиофайлы.

Реальная технология (из кода)

CallBox использует gRPC (Yandex SpeechKit v3) для генерации речи.

Основной метод: Yandex SpeechKit

Из исходного кода tts_service.py:

import grpc
import yandex.cloud.ai.tts.v3.tts_pb2 as tts_pb2
import yandex.cloud.ai.tts.v3.tts_service_pb2_grpc as tts_service_pb2_grpc

async def _generate_via_speechkit(self, text: str, language: str) -> bytes:
    """Генерирует аудио через Yandex SpeechKit gRPC API v3"""
    ...

Параметр	Значение	Источник
Протокол	gRPC over SSL	Код: `grpc.secure_channel()`
Endpoint	`tts.api.yandexcloud.kz:443`	Конфиг: `YANDEX_SPEECHKIT_GRPC_HOST`
API Key	`AQWJYb0I***`	Конфиг: `YANDEX_SPEECHKIT_API_KEY`
Метод	`UtteranceSynthesis`	Код: `stub.UtteranceSynthesis()`

Голоса и параметры (из кода)

Маппинг голосов:

voice_map = {
    "ru": "zhanar_ru",  # zhanar_ru
    "kz": "zhanar",      # zhanar
}

Язык	Голос	Описание
ru	zhanar_ru (русскоязычная версия Жанар)
kz	zhanar (казахская версия Жанар)

Параметры синтеза (из кода)

Из tts_pb2.UtteranceSynthesisRequest:

request = tts_pb2.UtteranceSynthesisRequest(
    text=text,
    output_audio_spec=tts_pb2.AudioFormatOptions(
        container_audio=tts_pb2.ContainerAudio(
            container_audio_type=tts_pb2.ContainerAudio.WAV
        )
    ),
    hints=[
        tts_pb2.Hints(voice=voice),
        tts_pb2.Hints(role="friendly"),
        tts_pb2.Hints(speed=1.0),
    ],
    loudness_normalization_type=tts_pb2.UtteranceSynthesisRequest.LUFS,
)

Параметр	Значение	Описание
role	`friendly`	Стиль речи
speed	`1.0`	Скорость (нормальная)
normalization	`LUFS`	Нормализация громкости
format	`WAV`	Формат контейнера

Постобработка (из кода)

Конвертация для Asterisk:

# Код из _save_speechkit_audio():
# Конвертируем: WAV (22050 Hz) → WAV 8kHz mono PCM16 + loudnorm
ffmpeg_cmd = [
    'ffmpeg', '-i', temp_wav, 
    '-ar', '8000',          # 8kHz
    '-ac', '1',             # mono
    '-acodec', 'pcm_s16le', # PCM 16-bit
    '-af', 'loudnorm',      # нормализация громкости
    output_path
]

Итоговый формат: - Частота: 8000 Hz (для совместимости с Asterisk) - Каналы: Mono - Кодек: PCM 16-bit signed little-endian

Fallback: Gradio Client

Код содержит также fallback на Gradio (возможно старая реализация):

def get_gradio_client():
    from gradio_client import Client
    _gradio_client = Client(
        settings.TTS_API_URL,
        auth=(settings.TTS_API_USER, settings.TTS_API_PASSWORD)
    )

Этот метод не используется если Yandex SpeechKit работает.

Интеграция с CallBox

Архитектура (из docstring)

1. ТИПОВЫЕ ФРАЗЫ — предгенерированные wav файлы в /templates/
2. ПРОИЗВОЛЬНЫЙ ТЕКСТ — генерируется через TTS API, кешируется в /custom/{org_prefix}/
3. ИТОГОВОЕ ПРИВЕТСТВИЕ — склеенный файл в /greetings/{route_id}.wav

Процесс генерации

graph LR
    A[Редактирование маршрута] --> B[TTSService]
    B --> C[Yandex SpeechKit gRPC]
    C --> D[WAV 22050 Hz]
    D --> E[ffmpeg: 8kHz mono PCM16]
    E --> F[Сохранение в /greetings/]
    F --> G[Asterisk Playback]

Используется в

Backend: app/services/tts_service.py
API: Неявно при сохранении входящих маршрутов
Asterisk: Playback(callbox/greetings/{route_id})

Мониторинг

Логи генерации:

docker logs callbox-backend | grep "TTS|SpeechKit"

Проверка доступности Yandex Cloud:

# gRPC endpoint должен отвечать
nc -zv tts.api.yandexcloud.kz 443

Связанные компоненты

Asterisk Dialplan — воспроизведение приветствий
Incoming Routes API — управление маршрутами

Документация генерируется из реального кода tts_service.py. НЕ редактировать вручную.