Производительность
Замеры осуществлялись разными людьми с помощью нашего бенчмарка на разных устройствах и разных интернет-соединениях. Вот результаты:
Real-Time Factor
< 1 - скорость обработки быстрее real-time.
Данные измерения получены для формата linear16 (raw PCM) без декодирования.При использовании сжатых форматов (opus, ogg-opus, mp3, aac и др.) к задержке добавляется 50–100 мс на декодирование в зависимости от кодека.Фактические значения latency зависят от скорости вашего интернет-соединения и могут отличаться.
Важно Токен передаётся заголовкомAuthorization: Bearer <ваш_токен>либо query-параметромtoken. Если переданы оба, приоритет у заголовка.
Из браузера доступен только query-параметр: WebSocket API не позволяет задавать
заголовки. Учитывайте, что токен в URL попадает в историю браузера и журналы
промежуточных прокси — для серверных интеграций предпочтительнее заголовок.
Пример потоковой транскрибации
Подключение к WebSocket
Подключение к WebSocket
Установите WebSocket-соединение с указанием токена авторизации.URL для подключения:Либо без токена в URL — с заголовком, как в REST-части API:Параметры подключения:
Формат аудио для отправки:
- Поддерживаемые частоты: 8000, 16000, 22050, 32000, 44100, 48000 Hz
- Каналы: 1 (mono) или 2 (stereo)
- Рекомендуемый формат: linear16 (int16 PCM, little-endian)
Отправка аудио
Отправка аудио
Отправляйте аудиоданные как бинарные WebSocket-сообщения.
Совет Размер чанков может быть произвольным. Сервер буферизует данные и обрабатывает их блоками по 300ms.
Авторизация заголовком (PCM16, 16000 Hz)
Авторизация заголовком (PCM16, 16000 Hz)
Серверным интеграциям удобнее передавать токен заголовком — тем же, что и в
REST-части API. Пример для телефонного профиля: raw PCM16, mono, 16000 Hz.
Параметр
additional_headers доступен в библиотеке websockets начиная с версии
14.0. В более ранних версиях используйте extra_headers.Получение результатов
Получение результатов
Сервер отправляет промежуточные результаты по мере обработки аудио.Промежуточный результат (type: partial):Финальное сообщение (type: final):При завершении сессии (отправка пустого сообщения или закрытие соединения):
Промежуточный результат приходит на каждые 300 мс звука, в том числе с пустым
chunk_text. Уже отданный текст не переписывается: новый текст только дописывается
в конец, поэтому расшифровку можно собирать по chunk_text.Таймкоды. start и end — секунды от первого отправленного отсчёта звука. Время
считается по самому звуку, поэтому не зависит от темпа отправки: ни от пауз между
сообщениями, ни от отправки быстрее реального времени. Точность — обычно в пределах
0.1 с, у отдельных слов до 0.2 с.- Каждое слово приходит в
wordsодин раз — в сообщении, где оно закончилось. Последнее слово, которое ещё произносится, придёт в одном из следующих сообщений. - Фраза приходит в
phrases, когда после неё наступила пауза не короче 0.6 с, или в последнем сообщении передfinal. Обычно это 1–1.5 с после конца фразы. Слова фразы к этому моменту уже пришли вwords. Речь без пауз делится на фразы не длиннее 60 с. - Склеенные по порядку
phrasesсодержат все слова сессии, ровно по одному разу. Для субтитров и строк расшифровки удобнее братьphrases, для подсветки слов в реальном времени —words.
Форматирование текста
Форматирование текста
С параметром В сообщении Когда после паузы предложение закончено, оно переходит в
formatting=true в каждом промежуточном результате появляется блок
formatted — тот же текст, но в читаемом виде: со знаками препинания, заглавными
буквами, буквой «ё», а числа, даты, время, суммы, телефоны, адреса и e-mail записаны
цифрами и символами.config в ответ придёт "formatting": true.committed и больше не
изменится:Как показывать:
formatted.textвсегда начинается сformatted.committed. Показывайтеcommittedкак есть, а остатокtextзаменяйте целиком в каждом сообщении: хвост незаконченного предложения может переписываться (например, запятая появляется, когда прозвучат следующие слова).- Число в конце незаконченного предложения остаётся словами, пока не прозвучит следующее слово или предложение не закончится: «четырнадцать тридцать» → «14:30».
- Предложение считается законченным после паузы в речи от 0.6 с, если по смыслу оно завершено, или в конце записи. Точку в конце незаконченного предложения сервер не ставит. Длинная речь без пауз фиксируется частями примерно по 40 с (около 100 слов), граница части может прийти посреди предложения. На паузе посреди фразы изредка появляется лишняя точка.
- Итоговый текст сессии —
formatted.textпоследнего сообщенияpartialпередfinal: в нём весь текст зафиксирован (textсовпадает сcommitted). - Остальные поля не меняются:
chunk_text,full_text,wordsиphrases— по-прежнему исходный текст без форматирования, таймкоды относятся к нему. - Без
formatting=trueблокаformattedв сообщениях нет.
formatted может перестать обновляться до конца сессии. Распознавание при этом не
прерывается: если formatted.text перестал меняться, а full_text растёт,
показывайте full_text.Обработка ошибок
Обработка ошибок
При возникновении ошибок сервер отправляет сообщение с описанием проблемы.Сообщение об ошибке (type: error):Пример ошибки авторизации:Коды ошибок:
HTTP 403 при подключении — токен не передан или неактивен. Соединение
отклоняется на этапе рукопожатия, поэтому описания причины в ответе нет:
проверьте, что токен передан заголовком либо query-параметром, и что ключ
активен в личном кабинете.Коды закрытия WebSocket:
Полный пример с микрофоном
Полный пример с микрофоном
Пример потоковой транскрибации с микрофона в реальном времени.
Зависимости Для работы с микрофоном установите: pip install pyaudio websockets
Поддерживаемые кодеки
API поддерживает широкий спектр аудиокодеков. Для минимальной задержки рекомендуется использовать raw PCM форматы.Рекомендуемые форматы (минимальная задержка)
Рекомендуемые форматы (минимальная задержка)
Raw PCM форматы — без накладных расходов на декодирование:
Эти форматы обрабатываются напрямую без декодирования, что обеспечивает минимальную задержку.
Сжатые форматы
Сжатые форматы
Lossless:
Современные кодеки:
Lossy форматы:
Контейнерные форматы:
Телефонные кодеки
Телефонные кодеки
Для интеграции с телефонными системами поддерживаются узкополосные кодеки:
Телефонные кодеки оптимизированы для узкой полосы пропускания.
Рекомендуется использовать с
sample_rate=8000.Примеры интеграции с UI
Мы подготовили готовые примеры для интеграции потоковой транскрибации в ваше веб-приложение. Выберите пример для вашего фреймворка:Интеграция в браузер (JavaScript)
Интеграция в браузер (JavaScript)
Пример интеграции потоковой транскрибации в веб-приложение с использованием Web Audio API.HTML-разметка:
React компонент
React компонент
Готовый React-компонент для потоковой транскрибации.
Vue 3 компонент
Vue 3 компонент
Пример компонента для Vue 3 с Composition API.