简单 HLS 剪辑

最近更新时间:2024-09-24 01:35:42

我的收藏

1. 接口描述

接口请求域名: vod.tencentcloudapi.com 。

对 HLS 视频进行按时间段裁剪,实时生成一个新的视频(HLS 格式),开发者可以将其立即分享出去,或者长久保存起来。

腾讯云点播支持两种剪辑模式:

  • 剪辑固化:将剪辑出来的视频保存成独立的视频,拥有独立 FileId;适用于将精彩片段长久保存的场景;
  • 剪辑不固化:剪辑得到的视频附属于输入文件,没有独立 FileId;适用于将精彩片段临时分享的场景。

裁剪精度支持粗略裁剪和精确裁剪:

  • 粗略剪辑:基于输入 m3u8 文件进行裁剪,其最小剪辑精度为一个 ts 切片,无法实现秒级或者更为精确的剪辑精度。
  • 精确剪辑:按照 StartTimeOffset 和 EndTimeOffset 参数进行精确裁剪。使用精确裁剪需要开通即时转码的功能。

剪辑固化

所谓剪辑固化,是指将剪辑出来的视频保存成一个独立的视频(拥有独立的 FileId)。其生命周期不受原始输入视频影响(即使原始输入视频被删除,剪辑结果也不会受到任何影响);也可以对其进行转码、微信发布等二次处理。

举例如下:一场完整的足球比赛,原始视频可能长达 2 个小时,客户出于节省成本的目的可以对这个视频存储 2 个月,但对于剪辑的「精彩时刻」视频却可以指定存储更长时间,同时可以单独对「精彩时刻」视频进行转码、微信发布等额外的点播操作,这时候可以选择剪辑并且固化的方案。

剪辑固化的优势在于其生命周期与原始输入视频相互独立,可以独立管理、长久保存。

注意:如果剪辑时指定进行固化,通过 ModifyEventConfig 接口启用接收剪辑固化事件通知,固化成功后将会收到一个 PersitenceComplete 类型的事件通知。在收到这个事件通知之前,不应该对原始输入的视频进行删除、降冷等操作,否则剪辑生成的视频播放可能出现异常。

剪辑不固化

所谓剪辑不固化,是指剪辑所得到的结果(m3u8 文件)与原始输入视频共享相同的 ts 分片,新生成的视频不是一个独立完整的视频(没有独立 FileId,只有播放 URL),其有效期与原始输入的完整视频有效期是一致的。一旦原始输入的视频被删除,也会导致该片段无法播放。

剪辑不固化,由于其剪辑结果不是一个独立的视频,因而也不会纳入点播媒资视频管理(例如控制台的视频总数不会统计这一片段)中,也无法单独针对这个片段做转码、微信发布等任何视频处理操作。

剪辑不固化的优势在于其剪辑操作十分“轻量化”,不会产生额外的存储开销。但其不足之处在于生命周期与原始录制视频相同,且无法进一步进行转码等视频处理。

默认接口请求频率限制:100次/秒。

推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数

