Editing and production parameters - Intelligent Media Services

This topic describes the common editing and production parameters.

OutputMediaConfig

The configuration of a media file. The value must be in the JSON format. You can specify the URL of the media file in an Object Storage Service (OSS) bucket or the storage location of the media file in ApsaraVideo VOD. If you want to store the media file in the OSS bucket, you must specify the MediaURL field. If you want to store the media file in ApsaraVideo VOD, you must specify the StorageLocation and FileName fields.

Fields

Field	Type	Required	Description
MediaURL	String	This field is required when you store the media file in the OSS bucket.	The URL of the media file in the OSS bucket. Example: http://-bucket.oss-cn-shanghai.aliyuncs.com/outputOss.mp4. Note: Make sure that the OSS bucket resides in the same region as the service that you want to invoke. You cannot specify an OSS acceleration endpoint or Content Delivery Network (CDN) domain name. For more information about the supported file formats, see File formats that support editing.
StorageLocation	String	This field is required when you store the media file in ApsaraVideo VOD.	The storage location of the media file in ApsaraVideo VOD. The value does not include the http:// prefix. Example: outin-xxxxxx.oss-cn-shanghai.aliyuncs.com.
FileName	String	This field is required when you store the media file in ApsaraVideo VOD.	The name of the media file in ApsaraVideo VOD. The file name includes the file suffix, but not the file path. Example: outputVod.mp4.
Video	String	No	The configurations of the output video and video stream. For more information, see Video.
Width	Integer	No	The width of the output video. You can leave this field empty. The default value is the maximum width of multiple videos.
Height	Integer	No	The height of the output video. You can leave this field empty. The default value is the maximum height of multiple videos.
Bitrate	Integer	No	The bitrate of the output video. Unit: Kbit/s. You can leave this field empty. The default value is the maximum bitrate of multiple videos.
MaxDuration	Float	No	The maximum duration of the output video. Unit: seconds. For more information, see Configure the MaxDuration field.
ProduceTemplateId	String	No	The ID of the template that is used for video production, which is the same as the ID of the ApsaraVideo Media Processing (MPS) transcoding template. This is a custom field. You can use this field to transcode the produced video and process customized videos in specific scenarios. You can create a transcoding template in MPS.
VodTemplateGroupId	String	No	The ID of the VOD transcoding template group. You can obtain the ID from the ApsaraVideo VOD console. If you do not need to transcode the produced video, set this field to VOD_NO_TRANSCODE. For more information, see Transcoding templates.
Endpoint	String	No	The endpoint of the cloud service provider. This field is required when Amazon Simple Storage Service (S3) is used.
Bucket	String	No	The S3 bucket. This field is required when S3 is used.
ObjectKey	String	No	The object name. This field is required when S3 is used.
AccessKeyId	String	No	The temporary AccessKey ID that is obtained from the cloud service provider. This field is required when S3 is used.
AccessKeySecret	String	No	The temporary AccessKey secret that is obtained from the cloud service provider. This field is required when S3 is used.

Video

The fields of the OutputMediaConfig parameter, which specify the configurations of the output video and video stream. The following table describes configuration examples.

Field	Type	Required	Definition	Description
Fps	Integer	No	The frame rate of the output video stream.	Valid values: 1 to 60. Default value: 25.
Orientation	String	No	The orientation mode in which the video is displayed.	Valid values: Horizontal and Vertical. Horizontal: landscape mode. Vertical: portrait mode. If you set this field to Horizontal, the system determines the maximum width and height of the output video based on the width and height of the video with the largest width among all videos in landscape mode. If you set this field to Vertical, the system determines the maximum width and height of the output video based on the width and height of the video with the largest height among all videos in portrait mode. If you specify the Width and Height fields, this field does not take effect.
Codec	String	No	The encoding format.	Valid values: H.264 and H.265. Default value: H.264.
Profile	String	No	The video encoding profile.	Valid values: baseline, main, and high. Default value: high. Note: This field is valid only if the Codec field is set to H.264.
Crf	Integer	No	The constant rate factor.	Valid values: 0 to 51. Default value: If you set Codec to H.264, this field is 23 by default. If you set Codec to H.265, this field is 26 by default. Note: If you specify the Crf and Bitrate fields, the Bitrate field does not take effect.
Preset	String	No	The preset video algorithm.	Valid values: veryfast, fast, medium, slow, and slower. Default value: medium. Note: This field is valid only if the Codec field is set to H.264.

Examples

OSS

If you store the media file to your OSS bucket, you must specify the MediaURL field. Other fields are optional. The Bitrate field specifies the bitrate of the output video. A higher bitrate indicates a clearer video. The maximum value of the Bitrate field is 5000. The Width and Height fields specify the video resolution.

{
 "MediaURL":"https://your-bucket.oss-cn-shanghai.aliyuncs.com/outputOss.mp4",
 "Bitrate": 2000,  
 "Width": 800,  
 "Height": 680
}

The URL of the OSS bucket is in the https://${bucket}.${oss-region-name}.aliyuncs.com/${fileKey} format.

bucket is the name of the OSS bucket, and fileKey is the name of the OSS object. The name of the OSS object includes the object path and suffix.

oss-region-name.aliyuncs.com is the public endpoint of the OSS bucket. The following code provides the public endpoints of the China (Shanghai), China (Hangzhou), and China (Beijing) regions:

oss-cn-shanghai.aliyuncs.com
oss-cn-hangzhou.aliyuncs.com 
oss-cn-beijing.aliyuncs.com

VOD

If you want to store the media file in ApsaraVideo VOD, you must specify the StorageLocation and FileName fields. You can view available ApsaraVideo VOD storage locations in the ApsaraVideo VOD console.

