Adds a component to a production studio.

Usage note

This interface currently supports adding three types of components: pictures, text, and subtitles. You must create a production studio before adding any components to it. For how, see CreateCaster.

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

Parameter Type Required Example Description
Action String Yes AddCasterComponent

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

CasterId String Yes a2b8e671-2fe5-4642-a2ec-bf93880e****

The ID of the production studio.

If you create a production studio through the CreateCaster interface, check the value of the CasterId parameter in the response.

If you create a production studio through the ApsaraVideo Live Console, log in to the console, then check the ID of the production studio through the following path:

Production Studios > Production Studio Management

Note The CasterId is reflected in the Name column on the Production Studio Management page.
ComponentLayer String Yes {"HeightNormalized":"1","PositionRefer":"topRight","WidthNormalized":"0","PositionNormalized":["0.1","0.2"]}

The information about the component layer, such as the size and layout. This parameter contains the following fields:

  • HeightNormalized: the normalized value of heights for the elements in the component layer.
  • WidthNormalized: the normalized value of widths for the elements in the component layer.
  • PositionNormalized: the normalized value of the coordinates of the component layer.
  • PositionRefer: the reference coordinates of the component layer.

The value is a JSON string. Use upper camel case for field names.

ComponentType String Yes text

The type of the component. Valid values:

  • text: a text component.
  • image: an image component.
  • caption: a subtitle component.
LocationId String Yes RC01

The location ID of the component. Each location ID can be assigned to only one component and must be in the RC[Number] format. The values specified by this parameter must be in ascending order, such as RC01 to RC99.

Note If the ComponentType parameter is set to caption, the LocationId parameter specifies the location ID of the video source referenced by the component.
ComponentName String No text01

The name of the component. By default, the name is the ID of the component.

Effect String No animateH

The effect of the component. Valid values:

  • none: sets no effect for the component. This is the default value.
  • animateH: sets horizontal scrolling for the component.
  • animateV: sets vertical scrolling for the component.
LayerOrder String No cover

The stacking order of the component.

  • cover
  • background
TextLayerContent String No {"BorderWidthNormalized":"1","SizeNormalized":"0.2","Color":"0x000000","FontName":"KaiTi","BorderColor":"0x000000","Text":"hello world!"}

The information about the text layer. This parameter contains the following fields:

  • SizeNormalized: the normalized value of the font size of the subtitle. The value of this field equals the font size divided by the output height. Valid values: [0,1]. The maximum font size of the subtitle is 1,024, even if the font size calculated based on this field is greater than 1,024.
  • BorderWidthNormalized: the normalized value of the border width of the subtitle. The value of this field equals the border width divided by the font size. Valid values: [0,1]. The default value is 0. The maximum border width is 16, even if the border width calculated based on this field is greater than 16.
  • FontName: the font name of the text. Default value: KaiTi. For more information about the valid values, see Description of available fonts in a streaming panel.
  • BorderColor: the color of the subtitle border. Valid values: 0x000000 to 0xffffff. By default, this parameter is not set. In this case, the border color of the subtitle is transparent.
  • Text: the content of the text. By default, this parameter is not set. In this case, the text contains no content.
  • Color: the color of the text. The default value is 0xff0000, which indicates that the text is in red.

The value is a JSON string. Use upper camel case for field names.

Note This parameter takes effect and is required only when the ComponentType parameter is set to text.
ImageLayerContent String No {"MaterialId":"6cf724c6ebfd4a59b5b3cec6f10d****"}

The information about the image layer. This parameter contains the following field:

  • MaterialId: the ID of the material from the media library.

The value is a JSON string. Use upper camel case for the field name.

Note This parameter is required when the ComponentType parameter is set to image.
CaptionLayerContent String No {"BorderWidthNormalized":0.01,"SizeNormalized":0.05,"Color":"0x000000","LocationId":"RV01","SourceLan":"cn","FontName":"KaiTi","BorderColor":"0xffffff"}