参数名称 必选 类型 描述
Action String 公共参数,本接口取值:SimpleHlsClip。
Version String 公共参数,本接口取值:2018-07-17。
Region String 公共参数,此参数为可选参数。
Url String 需要裁剪的腾讯云点播 HLS 视频 URL。
示例值:http://xxxxx.vod2.myqcloud.com/xxxxx/aaaaaa/hhh.m3u8
SubAppId Integer 点播应用 ID。从2023年12月25日起开通点播的客户,如访问点播应用中的资源(无论是默认应用还是新创建的应用),必须将该字段填写为应用 ID。
示例值:1
StartTimeOffset Float 裁剪的开始偏移时间,单位秒。默认 0,即从视频开头开始裁剪。负数表示距离视频结束多少秒开始裁剪。例如 -10 表示从倒数第 10 秒开始裁剪。
示例值:2
EndTimeOffset Float 裁剪的结束偏移时间,单位秒。默认 0,即裁剪到视频尾部。负数表示距离视频结束多少秒结束裁剪。例如 -10 表示到倒数第 10 秒结束裁剪。
示例值:10
IsPersistence Integer 是否固化。0 不固化,1 固化。默认不固化。
示例值:0
ExpireTime String 剪辑固化后的视频存储过期时间。格式参照 ISO 日期格式。填“9999-12-31T23:59:59Z”表示永不过期。过期后该媒体文件及其相关资源(转码结果、雪碧图等)将被永久删除。仅 IsPersistence 为 1 时有效,默认剪辑固化的视频永不过期。
示例值:2020-09-09T23:59:59+08:00
Procedure String 剪辑固化后的视频点播任务流处理,详见上传指定任务流。仅 IsPersistence 为 1 且 Precision 为 Rough 时有效。
示例值:""
ClassId Integer 分类ID,用于对媒体进行分类管理,可通过 创建分类 接口,创建分类,获得分类 ID。
  • 默认值:0,表示其他分类。

  • 仅 IsPersistence 为 1 时有效。
    示例值:1
    SourceContext String 来源上下文,用于透传用户请求信息,上传完成回调 将返回该字段值,最长 250 个字符。仅 IsPersistence 为 1 时有效。
    示例值:""
    SessionContext String 会话上下文,用于透传用户请求信息,当指定 Procedure 参数后,任务流状态变更回调 将返回该字段值,最长 1000 个字符。仅 IsPersistence 为 1 时有效。
    示例值:""
    Precision String 裁剪精度,取值有:
  • Rough: 粗略裁剪,最小剪辑精度是单个 ts 分片;
  • Precise: 精确裁剪,做到按照剪辑时间点的毫秒级精确剪辑。
  • 默认取值 Rough。
    OutputMediaType String 输出视频类型,取值有:
  • hls: 输出 hls 文件;
  • mp4:输出 mp4 文件,MP4 文件的大小不超过5G,时长小于2小时。仅当 Precision 选择 Precise 且 IsPersistence 选择0时有效,即只有非固化的精确剪辑时支持输出 MP4。
  • 默认取值 hls。
    ExtInfo String 保留字段,特殊用途时使用。 示例值:""

    3. 输出参数

    参数名称 类型 描述
    Url String 裁剪后的视频地址。
    示例值:http://xxxxx.vod2.myqcloud.com/xxxxx/aaaaaa/10_50.m3u8
    MetaData MediaMetaData 裁剪后的视频元信息。目前SizeRotateVideoDurationAudioDuration 几个字段暂时缺省,没有真实数据。
    FileId String 剪辑固化后的视频的媒体文件的唯一标识。
    示例值:5285485487985271487
    TaskId String 剪辑固化后的视频任务流 ID。
    示例值:""
    RequestId String 唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。

    4. 示例

    示例1 裁剪 HLS 视频(时间偏移量为负数)

    裁剪第 2 秒开始到倒数第 10 秒

    输入示例

    POST / HTTP/1.1
    Host: vod.tencentcloudapi.com
    Content-Type: application/json
    X-TC-Action: SimpleHlsClip
    <公共请求参数>
    
    {
        "Url": "http://xxxxx.vod2.myqcloud.com/xxxxx/aaaaaa/hhhh.m3u8",
        "StartTimeOffset": 2.0,
        "EndTimeOffset": 10.0
    }

    输出示例

    {
        "Response": {
            "Url": "http://xxxxx.vod2.myqcloud.com/xxxxx/aaaaaa/10_50.m3u8",
            "FileId": "",
            "TaskId": "",
            "MetaData": {
                "Size": 0,
                "Container": "hls",
                "Bitrate": 622014,
                "Height": 480,
                "Width": 640,
                "Duration": 48.0,
                "Rotate": 0,
                "VideoStreamSet": [
                    {
                        "Bitrate": 592385,
                        "Height": 480,
                        "Width": 640,
                        "Codec": "h264",
                        "Fps": 25,
                        "CodecTag": "",
                        "DynamicRangeInfo": {
                            "Type": "",
                            "HDRType": ""
                        }
                    }
                ],
                "AudioStreamSet": [
                    {
                        "Bitrate": 29629,
                        "SamplingRate": 44100,
                        "Codec": "aac"
                    }
                ],
                "VideoDuration": 0.0,
                "AudioDuration": 0.0,
                "Md5": "Md5"
            },
            "RequestId": "12ae8d8e-dce3-4151-9d4b-5594145287e1"
        }
    }

    示例2 裁剪 HLS 视频(时间偏移量均为正数)

    裁剪视频第 2 秒到 第 10 秒

    输入示例

    POST / HTTP/1.1
    Host: vod.tencentcloudapi.com
    Content-Type: application/json
    X-TC-Action: SimpleHlsClip
    <公共请求参数>
    
    {
        "Url": "http://xxxxx.vod2.myqcloud.com/xxxxx/aaaaaa/hhh.m3u8",
        "StartTimeOffset": 2.0,
        "EndTimeOffset": 10.0
    }

    输出示例

    {
        "Response": {
            "Url": "http://xxxxx.vod2.myqcloud.com/xxxxx/aaaaaa/10_50.m3u8",
            "FileId": "",
            "TaskId": "",
            "MetaData": {
                "Size": 0,
                "Container": "hls",
                "Bitrate": 622014,
                "Height": 480,
                "Width": 640,
                "Duration": 48.0,
                "Rotate": 0,
                "VideoStreamSet": [
                    {
                        "Bitrate": 592385,
                        "Height": 480,
                        "Width": 640,
                        "Codec": "h264",
                        "Fps": 25,
                        "CodecTag": "",
                        "DynamicRangeInfo": {
                            "Type": "",
                            "HDRType": ""
                        }
                    }
                ],
                "AudioStreamSet": [
                    {
                        "Bitrate": 29629,
                        "SamplingRate": 44100,
                        "Codec": "aac"
                    }
                ],
                "VideoDuration": 0.0,
                "AudioDuration": 0.0,
                "Md5": "Md5"
            },
            "RequestId": "12ae8d8e-dce3-4151-9d4b-5594145287e1"
        }
    }

    5. 开发者资源

    腾讯云 API 平台

    腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台,方便您从同一入口查询及使用腾讯云提供的所有 API 服务。

    API Inspector

    用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况,并自动生成各语言版本的 API 代码,也可前往 API Explorer 进行在线调试。

    SDK

    云 API 3.0 提供了配套的开发工具集(SDK),支持多种编程语言,能更方便的调用 API。

    命令行工具

    6. 错误码

    以下仅列出了接口业务逻辑相关的错误码,其他错误码详见 公共错误码

    错误码 描述
    FailedOperation 操作失败。
    FailedOperation.InvalidVodUser 没有开通点播业务。
    InternalError 内部错误。
    InvalidParameterValue 参数取值错误。
    InvalidParameterValue.EndTimeOffset 参数错误:无效的结束时间。
    InvalidParameterValue.ExpireTime 参数值错误:ExpireTime 格式错误。
    InvalidParameterValue.IsPersistence 参数值错误:错误固化参数。
    InvalidParameterValue.OutputMediaType 参数值错误:错误的输出媒体文件类型。
    InvalidParameterValue.Precision 参数值错误:错误的精度参数。
    InvalidParameterValue.Procedure 参数值错误:错误的 Procedure 。
    InvalidParameterValue.StartTimeOffset 参数错误:无效的起始时间。
    InvalidParameterValue.Url 参数错误:无效的Url。
    ResourceUnavailable.MasterPlaylist 参数错误:不支持MasterPlaylist的M3u8。
    UnauthorizedOperation 未授权操作。