Chapter 16 POST

putRecordingTextTrack – Upload Text Track

The putRecordingTextTrack endpoint allows you to upload subtitle or caption files for a recording. Supported formats are SRT, SSA/ASS, and WebVTT. All uploaded files are internally converted to WebVTT. The response is returned in JSON format.

This endpoint only supports POST requests. GET requests are not accepted.

Endpoint

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

The subtitle file must be sent as multipart/form-data in the POST body. The checksum is calculated from the URL query parameters only — the POST body is not included in the checksum calculation.

URL Parameters (Query String)

Parameter Type Required Default Description
recordID String Yes — A single recording ID. Unlike other endpoints, this parameter does not accept a comma-separated list — only one recording ID is allowed.
kind Enum Yes — The type of text track. Accepted values are subtitles or captions.
lang String Yes — A language tag conforming to RFC 5646 (e.g. de-DE, en-US).
label String No Auto-detected from lang A human-readable display name for the track (e.g. "German"). If omitted, the language name is derived automatically from the lang value.

POST Body (multipart/form-data)

Parameter Type Required Default Description
file Binary Yes — The subtitle file to upload. Supported formats: SRT (application/x-subrip), SSA/ASS, and WebVTT (text/vtt). If the file is missing or empty, the API returns a FAILED response.

Example Request

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"

Example Response

A successful call returns the following JSON: 

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

Error Responses

messageKey Description
paramError A required parameter is missing (checksum, recordID, kind, or lang). Note: the official documentation incorrectly lists this as missingParameter.
noRecordings The specified recording ID was not found.
invalidKind The kind value is invalid. Must be subtitles or captions.
invalidLang The language tag format is invalid. It must conform to RFC 5646.
empty_uploaded_text_track The uploaded file was empty or no file was included in the request.

Important Behavior

Text track processing is asynchronous. After a successful upload, it may take several minutes before the track is available in the recording playback.

If a track with the same kind and language already exists, it is overwritten with the new file.

Uploading an empty file or sending a request without a file does not delete an existing track. The API returns a FAILED response instead.

All uploaded subtitle formats (SRT, SSA/ASS) are automatically converted to WebVTT for playback.

bbbserver.de Notes

bbbserver.de: This endpoint is not available on the bbbserver.de platform. Uploading subtitles via the API is not supported.

Tips

Use the getRecordingTextTracks endpoint to verify that your uploaded text track has been processed and is available for playback before linking it in your application.

  • WebVTT is the recommended format as it requires no conversion and is natively supported by browsers.
  • When uploading multiple language tracks, use distinct RFC 5646 language tags to avoid accidentally overwriting existing tracks.
  • Set a descriptive label parameter to help viewers identify the correct track in the playback language selector.
  • Remember that the checksum is calculated from the URL query parameters only — do not include the file content in the checksum.

Frequently Asked Questions

BigBlueButton accepts SRT (SubRip), SSA/ASS (SubStation Alpha), and WebVTT (Web Video Text Tracks) files. All formats are internally converted to WebVTT for playback. The supported formats beyond WebVTT are derived from the source code and are not explicitly listed in the official documentation.

Yes. You can call the putRecordingTextTrack endpoint multiple times with different lang values to upload tracks for different languages. Each combination of kind and lang is stored as a separate track.

The existing track with the same kind and lang combination is overwritten with the new file. There is no versioning or backup of previous tracks.

No. Sending a request without a file or with an empty file does not delete an existing track. The API simply returns a FAILED response with the error key empty_uploaded_text_track. There is no dedicated endpoint for deleting text tracks.

Processing is asynchronous. After a successful upload, it typically takes a few minutes before the text track becomes available in the recording playback. The exact duration depends on server load and file size.

The checksum is calculated exclusively from the URL query parameters. The POST body containing the subtitle file is not part of the checksum calculation. This is by design and consistent with how BigBlueButton handles multipart POST requests.