Chapter 15 GET POST

getRecordingTextTracks – Text Tracks

The getRecordingTextTracks endpoint returns a list of all subtitle and caption tracks associated with a specific recording. Unlike most BigBlueButton API endpoints, the response is returned in JSON format rather than XML.

Endpoint

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

Both GET and POST methods are supported. When using POST, send parameters as application/x-www-form-urlencoded in the request body.

Parameters

Parameter Type Description
recordID String Required. The recording ID of the recording whose text tracks you want to retrieve. Only a single recording ID is accepted — comma-separated lists are not supported.

Unlike other recording endpoints, getRecordingTextTracks only accepts a single recordID value. Passing multiple comma-separated IDs will result in an error or unexpected behavior.

Response Fields

Each track object in the response contains the following attributes:

Field Type Description
href String The download URL for the text track file in WebVTT format.
kind String The type of text track, following the HTML5 video element specification. Possible values: subtitles or captions.
label String The display name shown in the subtitle selection menu of the recording playback interface.
lang String The language tag as defined by RFC 5646 (e.g., en-US, de-DE, pt-BR).
source String The origin of the text track. Known values: live (live transcription during the meeting), automatic (machine-generated after the meeting), upload (manually uploaded).

Example Request

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

Example Response

Success

{
  "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 — Missing Record ID

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

Error Responses

Message Key Description
checksumError The checksum is invalid or does not match the request parameters.
missingParamRecordID The required recordID parameter was not provided in the request.
noRecordings No recording was found matching the specified recording ID.

bbbserver.de Notes

bbbserver.de: This endpoint is not available on the bbbserver.de platform. Text tracks for recordings cannot be retrieved through the API.

Tips

This is the only standard BigBlueButton API endpoint that returns JSON instead of XML. Make sure your API client handles this difference when parsing the response.

  • Use the lang field to filter tracks by language when building a subtitle selection UI for your users.
  • The href field provides a direct download link to the WebVTT file, which can be used with any standard HTML5 video player.
  • Check the source field to distinguish between manually uploaded captions and automatically generated ones, which may vary in quality.
  • To add or update text tracks, use the companion endpoint putRecordingTextTrack.

Frequently Asked Questions

The getRecordingTextTracks endpoint was added later in the BigBlueButton API evolution and was designed to return JSON from the start. This is an exception to the general rule that BigBlueButton API responses use XML. Your client code needs to handle this format difference accordingly.

No. Unlike other recording endpoints that accept comma-separated lists, getRecordingTextTracks only accepts a single recordID per request. To retrieve tracks for multiple recordings, you must send separate API calls for each recording.

Text tracks are provided in WebVTT (Web Video Text Tracks) format, the standard subtitle format for HTML5 video playback. The file can be downloaded directly from the URL provided in the href field of the response.

Subtitles are intended for viewers who can hear the audio but need a text translation, while captions are designed for deaf or hard-of-hearing viewers and may include descriptions of non-speech audio such as sound effects. The kind field in the response indicates which type a given track is.

The known values are: live (generated during the meeting via live transcription), automatic (machine-generated after the meeting), and upload (manually uploaded by a user). Note that these values are based on source code analysis and community observations, as they are not fully documented in the official specification.