VideoDB Video Perception Skill
One skill that lets your coding agent ingest, understand, search, edit, and stream video and audio server-side — no local ffmpeg glue required.
Positives: explicitly instructs the agent NOT to handle the API key and lets the user set it; declared allowed-tools are restrained (Read/Grep/Glob/Bash python). Deductions: Bash(python:*) effectively permits arbitrary Python execution (network, filesystem); desktop/mic/system-audio capture collects highly sensitive data with no explicit user-confirmation step; data flow to the third-party VideoDB cloud is described but retention/deletion policy and rollback mechanisms are absent.
Docs are highly self-consistent: edge handling for 'partial' understanding runs, a common-pitfalls table with real error messages, breaking-change notes (SearchResponse vs SearchResult), macOS-only constraints. But this is a static review with no committed tests or CI execution evidence covering key paths, so capped at 10 by calibration.
Scenarios, inputs/outputs, and trigger examples (canonical prompts) are clear; boundaries declared (capture macOS-only, slow reframe, plan-gated features). Deductions: core function depends entirely on the overseas VideoDB cloud and console.videodb.io with no mainland-China reachability discussion and no Chinese-language support note; non-fit ranges only partially covered.
Good layering (SKILL.md plus reference/ docs with progressive disclosure) and MIT license at repo level. Deductions: no skill-level version or changelog, maintenance ownership and update path not declared within the skill, and troubleshooting leans on external SDK behavior.
Complete, actionable code paths from ingest to editing with high-value pitfall guidance (.length as string, Clip duration validation, force=True semantics). But static review cannot verify outputs are directly usable, and marginal value over calling the SDK directly is partly documentation integration with limited evidence — capped below full marks.
Cites many concrete API behaviors and error messages, giving auditable primary material. But no third-party execution evidence, no test reproduction, and no cross-source corroboration; most claims remain author assertions — 4 of a capped 5.
- The skill can run arbitrary Python via Bash(python:*) and supports screen/mic/system-audio capture; obtain explicit user consent for capture scope before use.
- All media and index data are uploaded to the overseas VideoDB cloud; avoid sensitive content, and mainland-China reachability is unverified.
- Desktop capture is macOS-only; reframe and similar operations can block for minutes — limit segments or use async callbacks.
- No skill-level versioning or changelog; behavior may shift with SDK updates — pin videodb>=0.5.0 and verify independently.
- This is a static source review with no code execution; real-world usability must be reproduced by the user.
What does this skill do, and when should you use it?
This is VideoDB's official Agent Skill, bringing end-to-end server-side video workflows into coding agents like Claude Code. It follows a See → Understand → Act loop: ingest local files, URLs, YouTube videos, or RTSP live feeds; run analyzers over speech, scenes, objects, OCR, and brands to build searchable indexes; then produce results via timeline editing, subtitles, dubbing, and generative media — all returning playable HLS links. The skill itself is a detailed SKILL.md plus reference docs and scripts, while the heavy processing runs on VideoDB's cloud. It requires a VideoDB API key (free tier available) and Python 3.9+.
Calls the VideoDB server-side API through the videodb Python SDK: uploads local files, URLs, or RTSP streams and returns playable links; runs analyzers (spoken_words, vlm, object_detection, ocr, brand_detection, activity_recognition, etc.) into artifacts and indexes each one; retrieves timestamped moments and evidence via search/semantic_search/query/aggregate/ask; performs clips, subtitle burn-in, text/image/audio overlays on an Editor Timeline; transcodes and reframes via transcode/reframe; generates images, audio, voiceovers, and music; and runs real-time understanding with event alerts on desktop capture (macOS only) and RTSP feeds.
- A developer who wants their agent to turn a YouTube or local video into a shareable stream link without building a transcoding pipeline
- A content team that needs to find specific moments in long video by meaning (e.g. 'every scene with a product') and get timestamped clips
- An ops/marketing person batch-converting aspect ratio (vertical/square) and resolution for TikTok/Instagram
- A creator auto-generating subtitles, translated dubbing, and branded overlays, then exporting the finished video
- A security setup plugging in an RTSP camera for real-time monitoring with alerts when a person enters a zone
- A desktop user recording a session and getting an actionable summary with playable evidence links
What are this skill's strengths and limitations?
- Covers the full video chain — ingest, understand, retrieve, edit, generate, stream — behind one consistent interface
- All heavy computation is server-side; no ffmpeg or local encoding tools needed on the client
- Exceptionally thorough SKILL.md: error tables, version pitfalls (e.g. .compile() on SearchResponse), and v1→v2 indexing migration guidance
- Rich reference/ documentation and runnable code examples reduce trial-and-error
- Sandbox Compute supports running open-weight models (Gemma, Qwen, Whisper, FLUX, RT-DETR)
- Free tier and free API key, no credit card required
- Hard dependency on the VideoDB cloud and an API key — it's a paid SaaS beyond the free tier, unsuitable for fully offline use
- Desktop capture is macOS only
- reframe() is a slow server-side op that can time out on long videos; you must limit segments or use async callbacks
- Some features (generate_video, create_collection) are plan-gated
- No test suite or independent benchmarks in the source material — real-world results need your own verification
How do you install this skill?
Run npx skills add video-db/skills in your AI coding agent, or use the Claude Code plugin: /plugin marketplace add video-db/skills then /plugin install videodb@videodb-skills. Then tell the agent "setup videodb" — it will install the SDK (pip install "videodb[capture]" >=0.5.0 python-dotenv) and verify the connection. Get your own API key at https://console.videodb.io (free tier, no credit card) and set it via export VIDEO_DB_API_KEY=sk-xxx or your project's .env; the skill explicitly forbids the agent from handling the key itself.
How do you use this skill?
Give the agent natural-language instructions; the skill loads automatically. Example prompts: "Ingest this file and return a playable stream link"; "Index this folder and find every scene with people, return timestamps"; "Generate subtitles, burn them in, and add light background music"; "Start desktop capture and alert when a password field appears." The skill generates inline Python using the videodb SDK (it must cd into your project directory first so load_dotenv finds the .env). Full reference docs live under reference/ in the skill folder.
How does this skill compare with similar options?
SKILL.md explicitly contrasts this with local tooling: it instructs the agent not to use ffmpeg, moviepy, or local encoders whenever VideoDB supports the operation, falling back to local tools only for speed changes, crop/zoom, color grading, and keyframe animation. In short, it positions itself as a cloud video-processing API alternative to hand-rolled local ffmpeg pipelines.