Update a cloud transcoding task
Updated
Updates an existing Cloud Transcoding task.
https://api.sd-rtn.com/v1/projects/{appId}/rtsc/cloud-transcoder/tasks/{taskId}Use this endpoint to Update a Cloud Transcoding task.
appIdstringThe App ID of your project from Agora Console.
taskIdstringThe transcoding task UUID used to identify the cloud transcoder for this request.
builderTokenstringThe tokenName you obtained in the response body of the Acquire method. See Acquire a builder token.
sequenceIdstringThe sequence number of the Update request. Each subsequent Update request must use a value greater than the previous one. A value equal to or lower than the current one is rejected with a 400 error.
updateMaskstringSpecifies the configuration item to be updated. Set it to services.cloudTranscoder.config to indicate a full update.
Content-TypestringThe request content type. Use application/json.
X-Request-IDstringUUID (Universally Unique Identifier), used to identify this request.
If the request fails, print out the value in the log to troubleshoot the problem. If the response status code of the request is not 2XX, then the response header may not contain this field.
Request
- When updating a cloud transcoder, the request body must contain all the fields from the
Createrequest in the request body. For fields that you do not need to update, use the original values. See Updatable fields for the Cloud Transcoding parameters you can modify.
servicesobjectcloudTranscoderobjectserviceTypestringShould be "cloudTranscoderV2".
The service type. Use "cloudTranscoderV2".
configobjectSame as the fields you set in the Create request body.
transcoderobjectidleTimeoutnumberThe maximum period, in seconds, that Cloud Transcoder can be idle. If the idle state exceeds this value, Cloud Transcoder is automatically destroyed.
streamProcessModestringIf this parameter is not specified, the working mode of Cloud transcoder is the merge mode. You can specify the following modes:
heterogeneous-single: Heterogeneous single stream mode. The types of input stream and output stream can be different or the same. The currently supported stream types are RTC and CDN.single: RTC stream relay mode. Relays the host's audio and video data and signaling in the source channel to the destination channel.
Note
-
If you set
streamProcessModetoheterogeneous-singleorsingle, then theaudioInputsorvideoInputslist may contain at most one item. -
If you need to mix audio, combine images, or mix audio and combine images, no
streamProcessModesettings are required.
audioInputsarray<object>Audio input source list, supports two types: RTC audio stream and CDN audio stream. If you specify multiple input audio sources, the streams are mixed.
Note
Either rtc or streamUrl must be filled in.
streamUrlstringThe URL of the audio source stream. Required when the audio input source is CDN.
volumenumberThe volume of the audio source stream. This parameter only takes effect when the audio input source is CDN.
repeatnumberThe number of times to play the media stream. 1 means play once, -1 means loop, and any positive integer specifies a playback count.
rtcobjectWhen the audio input source is RTC, this object is required.
rtcChannelstringThe RTC channel name for the input source. Currently, you can only subscribe to audio and video sources from a single channel; the audio and video sources must belong to the same channel.
rtcUidnumberThe UID of the input source user. This UID uniquely identifies the user whose audio or video stream is being transcoded in the RTC channel.
rtcTokenstringThe token that Cloud Transcoder uses to join the input RTC channel for transcoding. Using a token ensures channel security and prevents malicious users from disrupting other users in the channel. See Token authentication for details.
Cloud Transcoder's UID in the input RTC channel is randomly assigned by Agora.
When generating this token, set uid to 0.
videoInputsarray<object>Video input source list, supports RTC video stream and CDN video stream. If you specify multiple input video sources, the streams are merged.
streamUrlstringThe URL of the video source stream. Required when the video input source is CDN.
repeatnumberThe number of times to play the media stream. 1 means play once, -1 means loop, and any positive integer specifies a playback count.
rtcobjectThis object is required when the video input source is RTC.
rtcChannelstringThe RTC channel name for the input source. Currently, you can only subscribe to audio and video sources from a single channel; the audio and video sources must belong to the same channel.
rtcUidnumberThe UID of the input source user. This UID uniquely identifies the user whose audio or video stream is being transcoded in the RTC channel.
rtcTokenstringThe token that Cloud Transcoder uses to join the input RTC channel for transcoding. Using a token ensures channel security and prevents malicious users from disrupting other users in the channel. See Token authentication for details.
Cloud Transcoder's UID in the input RTC channel is randomly assigned by Agora.
When generating this token, set uid to 0.
placeholderImageUrlstringThe URL of the placeholder image displayed when the user is offline. It must be a valid image URL and contain the jpg or png suffix.
regionobjectxnumberThe x coordinate of the image on the canvas (px). The x coordinate is the horizontal displacement of the upper left corner of the image relative to the origin, where the upper left corner of the canvas is the origin.
ynumberThe y coordinate of the image on the canvas (px). The y coordinate is the vertical displacement of the upper left corner of the image relative to the origin, where the upper left corner of the canvas is the origin.
widthnumberThe width of the video region (px). The region must fit within the canvas and can't exceed 1920 × 1080.
heightnumberThe height of the video region (px). The region must fit within the canvas and can't exceed 1920 × 1080.
zOrdernumberThe layer order of the host screen. 0 represents the bottom layer. 100 represents the top layer.
canvasobjectwidthnumberThe width of the canvas (px).
heightnumberThe height of the canvas (px).
colornumberThe background color of the canvas as a decimal RGB value.
backgroundImagestringCanvas background image. Must be a valid image URL with a jpg or png suffix. If omitted, there is no canvas background image.
fillModestringFill mode for the canvas background image.
waterMarksarray<object>Watermark list. To add no watermarks, omit this field. An empty list isn't accepted.
imageUrlstringThe URL of the watermark image.
regionobjectxnumberThe x coordinate of the watermark on the canvas (px). The x coordinate is the horizontal displacement of the upper left corner of the watermark relative to the upper left corner of the canvas.
ynumberThe y coordinate of the watermark on the canvas (px). The y coordinate is the vertical displacement of the upper left corner of the watermark relative to the upper left corner of the canvas.
widthnumberThe width of the watermark (px).
heightnumberThe height of the watermark (px).
zOrdernumberThe layer order of the watermark. 0 represents the bottom layer. 100 represents the top layer.
fillModestringWatermark fill mode:
"FILL": Scale the image and crop it in the center while maintaining the aspect ratio."FIT": Scale the image to fill the display while maintaining the aspect ratio.
outputsarray<object>Configure output settings to publish to a single RTC channel or to CDN addresses. The array can contain only one output.
RTC and CDN outputs are mutually exclusive. You must specify either streamUrl or rtc, but not both.
streamUrlarray<string>The CDN addresses to publish the transcoded stream to. You can specify up to 10 addresses. All addresses share the audioOption and videoOption settings of this output.
rtcobjectRequired for publishing to an RTC channel. Currently, you can publish to only one RTC channel.
rtcChannelstringThe RTC channel name for the transcoded audio and video.
rtcUidnumberThe UID of Cloud Transcoder in the output RTC channel. Make sure this value is different from the UID of other users in the channel.
rtcTokenstringThe token that the Cloud Transcoder uses to join the output RTC channel. Using a token ensures channel security and prevents malicious users from disrupting other users in the channel. See Token authentication for details.
When generating this token, set uid to the value of outputs.rtc.rtcUid.
audioOptionobjectprofileTypestringAudio properties of the transcoded output:
"AUDIO_PROFILE_DEFAULT": 48 kHz sampling rate, music encoding, mono channel, maximum encoding bitrate is 64 Kbps."AUDIO_PROFILE_SPEECH_STANDARD": 32 kHz sampling rate, speech encoding, mono channel, maximum encoding bitrate is 18 Kbps."AUDIO_PROFILE_MUSIC_STANDARD": 48 KHz sampling rate, music encoding, mono channel, maximum encoding bitrate is 64 Kbps."AUDIO_PROFILE_MUSIC_STANDARD_STEREO": 48 KHz sampling rate, music encoding, stereo channel, maximum encoding bitrate is 80 Kbps."AUDIO_PROFILE_MUSIC_HIGH_QUALITY": 48 KHz sampling rate, music encoding, mono channel, maximum encoding bitrate is 96 Kbps."AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO": 48 kHz sampling rate, music encoding, dual channels, and a maximum encoding bitrate of 128 Kbps.
videoOptionobjectwidthnumberThe width of the transcoded output video (px). The output resolution can't exceed 1920 × 1080.
heightnumberThe height of the transcoded output video (px). The output resolution can't exceed 1920 × 1080.
bitratenumberThe bitrate of the transcoded output video.
codecstringThe codec used to transcode the output video.
Possible values:
"H264": Standard H.264 encoding. Supported for RTC and CDN outputs."H265": Standard H.265 encoding. Supported for RTC and CDN outputs."VP8": Standard VP8 encoding. Supported for RTC outputs only.
fpsnumberThe frame rate (fps) of the transcoded output video.
modestringCan be set to RAW, which means the output video is not transcoded. The encoding format of the input video remains unchanged.
If the output video is transcoded, do not set this field.
In RAW mode, the number of inputs set in videoInputs can only be 1.
lowBitrateHighQualitybooleanWhether to enable low-bitrate high-quality mode.
Response
-
If the returned status code is
200, the request was successful. The response body contains the updated task. -
If the returned status code is not
200, the request failed. -
If the request fails, use the
X-Request-IDvalue in the log to troubleshoot the problem. If the response status code is not2XX, then the response header may not contain this field.
Response Body
The request succeeded and returned task information. sequenceId is the value you passed, and services.cloudTranscoder.config contains the updated configuration.
Response Headers
taskIdstringA UUID used to identify the cloud transcoder for this request operation.
createTsnumberUnix timestamp (seconds) when the transcoding task was created.
statusstringThe running status of the transcoding task:
"IDLE": Task not started."PREPARED": The task has received a start request."STARTING": The task is starting."CREATED": Task initialization completed."STARTED": The task has started."IN_PROGRESS": Task in progress."STOPPING": The task is stopping."STOPPED": The task has stopped."EXIT": The task exited normally."FAILURE_STOP": The task exited abnormally.
sequenceIdstringThe sequence ID.
servicesobjectcloudTranscoderobjectconfigobjectSame as the fields you set in the Create request body.
createTsnumberUnix timestamp (in seconds) when the service was created.
detailsobjectReserved field.
messagestringReserved field.
serviceTypestringShould be "cloudTranscoderV2".
statusstringThe running status of the transcoding service in the transcoding task:
"serviceIdle": The service has not started."serviceReady": The service is ready to start."serviceStarted": The service has started."serviceInProgress": The service is currently running."serviceCompleted": The service has stopped, and all tasks have been completed."servicePartialCompleted": The service has stopped, but the task was only partially completed."serviceValidationFailed": The service failed due to invalid parameters."serviceAbnormal": The service exited unexpectedly."serviceUnknown": The service status is unknown.
This field is meant for the Agora technical team to investigate any issues. You do not need to focus on it.
eventHandlersobjectexecutionobjectpropertiesobjectvariablesobjectworkflowsobjectReference
The Update request supports modifying the following fields only:
- Add or delete
rtcmembers inaudioInputs[]andvideoInputs[]to subscribe or unsubscribe from the host's audio and video streams. - Modify the
regionfield invideoInputs[]to update the host's combined picture layout. - Modify the
audioOptionandvideoOptionfields inoutputs[]to update the transcoding output audio and video configurations.
Response
See Updatable fields for the Cloud Transcoding parameters you can modify.
Request examples
# Use a sequenceId greater than the previous update request.# Send the full configuration; keep unchanged fields at their original values.curl --request PATCH \ --url 'https://api.sd-rtn.com/v1/projects/<app_id>/rtsc/cloud-transcoder/tasks/<task_id>?builderToken=<builder_token>&sequenceId=1&updateMask=services.cloudTranscoder.config' \ --header 'Authorization: Basic <credentials>' \ --header 'Content-Type: application/json' \ --data ' { "services": { "cloudTranscoder": { "serviceType": "cloudTranscoderV2", "config": { "transcoder": { "idleTimeout": 300, "audioInputs": [ { "rtc": { "rtcChannel": "test01", "rtcUid": 123, "rtcToken": "aab8b8f5a8cd4469a63042fcfafe7***" } }, { "rtc": { "rtcChannel": "test01", "rtcUid": 456, "rtcToken": "aab8b8f5a8cd4469a63042fcfafe7***" } } ], "canvas": { "width": 960, "height": 480, "color": 0, "backgroundImage": "https://example.jpg", "fillMode": "FIT" }, "waterMarks": [ { "imageUrl": "https://example.png", "region": { "x": 0, "y": 0, "width": 120, "height": 120, "zOrder": 50 } } ], "videoInputs": [ { "rtc": { "rtcChannel": "test01", "rtcUid": 123, "rtcToken": "aab8b8f5a8cd4469a63042fcfafe7***" }, "placeholderImageUrl": "https://example.jpg", "region": { "x": 0, "y": 0, "width": 320, "height": 360, "zOrder": 2 } }, { "rtc": { "rtcChannel": "test01", "rtcUid": 456, "rtcToken": "aab8b8f5a8cd4469a63042fcfafe7***" }, "placeholderImageUrl": "https://example.jpg", "region": { "x": 320, "y": 0, "width": 320, "height": 320, "zOrder": 2 } } ], "outputs": [ { "rtc": { "rtcChannel": "test", "rtcUid": 1000, "rtcToken": "aab8b8f5a8cd4469a63042fcfafe7***" }, "audioOption": { "profileType": "AUDIO_PROFILE_MUSIC_STANDARD" }, "videoOption": { "fps": 30, "codec": "H264", "bitrate": 800, "width": 960, "height": 480, "lowBitrateHighQuality": false } } ] } } } } }'Response example
{ "createTs": 1661324613, "eventHandlers": {}, "execution": { "workflows": {} }, "properties": {}, "sequenceId": "1", "services": { "cloudTranscoder": { "config": {}, "createTs": 1661324614, "details": {}, "message": "", "serviceType": "cloudTranscoderV2", "status": "serviceInProgress" } }, "status": "IN_PROGRESS", "taskId": "609f28f2644f1ae1ceb041b7047e3***", "variables": {}, "workflows": {}}