Update a cloud transcoding task
Update a 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.
Request
Path parameters
The App ID of your project from Agora Console.
The transcoding task UUID used to identify the cloud transcoder for this request.
Query parameters
The tokenName you obtained in the response body of the Acquire method. See Acquire a builder token.
The sequence number of the Update request. The value must be greater than or equal to 0. Ensure that each subsequent Update request has a sequence number greater than the previous one. The sequence number ensures that the Agora server updates the cloud transcoder based on the latest specified configuration.
Agora recommends setting sequenceId to 0 for the first Update request, 1 for the second request, 2 for the third request, and so on. The Agora server updates the cloud transcoder according to the latest request, that is, the one with the highest sequence number.
Specifies the configuration item to be updated. Set it to services.cloudTranscoder.config to indicate a full update.
Request body
When updating a cloud transcoder, the request body must contain all the fields from the Create request 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.
BODYrequired
- services objectrequired
Show propertiesHide properties
- cloudTranscoder objectrequired
Show propertiesHide properties
- serviceType stringrequired
The service type. Use
"cloudTranscoderV2". - config objectrequired
Show propertiesHide properties
- transcoder objectrequired
Show propertiesHide properties
- idleTimeout numbernullable
Default:
300Possible values:
1 to 86400The maximum period (in seconds) that Cloud Transcoder can be idle. Idle means that all hosts corresponding to the audio and video streams processed by Cloud Transcoder have left the channel. If the idle state exceeds the set time, Cloud Transcoder is automatically destroyed.
- streamProcessMode stringnullable
Default:
mixIf 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.
info-
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.
- audioInputs arraynullable
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.
infoEitherrtcorstreamUrlmust be filled in.Show propertiesHide properties
- streamUrl stringnullable
The URL of the audio source stream. Required when the audio input source is CDN.
- volume numbernullable
Default:
100Possible values:
0 to 200The volume of the audio source stream. This parameter only takes effect when the audio input source is CDN.
- repeat numbernullable
Default:
1The number of times to play the media stream. This parameter only takes effect when the audio input source is CDN.
1: Play the media stream once.-1: Play the media stream in a loop.n: Specify the number of times to play the media stream. Cannot be set to 0.
- rtc objectnullable
When the audio input source is RTC, this object is required.
Show propertiesHide properties
- rtcChannel stringrequired
The RTC channel name for the audio input source. Currently, only audio and video sources that subscribe to a single channel are supported. The audio source and video source must belong to the same channel.
- rtcUid numberrequired
The UID corresponding to the audio input source. The same UID must not exist in the RTC channel.
- rtcToken stringrequired
The token that the Cloud Transcoder uses to join the 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.
The UID of Cloud Transcoder in the RTC channel is randomly assigned by Agora. Therefore, when generating a token, set the uid to
0.
- videoInputs arraynullable
Video input source list, supports RTC video stream and CDN video stream. If you specify multiple input video sources, the streams are merged.
Show propertiesHide properties
- streamUrl stringnullable
The URL of the video source stream. Required when the video input source is CDN.
- repeat numbernullable
Default:
1The number of times to play the media stream. This parameter only takes effect when the input source is CDN.
1: Play the media stream once.-1: Play the media stream in a loop.n: Specify the number of times to play the media stream. Cannot be set to 0.
- rtc objectnullable
This object is required when the video input source is RTC.
Show propertiesHide properties
- rtcChannel stringrequired
The RTC channel name for the video input source. Currently, only audio and video sources that subscribe to a single channel are supported. The audio source and video source must belong to the same channel.
- rtcUid numberrequired
The UID corresponding to the video input source. The same UID must not exist in the RTC channel.
- rtcToken stringrequired
The token that the Cloud Transcoder uses to join the 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.
The UID of Cloud Transcoder in the RTC channel is randomly assigned by Agora. Therefore, when generating a token, set the uid to
0.
- placeholderImageUrl stringnullable
The URL of the placeholder image displayed when the user is offline. It must be a valid image URL and contain the
jpgorpngsuffix. - region objectrequired
Show propertiesHide properties
- x numberrequired
Possible values:
0 to 3840The 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.
- y numberrequired
Possible values:
0 to 3840The 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.
- width numberrequired
Possible values:
120 to 3840The width of the screen (px).
- height numberrequired
Possible values:
120 to 3840The height of the screen (px).
- zOrder numberrequired
Possible values:
2 to 100The layer order of the host screen.
2represents the layer above the placeholder layer.100represents the top layer.
- canvas objectrequired
Show propertiesHide properties
- width numberrequired
Possible values:
120 to 3840The width of the canvas (px).
- height numberrequired
Possible values:
120 to 3840The height of the canvas (px).
- color numberrequired
Possible values:
0 to 16777215The background color of the canvas. The RGB color value represented as a decimal number
- backgroundImage stringnullable
Canvas background image. Must be a valid image URL with a
jpgorpngsuffix. If omitted, there is no canvas background image. - fillMode stringnullable
Default:
"FILL"Fill mode for the canvas background image:
"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.
- watermarks arrayrequired
Show propertiesHide properties
- imageUrl stringrequired
The URL of the watermark image. It must be a valid URL with a
jpgorpngsuffix. - region objectrequired
Show propertiesHide properties
- x numberrequired
Possible values:
0 to 3840The x coordinate of the watermark on the canvas (px). The x coordinate is the horizontal displacement of the upper left corner of the image relative to the origin.
- y numberrequired
Possible values:
0 to 3840The y coordinate of the watermark on the canvas (px). The y coordinate is the vertical displacement of the upper left corner of the image relative to the origin.
- width numberrequired
Possible values:
120 to 3840The width of the watermark (px).
- height numberrequired
Possible values:
120 to 3840The height of the watermark (px).
- zOrder numberrequired
Possible values:
0 to 100The layer order of the watermark.
0represents the bottom layer.100represents the top layer.
- fillMode stringnullable
Default:
"FILL"Watermark 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.
- outputs arrayrequired
Configure output settings to publish to an RTC channel or CDN address.
You must specify either
streamUrlorrtc.Show propertiesHide properties
- streamUrl stringnullable
CDN streaming address.
- rtc objectrequired
Required for publishing to an RTC channel.
Show propertiesHide properties
- rtcChannel stringrequired
The RTC channel name for the transcoded audio and video.
- rtcUid numberrequired
The UID of the RTC channel for the transcoded audio and video streams. Make sure this value is different from the UID of other users in the channel.
- rtcToken stringrequired
The 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, use
outputs.rtc.rtcUidto generate the token.
- audioOption objectnullable
Show propertiesHide properties
- profileType stringnullable
Default:
AUDIO_PROFILE_DEFAULTAudio 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.
- videoOption objectnullable
Show propertiesHide properties
- width numberrequired
Possible values:
120 to 3840The width of the transcoded output video (px).
- height numberrequired
Possible values:
120 to 3840The height of the transcoded output video (px).
- bitrate numberrequired
Possible values:
1 to 10000The bitrate of the transcoded output video.
- codec stringrequired
The codec used to transcode the output video.
Possible values:
"H264": Standard H.264 encoding."VP8": Standard VP8 encoding.
- fps numbernullable
Default:
15Possible values:
1 to 30The frame rate (fps) of the transcoded output video.
- mode stringnullable
Can 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
RAWmode, the number of inputs set invideoInputscan only be 1.
Response
Response header
UUID (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.
Response body
-
If the returned status code is
2XX, the request was successful. The response body is empty. -
If the returned status code is not
200, the request failed.Non 200
- message string
Describes why 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.
Reference
Updatable fields
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.