Volcengine TOS Video Process

Inspect videos, extract frames, and concatenate video clips stored in Volcengine TOS — metadata lookup, single snapshot, multi-frame capture, video concatenation, and TOS-to-TOS persistence.

Setup (once per environment)

Install dependencies on first use:

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

Then run scripts with Python 3.7+:

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

If you see a ModuleNotFoundError for tos, reinstall dependencies.

Environment Variables

This skill relies on the TOS identity declared in the metadata block. Common runtime variables are:

Environment Variable	Required	Description
`TOS_ACCESS_KEY`	Yes	TOS access key ID
`TOS_SECRET_KEY`	Yes	TOS secret access key
`TOS_ENDPOINT`	Yes	TOS endpoint URL
`TOS_REGION`	Yes	TOS region
`TOS_BUCKET`	Yes	Source bucket that stores the video
`TOS_OBJECT_KEY`	No	Source object key of the video. Some scripts accept alternatives, while `video_info.py` and `video_snapshot.py` read this value from the environment
`TOS_SECURITY_TOKEN`	No	STS session token when using temporary credentials
`TOS_SAVEAS_BUCKET`	No	Default target bucket for saving snapshots
`TOS_SAVEAS_OBJECT_PREFIX`	No	Default key prefix for saving snapshots

Quick start (common tasks)

# 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

Available scripts

Script	Purpose
`scripts/video_info.py`	Read video metadata (format, duration, resolution, codec, frame rate).
`scripts/video_snapshot.py`	Capture a single frame at a given timestamp. Supports local save or TOS-to-TOS persistence.
`scripts/video_snapshots.py`	Batch-capture multiple frames across a timeline. Supports explicit timestamps, interval mode, concurrent execution, and TOS-to-TOS persistence.
`scripts/video_concat.py`	Concatenate multiple video clips into one. Uses TOS gateway `media_jobs` async API with `job_type=Concat`. Supports `--wait` to poll until completion.

video_snapshots.py and video_concat.py support --key-style object selection. video_info.py and video_snapshot.py currently read TOS_OBJECT_KEY from the environment. video_snapshots.py also supports --bucket override for multi-bucket testing. Run any script with -h for full usage.

Out of scope

Full video transcoding pipelines (this skill covers metadata + frame extraction + concatenation only).
Image-only or document-only workflows (use byted-tos-image-process or byted-tos-doc-process).
Non-TOS storage providers.

Rules

Authentication: Authentication is provided by the TOS identity declared in the metadata block above. Object selection can be overridden per script with --key.
Timestamp unit: All timestamp parameters are in milliseconds (e.g., 5000 = 5 seconds).
Validate timestamps: Ensure snapshot timestamps do not exceed the video duration. Use video_info.py to read duration first when needed.
Save to TOS: Use --save-to-tos with TOS_SAVEAS_BUCKET / TOS_SAVEAS_OBJECT_PREFIX to persist snapshots back to TOS without local download.
Parameter source of truth: Official Volcengine TOS documentation is authoritative for the full video/snapshot parameter matrix. When uncertain, check REFERENCE.md.
Language: Reply in the user's preferred language.

byted-tos-video-process