LiveRealTimeClip

Last updated: 2020-03-27 18:45:42

1. API Description

Domain name for API request: vod.tencentcloudapi.com.

Live clipping means that during a live broadcast (before it ends), you can select a segment of previous live broadcast content to generate a new video (in HLS format) in real time and share it immediately or store it persistently.

VOD supports two live clipping modes:

  • Persistent clipping: in this mode, the clipped video is saved as an independent video file with a FileId, which is suitable for persistently storing highlights;
  • Temporary clipping: in this mode, the clipped video is part of the LVB recording file with no FileId, which is suitable for temporarily sharing highlights;

Note:

  • The live clipping feature can be used only when time shifting has been enabled for the target live stream.
  • Live clipping is performed based on the m3u8 file generated by LVB recording, so its minimum clipping granularity is one ts segment rather than at or below the second level.

Persistent clipping

In persistent clipping mode, the clipped video is saved as an independent video file with a FileId, and its lifecycle is not subject to the source LVB recording video (even if the source video is deleted, the clipped video will not be affected in any way). It can be further processed (transcoded, published on WeChat, etc.).

An example is as follows: for a complete football match, the source LVB recording video may be up to 2 hours in length. You want to store this video for only 2 months for the purpose of cost savings. However, you want to specify a longer retention period for the "highlights" video created by live clipping and perform additional VOD operations on it such as transcoding and release on WeChat. In this case, you need to choose the persistent clipping mode of live clipping.

The advantage of persistent clipping is that the clipped video has a lifecycle independent of the source recording video and can be managed independently and stored persistently.

Temporary clipping

In temporary clipping mode, the clipped video (m3u8 file) shares the same ts segments with the LVB recording video instead of being an independent video. It only has a playback URL but has no FileId, and its validity period is the same as that of the LVB recording video; therefore, if the LVB recording video is deleted, it cannot be played back.

For temporary clipping, as the clipping result is not an independent video, it will not be included in VOD's media asset management (for example, it will not be counted in the total videos in the console), and no video processing operations can be separately performed on it, such as transcoding and release on WeChat.

The advantage of temporary clipping is that the clipping operation is very "lightweight" and does not incur additional storage fees. However, the clipped video has the same lifecycle as the source recording video and cannot be further transcoded or processed.

A maximum of 100 requests can be initiated per second for this API.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name Required Type Description
Action Yes String Common parameter. The value used for this API: LiveRealTimeClip.
Version Yes String Common parameter. The value used for this API: 2018-07-17.
Region No String Common parameter. This parameter is not required for this API.
StreamId Yes String LVB code of a stream.
StartTime Yes String Start time of stream clipping in ISO date format.
EndTime Yes String End time of stream clipping in ISO date format.
IsPersistence No Integer Whether to clip persistently. 0: no, 1: yes. Default: no.
ExpireTime No String Storage expiration time of video generated by persistent clipping in ISO date format. 9999-12-31T23:59:59Z means never expire. After the expiration, the media file and its related resources (such as transcoding results and image sprites) will be permanently deleted. This parameter will be valid only when IsPersistence is 1. By default, the video will never expire.
Procedure No String VOD task flow processing for video generated by persistent clipping. For more information, please see Specifying Task Flow After Upload. This parameter will be valid only when IsPersistence is 1.
MetaDataRequired No Integer Whether the metadata of clipped video needs to be returned. 0: no, 1: yes. Default value: no.
Host No String Domain name used for live clipping. Time shifting must be enabled in LVB.
ExtInfo No String Reserved field. Do not enter a value for it.
SubAppId No Integer Subapplication ID in VOD. If you need to access a resource in a subapplication, enter the subapplication ID in this field; otherwise, leave it empty.

3. Output Parameters

Parameter Name Type Description
Url String Playback URL of clipped video.
FileId String Unique media file ID of video generated by persistent clipping.
Note: this field may return null, indicating that no valid values can be obtained.
VodTaskId String Task flow ID of video generated by persistent clipping.
Note: this field may return null, indicating that no valid values can be obtained.
MetaData MediaMetaData Metadata of clipped video.
Note: this field may return null, indicating that no valid values can be obtained.
RequestId String The unique request ID, which is returned for each request. RequestId is required for locating a problem.

4. Example

Example1 Temporary live clipping

Input Example

https://vod.tencentcloudapi.com/?Action=LiveRealTimeClip
&StreamId=record-stream
&StartTime=2018-09-20T10:00:00Z
&EndTime=2018-09-20T11:00:00Z
&<Common request parameters>

Output Example

{
  "Response": {
    "Url": "http://video.com/playlist.m3u8",
    "FileId": "",
    "VodTaskId": "",
    "MetaData": null
  }
}

Example2 Persistent live clipping

Input Example

https://vod.tencentcloudapi.com/?Action=LiveRealTimeClip
&StreamId=record-stream
&StartTime=2018-09-20T10:00:00Z
&EndTime=2018-09-20T11:00:00Z
&IsPersistence=1
&Procedure=SomeProcedure
&<Common request parameters>

Output Example

{
  "Response": {
    "Url": "http://video.com/playlist.m3u8",
    "FileId": "",
    "VodTaskId": "",
    "MetaData": null,
    "RequestId": "requestId"
  }
}

5. Developer Resources

API Explorer

This tool allows online call, signature authentication, SDK code generation and quick search of APIs to greatly improve the efficiency of using TencentCloud APIs.

SDK

TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

Command Line Interface

6. Error Code

The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

Error Code Description
InternalError Internal error.
InvalidParameterValue.ClipDuration Incorrect parameter value: the clipping duration is too long.
InvalidParameterValue.EndTime Incorrect parameter value: invalid EndTime.
InvalidParameterValue.ExpireTime Incorrect parameter value: incorrect ExpireTime format.
InvalidParameterValue.StartTime Incorrect parameter value: invalid StartTime.
InvalidParameterValue.StreamIdInvalid Incorrect parameter value: invalid StreamId.
UnauthorizedOperation Unauthorized operation.