byted-tos-video-process

火山引擎 TOS 视频处理

检查视频、提取帧，并拼接存储在火山引擎 TOS 中的视频片段——包括元数据查询、单帧截图、多帧截取、视频拼接，以及将结果持久化到 TOS。

设置（每个环境仅需一次）

首次使用时安装依赖：

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

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

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

如果出现 ModuleNotFoundError，提示找不到 tos，请重新安装依赖。

环境变量

此技能依赖 metadata 块中声明的 TOS 身份信息。常见的运行时变量如下：

环境变量	必需	说明
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	否	保存截图的默认键前缀

快速开始（常见任务）

# Read video metadata (resolution, duration, codec)
TOS_OBJECT_KEY=demo.mp4 python3 {baseDir}/scripts/video_info.py

# Capture a single frame at 5 seconds
TOS_OBJECT_KEY=demo.mp4 python3 {baseDir}/scripts/video_snapshot.py --time 5000 --output frame_5s.jpg

# Capture multiple frames and save locally
python3 {baseDir}/scripts/video_snapshots.py --key demo.mp4 --timestamps 1000 3000 5000

# Capture multiple frames by interval
python3 {baseDir}/scripts/video_snapshots.py --key demo.mp4 \
  --interval-ms 5000 --duration-ms 60000 --output-dir snapshots

# Capture multiple frames and save to TOS
python3 {baseDir}/scripts/video_snapshots.py --key demo.mp4 --timestamps 1000 3000 5000 --save-to-tos

# Concatenate multiple video clips
python3 {baseDir}/scripts/video_concat.py --key clip1.mp4 --fragments "clip2.mp4,clip3.mp4" --output-key merged.mp4 --wait

可用脚本

脚本	用途
scripts/video_info.py	读取视频元数据（格式、时长、分辨率、编码格式、帧率）。
scripts/video_snapshot.py	在指定时间戳截取单帧。支持保存到本地或将结果持久化到 TOS。
scripts/video_snapshots.py	批量截取时间线上的多帧。支持指定时间戳、间隔模式、并发执行，以及将结果持久化到 TOS。
scripts/video_concat.py	将多个视频片段拼接为一个视频。使用 TOS 网关的 media_jobs 异步 API，设置 job_type=Concat。支持使用 --wait 轮询直至完成。

video_snapshots.py 和 video_concat.py 支持使用 --key 样式选择对象。video_info.py 和 video_snapshot.py 目前会从环境变量读取 TOS_OBJECT_KEY。video_snapshots.py 也支持通过 --bucket 覆盖存储桶，以便进行多存储桶测试。运行任意脚本并添加 -h，即可查看完整用法。

不在范围内

• 完整的视频转码流水线（此技能仅涵盖元数据、帧提取和视频拼接）。
• 仅处理图像或仅处理文档的工作流（请使用 byted-tos-image-process 或 byted-tos-doc-process）。
• 非 TOS 存储服务提供商。

规则

• 身份验证：身份验证使用上方 metadata 块中声明的 TOS 身份信息。可通过每个脚本的 --key 覆盖对象选择。
• 时间戳单位：所有时间戳参数均以毫秒为单位（例如，5000 = 5 秒）。
• 验证时间戳：确保截图时间戳不超过视频时长。必要时，先使用 video_info.py 读取时长。
• 保存到 TOS：使用 --save-to-tos 以及 TOS_SAVEAS_BUCKET / TOS_SAVEAS_OBJECT_PREFIX，无需下载到本地即可将截图持久化回 TOS。
• 参数权威来源：关于完整的 video/snapshot 参数矩阵，以火山引擎 TOS 官方文档为准。如有疑问，请查看 REFERENCE.md。
• 语言：使用用户偏好的语言回复。

延伸阅读

• 设置和环境：README.md
• 参数参考：REFERENCE.md
• 端到端工作流：WORKFLOWS.md