bytedance 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-processorbyted-tos-doc-process). - Non-TOS storage providers.
Rules
- Authentication: Authentication is provided by the TOS identity declared in the
metadatablock 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.pyto read duration first when needed. - Save to TOS: Use
--save-to-toswithTOS_SAVEAS_BUCKET/TOS_SAVEAS_OBJECT_PREFIXto persist snapshots back to TOS without local download. - Parameter source of truth: Official Volcengine TOS documentation is authoritative for the full
video/snapshotparameter matrix. When uncertain, check REFERENCE.md. - Language: Reply in the user's preferred language.
Further reading
- Setup and environment: README.md
- Parameter reference: REFERENCE.md
- End-to-end workflows: WORKFLOWS.md