Cloud Transcoding
ABR codec templates, builder tokens (5-minute TTL), transcoder task lifecycle and playback URLs.
Cloud Transcoding (rtsc/cloud-transcoder in the interface definition) turns a channel's raw media into multiple adaptive-bitrate (ABR) outputs, for distributing "one live stream in several qualities". The difference from Media Push is: Media Push is responsible for sending the stream out, while Cloud Transcoding is responsible for turning the stream into several renditions.
Resource model (the three layers that are easy to confuse)
ABR codec template → describes "which renditions exist" (encoding parameters for 1080p / 720p / 480p)
builderToken → one-shot write credential, 5-minute TTL, usable only to create/update tasks
task → the transcoding task that actually runs: input channel + output renditions, with a lifecycleThe order cannot be reversed: the template comes first, then you take a builderToken, then you create the task.
Step 1: configure the ABR template
# list existing templates
curl -s "$NIMEET_API_BASE/v1/projects/$APP_ID/rtls/abr/config/codecs" \
-H "Authorization: Basic $NIMEET_CUSTOMER_BASIC"
# create / overwrite one rendition (you choose the codecId, e.g. "720p")
curl -s -X POST "$NIMEET_API_BASE/v1/projects/$APP_ID/rtls/abr/config/codecs/720p" \
-H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
-H 'Content-Type: application/json' \
-d '{"enabled":true,"video":{"width":1280,"height":720,"frameRate":30,"bitrate":2000}}'Both body fields are required: enabled (boolean) and video (object). codecId is a path parameter, and POSTing the same id again overwrites it.
Step 2: obtain a builderToken (5 minutes, single use)
curl -s -X POST "$NIMEET_API_BASE/v1/projects/$APP_ID/rtsc/cloud-transcoder/builderTokens" \
-H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
-H 'Content-Type: application/json' \
-d '{"instanceId":"transcoder-1","services":{"cloudTranscoder":{"channelName":"weekly-sync"}}}'| Field | Description |
|---|---|
instanceId | Transcoding instance identifier (required string); several operations on the same instance share state |
services | Service configuration (required object); the cloudTranscoder sub-object carries the channel, the output renditions, and so on |
Response tokenName | The builderToken parameter for later operations; valid for the next 5 minutes only and usable successfully exactly once |
Step 3: create the transcoding task
curl -s -X POST "$NIMEET_API_BASE/v1/projects/$APP_ID/rtsc/cloud-transcoder/tasks?builderToken=$BUILDER_TOKEN" \
-H "Authorization: Basic $NIMEET_CUSTOMER_BASIC" \
-H 'Content-Type: application/json' \
-d '{"instanceId":"transcoder-1","services":{"cloudTranscoder":{"channelName":"weekly-sync","outputs":["720p","480p"]}}}'The response is a task snapshot: taskId, createTs, status, sequenceId, services, eventHandlers, execution, properties, variables, workflows. sequenceId is used for optimistic concurrency on later updates.
Lifecycle
| Operation | Endpoint | Required parameters |
|---|---|---|
| Create | POST /v1/projects/{appId}/rtsc/cloud-transcoder/tasks | builderToken (query) |
| Query | GET /v1/projects/{appId}/rtsc/cloud-transcoder/tasks/{taskId} | builderToken (query) |
| Update | PATCH /v1/projects/{appId}/rtsc/cloud-transcoder/tasks/{taskId} (body: services) | builderToken (query) |
| Destroy | DELETE /v1/projects/{appId}/rtsc/cloud-transcoder/tasks/{taskId} | builderToken (query) |
Note that queries need a builderToken as well — that is Agora's Cloud Transcoding design (all task operations go through a temporary credential), not an extra restriction on our side.
Relationship with other media services
| Combination | Effect |
|---|---|
| Cloud Transcoding + Media Push | Multi-rendition output is pushed to a CDN and viewers pick a rendition based on their network |
| Cloud Transcoding + Cloud Recording | Records several renditions (more storage and cost; usually only one is recorded) |
| Media Gateway + Cloud Transcoding | OBS pushes into the channel, which is then transcoded into several renditions for distribution |
Quotas and errors
| Scenario | Response |
|---|---|
| Service not enabled | 403 service_not_enabled |
| builderToken expired / already used / unknown | 401 invalid_token (message: builderToken is unknown, already used or has expired) |
services.cloudTranscoder.config.transcoder missing | 400 invalid_parameter (that nested structure is required) |
| Concurrent transcoding tasks exceeded | 429 streaming_quota_exceeded |
End-to-end example
node run-all.mjs --only=2121-cloud-transcoding-lifecycle.mjs: create template → request builderToken → create task → query → destroy (writes, so it needs --all).