You need to enable JavaScript to run this app.
文档中心
视频点播

视频点播

请输入
  • 文档首页
    • 视频点播用户指南媒体处理视频实时处理
复制全文
下载 pdf
我的收藏
媒体处理
视频实时处理
复制全文
下载 pdf
我的收藏
视频实时处理

对于存储在视频点播空间中的视频资源，您可以通过在资源 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 的子参数。通过这些参数的组合，您可以实现在视频中添加指定内容、大小、颜色和位置的文字水印。

费用说明

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

使用限制

  • 存储源限制：视频实时处理功能仅适用于存储在点播存储桶内的文件，不支持对通过添加对象存储 Bucket 方式存储的视频文件进行处理。
  • CDN 缓存配置限制：为避免 CDN 缓存干扰，请确保实时处理的查询参数 x-vod-process 已添加到点播域名的缓存键规则中。若未配置，CDN 节点将忽略 x-vod-process 参数。这将导致源视频、以及使用不同参数实时处理后生成的各个版本，都共用同一个缓存键，从而引发缓存污染。例如，在您请求并缓存了一个带实时处理参数的 URL 后，后续对同一个源视频的请求可能会错误地返回已处理的缓存结果。验证步骤：
    1. 调用 DescribeDomainConfig 接口查询当前域名配置，检查 CacheKey.CacheKeyAction.CacheKeyComponents 数组中是否包含针对 x-vod-process 参数的规则。
    2. 如果缺少该规则，调用 UpdateDomainConfig 接口进行配置。在请求体中，您需要传入完整的 CacheKey 对象，将 x-vod-process 参数作为缓存键的组成部分：
      {
    "CacheKey": [
        {
            "CacheKeyAction": {
                "CacheKeyComponents": [
                    {
                        "Action": "includePart",
                        "IgnoreCase": false,
                        "Object": "queryString",
                        "Subobject": "x-vod-process"
                    }
                ]
            },
            "Condition": {
                "ConditionRule": [
                    {
                        "Object": "directory",
                        "Operator": "match",
                        "Type": "url",
                        "Value": "/"
                    }
                ],
                "Connective": "OR"
            }
        }
    ]
}

实时截图

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

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

使用限制

QPS：20 次/秒。

请求参数说明

参数

是否必须

参数说明

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 鉴权串互不冲突。

使用限制

QPS：20 次/秒。

处理结果

处理返回提取到的元信息 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

音频采样格式。

channel_layout

string

音频通道分布。

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 MB。
  • 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
}

实时转码

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

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

注意

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

使用限制

  • 输入片源限制：
    • 格式：仅支持 MP4、MOV 和 H.264、H.265。
    • 分辨率：支持 4K 及以下。
    • 时长限制：不超过 3 小时。
    • 不支持 HDR。
  • QPS：20 次/秒。

前提条件

触发实时转码前，请完成以下配置：

  • 已添加点播加速域名
  • 提交工单联系火山引擎技术支持团队申请开通实时转码白名单功能，并在域名配置的高级配置中开启视频实时处理。
  • 若域名已开启 URL 鉴权，则仅支持 A 类型鉴权。

请求参数说明

Path 触发实时转码的 URL 格式如下：

https://www.example.com/test.mp4/.vod-process/op={base64urlsafe-encode}/media.m3u8

其中：

  • .vod-process：实时转码 Path 触发标识。
  • op：实时转码任务参数。参数值需将 JSON 任务参数进行 Base64 URL Safe 编码。
  • media.m3u8：输出的 HLS 播放文件后缀。

Path 触发方式使用 JSON 描述实时转码任务，顶层参数如下表所示。

参数说明取值
Type类型Task
Task任务类型Object of Task

Task

参数说明取值
Type类型VideoTranscode 或 VideoAbr。VideoTranscode 表示视频转码参数，VideoAbr 表示视频 ABR 参数。
VideoTranscode视频转码参数当 Type 为 VideoTranscode 时填写，Object of VideoTranscode。
VideoAbr视频 ABR 参数当 Type 为 VideoAbr 时填写，Object of VideoAbr。

VideoTranscode

参数说明取值
Format封装格式hls
Video视频处理参数Object of Video
Logo水印功能Object of Logo
Trim视频裁剪Object of Trim
Strategy转码策略Object of Strategy
Save持久化Object of Save

VideoAbr

参数说明取值
Format封装格式hls
Outputs输出视频流Array of Output，最多支持 10 路流。
Save持久化Object of Save

Output

参数说明取值
Video视频处理参数Object of Video
Logo水印功能Object of Logo
Strategy转码策略Object of Strategy

Video

