Merge Media Files

Description

When users perform CDN recording, the recorded media files are stored on the CDN server. Users can call this interface to crop and merge multiple media files.

Currently, only merging media files in MP3/MP4/M3U8 formats is supported.

Attention

Before using this interface for the first time, please confirm whether the CDN recording service has been enabled. If not enabled, please go to ZEGOCLOUD Console to enable it by yourself. For details, please refer to Console - Service Configuration - CDN, or contact ZEGOCLOUD Technical Support to enable it.
Please contact ZEGOCLOUD Technical Support to enable the media file merging function and configure the callback address. After the media file merging is completed, you will be notified through the Media File Merging Completed Callback.
The recorded files merged using this function will be permanently saved and the retention period cannot be modified through configuration. If deletion is required, you can use the Delete Media Files interface.

API Prototype

Request method: GET
Request URL: https://rtc-api.zego.im/?Action=MergeMedia
Transmission protocol: HTTPS
Call frequency limit: 20 times/second

Request Parameters

The following request parameter list only lists the interface request parameters and some public parameters. For the complete public parameter list, please refer to Calling Method.

Parameter	Type	Required	Description
Vendor	String	Yes	Possible values and corresponding CDN vendors: Tencent: Tencent Cloud. Huawei: Huawei Cloud.
Format	String	No	File format after merging, the default format is MP4. Tencent Cloud: MP3, MP4, M3U8. Attention When the CDN vendor used is "Tencent Cloud", if the merged file is in MP3 or MP4 format, you need to ensure that the "audio format" of the input source file is AAC-LC encoded, otherwise the merged video file may have no sound. Huawei Cloud: MP4, M3U8.
Type	String	No	Merge operation type. 0: Default value, merge files directly without cropping. 1: Crop and other operations on media files, then merge files. At this time, the InputFileId[] parameter is invalid, and the HandleMediaArgs.N.FileId parameter must be passed in. When the value of this parameter is 1, it is only valid when Vendor is Tencent, and invalid when the value is Huawei.
InputFileId[]	Array of String	When Type is 0, this parameter is valid and required. When Type is 1, this parameter is invalid.	List of file IDs to be merged, merged in the order of the file list. Where: Tencent Cloud: Fill in the `FilelD` returned by the Recording File Generated Callback, and supports merging up to 10 files. Huawei Cloud: Fill in the `ObsObject` returned by the Recording File Generated Callback, and supports merging up to 5 files. Example: InputFileId[]=5285890813221514958&InputFileId[]=5285890813221513290
HandleMediaArgs.N.FileId	String	Required when Type is 1.	List of file IDs that need to be cropped and then merged, merged in ascending order of N in the field name, supporting up to 10 files. Tencent Cloud: Fill in the `FilelD` returned by the Recording File Generated Callback. Huawei Cloud: Fill in the `ObsObject` returned by the Recording File Generated Callback. Attention N must start from 0 and increment sequentially, with a maximum value of 9. Not starting from 0 or skipping a number will result in incorrect cropping and merging of files. For example, HandleMediaArgs.0.FileId=5285890813221514958&HandleMediaArgs.1.FileId=5285890813221513290
HandleMediaArgs.N.StartTime	Number	Valid when Type is 1, optional.	Time offset for starting cropping of the media file corresponding to HandleMediaArgs.N.FileId, the default is 0, unit: seconds. For example, HandleMediaArgs.0.StartTime corresponds to the start cropping time of the media file HandleMediaArgs.0.FileId.
HandleMediaArgs.N.EndTime	Number	Valid when Type is 1, optional.	Time offset for ending cropping of the media file corresponding to HandleMediaArgs.N.FileId, the default is the end time of the video file, unit: seconds. For example, HandleMediaArgs.0.EndTime corresponds to the end cropping time of the media file HandleMediaArgs.0.FileId.
OutputFileName	String	Required when Vendor is Tencent. Optional when Vendor is Huawei. If not filled, it will be automatically generated by the system.	Name of the merged media file, excluding file format. When using, please UrlEncode the content of this parameter.
ExpireTime	Number	No	Valid storage duration of the merged media file (unit: hours), i.e., file expiration time = interface request time + valid storage duration. Value is 0 (default): indicates that the file will be saved permanently and will not expire. Value greater than 0: the file will be deleted after this duration. Attention This field is only valid when Vendor is Tencent. If the task completion time of merging media files is greater than its valid storage duration, the file will not be generated, and the Media File Merging Completed Callback will return 404 when accessing the merged file URL.

