Глава 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.
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/captions/replace-with-recording-id/de-DE.vtt",
        "kind": "subtitles",
        "label": "Deutsch",
        "lang": "de-DE",
        "source": "upload"
      },
      {
                "href": "https://api-guide.bbbserver.com/captions/replace-with-recording-id/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 Не найдена запись, соответствующая указанному идентификатору записи.

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

bbbserver.de: Этот эндпоинт недоступен на платформе bbbserver.de. Текстовые дорожки для записей нельзя получить через API.

Советы

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

  • Используйте поле lang для фильтрации дорожек по языку при создании интерфейса выбора субтитров для ваших пользователей.
  • Поле href предоставляет прямую ссылку для загрузки файла WebVTT, которую можно использовать с любым стандартным видеоплеером HTML5.
  • Проверяйте поле 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