Hoofdstuk 16 POST

putRecordingTextTrack – Tekstspoor uploaden

Met het endpoint putRecordingTextTrack kun je ondertitel- of captionbestanden uploaden voor een opname. Ondersteunde formaten zijn SRT, SSA/ASS en WebVTT. Alle geüploade bestanden worden intern geconverteerd naar WebVTT. Het antwoord wordt geretourneerd in JSON-formaat.

Dit endpoint ondersteunt alleen POST-verzoeken. GET-verzoeken worden niet geaccepteerd.

Endpoint

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

Het ondertitelbestand moet als multipart/form-data in de POST-body worden verzonden. De checksum wordt alleen berekend op basis van de URL-queryparameters — de POST-body wordt niet meegenomen in de berekening van de checksum.

URL-parameters (querystring)

Parameter Type Vereist Standaard Beschrijving
recordID String Ja — Eén enkele opname-ID. In tegenstelling tot andere endpoints accepteert deze parameter geen door komma's gescheiden lijst — slechts één opname-ID is toegestaan.
kind Enum Ja — Het type teksttrack. Geaccepteerde waarden zijn subtitles of captions.
lang String Ja — Een taaltag conform RFC 5646 (bijv. de-DE, en-US).
label String Nee Automatisch gedetecteerd uit lang Een voor mensen leesbare weergavenaam voor de track (bijv. "Duits"). Indien weggelaten, wordt de taalnaam automatisch afgeleid van de waarde lang.

POST Body (multipart/form-data)

Parameter Type Vereist Standaard Beschrijving
file Binary Ja — Het te uploaden ondertitelbestand. Ondersteunde formaten: SRT (application/x-subrip), SSA/ASS en WebVTT (text/vtt). Als het bestand ontbreekt of leeg is, retourneert de API een FAILED-antwoord.

Voorbeeldverzoek

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"

Voorbeeldrespons

Een succesvolle aanroep retourneert de volgende JSON: 

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

Foutresponses

messageKey Beschrijving
paramError Een vereiste parameter ontbreekt (checksum, recordID, kind of lang). Opmerking: de officiële documentatie vermeldt dit onjuist als missingParameter.
noRecordings De opgegeven opname-ID is niet gevonden.
invalidKind De waarde kind is ongeldig. Moet subtitles of captions zijn.
invalidLang Het formaat van de taaltag is ongeldig. Het moet voldoen aan RFC 5646.
empty_uploaded_text_track Het geüploade bestand was leeg of er was geen bestand opgenomen in het verzoek.

Belangrijk gedrag

De verwerking van teksttracks is asynchroon. Na een succesvolle upload kan het enkele minuten duren voordat de track beschikbaar is bij het afspelen van de opname.

Als er al een track bestaat met dezelfde kind en taal, wordt deze overschreven met het nieuwe bestand.

Het uploaden van een leeg bestand of het verzenden van een verzoek zonder bestand verwijdert geen bestaande track. De API retourneert in plaats daarvan een FAILED-antwoord.

Alle geüploade ondertitelformaten (SRT, SSA/ASS) worden automatisch geconverteerd naar WebVTT voor afspelen.

bbbserver.de Notities

bbbserver.de: Dit endpoint is niet beschikbaar op het platform bbbserver.de. Het uploaden van ondertitels via de API wordt niet ondersteund.

Tips

Gebruik het endpoint getRecordingTextTracks om te controleren of je geüploade teksttrack is verwerkt en beschikbaar is voor weergave voordat je ernaar linkt in je applicatie.

  • WebVTT is het aanbevolen formaat omdat het geen conversie vereist en native door browsers wordt ondersteund.
  • Gebruik bij het uploaden van meerdere taaltracks verschillende RFC 5646-taaltags om te voorkomen dat bestaande tracks per ongeluk worden overschreven.
  • Stel een beschrijvende parameter label in om kijkers te helpen de juiste track te herkennen in de taalkeuze van de afspeler.
  • Vergeet niet dat de checksum alleen wordt berekend op basis van de URL-queryparameters — neem de bestandsinhoud niet op in de checksum.

Veelgestelde vragen

BigBlueButton accepteert bestanden van het type SRT (SubRip), SSA/ASS (SubStation Alpha) en WebVTT (Web Video Text Tracks). Alle formaten worden intern geconverteerd naar WebVTT voor afspelen. De ondersteunde formaten naast WebVTT zijn afgeleid uit de broncode en worden niet expliciet vermeld in de officiële documentatie.

Ja. Je kunt het endpoint putRecordingTextTrack meerdere keren aanroepen met verschillende waarden voor lang om tracks voor verschillende talen te uploaden. Elke combinatie van kind en lang wordt als een aparte track opgeslagen.

De bestaande track met dezelfde combinatie van kind en lang wordt overschreven met het nieuwe bestand. Er is geen versiebeheer of back-up van eerdere tracks.

Nee. Het verzenden van een verzoek zonder bestand of met een leeg bestand verwijdert een bestaande track niet. De API retourneert simpelweg een FAILED-antwoord met de foutsleutel empty_uploaded_text_track. Er is geen apart endpoint voor het verwijderen van teksttracks.

De verwerking is asynchroon. Na een succesvolle upload duurt het doorgaans enkele minuten voordat de teksttrack beschikbaar wordt bij het afspelen van de opname. De exacte duur hangt af van de serverbelasting en de bestandsgrootte.

De checksum wordt uitsluitend berekend op basis van de URL-queryparameters. De POST-body die het ondertitelbestand bevat, maakt geen deel uit van de checksum-berekening. Dit is bewust zo ontworpen en komt overeen met hoe BigBlueButton multipart-POST-verzoeken afhandelt.