Capítulo 15 GET POST

getRecordingTextTracks – Pistas de texto

El endpoint getRecordingTextTracks devuelve una lista de todas las pistas de subtítulos y captions asociadas a una grabación específica. A diferencia de la mayoría de los endpoints de la API de BigBlueButton, la respuesta se devuelve en formato JSON en lugar de XML.

Endpoint

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

Se admiten los métodos GET y POST. Al usar POST, envía los parámetros como application/x-www-form-urlencoded en el cuerpo de la solicitud.

Parámetros

Parámetro Tipo Descripción
recordID String Obligatorio. El ID de la grabación de la cual quieres recuperar las pistas de texto. Solo se acepta un único ID de grabación; no se admiten listas separadas por comas.

A diferencia de otros endpoints de grabación, getRecordingTextTracks solo acepta un único valor de recordID. Pasar varios IDs separados por comas dará lugar a un error o a un comportamiento inesperado.

Campos de respuesta

Cada objeto de pista en la respuesta contiene los siguientes atributos:

Campo Tipo Descripción
href String La URL de descarga del archivo de pista de texto en formato WebVTT.
kind String El tipo de pista de texto, siguiendo la especificación del elemento de vídeo HTML5. Valores posibles: subtitles o captions.
label String El nombre para mostrar que aparece en el menú de selección de subtítulos de la interfaz de reproducción de la grabación.
lang String La etiqueta de idioma según se define en RFC 5646 (p. ej., en-US, de-DE, pt-BR).
source String El origen de la pista de texto. Valores conocidos: live (transcripción en vivo durante la reunión), automatic (generada automáticamente después de la reunión), upload (subida manualmente).

Ejemplo de solicitud

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

Respuesta de ejemplo

Éxito

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

Error — Falta el ID del registro

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

Respuestas de error

Clave del mensaje Descripción
checksumError El checksum es inválido o no coincide con los parámetros de la solicitud.
missingParamRecordID El parámetro obligatorio recordID no se proporcionó en la solicitud.
noRecordings No se encontró ninguna grabación que coincida con el ID de grabación especificado.

bbbserver.de Notas

bbbserver.de: Este endpoint no está disponible en la plataforma bbbserver.de. Las pistas de texto de las grabaciones no pueden recuperarse mediante la API.

Consejos

Este es el único endpoint estándar de la API de BigBlueButton que devuelve JSON en lugar de XML. Asegúrate de que tu cliente API maneje esta diferencia al analizar la respuesta.

  • Usa el campo lang para filtrar pistas por idioma al crear una interfaz de selección de subtítulos para tus usuarios.
  • El campo href proporciona un enlace de descarga directa al archivo WebVTT, que puede utilizarse con cualquier reproductor de vídeo estándar HTML5.
  • Comprueba el campo source para distinguir entre subtítulos subidos manualmente y los generados automáticamente, cuya calidad puede variar.
  • Para añadir o actualizar pistas de texto, usa el endpoint complementario putRecordingTextTrack.

Preguntas frecuentes

El endpoint getRecordingTextTracks se añadió más tarde en la evolución de la API de BigBlueButton y fue diseñado para devolver JSON desde el principio. Esta es una excepción a la regla general de que las respuestas de la API de BigBlueButton usan XML. Tu código cliente debe gestionar esta diferencia de formato en consecuencia.

No. A diferencia de otros endpoints de grabación que aceptan listas separadas por comas, getRecordingTextTracks solo acepta un único recordID por solicitud. Para recuperar pistas de varias grabaciones, debes enviar llamadas API separadas para cada grabación.

Las pistas de texto se proporcionan en formato WebVTT (Web Video Text Tracks), el formato estándar de subtítulos para la reproducción de vídeo HTML5. El archivo puede descargarse directamente desde la URL proporcionada en el campo href de la respuesta.

Los subtítulos están pensados para espectadores que pueden oír el audio pero necesitan una traducción textual, mientras que los captions están diseñados para espectadores sordos o con dificultades auditivas y pueden incluir descripciones de audio no verbal, como efectos de sonido. El campo kind en la respuesta indica qué tipo es una pista determinada.

Los valores conocidos son: live (generado durante la reunión mediante transcripción en vivo), automatic (generado automáticamente después de la reunión) y upload (subido manualmente por un usuario). Ten en cuenta que estos valores se basan en análisis del código fuente y observaciones de la comunidad, ya que no están completamente documentados en la especificación oficial.