Kapitel 16 POST

putRecordingTextTrack – Textspur hochladen

Der Endpunkt putRecordingTextTrack ermöglicht das Hochladen von Untertitel- oder Caption-Dateien für eine Aufzeichnung. Unterstützte Formate sind SRT, SSA/ASS und WebVTT. Alle hochgeladenen Dateien werden intern in WebVTT konvertiert. Die Antwort wird im Format JSON zurückgegeben.

Dieser Endpunkt unterstützt nur POST-Anfragen. GET-Anfragen werden nicht akzeptiert.

Endpunkt

POST https://api-guide.bbbserver.com/bigbluebutton/api/putRecordingTextTrack?<parameters>&checksum=replace-with-checksum

Die Untertiteldatei muss als multipart/form-data im POST-Body gesendet werden. Die Prüfsumme wird nur aus den URL-Query-Parametern berechnet — der POST-Body wird nicht in die Prüfsummenberechnung einbezogen.

URL-Parameter (Query-String)

Parameter Typ Erforderlich Standard Beschreibung
recordID String Ja — Eine einzelne Aufzeichnungs-ID. Im Gegensatz zu anderen Endpunkten akzeptiert dieser Parameter keine kommagetrennte Liste — es ist nur eine Aufzeichnungs-ID zulässig.
kind Enum Ja — Der Typ der Textspur. Zulässige Werte sind Untertitel oder Beschriftungen.
lang String Ja — Ein Sprach-Tag gemäß RFC 5646 (z. B. de-DE, en-US).
label String Nein Automatisch erkannt aus lang Ein menschenlesbarer Anzeigename für die Spur (z. B. „Deutsch“). Wenn er weggelassen wird, wird der Sprachname automatisch aus dem Wert lang abgeleitet.

POST Body (multipart/form-data)

Parameter Typ Erforderlich Standard Beschreibung
file Binary Ja — Die hochzuladende Untertiteldatei. Unterstützte Formate: SRT (application/x-subrip), SSA/ASS und WebVTT (text/vtt). Wenn die Datei fehlt oder leer ist, gibt die API eine FAILED-Antwort zurück.

Beispielanfrage

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"

Beispielantwort

Ein erfolgreicher Aufruf gibt das folgende JSON zurück: 

{
  "response": {
    "returncode": "SUCCESS",
    "messageKey": "upload_text_track_success",
    "message": "Text track uploaded successfully",
        "recordId": "replace-with-recording-id"
  }
}

Fehlerantworten

messageKey Beschreibung
paramError Ein erforderlicher Parameter fehlt (checksum, recordID, kind oder lang). Hinweis: Die offizielle Dokumentation führt dies fälschlicherweise als missingParameter auf.
noRecordings Die angegebene Aufzeichnungs-ID wurde nicht gefunden.
invalidKind Der Wert kind ist ungültig. Er muss Untertitel oder Beschriftungen sein.
invalidLang Das Format des Sprach-Tags ist ungültig. Es muss RFC 5646 entsprechen.
empty_uploaded_text_track Die hochgeladene Datei war leer oder es wurde keine Datei in der Anfrage mitgesendet.

Wichtiges Verhalten

Die Verarbeitung von Textspuren erfolgt asynchron. Nach einem erfolgreichen Upload kann es mehrere Minuten dauern, bis die Spur in der Aufzeichnungswiedergabe verfügbar ist.

Wenn bereits ein Track mit derselben kind und Sprache existiert, wird er mit der neuen Datei überschrieben.

Das Hochladen einer leeren Datei oder das Senden einer Anfrage ohne Datei löscht keinen bestehenden Track. Die API gibt stattdessen eine FAILED-Antwort zurück.

Alle hochgeladenen Untertitelformate (SRT, SSA/ASS) werden für die Wiedergabe automatisch in WebVTT konvertiert.

bbbserver.de Hinweise

bbbserver.de: Dieser Endpunkt ist auf der Plattform bbbserver.de nicht verfügbar. Das Hochladen von Untertiteln über die API wird nicht unterstützt.

Tipps

Verwenden Sie den Endpunkt getRecordingTextTracks, um zu überprüfen, ob Ihre hochgeladene Textspur verarbeitet wurde und zur Wiedergabe verfügbar ist, bevor Sie sie in Ihrer Anwendung verlinken.

  • WebVTT ist das empfohlene Format, da es keine Konvertierung erfordert und von Browsern nativ unterstützt wird.
  • Wenn Sie mehrere Sprach-Tracks hochladen, verwenden Sie unterschiedliche RFC 5646-Sprach-Tags, um ein versehentliches Überschreiben bestehender Tracks zu vermeiden.
  • Setzen Sie einen aussagekräftigen Parameter label, damit Zuschauer den richtigen Track im Sprachwähler der Wiedergabe leichter erkennen können.
  • Beachten Sie, dass die Prüfsumme nur aus den URL-Abfrageparametern berechnet wird — beziehen Sie den Dateiinhalt nicht in die Prüfsumme ein.

Häufig gestellte Fragen

BigBlueButton akzeptiert Dateien in SRT (SubRip), SSA/ASS (SubStation Alpha) und WebVTT (Web Video Text Tracks). Alle Formate werden für die Wiedergabe intern in WebVTT konvertiert. Die unterstützten Formate zusätzlich zu WebVTT stammen aus dem Quellcode und sind in der offiziellen Dokumentation nicht ausdrücklich aufgeführt.

Ja. Sie können den Endpunkt putRecordingTextTrack mehrfach mit unterschiedlichen lang-Werten aufrufen, um Tracks für verschiedene Sprachen hochzuladen. Jede Kombination aus kind und lang wird als separater Track gespeichert.

Der bestehende Track mit derselben Kombination aus kind und lang wird mit der neuen Datei überschrieben. Es gibt keine Versionierung oder Sicherung früherer Tracks.

Nein. Das Senden einer Anfrage ohne Datei oder mit einer leeren Datei löscht keinen bestehenden Track. Die API gibt einfach eine FAILED-Antwort mit dem Fehler-Schlüssel empty_uploaded_text_track zurück. Es gibt keinen dedizierten Endpunkt zum Löschen von Text-Tracks.

Die Verarbeitung erfolgt asynchron. Nach einem erfolgreichen Upload dauert es in der Regel einige Minuten, bis die Textspur in der Aufzeichnungswiedergabe verfügbar wird. Die genaue Dauer hängt von der Serverlast und der Dateigröße ab.

Die Prüfsumme wird ausschließlich aus den URL-Abfrageparametern berechnet. Der POST-Body mit der Untertiteldatei ist nicht Teil der Prüfsummenberechnung. Dies ist beabsichtigt und entspricht der Art, wie BigBlueButton Multipart-POST-Anfragen verarbeitet.