Версия API: 4.x последняя 3.x

Вы просматриваете документацию API для BigBlueButton 3.x. Текущая версия — BigBlueButton 4.x. Планируете обновление? В руководстве по миграции перечислены все изменения, которые необходимо внести в ваши вызовы API.

Глава 15 GET POST

getRecordingTextTracks – Текстовые дорожки

Эндпоинт getRecordingTextTracks возвращает список всех дорожек субтитров и подписей, связанных с определённой записью. В отличие от большинства эндпоинтов API BigBlueButton, ответ возвращается в формате JSON, а не XML.

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

GET/POST https://api-guide.bbbserver.com/bigbluebutton/api/getRecordingTextTracks?<parameter>&checksum=replace-with-checksum

Поддерживаются методы GET и POST. При использовании POST отправляйте параметры как application/x-www-form-urlencoded в теле запроса.

Параметры

Параметр Тип Описание
recordID String Обязательно. Идентификатор записи, для которой вы хотите получить текстовые дорожки. Принимается только один recording ID — списки, разделённые запятыми, не поддерживаются.

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

Поля ответа

Каждый объект дорожки в ответе содержит следующие атрибуты:

Поле Тип Описание
href String URL для скачивания файла текстовой дорожки в формате WebVTT. URL содержит одноразовый токен, срок действия которого истекает через час.
kind String Тип текстовой дорожки в соответствии со спецификацией элемента видео HTML5. Возможные значения: subtitles или captions.
label String Отображаемое имя, показываемое в меню выбора субтитров в интерфейсе воспроизведения записи.
lang String Языковой тег согласно RFC 5646 (например, en-US, de-DE, pt-BR).
source String Источник текстовой дорожки. Известные значения: live (транскрибирование в реальном времени во время конференции), automatic (автоматическое создание с помощью распознавания речи), upload (загрузка вручную).

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

curl --request GET \
    "https://api-guide.bbbserver.com/bigbluebutton/api/getRecordingTextTracks?recordID=replace-with-recording-id&checksum=replace-with-checksum"

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

Успех

{
  "response": {
    "returncode": "SUCCESS",
    "tracks": [
      {
                "href": "https://api-guide.bbbserver.com/bigbluebutton/textTrack/replace-with-token/replace-with-recording-id/subtitles_de-DE.vtt",
        "kind": "subtitles",
        "label": "Deutsch",
        "lang": "de-DE",
        "source": "upload"
      },
      {
                "href": "https://api-guide.bbbserver.com/bigbluebutton/textTrack/replace-with-token/replace-with-recording-id/subtitles_en-US.vtt",
        "kind": "subtitles",
        "label": "English",
        "lang": "en-US",
        "source": "live"
      }
    ]
  }
}

Ошибка — отсутствует ID записи

{
  "response": {
    "returncode": "FAILED",
    "messageKey": "missingParamRecordID",
    "message": "You must specify a recordID."
  }
}

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

Ключ сообщения Описание
checksumError Значение checksum недействительно или не соответствует параметрам запроса.
missingParamRecordID Обязательный параметр recordID не был передан в запросе.
noRecordings Не найдена запись, соответствующая указанному идентификатору записи.

Советы

Как и putRecordingTextTrack, эта конечная точка возвращает JSON вместо XML. Убедитесь, что ваш API-клиент учитывает это различие при разборе ответа.

  • Используйте поле lang для фильтрации дорожек по языку при создании интерфейса выбора субтитров для ваших пользователей.
  • Поле href содержит ссылку для скачивания файла WebVTT. Ссылка содержит одноразовый токен, действующий в течение часа, поэтому скачайте файл сразу, а не сохраняйте и не встраивайте ссылку.
  • Проверяйте поле source, чтобы различать субтитры, загруженные вручную, и автоматически сгенерированные, качество которых может отличаться.
  • Чтобы добавить или обновить текстовые дорожки, используйте связанную конечную точку putRecordingTextTrack.

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

Эндпоинт getRecordingTextTracks был добавлен позже в ходе развития API BigBlueButton и с самого начала был спроектирован так, чтобы возвращать JSON. Это исключение из общего правила, согласно которому ответы API BigBlueButton используют XML. Ваш клиентский код должен соответствующим образом учитывать это различие форматов.

Нет. В отличие от других эндпоинтов записей, принимающих списки, разделённые запятыми, getRecordingTextTracks принимает только один recordID на запрос. Чтобы получить дорожки для нескольких записей, необходимо отправить отдельные вызовы API для каждой записи.

Текстовые дорожки предоставляются в формате WebVTT (Web Video Text Tracks), стандартном формате субтитров для воспроизведения видео HTML5. Файл можно загрузить напрямую по URL, указанному в поле href ответа.

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

Известные значения: live (создано во время конференции посредством транскрибирования в реальном времени), automatic (создано автоматически с помощью распознавания речи) и upload (загружено пользователем вручную).
Руководство по API BigBlueButton