Hoofdstuk 15 GET POST

getRecordingTextTracks – Tekstsporen

Het endpoint getRecordingTextTracks retourneert een lijst van alle ondertitel- en captiontracks die aan een specifieke opname zijn gekoppeld. In tegenstelling tot de meeste BigBlueButton-API-endpoints wordt de response geretourneerd in JSON-formaat in plaats van XML.

Endpoint

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

Zowel de methoden GET als POST worden ondersteund. Bij gebruik van POST stuur je parameters als application/x-www-form-urlencoded in de requestbody.

Parameters

Parameter Type Beschrijving
recordID String Vereist. De opname-ID van de opname waarvan je de teksttracks wilt ophalen. Er wordt slechts één opname-ID geaccepteerd — door komma's gescheiden lijsten worden niet ondersteund.

In tegenstelling tot andere recording-endpoints accepteert getRecordingTextTracks alleen één enkele recordID-waarde. Het doorgeven van meerdere door komma's gescheiden ID's resulteert in een fout of onverwacht gedrag.

Responsvelden

Elk trackobject in de respons bevat de volgende attributen:

Veld Type Beschrijving
href String De download-URL voor het texttrack-bestand in WebVTT-formaat.
kind String Het type texttrack, volgens de specificatie van het HTML5-video-element. Mogelijke waarden: subtitles of captions.
label String De weergegeven naam die wordt getoond in het ondertitelselectiemenu van de opname-afspeelinterface.
lang String De taalcode zoals gedefinieerd door RFC 5646 (bijv. en-US, de-DE, pt-BR).
source String De herkomst van de teksttrack. Bekende waarden: live (live transcriptie tijdens de vergadering), automatic (machinaal gegenereerd na de vergadering), upload (handmatig geüpload).

Voorbeeldverzoek

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

Voorbeeldrespons

Succes

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

Fout — Ontbrekende record-ID

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

Foutresponses

Berichtsleutel Beschrijving
checksumError De checksum is ongeldig of komt niet overeen met de requestparameters.
missingParamRecordID De vereiste parameter recordID is niet opgegeven in de request.
noRecordings Er is geen opname gevonden die overeenkomt met de opgegeven opname-ID.

bbbserver.de Notities

bbbserver.de: Dit endpoint is niet beschikbaar op het bbbserver.de-platform. Texttracks voor opnames kunnen niet via de API worden opgehaald.

Tips

Dit is het enige standaard BigBlueButton-API-endpoint dat JSON retourneert in plaats van XML. Zorg ervoor dat je API-client dit verschil verwerkt bij het parsen van de response.

  • Gebruik het veld lang om tracks op taal te filteren bij het bouwen van een UI voor ondertitelselectie voor je gebruikers.
  • Het veld href biedt een directe downloadlink naar het WebVTT-bestand, dat met elke standaard HTML5-videospeler kan worden gebruikt.
  • Controleer het veld source om onderscheid te maken tussen handmatig geüploade captions en automatisch gegenereerde captions, die in kwaliteit kunnen verschillen.
  • Gebruik het bijbehorende endpoint putRecordingTextTrack om teksttracks toe te voegen of bij te werken.

Veelgestelde vragen

Het endpoint getRecordingTextTracks is later toegevoegd in de evolutie van de BigBlueButton-API en is vanaf het begin ontworpen om JSON te retourneren. Dit is een uitzondering op de algemene regel dat responses van de BigBlueButton-API XML gebruiken. Je clientcode moet dit formaatverschil dienovereenkomstig afhandelen.

Nee. In tegenstelling tot andere opname-endpoints die door komma's gescheiden lijsten accepteren, accepteert getRecordingTextTracks slechts één enkele recordID per request. Om tracks voor meerdere opnames op te halen, moet je voor elke opname afzonderlijke API-calls versturen.

Texttracks worden geleverd in WebVTT-formaat (Web Video Text Tracks), het standaard ondertitelingsformaat voor HTML5-videoweergave. Het bestand kan rechtstreeks worden gedownload via de URL in het veld href van de response.

Subtitles zijn bedoeld voor kijkers die de audio kunnen horen maar een tekstvertaling nodig hebben, terwijl captions bedoeld zijn voor dove of slechthorende kijkers en beschrijvingen kunnen bevatten van niet-spraakgeluid zoals geluidseffecten. Het veld kind in de response geeft aan om welk type een bepaalde track gaat.

De bekende waarden zijn: live (gegenereerd tijdens de vergadering via live transcriptie), automatic (machinaal gegenereerd na de vergadering) en upload (handmatig geüpload door een gebruiker). Let op dat deze waarden gebaseerd zijn op broncodeanalyse en observaties uit de community, omdat ze niet volledig zijn gedocumenteerd in de officiële specificatie.