Versione API: 4.x più recente 3.x

Stai visualizzando la documentazione API per BigBlueButton 3.x. La versione attuale è BigBlueButton 4.x. Stai pianificando un aggiornamento? La guida alla migrazione elenca tutte le modifiche necessarie alle tue chiamate API.

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 per scaricare il file della traccia testuale in formato WebVTT. L'URL contiene un token monouso che scade dopo un'ora.
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 tempo reale durante la riunione), automatic (generata automaticamente tramite riconoscimento vocale), 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/bigbluebutton/textTrack/replace-with-token/replace-with-recording-id/subtitles_de-DE.vtt",
        "kind": "subtitles",
        "label": "Deutsch",
        "lang": "de-DE",
        "source": "upload"
      },
      {
                "href": "https://api-guide.bbbserver.com/bigbluebutton/textTrack/replace-with-token/replace-with-recording-id/subtitles_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.

Suggerimenti

Come putRecordingTextTrack, questo endpoint restituisce JSON anziché XML. Assicurati che il tuo client API gestisca questa differenza durante l'analisi 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 per scaricare il file WebVTT. Il link contiene un token monouso valido per un'ora, quindi scarica subito il file anziché memorizzare o incorporare il link.
  • 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 (generata durante la riunione tramite trascrizione in tempo reale), automatic (generata automaticamente tramite riconoscimento vocale) e upload (caricata manualmente da un utente).