byted-tos-video-process

用途

byted-tos-video-process 用于处理存储在火山引擎 TOS（对象存储）中的视频。它涵盖三类核心任务：读取视频元数据、从视频中截取帧、以及将多个视频片段拼接为一个视频。所有操作均针对 TOS 上的对象进行，支持将结果直接持久化回 TOS。

主要能力

技能提供以下脚本：

scripts/video_info.py：读取视频元数据，包括格式、时长、分辨率、编码和帧率。该脚本从环境变量 TOS_OBJECT_KEY 读取源视频对象键。
scripts/video_snapshot.py：在给定时间点截取单帧。支持保存到本地，也支持 TOS-to-TOS 持久化。该脚本从环境变量 TOS_OBJECT_KEY 读取源视频对象键。
scripts/video_snapshots.py：在时间线上批量截取多帧。支持显式指定时间点、按时间间隔截取、并发执行，以及 TOS-to-TOS 持久化。支持 --key 选择对象，也支持 --bucket 覆盖以进行多桶测试。
scripts/video_concat.py：将多个视频片段拼接为一个视频。使用 TOS 网关的 media_jobs 异步 API，job_type=Concat，支持 --wait 轮询直到任务完成。支持 --key-style 对象选择。

时间戳参数统一以毫秒为单位，例如 5000 表示 5 秒。所有脚本均可通过 -h 查看完整用法。拼接与批量截帧脚本支持按对象选择（--key-style 或 --key），而 video_info.py 和 video_snapshot.py 目前从环境变量 TOS_OBJECT_KEY 读取对象键。批量截帧可使用 --save-to-tos 配合 TOS_SAVEAS_BUCKET / TOS_SAVEAS_OBJECT_PREFIX，将截图直接保存回 TOS，无需先下载到本地。

使用方式

环境准备（每个环境执行一次）：

首次使用时安装依赖：

cd {baseDir}
pip install -r {baseDir}/requirements.txt

随后使用 Python 3.7+ 运行脚本：

python3 {baseDir}/scripts/<script>.py <args>

如果出现 tos 的 ModuleNotFoundError，请重新安装依赖。

环境变量：

环境变量	是否必填	说明
TOS_ACCESS_KEY	是	TOS 访问密钥 ID
TOS_SECRET_KEY	是	TOS 秘密访问密钥
TOS_ENDPOINT	是	TOS 端点 URL
TOS_REGION	是	TOS 区域
TOS_BUCKET	是	存储视频的源存储桶
TOS_OBJECT_KEY	否	视频的源对象键。部分脚本接受替代参数，而 video_info.py 和 video_snapshot.py 从环境变量读取该值
TOS_SECURITY_TOKEN	否	使用临时凭证时的 STS 会话令牌
TOS_SAVEAS_BUCKET	否	保存截图默认目标存储桶
TOS_SAVEAS_OBJECT_PREFIX	否	保存截图默认对象键前缀

常见任务示例：

# 读取视频元数据（分辨率、时长、编码）
TOS_OBJECT_KEY=demo.mp4 python3 {baseDir}/scripts/video_info.py

# 截取第 5 秒的单帧
TOS_OBJECT_KEY=demo.mp4 python3 {baseDir}/scripts/video_snapshot.py --time 5000 --output frame_5s.jpg

# 截取多帧并保存到本地
python3 {baseDir}/scripts/video_snapshots.py --key demo.mp4 --timestamps 1000 3000 5000

# 按间隔截取多帧
python3 {baseDir}/scripts/video_snapshots.py --key demo.mp4 \
  --interval-ms 5000 --duration-ms 60000 --output-dir snapshots

# 截取多帧并保存到 TOS
python3 {baseDir}/scripts/video_snapshots.py --key demo.mp4 --timestamps 1000 3000 5000 --save-to-tos

# 拼接多个视频片段
python3 {baseDir}/scripts/video_concat.py --key clip1.mp4 --fragments "clip2.mp4,clip3.mp4" --output-key merged.mp4 --wait

适用场景与限制

该技能适用于围绕 TOS 上视频的元数据检查、抽帧截图和片段拼接等任务。

不在范围内：

完整的视频转码流水线（本技能仅覆盖元数据、截帧与拼接）。
仅图片或仅文档的工作流（可使用 byted-tos-image-process 或 byted-tos-doc-process）。
非 TOS 的存储提供商。

规则与注意事项：

鉴权由元数据块中声明的 TOS 身份提供，对象选择可通过各脚本的 --key 覆盖。
所有时间戳参数单位为毫秒（例如 5000 = 5 秒）。
请确保截图时间点不超过视频时长，必要时先用 video_info.py 读取时长。
如需将截图持久化回 TOS 而不下载到本地，可使用 --save-to-tos 配合 TOS_SAVEAS_BUCKET / TOS_SAVEAS_OBJECT_PREFIX。
关于完整的视频与截图参数矩阵，以火山引擎 TOS 官方文档为准；不确定时可查阅 REFERENCE.md。

进一步阅读：安装与环境见 README.md；参数参考见 REFERENCE.md；端到端工作流见 WORKFLOWS.md。

技能介绍

用途

主要能力

使用方式

适用场景与限制