Kapitel 15 GET POST

getRecordingTextTracks – Tekstspor

Endpointet getRecordingTextTracks returnerer en liste over alle undertekst- og caption-spor, der er knyttet til en bestemt optagelse. I modsætning til de fleste BigBlueButton API-endpoints returneres svaret i JSON-format i stedet for XML.

Endepunkt

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

Både GET- og POST-metoder understøttes. Ved brug af POST skal parametre sendes som application/x-www-form-urlencoded i request body.

Parametre

Parameter Type Beskrivelse
recordID String Påkrævet. Optagelses-ID'et for den optagelse, hvis tekstspor du vil hente. Kun ét enkelt optagelses-ID accepteres — kommaseparerede lister understøttes ikke.

I modsætning til andre optagelses-endpoints accepterer getRecordingTextTracks kun én enkelt værdi for recordID. Hvis du sender flere kommaseparerede ID'er, vil det resultere i en fejl eller uventet adfærd.

Svarfelter

Hvert sporobjekt i svaret indeholder følgende attributter:

Felt Type Beskrivelse
href String Download-URL'en til tekstsporfilen i WebVTT-format.
kind String Typen af tekstspor, i overensstemmelse med specifikationen for HTML5-videoelementet. Mulige værdier: subtitles eller captions.
label String Det viste navn, der vises i menuen til valg af undertekster i optagelsens afspilningsgrænseflade.
lang String Sprog-tagget som defineret af RFC 5646 (f.eks. en-US, de-DE, pt-BR).
source String Tekstsporets oprindelse. Kendte værdier: live (live-transskription under mødet), automatic (maskingenereret efter mødet), upload (manuelt uploadet).

Eksempel på anmodning

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

Eksempelsvar

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

Fejl — Manglende post-ID

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

Fejlsvar

Beskednøgle Beskrivelse
checksumError checksum er ugyldig eller matcher ikke request-parametrene.
missingParamRecordID Den påkrævede parameter recordID blev ikke angivet i requesten.
noRecordings Der blev ikke fundet nogen optagelse, der matcher det angivne optagelses-ID.

bbbserver.de Bemærkninger

bbbserver.de: Dette endpoint er ikke tilgængeligt på platformen bbbserver.de. Tekstspor for optagelser kan ikke hentes via API'et.

Tips

Dette er det eneste standard BigBlueButton API-endpoint, som returnerer JSON i stedet for XML. Sørg for, at din API-klient håndterer denne forskel ved parsing af svaret.

  • Brug feltet lang til at filtrere spor efter sprog, når du bygger en brugerflade til valg af undertekster for dine brugere.
  • Feltet href giver et direkte download-link til WebVTT-filen, som kan bruges med enhver standard HTML5-videoplayer.
  • Kontrollér feltet source for at skelne mellem manuelt uploadede billedtekster og automatisk genererede, som kan variere i kvalitet.
  • For at tilføje eller opdatere tekstspor skal du bruge det tilhørende endpoint putRecordingTextTrack.

Ofte stillede spørgsmål

Endpointet getRecordingTextTracks blev tilføjet senere i udviklingen af BigBlueButton API'et og blev designet til at returnere JSON fra starten. Dette er en undtagelse fra den generelle regel om, at BigBlueButton API-svar bruger XML. Din klientkode skal håndtere denne formatforskel tilsvarende.

Nej. I modsætning til andre optagelses-endpoints, der accepterer kommaseparerede lister, accepterer getRecordingTextTracks kun ét enkelt recordID pr. request. For at hente spor for flere optagelser skal du sende separate API-kald for hver optagelse.

Tekstspor leveres i WebVTT-format (Web Video Text Tracks), standardformatet for undertekster til HTML5-videoafspilning. Filen kan downloades direkte fra den URL, der er angivet i feltet href i svaret.

Subtitles er beregnet til seere, der kan høre lyden, men har brug for en tekstoversættelse, mens captions er designet til døve eller hørehæmmede seere og kan indeholde beskrivelser af ikke-verbal lyd såsom lydeffekter. Feltet kind i svaret angiver, hvilken type et givet spor er.

De kendte værdier er: live (genereret under mødet via live-transskription), automatic (maskingenereret efter mødet) og upload (manuelt uploadet af en bruger). Bemærk, at disse værdier er baseret på kildekodeanalyse og community-observationer, da de ikke er fuldt dokumenteret i den officielle specifikation.