API version: 4.x latest 3.x

You are viewing the API documentation for BigBlueButton 3.x. The current version is BigBlueButton 4.x. Planning an upgrade? The migration guide lists every change your API calls need.

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. The URL contains a single-use token that expires after one hour.
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 via speech recognition), 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/bigbluebutton/textTrack/replace-with-token/replace-with-recording-id/subtitles_de-DE.vtt",
        "kind": "subtitles",
        "label": "Deutsch",
        "lang": "de-DE",
        "source": "upload"
      },
      {
                "href": "https://api-guide.bbbserver.com/bigbluebutton/textTrack/replace-with-token/replace-with-recording-id/subtitles_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.

Tips

Like putRecordingTextTrack, this endpoint 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 download link to the WebVTT file. The link contains a single-use token that is valid for one hour, so download the file right away instead of storing or embedding the link.
  • 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 via speech recognition), and upload (manually uploaded by a user).