You need to enable JavaScript to run this app.
导航
视频点播
  • 文档首页
    • /视频点播/开发指南/媒体处理/视频实时处理
视频实时处理
最近更新时间：2024.11.26 20:02:06首次发布时间：2024.05.17 13:37:58
我的收藏

对于存储在视频点播空间中的视频资源，您可以通过在资源 URL 中添加处理参数 x-vod-process 来进行实时处理，包含进行实时截图、获取视频资源的元信息和实时获取文件哈希值。本文详细介绍如何使用实时处理功能。

注意

实时处理为白名单功能。使用前请提交工单联系火山引擎技术支持团队申请开通。

特殊字符规则说明

在设置处理参数 x-vod-process 时，您可以使用特殊字符，具体规则如下：

  • 使用下划线 _ 来分隔参数的名称和取值。例如 f_hls 表示输出 HLS 格式视频。
  • 使用逗号 , 来分隔不同的参数。例如 video-w_720,h_360~ 表示输出宽度为 720、高度为 360 的视频。
  • 使用短横线 - 标志子参数的起点，使用波浪线 ~ 标志子参数的结束。例如在 logo-text-c_422YNHFR====,s_40,color_FF00FFFF~x_20,y_20~ 中，c、s、color 是 text 的子参数，text、x、y 是 logo 的子参数。通过这些参数的组合，您可以实现在视频中添加指定内容、大小、颜色和位置的文字水印。

费用说明

实时处理为付费服务，详细价格可参见实时处理费用。

实时截图

将 x-vod-process 设为 video/snapshot，可以从视频流中截取指定时间点的单帧画面，并按指定大小缩放成图片。示例如下：

https://example.volcengine.com/video.mp4?x-vod-process=video/snapshot,t_7000

请求参数说明

参数

是否必须

参数说明

t

否

截图时间点。取值范围为 [0, 视频时长]。仅支持整数。默认值为 0，单位为毫秒。

说明

截图时间小于 0 时，按 0 计算，即输出首帧；大于片源时长，会报错。

w

否

截图宽度。取值范围为 [0, 视频宽度]。仅支持整数。单位为像素（px）。

说明

  • 截图宽高均为 0 时，按片源分辨率输出；若其中一个为 0，则根据另一边指定的值，按片源宽高比输出。
  • 同时设置截图宽高并且宽高比与片源不一致时，截图可能会拉伸变形。
  • 仅设置截图宽度或仅设置截图高度时，会根据片源宽高比进行缩放。

h

否

截图高度。取值范围为 [0, 视频高度]。仅支持整数。单位为像素（px）。

m

否

截图模式。取值如下：

  • accurate: （默认）根据指定的截图时间点精确截图。
  • fast: 截取指定的截图时间点之前最近的一个关键帧。

f

否

输出图片格式。取值如下：

  • jpg（默认）
  • png

rotate

否

截图旋转角度。取值如下：

  • auto：（默认）在截图生成之后根据视频信息进行自动旋转。

说明

  • 视频没有旋转信息，默认不旋转。
  • 视频带旋转信息时，默认自动校正。
  • 90、180、270：按指定角度顺时针旋转。

处理结果

处理返回截图的二进制数据流：

  • 如果输出图片格式设置为 jpg，HTTP Content-Type header 为 image/jpeg
  • 如果输出图片格式设置为 png，HTTP Content-Type header 为 image/png

实时获取元信息

将 x-vod-process 设为 video/info，可以获取指定视频资源的元信息。示例如下：

https://example.volcengine.com/video.mp4?x-vod-process=video/info

说明

  • 如果域名开启了 URL 鉴权，对应的处理参数添加在 query 中即可，和 URL 鉴权串互不影响。
  • 如果域名开启了 URL 鉴权，需要注意修改对应域名的 CDN 缓存规则，需要提交工单，联系技术支持，配置仅带视频实时处理参数缓存。

处理结果

处理返回提取到的元信息 JSON 字符串，示例如下：

