Chapitre 16 POST

putRecordingTextTrack – Téléverser une piste de texte

Le point de terminaison putRecordingTextTrack vous permet de téléverser des fichiers de sous-titres ou de légendes pour un enregistrement. Les formats pris en charge sont SRT, SSA/ASS et WebVTT. Tous les fichiers téléversés sont convertis en interne en WebVTT. La réponse est renvoyée au format JSON.

Ce point de terminaison prend uniquement en charge les requêtes POST. Les requêtes GET ne sont pas acceptées.

Point de terminaison

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

Le fichier de sous-titres doit être envoyé en tant que multipart/form-data dans le corps POST. La somme de contrôle est calculée uniquement à partir des paramètres de requête de l'URL — le corps POST n'est pas inclus dans le calcul de la somme de contrôle.

Paramètres d’URL (chaîne de requête)

Paramètre Type Obligatoire Par défaut Description
recordID String Oui — Un seul identifiant d’enregistrement. Contrairement aux autres points de terminaison, ce paramètre n’accepte pas de liste séparée par des virgules — un seul identifiant d’enregistrement est autorisé.
kind Enum Oui — Le type de piste de texte. Les valeurs acceptées sont subtitles ou captions.
lang String Oui — Une balise de langue conforme à RFC 5646 (par ex. de-DE, en-US).
label String Non Détecté automatiquement à partir de lang Un nom d’affichage lisible par l’humain pour la piste (par ex. "Allemand"). S’il est omis, le nom de la langue est dérivé automatiquement de la valeur lang.

Corps POST (multipart/form-data)

Paramètre Type Obligatoire Par défaut Description
file Binary Oui — Le fichier de sous-titres à téléverser. Formats pris en charge : SRT (application/x-subrip), SSA/ASS et WebVTT (text/vtt). Si le fichier est manquant ou vide, l'API renvoie une réponse FAILED.

Exemple de requête

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"

Exemple de réponse

Un appel réussi renvoie le JSON suivant : 

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

Réponses d’erreur

messageKey Description
paramError Un paramètre requis est manquant (checksum, recordID, kind ou lang). Remarque : la documentation officielle l’indique à tort comme missingParameter.
noRecordings L’identifiant d’enregistrement spécifié est introuvable.
invalidKind La valeur kind est invalide. Elle doit être subtitles ou captions.
invalidLang Le format de la balise de langue est invalide. Il doit être conforme à RFC 5646.
empty_uploaded_text_track Le fichier téléversé était vide ou aucun fichier n’a été inclus dans la requête.

Comportement important

Le traitement des pistes de texte est asynchrone. Après un téléversement réussi, plusieurs minutes peuvent être nécessaires avant que la piste soit disponible dans la lecture de l’enregistrement.

Si une piste avec le même kind et la même langue existe déjà, elle est écrasée par le nouveau fichier.

Téléverser un fichier vide ou envoyer une requête sans fichier ne supprime pas une piste existante. L'API renvoie à la place une réponse FAILED.

Tous les formats de sous-titres téléversés (SRT, SSA/ASS) sont automatiquement convertis en WebVTT pour la lecture.

Notes bbbserver.de

bbbserver.de: Ce point de terminaison n'est pas disponible sur la plateforme bbbserver.de. Le téléversement de sous-titres via l'API n'est pas pris en charge.

Conseils

Utilisez le point de terminaison getRecordingTextTracks pour vérifier que votre piste de texte téléversée a été traitée et qu’elle est disponible pour la lecture avant d’y faire référence dans votre application.

  • WebVTT est le format recommandé, car il ne nécessite aucune conversion et est pris en charge nativement par les navigateurs.
  • Lors du téléversement de plusieurs pistes de langue, utilisez des balises de langue RFC 5646 distinctes afin d'éviter d'écraser accidentellement des pistes existantes.
  • Définissez un paramètre label descriptif pour aider les spectateurs à identifier la bonne piste dans le sélecteur de langue de lecture.
  • N’oubliez pas que le checksum est calculé uniquement à partir des paramètres de requête de l’URL — n’incluez pas le contenu du fichier dans le checksum.

Foire aux questions

BigBlueButton accepte les fichiers SRT (SubRip), SSA/ASS (SubStation Alpha) et WebVTT (Web Video Text Tracks). Tous les formats sont convertis en interne en WebVTT pour la lecture. Les formats pris en charge au-delà de WebVTT proviennent du code source et ne sont pas explicitement listés dans la documentation officielle.

Oui. Vous pouvez appeler le point de terminaison putRecordingTextTrack plusieurs fois avec des valeurs lang différentes pour téléverser des pistes pour différentes langues. Chaque combinaison de kind et lang est stockée comme une piste distincte.

La piste existante avec la même combinaison kind et lang est écrasée par le nouveau fichier. Il n'existe aucun versionnage ni sauvegarde des pistes précédentes.

Non. Envoyer une requête sans fichier ou avec un fichier vide ne supprime pas une piste existante. L'API renvoie simplement une réponse FAILED avec la clé d'erreur empty_uploaded_text_track. Il n'existe aucun point de terminaison dédié à la suppression des pistes de texte.

Le traitement est asynchrone. Après un téléversement réussi, il faut généralement quelques minutes avant que la piste de texte devienne disponible dans la lecture de l’enregistrement. La durée exacte dépend de la charge du serveur et de la taille du fichier.

La somme de contrôle est calculée exclusivement à partir des paramètres de requête de l’URL. Le corps POST contenant le fichier de sous-titres ne fait pas partie du calcul de la somme de contrôle. C’est intentionnel et conforme à la manière dont BigBlueButton gère les requêtes multipart POST.