Request Example

https://rtc-api.zego.im/?Action=MergeMedia
&Vendor=Tencent
&Format=mp4
&Type=1
&HandleMediaArgs.0.FileId=5576678019238910395
&HandleMediaArgs.0.StartTime=0.5
&HandleMediaArgs.0.EndTime=10.5
&HandleMediaArgs.1.FileId=5576678019238910395
&HandleMediaArgs.1.StartTime=10
&HandleMediaArgs.1.EndTime=15
&OutputFileName=xxxx-xxxx-test-temp-2.mp4
&<Public request parameters>

https://rtc-api.zego.im/?Action=MergeMedia
&Vendor=Tencent
&Format=mp4
&Type=1
&HandleMediaArgs.0.FileId=5576678019238910395
&HandleMediaArgs.0.StartTime=0.5
&HandleMediaArgs.0.EndTime=10.5
&HandleMediaArgs.1.FileId=5576678019238910395
&HandleMediaArgs.1.StartTime=10
&HandleMediaArgs.1.EndTime=15
&OutputFileName=xxxx-xxxx-test-temp-2.mp4
&<Public request parameters>

Response Parameters

Parameter	Type	Description
Code	Number	Return code.
Message	String	Description of the operation result.
RequestId	String	Request ID, returned by ZEGO server.
Data	Object	Response data.
└ Tencent	Object	Content returned by `Tencent Cloud` (returned when Vendor is Tencent), for details see Tencent.
└ Huawei	Object	Content returned by `Huawei Cloud` (returned when Vendor is Huawei), for details see Huawei.

Tencent

Parameter	Type	Description
TaskId	String	Task ID for producing media files, you can query the production task through this ID.
RequestId	String	Unique request ID, returned by the CDN vendor corresponding to the Vendor parameter (i.e., Tencent Cloud), this RequestId needs to be provided when locating problems.

Huawei

Parameter	Type	Description
TaskId	String	Task ID for producing media files, you can query the production task through this ID.
RequestId	String	Unique request ID, returned by the CDN vendor corresponding to the Vendor parameter (i.e., Huawei), this RequestId needs to be provided when locating problems.

Response Example

{
    "Code":0,
    "Message":"success",
    "RequestId":"3574501647605445341",
    "Data":
      {
        "Tencent":
           {
             "TaskId":"1400341231-EditMedia-0d8b6f0a5c457f5722e6b27796ce1f2ctt0",
             "RequestId":"07f0bdbc-6a52-4ef9-ba7b-e96d6c81d6c3"
           },
        "Huawei":
           {
             "RequestId": "7a690e874857106ccfa5bed198cdsd79",
             "TaskId": "112037345"
           }
      }
}

{
    "Code":0,
    "Message":"success",
    "RequestId":"3574501647605445341",
    "Data":
      {
        "Tencent":
           {
             "TaskId":"1400341231-EditMedia-0d8b6f0a5c457f5722e6b27796ce1f2ctt0",
             "RequestId":"07f0bdbc-6a52-4ef9-ba7b-e96d6c81d6c3"
           },
        "Huawei":
           {
             "RequestId": "7a690e874857106ccfa5bed198cdsd79",
             "TaskId": "112037345"
           }
      }
}

Return Codes

The following only lists some return codes related to the interface business logic. For complete return codes, please refer to Global Return Codes.

Return Code	Description	Handling Suggestion
0	Request succeeded.	-
2	Input parameter error.	-
3	Related permissions not enabled.	Please contact ZEGOCLOUD Technical Support.
4	CDN type mismatch.	Please check parameters.
5	Configuration error.	Please contact ZEGOCLOUD Technical Support.
6	Too frequent requests.	Please retry later.
7	Authentication failed.	Please check whether the authentication parameters are correct.
1000	Request failed.	Please contact ZEGOCLOUD Technical Support.
41003	File does not exist.	Please confirm whether the file format, file ID, etc. are correct.