Kapitel 15 GET POST

getRecordingTextTracks – Textspuren

Der Endpunkt getRecordingTextTracks gibt eine Liste aller Untertitel- und Caption-Tracks zurück, die einer bestimmten Aufzeichnung zugeordnet sind. Anders als die meisten API-Endpunkte von BigBlueButton wird die Antwort im Format JSON statt XML zurückgegeben.

Endpunkt

GET/POST https://api-guide.bbbserver.com/bigbluebutton/api/getRecordingTextTracks?<parameter>&checksum=replace-with-checksum

Sowohl die Methoden GET als auch POST werden unterstützt. Bei Verwendung von POST senden Sie die Parameter als application/x-www-form-urlencoded im Request-Body.

Parameter

Parameter Typ Beschreibung
recordID String Erforderlich. Die Recording-ID der Aufzeichnung, deren Textspuren Sie abrufen möchten. Es wird nur eine einzelne Recording-ID akzeptiert — kommagetrennte Listen werden nicht unterstützt.

Im Gegensatz zu anderen Recording-Endpunkten akzeptiert getRecordingTextTracks nur einen einzelnen recordID-Wert. Die Übergabe mehrerer kommagetrennter IDs führt zu einem Fehler oder zu unerwartetem Verhalten.

Antwortfelder

Jedes Track-Objekt in der Antwort enthält die folgenden Attribute:

Feld Typ Beschreibung
href String Die Download-URL für die Text-Track-Datei im Format WebVTT.
kind String Der Typ des Text-Tracks gemäß der Spezifikation des HTML5-Videoelements. Mögliche Werte: subtitles oder captions.
label String Der Anzeigename, der im Untertitel-Auswahlmenü der Aufzeichnungs-Wiedergabeoberfläche angezeigt wird.
lang String Das Sprach-Tag gemäß RFC 5646 (z. B. en-US, de-DE, pt-BR).
source String Die Herkunft der Textspur. Bekannte Werte: live (Live-Transkription während des Meetings), automatic (maschinell nach dem Meeting erzeugt), upload (manuell hochgeladen).

Beispielanfrage

curl --request GET \
    "https://api-guide.bbbserver.com/bigbluebutton/api/getRecordingTextTracks?recordID=replace-with-recording-id&checksum=replace-with-checksum"

Beispielantwort

Erfolg

{
  "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"
      }
    ]
  }
}

Fehler — Fehlende Record-ID

{
  "response": {
    "returncode": "FAILED",
    "messageKey": "missingParamRecordID",
    "message": "You must specify a recordID."
  }
}

Fehlerantworten

Nachrichtenschlüssel Beschreibung
checksumError Die checksum ist ungültig oder stimmt nicht mit den Anfrageparametern überein.
missingParamRecordID Der erforderliche Parameter recordID wurde in der Anfrage nicht angegeben.
noRecordings Es wurde keine Aufzeichnung gefunden, die der angegebenen Recording-ID entspricht.

bbbserver.de Hinweise

bbbserver.de: Dieser Endpunkt ist auf der Plattform bbbserver.de nicht verfügbar. Text-Tracks für Aufzeichnungen können nicht über die API abgerufen werden.

Tipps

Dies ist der einzige standardmäßige API-Endpunkt von BigBlueButton, der JSON statt XML zurückgibt. Stellen Sie sicher, dass Ihr API-Client diesen Unterschied beim Parsen der Antwort berücksichtigt.

  • Verwenden Sie das Feld lang, um Tracks nach Sprache zu filtern, wenn Sie eine Untertitel-Auswahloberfläche für Ihre Benutzer erstellen.
  • Das Feld href liefert einen direkten Download-Link zur WebVTT-Datei, die mit jedem Standard-HTML5-Videoplayer verwendet werden kann.
  • Prüfen Sie das Feld source, um zwischen manuell hochgeladenen und automatisch erzeugten Untertiteln zu unterscheiden, deren Qualität variieren kann.
  • Um Textspuren hinzuzufügen oder zu aktualisieren, verwenden Sie den zugehörigen Endpunkt putRecordingTextTrack.

Häufig gestellte Fragen

Der Endpunkt getRecordingTextTracks wurde später in der Entwicklung der BigBlueButton-API hinzugefügt und war von Anfang an dafür ausgelegt, JSON zurückzugeben. Dies ist eine Ausnahme von der allgemeinen Regel, dass Antworten der BigBlueButton-API XML verwenden. Ihr Client-Code muss diesen Formatunterschied entsprechend behandeln.

Nein. Anders als andere Recording-Endpunkte, die kommagetrennte Listen akzeptieren, akzeptiert getRecordingTextTracks pro Anfrage nur eine einzelne recordID. Um Tracks für mehrere Aufzeichnungen abzurufen, müssen Sie für jede Aufzeichnung separate API-Aufrufe senden.

Text-Tracks werden im Format WebVTT (Web Video Text Tracks) bereitgestellt, dem Standard-Untertitelformat für die HTML5-Videowiedergabe. Die Datei kann direkt über die im Feld href der Antwort angegebene URL heruntergeladen werden.

Untertitel sind für Zuschauer gedacht, die den Ton hören können, aber eine textliche Übersetzung benötigen, während Captions für gehörlose oder schwerhörige Zuschauer gedacht sind und Beschreibungen nichtsprachlicher Audiosignale wie Soundeffekte enthalten können. Das Feld kind in der Antwort gibt an, um welchen Typ es sich bei einem bestimmten Track handelt.

Die bekannten Werte sind: live (während des Meetings durch Live-Transkription erzeugt), automatic (maschinell nach dem Meeting erzeugt) und upload (manuell von einem Benutzer hochgeladen). Beachten Sie, dass diese Werte auf Quellcodeanalyse und Beobachtungen der Community beruhen, da sie in der offiziellen Spezifikation nicht vollständig dokumentiert sind.