{
    "format": {
        "nb_streams": 2,
        "nb_programs": 0,
        "format_name": "mov,mp4,m4a,3gp,3g2,mj2",
        "format_long_name": "QuickTime / MOV",
        "start_time": "0",
        "duration": "10.006",
        "size": "3390677",
        "bit_rate": "2710915",
        "probe_score": 100,
        "tags": {
            "compatible_brands": "isommp41mp42",
            "creation_time": "2021-11-02T14:48:46.000000Z",
            "major_brand": "mp42",
            "minor_version": "1"
        }
    },
    "streams": [
        {
            "index": 0,
            "codec_name": "h264",
            "codec_long_name": "H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10",
            "codec_type": "video",
            "codec_tag_string": "avc1",
            "codec_time_base": "1/60",
            "codec_tag": "0x31637661",
            "duration": "103.5",
            "bit_rate": "1397708",
            "disposition": {
                "default": 1
            },
            "bits_per_raw_sample": "8",
            "r_frame_rate": "30/1",
            "avg_frame_rate": "30/1",
            "nb_frames": "3105",
            "time_base": "1/15360",
            "start_pts": 0,
            "start_time": "0.000000",
            "duration_ts": 1589760,
            "profile": "High",
            "width": 720,
            "height": 1280,
            "coded_width": 720,
            "coded_height": 1280,
            "has_b_frames": 2,
            "sample_aspect_ratio": "1:1",
            "display_aspect_ratio": "9:16",
            "level": 31,
            "chroma_location": "left",
            "refs": 1,
            "is_avc": "true",
            "nal_length_size": "4",
            "pix_fmt": "yuv420p",
            "channels": 0,
            "sample_rate": "0",
            "sample_fmt": "",
            "channel_layout": "",
            "bits_per_sample": 0,
            "initial_padding": 0,
        },
        {
            "index": 1,
            "codec_name": "aac",
            "codec_long_name": "AAC (Advanced Audio Coding)",
            "codec_type": "audio",
            "codec_tag_string": "mp4a",
            "codec_time_base": "1/48000",
            "codec_tag": "0x6134706d",
            "duration": "103.531",
            "bit_rate": "139644",
            "disposition": {
                "default": 1
            },
            "bits_per_raw_sample": "",
            "r_frame_rate": "0/0",
            "avg_frame_rate": "0/0",
            "nb_frames": "4855",
            "time_base": "1/48000",
            "start_pts": 0,
            "start_time": "0.000000",
            "duration_ts": 4969488,
            "profile": "LC",
            "display_aspect_ratio": "",
            "channels": 2,
            "sample_rate": "48000",
            "sample_fmt": "fltp",
            "channel_layout": "stereo",
            "bits_per_sample": 0,
            "initial_padding": 0,
            "tags": {
                "handler_name": "#Mainconcept MP4 Sound Media Handler",
                "language": "eng"
            }
        }
    ]
}

元信息参数说明

video/info类型返回 JSON 字符串，参数如下：

说明

因视频格式和封装格式差异，部分参数不存在信息时，将不返回。

参数

类型

说明

streams

Array of Stream

视频码流信息。

format

Format

封装信息。

Stream

参数

类型

说明

index

int

流索引值。

codec_name

string

编码器名称。

codec_long_name

string

编码器名全称。

codec_type

string

编码器类型，取值如下：

  • audio：音频流
  • video：视频流
  • subtitle：字幕流

codec_tag_string

string

编码器标签名。

codec_time_base

string

编码器每帧时长。

codec_tag

string

编码器标签。

duration

string

时长，单位为秒。

bit_rate

string

码率，单位为 bps。

disposition

map[string]string

该流的附加信息，具体请参考 Disposition 字段。

bits_per_raw_sample

string

原始数据每个采样的位数。

r_frame_rate

string

视频真实基础帧率。

avg_frame_rate

string

视频平均帧率，单位为 fps。

nb_frames

string

音频或视频帧数。

time_base

string

时间基数。

start_pts

int

起播演示时间戳（PTS）。

start_time

string

