Розділ 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 query — тіло 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, щоб допомогти глядачам визначити правильну доріжку в селекторі мови відтворення.
  • Пам’ятайте, що контрольна сума обчислюється лише з параметрів URL-запиту — не включайте вміст файлу до контрольної суми.

Поширені запитання

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