Create or reset template
Updated
Creates or resets a Media Gateway flow configuration template.
https://api.agora.io/{region}/v1/projects/{appId}/rtls/ingress/stream-templates/{templateId}In the template, you can configure transcoding parameters for video or audio streams, as well as parameters for mitigating network latency.
Up to 10 flow configuration templates can be created under an app ID, each with a unique templateId. Specify the templateId when creating a template; if a template corresponding to this ID already exists, the existing template will be reset with the incoming body data.
There are two ways to use flow configuration templates, which can be used in combination:
- Specify a global template for the app ID: All streaming keys under the app ID will use this template by default.
- Specify a configuration template for a specific streaming key: When using this key to push streams, the specific template will be used.
Note
By default, a template is not set for the app ID. That is, video transcoding is not enabled.
Path Parameters
regionstringRegion for the streaming key or stream. Supported values are na for North America, eu for Europe, ap for Asia except mainland China, and cn for mainland China.
Important
Make sure that:
- The
regionvalue is the same as for the input source stream. - The domain names for setting the
regionparameter and streaming are the same. - The
regionvalue is in lowercase.
appIdstringThe app ID provided by Agora to each developer. After creating a project in Agora Console, you can get an app ID. The app ID is a unique identifier for a project.
templateIdstringThe flow configuration template ID. The value can contain only lowercase letters, uppercase letters, and numbers, and cannot exceed 12 bytes. Set the value according to your business use case. For example, use "720p" and "1080p" for different target resolutions, or "gameA" and "gameB" for different game use cases.
Header Parameters
X-Request-IDstringThe UUID (Universally Unique Identifier) of the request. After you pass in this field, the Agora server returns this field in the response header. It is recommended to assign X-Request-ID a value. If omitted, the Agora server automatically generates a UUID and returns it.
Request Body
application/json
settingsobjectNote
To ensure a successful request, do not set the required fields to null or leave them empty.
transcodingobjectAudio and video transcoding configuration.
videoobjectenabledbooleanWhether to enable video transcoding.
modestringVideo transcoding mode. force forces transcoding. adaptive enables transcoding when the source stream contains B-frames.
codecstringCodec format for transcoding.
widthintegerEncoding width of the main stream in pixels. If not specified or set to 0, the source stream width is used unless height is set.
Note
If the ABR function is enabled, this field is required.
heightintegerEncoding height of the main stream in pixels. If not specified or set to 0, the source stream height is used unless width is set.
Note
If the ABR function is enabled, this field is required.
fpsintegerVideo encoding frame rate in fps. If not specified or set to 0, the source stream frame rate is used.
bitrateintegerEncoding bitrate of the main stream in Kbps. If omitted, the source stream bitrate is used. If set to 0, Agora automatically chooses a bitrate based on width and height.
Note
If you enable low-speed streaming (provide the following simulcastStream object), this field is required. If you do not enable low-speed streaming, it is recommended to use the automatically matched bitrate without setting the bitrate yourself.
advancedOptionsobjectpvcobjectenabledbooleanWhether to enable PVC.
saveBitrateRatiointegerBitrate saving ratio for PVC. For example, 20 means saving 20 percent of the bitrate. This parameter is effective only when video.bitrate is missing or 0.
superResolutionobjectenabledbooleanWhether to enable Super Resolution.
alphaBlendingintegerSuper Resolution intensity. Larger values indicate higher intensity.
simulcastStreamobjectLow-quality video stream configuration. If provided, Media Gateway enables the low-quality stream and uses these transcoding parameters.
widthintegerWidth in pixels. The value must be less than video.width. If omitted or set to 0, video.width / 2 is used.
heightintegerHeight in pixels. The value must be less than video.height. If omitted or set to 0, video.height / 2 is used.
fpsintegerFrame rate in fps. The value must be less than or equal to video.fps. If omitted or set to 0, the default value is 15.
bitrateintegerBitrate of the low-quality video stream in Kbps. The value must be less than video.bitrate. If omitted or set to 0, Agora chooses an appropriate bitrate based on resolution and fps.
Note
When enabling the low-quality stream and specifying low-quality bitrate, you need to specify video.bitrate at the same time.
simulcastStreamLayersarray<object>Layer transcoding parameters for adaptive bitrate. If specified, ABR is enabled.
Note
-
You can set either
simulcastStreamorsimulcastStreamLayer. If you set both,simulcastStreamsetting does not take effect. -
For resolution and bitrate settings for main and ABR streams, recommended values, and viewer subscription settings, refer to Enable adaptive bitrate.
idintegerLayer ID.
widthintegerEncoding width of the layer in pixels. If specified, this value must be smaller than video.width and decrease monotonically as layer ID increases.
heightintegerEncoding height of the layer in pixels. If specified, this value must be smaller than video.height and decrease monotonically as layer ID increases.
fpsintegerEncoding frame rate of the layer in fps. If specified, this value must be smaller than video.fps. If omitted or set to 0, the main stream frame rate is used.
bitrateintegerEncoding bitrate of the layer in Kbps. This value must be smaller than video.bitrate and decrease monotonically by layer ID.
audioobjectenabledbooleanWhether to enable audio transcoding.
profileintegerEncoded audio use case. The default value 0 means 48 KHz sampling rate, music encoding, mono, and a maximum encoding rate of 64 Kbps. Contact Agora technical support for other profile settings.
bitrateintegerAudio encoding bitrate in Kbps. If omitted, the value is determined by profile.
jitterBufferobjectNetwork jitter buffer. Takes effect only when video transcoding is enabled.
sizeintegerMaximum buffer length in ms. Media Gateway adds this value to the end-to-end delay to reduce lag caused by network jitter.
maxSizeintegerMaximum buffer length in ms. This value must be greater than jitterBuffer.size. When the jitter buffer exceeds this value, Media Gateway enables acceleration until it returns to jitterBuffer.size.
Response Body
The request succeeded and created or reset the template.
Response Headers
statusstringThe status of this request. success means the request succeeds.
Request examples
curl --location -g --request PUT 'https://api.agora.io/{{region}}/v1/projects/{{appId}}/rtls/ingress/stream-templates/{{templateId}}' \--data '{ "settings": { "transcoding": { "video": { "enabled": true, "codec": "H.264", "width": 1280, "height": 720, "fps": 24, "bitrate": 2200, "simulcastStream": { "width": 960, "height": 540, "fps": 24, "bitrate": 1670 } }, "audio": { "enabled": false, "profile": 3 } }, "jitterBuffer": { "size": 500, "maxSize": 800 } }}'Response example
{ "status": "success"}