The information about the subtitle layer. This parameter contains the following fields:

  • SizeNormalized: the normalized value of the font size of the subtitle. The value of this field equals the font size divided by the output height and is accurate to two decimal places. Valid values: [0,1]. The maximum font size of the subtitle is 1,024, even if the font size calculated based on this field is greater than 1,024.
  • BorderWidthNormalized: the normalized value of the border width of the subtitle. The value of this field equals the border width divided by the font size and is accurate to two decimal places. Valid values: [0,1]. The default value is 0. The maximum border width is 16, even if the border width calculated based on this field is greater than 16.
  • FontName: the font name of the text. Default value: KaiTi. For more information about the valid values, see Description of available fonts in a streaming panel.
  • BorderColor: the color of the subtitle border. Valid values: 0x000000 to 0xffffff. By default, this parameter is not set. In this case, the border color of the subtitle is transparent.
  • LocationId: the slot ID of the video source.
  • SourceLan: the source language of the audio in the video source. Valid values: en, cn, es, and ru, which indicate English, Chinese, Spanish, and Russian respectively. Default value: cn.
  • TargetLan: the destination language of the audio in the video source. Valid values: en, cn, es, and ru, which indicate English, Chinese, Spanish, and Russian respectively. Default value: cn.
  • ShowSourceLan: specifies whether to display the source language. Valid values: true: displays the source language. false: hides the source language. Default value: false.
  • Truncation: specifies whether the subtitle can be truncated. Valid values: true: specifies that the subtitle can be truncated. false: specifies that the subtitle cannot be truncated. Default value: false.
  • SourceLanPerLineWordCount: the number of words displayed in each line when the subtitle is in the source language. Default value: 20.
  • TargetLanPerLineWordCount: the number of words displayed in each line when the subtitle is in the destination language. Default value: 20.
  • SourceLanReservePages: the number of lines reserved when the subtitle is in the source language. This field takes effect only when the Truncation field is set to true. Default value: 2.
  • TargetLanReservePages: the number of lines reserved when the subtitle is in the destination language. This field takes effect only when the Truncation field is set to true. Default value: 2.

The value is a JSON string. Use upper camel case for field names.

Note This parameter is required when the ComponentType parameter is set to caption.
HtmlLayerContent String No {"htmlUrl":http://yexample.com}

The information about the HTML5 layer.

Description of available fonts in a production studio

Font

Value of FontName

KaiTi

KaiTi

Alibaba PuHuiTi-Regular

AlibabaPuHuiTi-Regular

Alibaba PuHuiTi-Bold

AlibabaPuHuiTi-Bold

Alibaba PuHuiTi-Light

AlibabaPuHuiTi-Light

Source Han Sans-Regular

NotoSansHans-Regular

Source Han Sans-Bold

NotoSansHans-Bold

Source Han Sans-Light

NotoSansHans-Light

Response parameters

Parameter Type Example Description
RequestId String 16A96B9A-F203-4EC5-8E43-CB92E68F4CD8

The ID of the request.

ComponentId String 21926b36-7dd2-4fde-ae25-51b5bc8e****

The ID of the component. Record this ID as it can be used to manage the component being added.

Examples

Sample requests

http(s)://live.aliyuncs.com/?Action=AddCasterComponent
&CasterId=a2b8e671-2fe5-4642-a2ec-bf93880e****
&ComponentLayer={"HeightNormalized":"1","PositionRefer":"topRight","WidthNormalized":"0","PositionNormalized":["0.1","0.2"]}
&ComponentType=text
&TextLayerContent={"BorderWidthNormalized":"1","SizeNormalized":"0.2","Color":"0x000000","FontName":"KaiTi","BorderColor":"0x000000","Text":"hello world!"}&LocationId=RC01
&<Common request parameters>

Sample success responses

XML format 

<AddCasterComponentResponse>
      <RequestId>16A96B9A-F203-4EC5-8E43-CB92E68F4CD8</RequestId>
      <ComponentId>21926b36-7dd2-4fde-ae25-51b5bc8e****</ComponentId>
</AddCasterComponentResponse>

JSON format 

{
   "RequestId": "16A96B9A-F203-4EC5-8E43-CB92E68F4CD8",
   "ComponentId": "21926b36-7dd2-4fde-ae25-51b5bc8e****"
}

Error codes

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