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.
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
langfield to filter tracks by language when building a subtitle selection UI for your users. - The
hreffield provides a download link to theWebVTTfile. 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
sourcefield 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
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.getRecordingTextTracks only accepts a single recordID per request. To retrieve tracks for multiple recordings, you must send separate API calls for each recording.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.kind field in the response indicates which type a given track is.live (generated during the meeting via live transcription), automatic (machine-generated via speech recognition), and upload (manually uploaded by a user).