Adds a real-time streaming (RTS) transcoding configuration for a streaming domain.

Usage note

This operation is applicable to main streaming domains. The supported custom template types are as follows:

  • h264: H.264.
  • h264-nbhd: H.264 Narrowband HD™.
  • h264-origin: H.264 original quality. If you use this type of template, the settings of streams remain unchanged after transcoding.
  • audio: audio-only transcoding. If you use this type of template, images are removed from input streams and audio-only streams are generated.

QPS limit

A single user can perform a maximum of 10 queries per second (QPS). Throttling is triggered when the number of calls per second exceeds the QPS limit. The throttling may affect your business. Thus, we recommend that you observe the QPS limit on this operation. For more information about what a single user means and the QPS details, see QPS limit on an API operation in ApsaraVideo Live.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

ParameterTypeRequiredExampleDescription
ActionStringYesAddRtsLiveStreamTranscode

The operation that you want to perform. Set the value to AddRtsLiveStreamTranscode.

DomainStringYesexample.com

The main streaming domain.

AppStringYesliveApp****

The name of the application to which the live stream belongs. The name must meet the following requirements:

The name support the following character types: letters, digits, underscores (_), and hyphens (-). We recommend that you specify a name that contain more than three characters in length. The name must start with a letter or digit.

TemplateStringYesld

The name of the custom transcoding template. The name must meet the following requirements:

The name support the following character types: letters, digits, underscores (_), and hyphens (-). We recommend that you specify a name that contain more than three characters in length. The name must start with a letter or digit.

Note The name cannot be the same as that of a standard transcoding template.
TemplateTypeStringYesh264

The type of the custom transcoding template. Valid values:

  • h264: H.264.
  • h264-nbhd: H.264 Narrowband HD™.
  • h264-origin: H.264 original quality. If you use this type of template, the settings of streams remain unchanged after transcoding.
  • audio: audio-only transcoding. If you use this type of template, images are removed from input streams and audio-only streams are generated.
HeightIntegerNo1280

The height of the output video. Unit: pixel.

The value must comply with all the following rules:

  • Height ≥ 100: The height of the video is at least 100 pixels.
  • max(Height,Width) ≤ 2560: The larger of the width and height of the video cannot exceed 2,560 pixels.
  • min(Height,Width) ≤ 1440: The smaller of the width and height of the video cannot exceed 1,440 pixels.

For example, a resolution of 1560 × 1560 pixels is invalid.

Note
  • An original quality template needs to retain the source information. Therefore, the video quality can be up to 4K.
  • This parameter is required if the TemplateType parameter is not set to audio.
WidthIntegerNo720

The width of the output video. Unit: pixel.

The value must comply with all the following rules:

  • Width ≥ 100: The width of the video is at least 100 pixels.
  • max(Height,Width) ≤ 2560: The larger of the width and height of the video cannot exceed 2,560 pixels.
  • min(Height,Width) ≤ 1440: The smaller of the width and height of the video cannot exceed 1,440 pixels.

For example, a resolution of 1560 × 1560 pixels is invalid.

Note
  • An original quality template needs to retain the source information. Therefore, the video quality can be up to 4K.
  • This parameter is required if the TemplateType parameter is not set to audio.
FPSIntegerNo30

The frame rate of the output video. Unit: FPS. Valid values: 1 to 60.

Note When TemplateType (custom transcoding template type) is set to h264 or h264-nbhd or h264-origin, this parameter is required.
VideoBitrateIntegerNo2000

The bitrate of the output video. Unit: Kbit/s. Valid values: 1 to 6000.

Note
  • The bitrate of the output video is as close to the value that you specify as possible, but not the same as the value, especially when the value is excessively large or small.
  • When TemplateType (custom transcoding template type) is set to h264 or h264-nbhd or h264-origin, this parameter is required.
AudioBitrateIntegerNo128

The bitrate of the output audio.

Unit: Kbit/s. Valid values: 1 to 1000.

Note When TemplateType (custom transcoding template type) is set to h264 or h264-nbhd or h264-origin, this parameter is required.
GopStringNo2

The group of pictures (GOP) of the output video. This parameter is used to specify the keyframe interval. Unit: seconds. Valid values: 1 to 3.

ProfileIntegerNo2

The video codec profile. The video codec profile determines how ApsaraVideo Live performs codec on the video. In normal cases, a greater value indicates a higher image quality and requires more codec resources. Valid values:

  • 1: baseline, which is suitable for mobile devices.
  • 2: main, which is suitable for standard-definition devices.
  • 3: high, which is suitable for high-definition devices.
DeleteBframesBooleanNofalse

Specifies whether to remove B frames during transcoding. Valid values:

  • true: Remove B frames.
  • false: Retain B frames. This is the default value.
    Note
    • If this parameter is not specified, the default value false is used.
    • When TemplateType (custom transcoding template type) is set to h264 or h264-nbhd or h264-origin, this parameter is required.
OpusBooleanNotrue

Specifies whether to transcode streams to the Opus format to be compatible with native WebRTC. Valid values:

  • true: Transcode streams to the Opus format.
  • false: Do not transcode streams to the Opus format.
    Note If this parameter is not specified, the default value false is used.
AudioCodecStringNoaac

The audio encoder. Valid values:

  • aac
  • mp3
Note To use the Opus encoder, you need only to set the Opus parameter to true.
AudioProfileStringNoaac_low

The audio codec profile. Valid values:

  • aac_low
  • aac_he
  • aac_he_v2
  • aac_ld
AudioRateIntegerNo44100

The audio sampling rate. Valid values: 22050 to 96000. The value 44100 is commonly used. Unit: Hz.

Note If the value of the AudioProfile parameter is aac_ld, the audio sampling rate cannot exceed 44,100.
AudioChannelNumIntegerNo2

The number of audio channels. Valid values:

  • 1: mono.
  • 2: stereo.
LazyStringNono

Specifies whether to trigger transcoding only when a stream is pulled. Valid values:

  • yes: Trigger transcoding only when a stream is pulled.
  • no: Trigger transcoding whenever a stream is pushed, no matter whether the stream is pulled.

Response parameters

ParameterTypeExampleDescription
RequestIdString16A96B9A-F203-4EC5-8E43-CB92E68F4CD8

The ID of the request.

Examples

Sample requests

https://live.aliyuncs.com/?Action=AddRtsLiveStreamTranscode
&Domain=example.com
&App=liveApp****
&Template=ld
&TemplateType=h264
&Height=1280
&Width=720
&FPS=25
&VideoBitrate=2400
&<Common request parameters>

Sample success responses

XML format

<AddLiveStreamTranscodeResponse>
      <RequestId>16A96B9A-F203-4EC5-8E43-CB92E68F4CD8</RequestId>
</AddLiveStreamTranscodeResponse>

JSON format

{"RequestId":"16A96B9A-F203-4EC5-8E43-CB92E68F4CD8"}

Error codes

For a list of error codes, visit the API Error Center.

Special error codes

Error code

Error message

HTTP status code

Description

InvalidDomain.NotFound

The domain provided does not exist in our records.

404

The error message returned because the domain name does not exist or does not belong to your Alibaba Cloud account.

IllegalOperation

Illegal domain operate is not permitted.

403

The error message returned because the current operation is not supported. For example, the specified domain name is not a live domain.

InvalidParameters

Invalid parameters.

400

The error message returned because one or more parameters are invalid. For example, the height or bitrate is too large.

ConfigAlreadyExists

Config has already exist.

400

The error message returned because an existing custom transcoding configuration is found.

InternalError

The request processing has failed due to some unknown error.

500

The error message returned because an unknown error has occurred.