Вы просматриваете документацию API для BigBlueButton 3.x. Текущая версия — BigBlueButton 4.x. Планируете обновление? В руководстве по миграции перечислены все изменения, которые необходимо внести в ваши вызовы API.
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 (загружено пользователем вручную).