Capitolo 15 GET POST

getRecordingTextTracks – Tracce di testo

L'endpoint getRecordingTextTracks restituisce un elenco di tutte le tracce di sottotitoli associate a una registrazione specifica. A differenza della maggior parte degli endpoint API di BigBlueButton, la risposta viene restituita in formato JSON anziché XML.

Endpoint

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

Sono supportati sia i metodi GET che POST. Quando usi POST, invia i parametri come application/x-www-form-urlencoded nel corpo della richiesta.

Parametri

Parametro Tipo Descrizione
recordID String Obbligatorio. L'ID della registrazione di cui vuoi recuperare le tracce testuali. È accettato un solo ID di registrazione: gli elenchi separati da virgole non sono supportati.

A differenza di altri endpoint relativi alle registrazioni, getRecordingTextTracks accetta solo un singolo valore recordID. Passare più ID separati da virgole provocherà un errore o un comportamento imprevisto.

Campi della risposta

Ogni oggetto track nella risposta contiene i seguenti attributi:

Campo Tipo Descrizione
href String L'URL di download del file della traccia testuale in formato WebVTT.
kind String Il tipo di traccia testuale, secondo la specifica dell'elemento video HTML5. Valori possibili: subtitles o captions.
label String Il nome visualizzato mostrato nel menu di selezione dei sottotitoli dell'interfaccia di riproduzione della registrazione.
lang String Il language tag come definito da RFC 5646 (ad es. en-US, de-DE, pt-BR).
source String L'origine della traccia testuale. Valori noti: live (trascrizione in diretta durante la riunione), automatic (generata automaticamente dopo la riunione), upload (caricata manualmente).

Esempio di richiesta

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

Risposta di esempio

Successo

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

Errore — ID record mancante

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

Risposte di errore

Chiave del messaggio Descrizione
checksumError Il checksum non è valido o non corrisponde ai parametri della richiesta.
missingParamRecordID Il parametro richiesto recordID non è stato fornito nella richiesta.
noRecordings Non è stata trovata alcuna registrazione corrispondente all'ID di registrazione specificato.

bbbserver.de Note

bbbserver.de: Questo endpoint non è disponibile sulla piattaforma bbbserver.de. Le tracce testuali delle registrazioni non possono essere recuperate tramite l'API.

Suggerimenti

Questo è l'unico endpoint API standard di BigBlueButton che restituisce JSON invece di XML. Assicurati che il tuo client API gestisca questa differenza durante il parsing della risposta.

  • Usa il campo lang per filtrare le tracce per lingua quando costruisci un'interfaccia di selezione dei sottotitoli per i tuoi utenti.
  • Il campo href fornisce un link diretto per scaricare il file WebVTT, che può essere usato con qualsiasi player video HTML5 standard.
  • Controlla il campo source per distinguere tra didascalie caricate manualmente e quelle generate automaticamente, che possono variare in qualità.
  • Per aggiungere o aggiornare tracce testuali, usa l'endpoint complementare putRecordingTextTrack.

Domande frequenti

L'endpoint getRecordingTextTracks è stato aggiunto più tardi nell'evoluzione dell'API BigBlueButton ed è stato progettato per restituire JSON fin dall'inizio. Questa è un'eccezione alla regola generale secondo cui le risposte API di BigBlueButton usano XML. Il codice del tuo client deve quindi gestire di conseguenza questa differenza di formato.

No. A differenza di altri endpoint per le registrazioni che accettano elenchi separati da virgole, getRecordingTextTracks accetta solo un singolo recordID per richiesta. Per recuperare le tracce di più registrazioni, devi inviare chiamate API separate per ciascuna registrazione.

Le tracce testuali sono fornite in formato WebVTT (Web Video Text Tracks), il formato standard dei sottotitoli per la riproduzione video HTML5. Il file può essere scaricato direttamente dall'URL fornito nel campo href della risposta.

I subtitles sono destinati agli spettatori che possono sentire l'audio ma necessitano di una traduzione testuale, mentre i captions sono progettati per spettatori sordi o con problemi di udito e possono includere descrizioni di audio non verbale come effetti sonori. Il campo kind nella risposta indica quale tipo ha una determinata traccia.

I valori noti sono: live (generato durante la riunione tramite trascrizione in tempo reale), automatic (generato automaticamente dopo la riunione) e upload (caricato manualmente da un utente). Nota che questi valori si basano sull'analisi del codice sorgente e sulle osservazioni della community, poiché non sono completamente documentati nella specifica ufficiale.