起播时间，单位为秒。

duration_ts

int

以时间基数计算的时长。

profile

string

编码器配置。

width

Int

视频宽，单位为 px。

height

Int

视频高，单位为 px。

coded_width

int

视频编码宽度，单位为 px。

coded_height

int

视频编码高度，单位为 px。

has_b_frames

Int

视频是否有 B 帧，1 表示有，0 表示无。

sample_aspect_ratio

string

采样宽高比。

display_aspect_ratio

string

显示宽高比。

level

int

视频编码等级。

chroma_location

string

色度数据位置。

refs

int

参考帧数量。

is_avc

string

是否是 AVC 编码。

nal_length_size

string

NAL 单元长度字节数。

pix_fmt

string

视频像素格式。

channels

int

音频通道数。

sample_rate

string

音频采样率，单位 Hz。

sample_fmt

string

音频采样格式。

channels_layout

int

音频通道分布。

bits_per_sample

int

音频采样码率，单位 bit。

initial_padding

int

音频起始填充字节数。

tags

map[string]string

码流 metadata 信息。具体参见 Tags 字段。

说明

除视频处理工具默认写入的字段外，也包括用户写入的自定义字段。

Disposition

参数

类型

说明

default

int

默认流标志。

dub

int

配音音轨标志。

original

int

原始音轨标志。

comment

int

评论音轨标志。

lyrics

int

歌词音轨标志。

karaoke

int

卡拉 OK 音轨标志。

forced

int

强制字幕标志。

hearing_impaired

int

听障人士字幕标志。

visual_impaired

int

视障人士字幕标志。

clean_effects

int

清晰音效音轨标志。

attached_pic

int

附近图像标志。

timed_thumbnails

int

定时缩略图标志。

captions

int

字幕标志。

descriptions

int

描述标志。

metadata

int

元数据标志。

dependent

int

依赖流标志。

still_image

int

静态图像标志。

Tags

参数

类型

说明

compatible_brands

string

封装兼容标志，一般处理工具默认写入。

creation_time

string

创建时间，一般处理工具默认写入。

major_brand

string

封装主要标志，一般处理工具默认写入。

minor_version

string

最低版本，一般处理工具默认写入。

handler_name

string

处理流的媒体方法名，一般处理工具默认写入。

language

string

语言，一般处理工具默认写入。

Format

参数

类型

说明

nb_streams

int

文件的码流数量。

nb_programs

int

文件的节目数量。

format_name

string

容器名称。

format_long_name

string

容器名全称。

start_time

string

起播时间，单位为秒。

duration

string

时长，单位为秒。

size

string

大小，单位为字节。

bit_rate

string

码率，单位为 bps。

probe_score

int

媒体文件探测得分，分数越高表示结果准确的概率越高。

tags

map[string]string

容器 metadata 信息。

实时获取文件哈希值

将 x-vod-process 设为 file/hash，可以获取指定文件的哈希值。示例如下：

https://example.volcengine.com/video.mp4?x-vod-process=file/hash,m_md5

使用限制

  • 指定的单文件大小不能超过 100 M。
  • QPS：10 秒/次。

请求参数说明

参数

是否必须

参数说明

m

否

设置文件哈希值算法。取值如下：

  • md5：（默认）MD5
  • sha1：SHA-1
  • sha256：SHA-256

处理结果

file/hash 类型返回 JSON 字符串，参数说明如下：

参数

类型

说明

hash

string

文件哈希值。不同算法返回的哈希值具体说明如下：

  • MD5 算法返回 128 位二进制数，通常以 32 个十六进制数字表示。
  • SHA-1 算法返回 160 位二进制数，通常以 40 个十六进制数字表示。
  • SHA-256 算法返回 256 位二进制数，通常以 64 个十六进制数字表示。

fsize

int

文件大小，单位为字节。

MD5 算法的返回示例如下：

{
    "hash": "545c426e1ba66***e5e3162f8367",
    "fsize": 9948754
}

SHA-1 算法的返回示例如下：

