Kapitel 16 POST

putRecordingTextTrack – Upload tekstspor

Endepunktet putRecordingTextTrack giver dig mulighed for at uploade undertekst- eller billedtekstfiler til en optagelse. Understøttede formater er SRT, SSA/ASS og WebVTT. Alle uploadede filer konverteres internt til WebVTT. Svaret returneres i JSON-format.

Dette endepunkt understøtter kun POST-anmodninger. GET-anmodninger accepteres ikke.

Endepunkt

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

Undertekstfilen skal sendes som multipart/form-data i POST-bodyen. Tjeksummen beregnes kun ud fra URL'ens query-parametre — POST-bodyen indgår ikke i beregningen af tjeksummen.

URL-parametre (query string)

Parameter Type Påkrævet Standard Beskrivelse
recordID String Ja — Et enkelt optagelses-ID. I modsætning til andre endpoints accepterer denne parameter ikke en kommasepareret liste — kun ét optagelses-ID er tilladt.
kind Enum Ja — Typen af tekstspor. Accepterede værdier er subtitles eller captions.
lang String Ja — Et sprog-tag i overensstemmelse med RFC 5646 (f.eks. de-DE, en-US).
label String Nej Automatisk detekteret fra lang Et læsbart visningsnavn for sporet (f.eks. "Tysk"). Hvis det udelades, afledes sprognavnet automatisk fra værdien lang.

POST-body (multipart/form-data)

Parameter Type Påkrævet Standard Beskrivelse
file Binary Ja — Undertekstfilen, der skal uploades. Understøttede formater: SRT (application/x-subrip), SSA/ASS og WebVTT (text/vtt). Hvis filen mangler eller er tom, returnerer API'et et FAILED-svar.

Eksempel på anmodning

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"

Eksempelsvar

Et vellykket kald returnerer følgende JSON: 

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

Fejlsvar

messageKey Beskrivelse
paramError En påkrævet parameter mangler (checksum, recordID, kind eller lang). Bemærk: den officielle dokumentation angiver fejlagtigt dette som missingParameter.
noRecordings Det angivne optagelses-ID blev ikke fundet.
invalidKind Værdien kind er ugyldig. Skal være subtitles eller captions.
invalidLang Formatet på sprog-tagget er ugyldigt. Det skal overholde RFC 5646.
empty_uploaded_text_track Den uploadede fil var tom, eller der var ingen fil inkluderet i anmodningen.

Vigtig adfærd

Behandling af tekstspor er asynkron. Efter en vellykket upload kan der gå flere minutter, før sporet er tilgængeligt i afspilningen af optagelsen.

Hvis der allerede findes et spor med samme kind og sprog, overskrives det med den nye fil.

Upload af en tom fil eller afsendelse af en anmodning uden fil sletter ikke et eksisterende spor. API'et returnerer i stedet et FAILED-svar.

Alle uploadede undertekstformater (SRT, SSA/ASS) konverteres automatisk til WebVTT til afspilning.

bbbserver.de Bemærkninger

bbbserver.de: Dette endepunkt er ikke tilgængeligt på platformen bbbserver.de. Upload af undertekster via API'et understøttes ikke.

Tips

Brug endpointet getRecordingTextTracks til at kontrollere, at dit uploadede tekstspor er blevet behandlet og er tilgængeligt til afspilning, før du linker til det i din applikation.

  • WebVTT er det anbefalede format, da det ikke kræver nogen konvertering og understøttes nativt af browsere.
  • Når du uploader flere sprogspor, skal du bruge forskellige RFC 5646-sprog-tags for at undgå utilsigtet at overskrive eksisterende spor.
  • Angiv en beskrivende parameter label for at hjælpe seerne med at identificere det korrekte spor i sprogvælgeren for afspilning.
  • Husk, at checksummen kun beregnes ud fra URL-forespørgselsparametrene — medtag ikke filindholdet i checksummen.

Ofte stillede spørgsmål

BigBlueButton accepterer filer af typerne SRT (SubRip), SSA/ASS (SubStation Alpha) og WebVTT (Web Video Text Tracks). Alle formater konverteres internt til WebVTT til afspilning. De understøttede formater ud over WebVTT er afledt af kildekoden og er ikke udtrykkeligt angivet i den officielle dokumentation.

Ja. Du kan kalde endepunktet putRecordingTextTrack flere gange med forskellige værdier for lang for at uploade spor til forskellige sprog. Hver kombination af kind og lang gemmes som et separat spor.

Det eksisterende spor med den samme kombination af kind og lang overskrives med den nye fil. Der er ingen versionsstyring eller backup af tidligere spor.

Nej. Afsendelse af en anmodning uden fil eller med en tom fil sletter ikke et eksisterende spor. API'et returnerer blot et FAILED-svar med fejlnøglen empty_uploaded_text_track. Der findes ikke et dedikeret endepunkt til at slette tekstspor.

Behandlingen er asynkron. Efter en vellykket upload tager det typisk et par minutter, før tekstsporet bliver tilgængeligt i afspilningen af optagelsen. Den præcise varighed afhænger af serverbelastning og filstørrelse.

Checksummen beregnes udelukkende ud fra URL-forespørgselsparametrene. POST-bodyen, der indeholder undertekstfilen, er ikke en del af checksum-beregningen. Dette er tilsigtet og stemmer overens med, hvordan BigBlueButton håndterer multipart-POST-anmodninger.