参数说明取值
Width输出宽度取值范围为 [0,4096]，默认与片源一致，需设为偶数。
Height输出高度取值范围为 [0,4096]，默认与片源一致，需设为偶数。
FrameRate输出帧率取值范围为 (0,60]，默认值为 25。
Codec编码格式当前仅支持 h264，默认值为 h264。

说明

  • 仅设置宽度或高度时，另一边会按照片源等比例缩放。
  • 同时设置宽度和高度时，系统会按照片源宽高比选取最大尺寸进行缩放。
  • 如果宽度和高度的取值不是偶数，则会将其加 1 以确保为偶数。

Logo

参数说明取值
Text文字水印Object of Text
Image图片水印地址格式为 filename://<filename>。图片仅支持 jpeg 和 png 格式。
PosXX 轴位置表示水印在视频图像上的 X 坐标原点。
PosYY 轴位置表示水印在视频图像上的 Y 坐标原点。
Width水印宽度水印宽度。
Height水印高度水印高度。
Position水印位置默认为 topleft，支持 topright、bottomleft、bottomright。

Text

参数说明取值
Content文本内容支持中英文。
Font字体支持 msyh、simkai，默认值为 msyh。
Size字体大小默认值为 20，取值范围为 (0,100]。
Color颜色支持 6 位或 8 位十六进制颜色值，也支持颜色单词，例如 FFFFFF、FFFFFFFF、white、green 等。

Save

参数说明取值
Name文件目录名转码输出文件前缀或目录。

Strategy

参数说明取值
Advance提前转码提前转码分片数，最大值为 10。

Trim

参数说明取值
Start裁切起始位置单位为秒，支持浮点数。
End裁切终止位置单位为秒，支持浮点数。

使用示例

示例 1：720p HLS 转码

请求参数如下：

{
    "Type": "Task",
    "Task": {
        "Type": "VideoTranscode",
        "VideoTranscode": {
            "Format": "hls",
            "Video": {
                "Width": 720
            }
        }
    }
}

将上述 JSON 进行 Base64 URL Safe 编码后，拼接到 op 参数中。请求 URL 示例如下：

https://www.example.com/test.mp4/.vod-process/op=eyJUeXBlIjoiVGFzayIsIlRhc2siOnsiVHlwZSI6IlZpZGVvVHJhbnNjb2RlIiwiVmlkZW9UcmFuc2NvZGUiOnsiRm9ybWF0IjoiaGxzIiwiVmlkZW8iOnsiV2lkdGgiOjcyMH19fX0=/media.m3u8

示例 2：ABR + 图片水印转码

请求参数如下：

{
    "Type": "Task",
    "Task": {
        "Type": "VideoAbr",
        "VideoAbr": {
            "Format": "hls",
            "Outputs": [
                {
                    "Video": {
                        "Height": 1080,
                        "FrameRate": 24,
                        "Codec": "h264"
                    },
                    "Logo": {
                        "Image": "filename://e907627749e7443aad872bc34e015812"
                    }
                },
                {
                    "Video": {
                        "Height": 720,
                        "FrameRate": 24,
                        "Codec": "h264"
                    },
                    "Logo": {
                        "Image": "filename://e907627749e7443aad872bc34e015812",
                        "PosX": 50,
                        "PosY": 100,
                        "Width": 200,
                        "Height": 250
                    }
                }
            ]
        }
    }
}

将上述 JSON 进行 Base64 URL Safe 编码后，拼接到 op 参数中。请求 URL 示例如下：

https://www.example.com/test.mp4/.vod-process/op=eyJUeXBlIjoiVGFzayIsIlRhc2siOnsiVHlwZSI6IlZpZGVvQWJyIiwiVmlkZW9BYnIiOnsiRm9ybWF0IjoiaGxzIiwiT3V0cHV0cyI6W3siVmlkZW8iOnsiSGVpZ2h0IjoxMDgwLCJGcmFtZVJhdGUiOjI0LCJDb2RlYyI6ImgyNjQifSwiTG9nbyI6eyJJbWFnZSI6ImZpbGVuYW1lOi8vZTkwNzYyNzc0OWU3NDQzYWFkODcyYmMzNGUwMTU4MTIifX0seyJWaWRlbyI6eyJIZWlnaHQiOjcyMCwiRnJhbWVSYXRlIjoyNCwiQ29kZWMiOiJoMjY0In0sIkxvZ28iOnsiSW1hZ2UiOiJmaWxlbmFtZTovL2U5MDc2Mjc3NDllNzQ0M2FhZDg3MmJjMzRlMDE1ODEyIiwiUG9zWCI6NTAsIlBvc1kiOjEwMCwiV2lkdGgiOjIwMCwiSGVpZ2h0IjoyNTB9fV19fX0=/media.m3u8
最近更新时间：2026.08.31 11:02:18
这个页面对您有帮助吗？
有用
有用
无用
无用