Chapitre 15 GET POST

getRecordingTextTracks – Pistes de texte

Le point de terminaison getRecordingTextTracks renvoie une liste de toutes les pistes de sous-titres et de légendes associées à un enregistrement spécifique. Contrairement à la plupart des points de terminaison API BigBlueButton, la réponse est renvoyée au format JSON plutôt qu’au format XML.

Point de terminaison

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

Les méthodes GET et POST sont toutes deux prises en charge. Lors de l’utilisation de POST, envoyez les paramètres au format application/x-www-form-urlencoded dans le corps de la requête.

Paramètres

Paramètre Type Description
recordID String Requis. L'identifiant de l'enregistrement dont vous souhaitez récupérer les pistes de texte. Un seul identifiant d'enregistrement est accepté — les listes séparées par des virgules ne sont pas prises en charge.

Contrairement aux autres endpoints d'enregistrement, getRecordingTextTracks n'accepte qu'une seule valeur recordID. Le passage de plusieurs identifiants séparés par des virgules entraînera une erreur ou un comportement inattendu.

Champs de réponse

Chaque objet track dans la réponse contient les attributs suivants :

Champ Type Description
href String L’URL de téléchargement du fichier de piste texte au format WebVTT.
kind String Le type de piste texte, conformément à la spécification de l’élément vidéo HTML5. Valeurs possibles : subtitles ou captions.
label String Le nom d'affichage montré dans le menu de sélection des sous-titres de l'interface de lecture de l'enregistrement.
lang String La balise de langue telle que définie par RFC 5646 (par ex., en-US, de-DE, pt-BR).
source String L'origine de la piste de texte. Valeurs connues : live (transcription en direct pendant la réunion), automatic (générée automatiquement après la réunion), upload (téléversée manuellement).

Exemple de requête

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

Exemple de réponse

Succès

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

Erreur — ID d’enregistrement manquant

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

Réponses d’erreur

Clé du message Description
checksumError Le checksum est invalide ou ne correspond pas aux paramètres de la requête.
missingParamRecordID Le paramètre requis recordID n’a pas été fourni dans la requête.
noRecordings Aucun enregistrement correspondant à l'identifiant d'enregistrement spécifié n'a été trouvé.

Notes bbbserver.de

bbbserver.de: Ce point de terminaison n’est pas disponible sur la plateforme bbbserver.de. Les pistes texte des enregistrements ne peuvent pas être récupérées via l’API.

Conseils

C’est le seul point de terminaison API standard de BigBlueButton qui renvoie du JSON au lieu de XML. Assurez-vous que votre client API gère cette différence lors de l’analyse de la réponse.

  • Utilisez le champ lang pour filtrer les pistes par langue lors de la création d'une interface de sélection de sous-titres pour vos utilisateurs.
  • Le champ href fournit un lien de téléchargement direct vers le fichier WebVTT, qui peut être utilisé avec n’importe quel lecteur vidéo HTML5 standard.
  • Vérifiez le champ source pour distinguer les légendes téléversées manuellement de celles générées automatiquement, dont la qualité peut varier.
  • Pour ajouter ou mettre à jour des pistes de texte, utilisez l'endpoint compagnon putRecordingTextTrack.

Foire aux questions

Le point de terminaison getRecordingTextTracks a été ajouté plus tard dans l’évolution de l’API BigBlueButton et a été conçu dès le départ pour renvoyer du JSON. Il s’agit d’une exception à la règle générale selon laquelle les réponses de l’API BigBlueButton utilisent XML. Votre code client doit gérer cette différence de format en conséquence.

Non. Contrairement aux autres points de terminaison d’enregistrement qui acceptent des listes séparées par des virgules, getRecordingTextTracks n’accepte qu’un seul recordID par requête. Pour récupérer les pistes de plusieurs enregistrements, vous devez envoyer des appels API séparés pour chaque enregistrement.

Les pistes texte sont fournies au format WebVTT (Web Video Text Tracks), le format de sous-titres standard pour la lecture vidéo HTML5. Le fichier peut être téléchargé directement à partir de l’URL fournie dans le champ href de la réponse.

Les sous-titres sont destinés aux spectateurs qui peuvent entendre l’audio mais ont besoin d’une traduction textuelle, tandis que les légendes sont conçues pour les spectateurs sourds ou malentendants et peuvent inclure des descriptions de sons non verbaux tels que les effets sonores. Le champ kind dans la réponse indique de quel type il s’agit.

Les valeurs connues sont : live (généré pendant la réunion via transcription en direct), automatic (généré automatiquement après la réunion) et upload (téléversé manuellement par un utilisateur). Notez que ces valeurs sont basées sur l’analyse du code source et les observations de la communauté, car elles ne sont pas entièrement documentées dans la spécification officielle.