Розділ 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 — списки, розділені комами, не підтримуються.

На відміну від інших endpoint-ів записів, getRecordingTextTracks приймає лише одне значення recordID. Передавання кількох ID, розділених комами, призведе до помилки або неочікуваної поведінки.

Поля відповіді

Кожен об’єкт доріжки у відповіді містить такі атрибути:

Поле Тип Опис
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 Не знайдено запису, що відповідає вказаному recording ID.

bbbserver.de Примітки

bbbserver.de: Ця кінцева точка недоступна на платформі bbbserver.de. Текстові доріжки для записів не можна отримати через API.

Поради

Це єдина стандартна кінцева точка API BigBlueButton, яка повертає JSON замість XML. Переконайтеся, що ваш API-клієнт враховує цю відмінність під час розбору відповіді.

  • Використовуйте поле lang для фільтрації доріжок за мовою під час створення UI вибору субтитрів для ваших користувачів.
  • Поле href надає пряме посилання для завантаження файлу WebVTT, яке можна використовувати з будь-яким стандартним відеопрогравачем HTML5.
  • Перевіряйте поле source, щоб відрізняти вручну завантажені підписи від автоматично згенерованих, які можуть відрізнятися за якістю.
  • Щоб додати або оновити текстові доріжки, використовуйте пов’язаний endpoint 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