Capítulo 16 POST

putRecordingTextTrack – Subir pista de texto

El endpoint putRecordingTextTrack te permite subir archivos de subtítulos o leyendas para una grabación. Los formatos compatibles son SRT, SSA/ASS y WebVTT. Todos los archivos subidos se convierten internamente a WebVTT. La respuesta se devuelve en formato JSON.

Este endpoint solo admite solicitudes POST. No se aceptan solicitudes GET.

Endpoint

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

El archivo de subtítulos debe enviarse como multipart/form-data en el cuerpo POST. La suma de verificación se calcula únicamente a partir de los parámetros de consulta de la URL; el cuerpo POST no se incluye en el cálculo de la suma de verificación.

Parámetros de URL (cadena de consulta)

Parámetro Tipo Obligatorio Predeterminado Descripción
recordID String Sí — Un único ID de grabación. A diferencia de otros endpoints, este parámetro no acepta una lista separada por comas; solo se permite un ID de grabación.
kind Enum Sí — El tipo de pista de texto. Los valores aceptados son subtitles o captions.
lang String Sí — Una etiqueta de idioma conforme con RFC 5646 (por ejemplo, de-DE, en-US).
label String No Detectado automáticamente a partir de lang Un nombre para mostrar legible para la pista (p. ej. "German"). Si se omite, el nombre del idioma se deriva automáticamente del valor lang.

Cuerpo de POST (multipart/form-data)

Parámetro Tipo Obligatorio Predeterminado Descripción
file Binary Sí — El archivo de subtítulos que se va a subir. Formatos compatibles: SRT (application/x-subrip), SSA/ASS y WebVTT (text/vtt). Si el archivo falta o está vacío, la API devuelve una respuesta FAILED.

Ejemplo de solicitud

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"

Respuesta de ejemplo

Una llamada correcta devuelve el siguiente JSON: 

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

Respuestas de error

messageKey Descripción
paramError Falta un parámetro obligatorio (checksum, recordID, kind o lang). Nota: la documentación oficial enumera esto incorrectamente como missingParameter.
noRecordings No se encontró el ID de grabación especificado.
invalidKind El valor de kind no es válido. Debe ser subtitles o captions.
invalidLang El formato de la etiqueta de idioma no es válido. Debe cumplir con RFC 5646.
empty_uploaded_text_track El archivo subido estaba vacío o no se incluyó ningún archivo en la solicitud.

Comportamiento importante

El procesamiento de pistas de texto es asíncrono. Después de una subida exitosa, pueden pasar varios minutos antes de que la pista esté disponible en la reproducción de la grabación.

Si ya existe una pista con la misma kind e idioma, se sobrescribe con el nuevo archivo.

Subir un archivo vacío o enviar una solicitud sin archivo no elimina una pista existente. La API devuelve una respuesta FAILED en su lugar.

Todos los formatos de subtítulos subidos (SRT, SSA/ASS) se convierten automáticamente a WebVTT para la reproducción.

bbbserver.de Notas

bbbserver.de: Este endpoint no está disponible en la plataforma bbbserver.de. No se admite la carga de subtítulos mediante la API.

Consejos

Usa el endpoint getRecordingTextTracks para verificar que la pista de texto subida ha sido procesada y está disponible para la reproducción antes de enlazarla en tu aplicación.

  • WebVTT es el formato recomendado, ya que no requiere conversión y es compatible de forma nativa con los navegadores.
  • Al subir varias pistas de idioma, usa etiquetas de idioma RFC 5646 distintas para evitar sobrescribir accidentalmente pistas existentes.
  • Establece un parámetro label descriptivo para ayudar a los espectadores a identificar la pista correcta en el selector de idioma de reproducción.
  • Recuerda que el checksum se calcula solo a partir de los parámetros de consulta de la URL; no incluyas el contenido del archivo en el checksum.

Preguntas frecuentes

BigBlueButton acepta archivos SRT (SubRip), SSA/ASS (SubStation Alpha) y WebVTT (Web Video Text Tracks). Todos los formatos se convierten internamente a WebVTT para la reproducción. Los formatos compatibles además de WebVTT se derivan del código fuente y no figuran explícitamente en la documentación oficial.

Sí. Puedes llamar al endpoint putRecordingTextTrack varias veces con distintos valores de lang para subir pistas de distintos idiomas. Cada combinación de kind y lang se almacena como una pista independiente.

La pista existente con la misma combinación de kind y lang se sobrescribe con el nuevo archivo. No hay versionado ni copia de seguridad de las pistas anteriores.

No. Enviar una solicitud sin archivo o con un archivo vacío no elimina una pista existente. La API simplemente devuelve una respuesta FAILED con la clave de error empty_uploaded_text_track. No existe un endpoint específico para eliminar pistas de texto.

El procesamiento es asíncrono. Después de una subida exitosa, normalmente pasan unos minutos antes de que la pista de texto esté disponible en la reproducción de la grabación. La duración exacta depende de la carga del servidor y del tamaño del archivo.

La suma de verificación se calcula exclusivamente a partir de los parámetros de consulta de la URL. El cuerpo POST que contiene el archivo de subtítulos no forma parte del cálculo de la suma de verificación. Esto es intencional y coherente con la forma en que BigBlueButton maneja las solicitudes multipart POST.