{ 
  "StorageLocation": "outin-*xxxxxx7d2a3811eb83da00163exxxxxx.oss-cn-shanghai.aliyuncs.com",  
  "FileName": "outputVod.mp4",  
  "Bitrate": 2000,  
  "Width": 800,  
  "Height": 680,
  "VodTemplateGroupId": "VOD_NO_TRANSCODE"
}

Configuration example of the Video field

Configuration example of the Video field of the OutputMediaConfig parameter

{
  "OutputMediaConfig": {
    "MediaURL":"https://your-bucket.oss-cn-shanghai.aliyuncs.com/outputOss.mp4",
    "Width": 800,  
    "Height": 680,
    "Video": {
      "Codec": "H.264",
      "Fps": 50,
      "Profile": "main",
      "Crf":15
    }
  }
}

ProjectMetadata

The metadata of the editing project. The value is in the JSON format.

Fields

Field

Type

Required

Description

String

The description of the editing project.

Title

String

The title of the editing project.

Examples

{
   "Description": "Description",
   "Title": "Title"
}

EditingProduceConfig

The parameter for common editing and production in the JSON format.

Fields

Field	Type	Required	Description
AudioChannelCopy	String	No	The audio channel that you want to copy. Valid value: left and right. If you set this field to left, the system copies the left and right audio channels of the output video as the left audio channel of the input video. If you set this field to right, the system copies the left and right audio channels of the output video as the right audio channel of the input video.
AutoRegisterInputVodMedia	Boolean	No	Specifies whether to automatically register the ApsaraVideo VOD media files in your timeline to the Intelligent Media Services (IMS) media asset library. Default value: true.
AutoRegisterOutputImsMedia	Boolean	No	Specifies whether to automatically register the video generated after editing and production to the IMS media asset library. Default value: true.
OutputWebmTransparentChannel	Boolean	No	Specifies whether to export the video with an alpha channel in the WebM format. Default value: false. If you want to export the video with an alpha channel in the WebM format, make sure that the MediaURL or FileName field of the OutputMediaConfig parameter ends with webm and only the Scale Effect is available in your timeline. Otherwise, the video in the MP4 format without an alpha channel is exported by default.
CoverConfig	JSON	No	The thumbnail. You can use a frame in the video as the thumbnail. The thumbnail is saved as an image and is stored in your OSS bucket. You cannot use the thumbnail to modify the first frame of the video. You can call the GetMediaInfo operation to query the URL of the thumbnail. StartTime: the time point of the thumbnail in the video. The value can be rounded to four decimal places. Unit: seconds.
NeedSnapshot	Boolean	No	Specifies whether to automatically capture snapshots for the media file. Default value: true.
NeedSprite	Boolean	No	Specifies whether to use snapshots to generate a sprite for the media file. Default value: true.
PipelineId	String	No	The ID of the custom pipeline. You can specify this field based on your business requirements. When multiple lines-of-business use the same Alibaba Cloud account to submit tasks, you can use this field to distinguish tasks from different lines-of-business. If you have requirements, submit a ticket.
MaxBitrate	Integer	No	The maximum bitrate of the output video. You can specify this field based on your business requirements. If you specify this field and the bitrate of the input video is greater than the value of this field, the system uses the value of this field as the bitrate of the output video. If you do not specify this field, the maximum bitrate of the output video is 5,000 by default.
KeepOriginMaxBitrate	Boolean	No	Specifies whether to use the maximum bitrate of the source file for the output video. Default value: false. If you set this field to true, the system uses the maximum bitrate of the source file for the output video. The maximum bitrate of the output video is 50,000.
KeepOriginVideoMaxFps	Boolean	No	Specifies whether to use the maximum frame rate of the source file for the output video. Default value: false. If you set this field to true, the system uses the maximum frame rate of the source file for the output video.

Examples

{
	"AutoRegisterInputVodMedia": true,
	"OutputWebmTransparentChannel": true,
	"CoverConfig": {
		"StartTime": 3.3
	},
	"AudioChannelCopy": "left",
  "PipelineId":"xxxd54a97cff4108b555b01166d4bxxx",
  "MaxBitrate": 5000,
  "KeepOriginMaxBitrate": false,
  "KeepOriginVideoMaxFps": false
}

MediaMetadata

The metadata of the media file generated after editing. The value must be in the JSON format.

Fields

Field	Type	Required	Description
Title	String	No	The title of the media file. The title can be up to 128 bytes in length. The title must be encoded in UTF-8.
Description	String	No	The description of the media file. The description can be up to 1,024 bytes in length. The value must be encoded in UTF-8.
Tags	String	No	The tag of the media file. You can specify a maximum of 16 tags. Separate multiple tags with commas (,). Each tag can be up to 32 bytes in length. The value must be encoded in UTF-8.
CateId	Long	No	The category ID of the media file.

UserData

The user data in the JSON format. When you submit a production task, you can add user data to the UserData parameter. If you configure the callback URL of the production task, the system sends a callback request to the URL after the production is complete, and the callback request contains the UserData parameter. The value of this parameter can be up to 1,024 bytes in length.

For your convenience, you can pass the callback configuration to the UserData parameter. For more information, see the best practice Configure callback settings for completed editing jobs.

The following table describes the field that is reserved in the UserData parameter.

Reserved field

Field

Type

Required

Description

NotifyAddress

String

The callback URL. HTTP callbacks and Alibaba Cloud Message Service (MNS) callbacks are supported.

Sample HTTP callback: http://yourdomain.com/callback.

Sample MNS callback: ice-callback-test. The name of the MNS queue must start with ice-callback.