Глава 16 POST

putRecordingTextTrack – Загрузить текстовую дорожку

Конечная точка putRecordingTextTrack позволяет загружать файлы субтитров или подписей для записи. Поддерживаемые форматы: SRT, SSA/ASS и WebVTT. Все загруженные файлы внутри системы преобразуются в WebVTT. Ответ возвращается в формате JSON.

Эта конечная точка поддерживает только запросы POST. Запросы GET не принимаются.

Конечная точка

POST https://api-guide.bbbserver.com/bigbluebutton/api/putRecordingTextTrack?<parameters>&checksum=replace-with-checksum

Файл субтитров должен быть отправлен как multipart/form-data в теле POST. Контрольная сумма вычисляется только по параметрам строки запроса URL — тело POST не включается в вычисление контрольной суммы.

Параметры URL (строка запроса)

Параметр Тип Обязательно По умолчанию Описание
recordID String Да — Идентификатор одной записи. В отличие от других конечных точек, этот параметр не принимает список, разделённый запятыми — допускается только один идентификатор записи.
kind Enum Да — Тип текстовой дорожки. Допустимые значения: subtitles или captions.
lang String Да — Языковой тег, соответствующий RFC 5646 (например, de-DE, en-US).
label String Нет Автоматически определяется из lang Отображаемое имя дорожки, понятное человеку (например, "German"). Если параметр опущен, название языка автоматически определяется из значения lang.

Тело POST (multipart/form-data)

Параметр Тип Обязательно По умолчанию Описание
file Binary Да — Файл субтитров для загрузки. Поддерживаемые форматы: SRT (application/x-subrip), SSA/ASS и WebVTT (text/vtt). Если файл отсутствует или пуст, API возвращает ответ FAILED.

Пример запроса

curl -X POST \
    "https://api-guide.bbbserver.com/bigbluebutton/api/putRecordingTextTrack?recordID=replace-with-recording-id&kind=subtitles&lang=de-DE&label=Deutsch&checksum=replace-with-checksum" \
  -F "file=@subtitles.srt;type=application/x-subrip"

Пример ответа

Успешный вызов возвращает следующий JSON: 

{
  "response": {
    "returncode": "SUCCESS",
    "messageKey": "upload_text_track_success",
    "message": "Text track uploaded successfully",
        "recordId": "replace-with-recording-id"
  }
}

Ответы с ошибками

messageKey Описание
paramError Отсутствует обязательный параметр (checksum, recordID, kind или lang). Примечание: в официальной документации это ошибочно указано как missingParameter.
noRecordings Указанный идентификатор записи не найден.
invalidKind Значение kind недопустимо. Должно быть subtitles или captions.
invalidLang Формат языкового тега недействителен. Он должен соответствовать RFC 5646.
empty_uploaded_text_track Загруженный файл был пустым или в запрос не был включён файл.

Важное поведение

Обработка текстовой дорожки выполняется асинхронно. После успешной загрузки может пройти несколько минут, прежде чем дорожка станет доступна при воспроизведении записи.

Если дорожка с тем же kind и языком уже существует, она будет перезаписана новым файлом.

Загрузка пустого файла или отправка запроса без файла не удаляет существующую дорожку. Вместо этого API возвращает ответ FAILED.

Все загруженные форматы субтитров (SRT, SSA/ASS) автоматически преобразуются в WebVTT для воспроизведения.

bbbserver.de Примечания

bbbserver.de: Эта конечная точка недоступна на платформе bbbserver.de. Загрузка субтитров через API не поддерживается.

Советы

Используйте конечную точку getRecordingTextTracks, чтобы убедиться, что загруженная текстовая дорожка была обработана и доступна для воспроизведения, прежде чем ссылаться на неё в вашем приложении.

  • WebVTT — рекомендуемый формат, так как он не требует преобразования и изначально поддерживается браузерами.
  • При загрузке нескольких языковых дорожек используйте разные языковые теги RFC 5646, чтобы случайно не перезаписать существующие дорожки.
  • Задайте описательный параметр label, чтобы помочь зрителям выбрать правильную дорожку в селекторе языка воспроизведения.
  • Помните, что checksum вычисляется только на основе параметров URL-запроса — не включайте содержимое файла в checksum.

Часто задаваемые вопросы

BigBlueButton принимает файлы SRT (SubRip), SSA/ASS (SubStation Alpha) и WebVTT (Web Video Text Tracks). Все форматы внутри системы преобразуются в WebVTT для воспроизведения. Поддерживаемые форматы помимо WebVTT определены по исходному коду и не перечислены явно в официальной документации.

Да. Вы можете вызывать конечную точку putRecordingTextTrack несколько раз с разными значениями lang, чтобы загружать дорожки для разных языков. Каждая комбинация kind и lang сохраняется как отдельная дорожка.

Существующая дорожка с той же комбинацией kind и lang будет перезаписана новым файлом. Версионирование или резервное копирование предыдущих дорожек отсутствует.

Нет. Отправка запроса без файла или с пустым файлом не удаляет существующую дорожку. API просто возвращает ответ FAILED с ключом ошибки empty_uploaded_text_track. Отдельной конечной точки для удаления текстовых дорожек нет.

Обработка выполняется асинхронно. После успешной загрузки обычно проходит несколько минут, прежде чем текстовая дорожка станет доступна при воспроизведении записи. Точная длительность зависит от нагрузки на сервер и размера файла.

Контрольная сумма вычисляется исключительно на основе параметров URL-запроса. Тело POST, содержащее файл субтитров, не участвует в вычислении контрольной суммы. Это сделано намеренно и соответствует тому, как BigBlueButton обрабатывает multipart-запросы POST.
Руководство по API BigBlueButton