Capitolo 16 POST

putRecordingTextTrack – Carica traccia di testo

L'endpoint putRecordingTextTrack ti consente di caricare file di sottotitoli o didascalie per una registrazione. I formati supportati sono SRT, SSA/ASS e WebVTT. Tutti i file caricati vengono convertiti internamente in WebVTT. La risposta viene restituita nel formato JSON.

Questo endpoint supporta solo richieste POST. Le richieste GET non sono accettate.

Endpoint

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

Il file dei sottotitoli deve essere inviato come multipart/form-data nel corpo POST. Il checksum viene calcolato solo dai parametri della query URL — il corpo POST non è incluso nel calcolo del checksum.

Parametri URL (query string)

Parametro Tipo Obbligatorio Predefinito Descrizione
recordID String Sì — Un singolo ID di registrazione. A differenza di altri endpoint, questo parametro non accetta un elenco separato da virgole: è consentito un solo ID di registrazione.
kind Enum Sì — Il tipo di traccia di testo. I valori accettati sono subtitles o captions.
lang String Sì — Un tag lingua conforme a RFC 5646 (ad es. de-DE, en-US).
label String No Rilevato automaticamente da lang Un nome visualizzabile leggibile per la traccia (ad es. "Tedesco"). Se omesso, il nome della lingua viene ricavato automaticamente dal valore lang.

Corpo POST (multipart/form-data)

Parametro Tipo Obbligatorio Predefinito Descrizione
file Binary Sì — Il file dei sottotitoli da caricare. Formati supportati: SRT (application/x-subrip), SSA/ASS e WebVTT (text/vtt). Se il file manca o è vuoto, l'API restituisce una risposta FAILED.

Esempio di richiesta

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"

Risposta di esempio

Una chiamata riuscita restituisce il seguente JSON: 

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

Risposte di errore

messageKey Descrizione
paramError Manca un parametro obbligatorio (checksum, recordID, kind o lang). Nota: la documentazione ufficiale elenca erroneamente questo come missingParameter.
noRecordings L'ID di registrazione specificato non è stato trovato.
invalidKind Il valore kind non è valido. Deve essere subtitles o captions.
invalidLang Il formato del tag lingua non è valido. Deve essere conforme a RFC 5646.
empty_uploaded_text_track Il file caricato era vuoto oppure nessun file era incluso nella richiesta.

Comportamento importante

L'elaborazione della traccia di testo è asincrona. Dopo un caricamento riuscito, possono essere necessari diversi minuti prima che la traccia sia disponibile nella riproduzione della registrazione.

Se esiste già una traccia con lo stesso kind e la stessa lingua, viene sovrascritta con il nuovo file.

Caricare un file vuoto o inviare una richiesta senza file non elimina una traccia esistente. L'API restituisce invece una risposta FAILED.

Tutti i formati di sottotitoli caricati (SRT, SSA/ASS) vengono convertiti automaticamente in WebVTT per la riproduzione.

bbbserver.de Note

bbbserver.de: Questo endpoint non è disponibile sulla piattaforma bbbserver.de. Il caricamento di sottotitoli tramite API non è supportato.

Suggerimenti

Usa l'endpoint getRecordingTextTracks per verificare che la traccia di testo caricata sia stata elaborata e sia disponibile per la riproduzione prima di collegarla nella tua applicazione.

  • WebVTT è il formato consigliato poiché non richiede conversione ed è supportato nativamente dai browser.
  • Quando carichi più tracce linguistiche, usa tag lingua RFC 5646 distinti per evitare di sovrascrivere accidentalmente tracce esistenti.
  • Imposta un parametro label descrittivo per aiutare gli spettatori a identificare la traccia corretta nel selettore della lingua di riproduzione.
  • Ricorda che il checksum viene calcolato solo dai parametri di query dell'URL: non includere il contenuto del file nel checksum.

Domande frequenti

BigBlueButton accetta file SRT (SubRip), SSA/ASS (SubStation Alpha) e WebVTT (Web Video Text Tracks). Tutti i formati vengono convertiti internamente in WebVTT per la riproduzione. I formati supportati oltre a WebVTT sono ricavati dal codice sorgente e non sono esplicitamente elencati nella documentazione ufficiale.

Sì. Puoi chiamare l'endpoint putRecordingTextTrack più volte con valori lang diversi per caricare tracce in lingue diverse. Ogni combinazione di kind e lang viene memorizzata come traccia separata.

La traccia esistente con la stessa combinazione di kind e lang viene sovrascritta con il nuovo file. Non esistono versionamento o backup delle tracce precedenti.

No. Inviare una richiesta senza file o con un file vuoto non elimina una traccia esistente. L'API restituisce semplicemente una risposta FAILED con la chiave di errore empty_uploaded_text_track. Non esiste un endpoint dedicato per eliminare le tracce di testo.

L'elaborazione è asincrona. Dopo un caricamento riuscito, in genere occorrono alcuni minuti prima che la traccia di testo diventi disponibile nella riproduzione della registrazione. La durata esatta dipende dal carico del server e dalla dimensione del file.

Il checksum viene calcolato esclusivamente a partire dai parametri di query dell'URL. Il body POST che contiene il file dei sottotitoli non fa parte del calcolo del checksum. Questo è intenzionale ed è coerente con il modo in cui BigBlueButton gestisce le richieste multipart POST.