{
    "hash": "cf8a6d0e8a391bd3***d7f51a0868b93b0e",
    "fsize": 9948754
}

SHA-256 算法的返回示例如下：

{
    "hash": "ac7b85629c572ad9c5f4b32c29***9d4ccb3ac65ff3ac3acfe478c",     
    "fsize": 9948754
}

实时转码

传统的离线转码是提前转码完成，再对转码后的文件进行分发播放。实时转码则是用户访问时才真正触发转码，快速完成转码后并返回产物。实时转码具有以下优点：

  • 极短耗时：秒级别内可以开始播放即时转码后的视频，同步返回，几乎无需等待时间。
  • 按需请求：转码请求和播放请求合二为一，能够按需发起请求。
  • 成本节约：业务侧仅需为播放视频付费，未播放视频没有转码和存储成本。

将 x-vod-process 设为 video/transcode，即可对视频进行实时转码。示例如下：

https://example.volcengine.com/video.mp4?x-vod-process=video/transcode,f_hls,video-w_720~logo-text-c_422YX2FPSXTLBNHFRWYA====,s_40,color_FF00FFFF~x_20,y_20~

片源限制

  • 支持格式：仅支持 MP4、MOV 和 H.264、H.265。
  • 分辨率限制：支持 4K 及以下。
  • 时长限制：不超过 3 小时。
  • 不支持 HDR。

请求参数说明

参数

是否必选

说明

f

是

转码输出产物封装格式。当前仅支持设为 hls。

video

否

视频处理参数，包含：

  • w: 转码输出产物的宽度，单位为 px。默认与片源一致。取值范围为 [0, 4096]，需设为偶数。
  • h: 转码输出产物高度，单位为 px。默认与片源一致。取值范围为 [0, 4096]，需设为偶数。
  • fr: 转码输出产物的帧率，单位为 fps。默认值为 25，取值范围为 (0,60]。
  • codec: 编码格式。默认为 h264。当前仅支持 h264。

说明

  • 仅设置宽度或高度时，另一边会按照片源等比例缩放。
  • 同时设置宽度和高度且宽高比和片源不一致时，系统会在保持片源宽高比的情况下，调整尺寸至能够符合设定的宽度和高度中的最大尺寸。
  • 如果宽度和高度的取值不是偶数，则会将其加 1 以确保为偶数。

logo

否

水印添加参数，包含：

  • text: 文字水印参数。
    • c: 文字内容，支持中英文，需使用 base32 编码。
    • f: 文字字体，取值如下：
      • （默认）msyh
      • simkai
    • s: 字体大小，默认为 20，取值范围 (0, 100]。
    • color: 文字颜色。支持十六进制方式（6 个字符或 8 个字符均可）和颜色单词，如 FFFFFF、FFFFFFFF、white、green等。
  • image: 图片水印地址。格式为 filename://<filename>，需使用 base32 编码。您需先将图片作为素材上传至视频点播服务，然后获取图片的 FileName。示例：base32_encode(filename://logo.jpg)。仅支持 jpeg 和 png 格式图片。
  • x: X 轴位置，即水印原点距离视频图像坐标原点的水平偏移。单位为 px。默认值为 0，取值范围为大于等于 0。
  • y: Y 轴位置，即水印原点距离视频图像坐标原点的垂直偏移。单位为 px。默认值为 0，取值范围为大于等于 0。
  • w: 水印宽度。单位为 px。默认值为 0，取值范围为大于等于 0。
  • h: 水印高度。单位为 px。默认值为 0，取值范围为大于等于 0。
  • p: 水印位置。取值如下：
    • topleft：（默认）表示坐标原点位于视频图像左上角，水印原点为水印的左上角。
    • topright：表示坐标原点位于视频图像的右上角，水印原点为水印的右上角。
    • bottomleft：表示坐标原点位于视频图像的左下角，水印原点为水印的左下角。
    • bottomright：表示坐标原点位于视频图像的右下角，水印原点为水印的右下角。

说明

具体请见水印位置示意图。