Как сделать субтитры SRT и VTT через AssemblyAI

Перед внедрением зафиксируйте поколение API или SDK, speech model, язык, регион и формат аудио. Каталог моделей и совместимость функций меняются. Постоянный ASSEMBLYAI_API_KEY держите на backend или в менеджере секретов; в клиентское приложение допустим только специально созданный временный streaming token.

Подтверждённые данные

• SDK предоставляет export_subtitles_srt и export_subtitles_vtt.
• chars_per_caption задаёт максимум символов на caption.
• Plain text не содержит таймкодов и меток говорящих.
• Формат [Speaker] timecode строят из utterances после включения speaker labels.

AssemblyAI разделяет pre-recorded, real-time и Sync STT. Первый режим создаёт асинхронный transcript, streaming работает в WebSocket-сессии, а Sync предназначен для короткого завершённого клипа. У них разные endpoints, состояния и ограничения; переносить параметры между режимами без проверки нельзя.

Подготовка контрольного файла

1. Создайте обезличенную запись с известным текстом. Для диаризации нужны известные границы и достаточная речь каждого участника; для тональности — заранее размеченные предложения.
2. Выполните ffprobe и запишите container, codec, sample rate, channels и duration. Расширение .wav или .mp3 не гарантирует фактическое содержимое.
3. Составьте эталон: обязательные слова, язык, число спикеров, интервалы или ожидаемые captions.
4. Для A/B-теста используйте идентичные байты и меняйте один параметр. Иначе разницу нельзя отнести к модели, prompt или keyterms.
5. Не используйте реальные платёжные, медицинские и паспортные сведения. Синтетический секрет должен легко находиться точным поиском.

file: control.wav
duration_seconds: 30
sample_rate: 16000
channels: 1
expected_language: ru
expected_phrase: "заказ сорок два готов"
contains_real_personal_data: false

Это форма карточки, а не универсальные требования. Заполните её фактическими данными файла. Для streaming добавьте размер chunk, период отправки и момент намеренного обрыва.

Настройка по шагам

1. Создайте отдельный ключ тестовой среды и экспортируйте его как ASSEMBLYAI_API_KEY. Не печатайте значение в CI и shell history.
2. Выберите один режим: pre-recorded, streaming или Sync. Сверьте endpoint, модель и ограничения длительности.
3. Запустите минимальный шаблон ниже без автоматических retry. Так сохранятся исходный HTTP-код и тело ошибки.
4. Для async различайте completed, error и промежуточные статусы. Ограничьте polling общим deadline и добавьте backoff.
5. Разберите только документированные поля. Отсутствующее поле — ошибка контракта, а не пустая строка.
6. Сравните ответ с эталоном: SRT проходит валидатор, интервалы возрастают, cue непустые, кириллица сохранена, конец не выходит за длительность видео.
7. Выполните отрицательный тест: неверный формат, истёкший token, неподдерживаемая длина или повторный webhook. Система обязана отказать предсказуемо.

Готовый шаблон

srt=transcript.export_subtitles_srt(chars_per_caption=32)
open(f'{transcript.id}.srt','w',encoding='utf-8').write(srt)
assert '-->' in srt

Идентификаторы и файлы заменяются значениями из текущей документации и вашей среды. Никогда не вставляйте рабочий ключ в статью или frontend. После теста сохраните transcript id, request metadata и исходный JSON без секрета.

Вход и ожидаемый выход

Контрольный вход должен быть реалистичным для продукта: голосовое сообщение, звонок, встреча или ролик. Один диктор в тишине не проверяет контакт-центр, а десятисекундный диалог не показывает устойчивость speaker labels. Подготовьте 20–50 обезличенных кейсов, включая шум, акцент, паузы и редкие термины.

Ожидаемый выход: SRT проходит валидатор, интервалы возрастают, cue непустые, кириллица сохранена, конец не выходит за длительность видео.

Проверка текста включает не только непустое поле. Считайте WER или долю обязательных фраз, отдельно фиксируйте ошибки имён, сумм и артикулов. Для streaming сверяйте отсутствие дублей partial/final, для subtitles — порядок таймкодов, для webhook — идемпотентность.

Критерии приёмки

• формат распознан
• таймкоды растут
• cue непустые
• UTF-8 сохранён
• длительность соблюдена

Сохраняйте model used, language code, transcript id, длительность, confidence, latency и итог PASS/FAIL. Порог confidence определяйте на своей размеченной выборке: универсального безопасного значения для всех микрофонов и языков нет.