byted-tos-video-process

name	byted-tos-video-process
description	Inspects videos, extracts frames, and concatenates video clips stored in Volcengine TOS: read video metadata, capture single snapshots, batch-capture multiple frames by explicit timestamps or interval, concatenate multiple video clips, and save results locally or back to TOS. Use this skill when the user needs to get video duration or codec info, capture a poster image or thumbnail, extract frames at specific timestamps, sample frames at regular intervals, merge or join multiple video clips into one — even if they don't explicitly mention 'video processing' or 'frame extraction'.
metadata	{"version":"1.0.0","openclaw":{"identity":[{"type":"apikey","provider":"tos_provider","env":["TOS_ACCESS_KEY","TOS_SECRET_KEY","TOS_ENDPOINT","TOS_REGION","TOS_BUCKET"],"required":true}],"optional":{"env":["TOS_OBJECT_KEY","TOS_SECURITY_TOKEN","TOS_SAVEAS_BUCKET","TOS_SAVEAS_OBJECT_PREFIX"]}}}
user-invocable	true
license	Apache-2.0

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.

Further reading

• Setup and environment: README.md
• Parameter reference: REFERENCE.md
• End-to-end workflows: WORKFLOWS.md