All Products
Search

This Product

    ApsaraVideo Live:SetCasterConfig

    Document Center

    ApsaraVideo Live:SetCasterConfig

    Last Updated:Dec 05, 2024

    Configures all parameters for a production studio. If a parameter is not specified, the production studio does not have the relevant configuration.

    Operation description

    You can call the CreateCaster operation to create a production studio and then call this operation to configure the production studio. This operation allows you to set all parameters for a production studio. If a parameter is not specified, the production studio does not have the relevant configuration.

    QPS limit

    You can call this operation up to 10 times per second per account. Requests that exceed this limit are dropped and you will experience service interruptions. We recommend that you take note of this limit when you call this operation.

    Debugging

    You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

    Authorization information

    The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

    • Operation: the value that you can use in the Action element to specify the operation on a resource.
    • Access level: the access level of each operation. The levels are read, write, and list.
    • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
      • The required resource types are displayed in bold characters.
      • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
    • Condition Key: the condition key that is defined by the cloud service.
    • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
    OperationAccess levelResource typeCondition keyAssociated operation
    live:SetCasterConfigupdate
    *Caster
    acs:live:*:{#accountId}:caster/{#CasterId}
      none
    		none

    Request parameters

    ParameterTypeRequiredDescriptionExample
    CasterIdstringYes

    The ID of the production studio.

    • If the production studio was created by calling the CreateCaster operation, check the value of the response parameter CasterId to obtain the ID.
    • If the production studio was created by using the ApsaraVideo Live console, obtain the ID on the Production Studio Management page. To go to the page, log on to the ApsaraVideo Live console and click Production Studios in the left-side navigation pane.
    Note You can find the ID of the production studio in the Instance ID/Name column.
    		a2b8e671-2fe5-4642-a2ec-bf93880e****
    CasterNamestringNo

    The name of the production studio.

    		liveCaster****
    DomainNamestringNo

    The main streaming domain.

    Complete the configuration of the domain name before the production studio is started. If you do not specify this parameter, the domain configuration for the production studio is cleared.

    		example.com
    TranscodeConfigstringNo

    The transcoding configuration.

    The value is a JSON string. Use upper camel case for fields of the string. If you do not specify this parameter, the transcoding configuration is cleared. If no transcoding template is available, an error occurs when the production studio is started.

    		{"casterTemplate": "lp_ld"}
    RecordConfigstringNo

    The recording configuration. The value is a JSON string. You can configure the following fields:

    • endpoint: the API server address of an Alibaba Cloud service.
    • ossBucket: the name of the Object Storage Service (OSS) bucket.
    • videoFormat: the format in which the video file can be exported. Example: [{\"OssObjectPrefix\":\"record/{AppName}/{StreamName}/{StartTime}_{EndTime}\",\"Format\":\"m3u8\",\"CycleDuration\":21600,\"SliceOssObjectPrefix\":\"record/{AppName}/{StreamName}/{UnixTimestamp}\"},{\"OssObjectPrefix\":\"record/{AppName}/{StreamName}/{StartTime}_{EndTime}\",\"Format\":\"flv\",\"CycleDuration\":21600}].
    • interval: the interval between recordings. Unit: milliseconds.
    Note If you do not specify this parameter, the recording feature is disabled and the recording configuration for the production studio is cleared.
    		{ "endpoint": "http://oss-cn-********.aliyuncs.com/api", "ossBucket****": "liveBucket****", "VideoFormat":[{\"OssObjectPrefix\":\"record/{AppName}/{StreamName}/{StartTime}_{EndTime}\",\"Format\":\"m3u8\",\"CycleDuration\":21600,\"SliceOssObjectPrefix\":\"record/{AppName}/{StreamName}/{UnixTimestamp}\"},{\"OssObjectPrefix\":\"record/{AppName}/{StreamName}/{StartTime}_{EndTime}\",\"Format\":\"flv\",\"CycleDuration\":21600}] "interval": 5 }
    DelayfloatNo

    Specifies whether to enable stream delay. Unit: seconds. Valid values:

    • 0 (default): disables stream delay.

    • A value greater than 0: enables stream delay.

    • Empty: clears the stream delay configuration.

      **

      **Note **The maximum value can be 300 seconds.

    		0
    UrgentMaterialIdstringNo

    The ID of the standby video from the media library. If you do not specify this parameter, the standby video configuration for the production studio is cleared.

    		a2b8e671
    UrgentLiveStreamUrlstringNo

    The URL of the standby live stream.

    		rtmp://demo.aliyundoc.com
    SideOutputUrlstringNo

    The custom stream redirect URL.

    If you do not specify this parameter, the production studio uses the redirect URL generated by the system.

    Note Redirect URLs support only the Real-Time Messaging Protocol (RTMP) protocol.
    		rtmp://****/aliyundoc.com:8000/caster/4a82a3d1b7f0462ea37348366201****?auth_key=1608953344-0-0-53f0758162964516ac850f2ddc3f****
    SideOutputUrlListstringNo

    The stream relay URLs. A relay URL can be an Alibaba Cloud URL or a URL from a third-party CDN provider. You can specify up to 20 relay URLs over the RTMP protocol.

    Note Use the following format to specify multiple relay URLs: "rtmp://domain/app1/stream1","rtmp://domain/app2/stream2".
    		rtmp://domain/app/stream?***
    CallbackUrlstringNo

    The callback URL. Enter a valid HTTP address for receiving callback notifications. If you do not specify this parameter, the production studio does not send callback notifications.

    		http://****/aliyundoc.com:8000/caster/4a82a3d1b7f0462ea37348366201****?auth_key=1608953344-0-0-53f0758162964516ac850f2ddc3f****
    ProgramEffectintegerNo

    Specifies whether to enable the carousel playback feature. Valid values:

    • 0: disables carousel playback.
    • 1: enables carousel playback.
    		1
    ProgramNamestringNo

    The name of the playlist for carousel playback. You can specify this parameter if you enable the carousel playback feature.

    		program_name
    ChannelEnableintegerNo

    Specifies whether to enable channels. Valid values:

    • 0 (default): disables channels.
    • 1: enables channels.
    Note You cannot disable channels after you enable them. If you set this parameter to 0, the production studio references video resources in a layout without using channels. If you enable channels for the first time, make sure that the production studio is in the idle state. After you enable channels, a new layout that references video resources by using channels is generated to replace the original one. Therefore, you must specify video resources for channels. You can use the channels to change the playback progress or status. If the video resource, preview, and program modules of the production studio use the same video source, the three modules display the same content.
    		1
    SyncGroupsConfigstringNo

    The multi-view synchronization configuration. You can specify this parameter to synchronize multiple video sources.

    There are two modes of multi-view synchronization.

    • A value of 0 for the mode field specifies the streamer mode. In this mode, multiple video sources are synchronized based on the settings by the streamer.
    • A value of 1 for the mode field specifies the conference mode. In this mode, all video sources are synchronized.

    In the streamer mode, the hostResourceId field specifies the video source on the streamer side.

    In the conference mode, the hostResourceId field is not available. You need to provide only resource IDs that are required.

    		"[{\"mode\":0,\"resourceIds\":[\"5a6c1c33-8424-46f6-813c-c152220a****\",\"4e6521dc-a40a-4077-b6bf-1fb12a76****\"],\"hostResourceId\":\"3aa2b39a-fd0e-4b8c-be73-b7af31c4****\"}]"
    UrgentImageIdstringNo

    The ID of the standby image from the media library.

    		a089175eb5f4427684fc0715159a****
    UrgentImageUrlstringNo

    The URL of the standby image.

    		http://learn.aliyundoc.com/AppName/image.jpg
    AutoSwitchUrgentOnbooleanNo

    Specifies whether the production studio automatically switches to the standby resource in case of a stream interruption.

    • true
    • false
    		true
    AutoSwitchUrgentConfigstringNo

    The configuration for automatic switchover to the standby resource.

    The eofThres field specifies the duration after which the production studio automatically switches to the standby resource if a stream interruption occurs. Unit: seconds.

    		{"eofThres":3}

    Response parameters

    ParameterTypeDescriptionExample
    object
    CasterIdstring

    The ID of the production studio. You can specify the ID in a request to query the streaming URLs of the production studio, start the production studio, add a video resource, a layout, a component, or a playlist to the production studio, or query layouts of the production studio.

    		b4810848-bcf9-4aef-bd4a-e6bba2d9****
    RequestIdstring

    The request ID.

    		16A96B9A-F203-4EC5-8E43-CB92E68F4CD8

    Examples

    Sample success responses

    JSONformat

    {
  "CasterId": "b4810848-bcf9-4aef-bd4a-e6bba2d9****",
  "RequestId": "16A96B9A-F203-4EC5-8E43-CB92E68F4CD8"
}

    Error codes

    HTTP status codeError codeError message
    400InvalidUserId.Malformed%s
    400InvalidCasterId.Malformed%s
    400InvalidParameter.Malformed%s
    400IncorrectCasterStatus.Inuse%s
    400InvalidCaster.ChannelDisableUnsupported%s
    400IncorrectCasterStatus.EnableChannel%s
    400MissingParameter%s
    403PermissionDenied%s
    404InvalidCaster.NotFound%s
    404InvalidDomainName.NotFound%s
    500InternalError%s

    For a list of error codes, visit the Service error codes.

    Change history

    Change timeSummary of changesOperation
    2024-08-21The Error code has changedView Change Details
    2023-11-22The Error code has changed. The request parameters of the API has changedView Change Details
    2023-03-31The Error code has changed. The request parameters of the API has changedView Change Details