/videodb

name: videodb
description: See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.
origin: ECC
allowed-tools: Read Grep Glob Bash(python:*)
argument-hint: "[task description]"

VideoDB Skill

**Perception + memory + actions for video, live streams, and desktop sessions.**

When to use

Desktop Perception

• Start/stop a **desktop session** capturing **screen, mic, and system audio**
• Stream **live context** and store **episodic session memory**
• Run **real-time alerts/triggers** on what's spoken and what's happening on screen
• Produce **session summaries**, a searchable timeline, and **playable evidence links**

Video ingest + stream

• Ingest a **file or URL** and return a **playable web stream link**
• Transcode/normalize: **codec, bitrate, fps, resolution, aspect ratio**

Index + search (timestamps + evidence)

• Build **visual**, **spoken**, and **keyword** indexes
• Search and return exact moments with **timestamps** and **playable evidence**
• Auto-create **clips** from search results

Timeline editing + generation

• Subtitles: **generate**, **translate**, **burn-in**
• Overlays: **text/image/branding**, motion captions
• Audio: **background music**, **voiceover**, **dubbing**
• Programmatic composition and exports via **timeline operations**

Live streams (RTSP) + monitoring

• Connect **RTSP/live feeds**
• Run **real-time visual and spoken understanding** and emit **events/alerts** for monitoring workflows

How it works

Common inputs

• Local **file path**, public **URL**, or **RTSP URL**
• Desktop capture request: **start / stop / summarize session**
• Desired operations: get context for understanding, transcode spec, index spec, search query, clip ranges, timeline edits, alert rules

Common outputs

• **Stream URL**
• Search results with **timestamps** and **evidence links**
• Generated assets: subtitles, audio, images, clips
• **Event/alert payloads** for live streams
• Desktop **session summaries** and memory entries

Running Python code

Before running any VideoDB code, change to the project directory and load environment variables:

from dotenv import load_dotenv
load_dotenv(".env")

import videodb
conn = videodb.connect()

This reads `VIDEO_DB_API_KEY` from: 1. Environment (if already exported) 2. Project's `.env` file in current directory

If the key is missing, `videodb.connect()` raises `AuthenticationError` automatically.

Do NOT write a script file when a short inline command works.

When writing inline Python (`python -c "..."`), always use properly formatted code — use semicolons to separate statements and keep it readable. For anything longer than ~3 statements, use a heredoc instead:

python << 'EOF'
from dotenv import load_dotenv
load_dotenv(".env")

import videodb
conn = videodb.connect()
coll = conn.get_collection()
print(f"Videos: {len(coll.get_videos())}")
EOF

Setup

When the user asks to "setup videodb" or similar:

1. Install SDK

pip install "videodb[capture]" python-dotenv

If `videodb[capture]` fails on Linux, install without the capture extra:

pip install videodb python-dotenv

2. Configure API key

The user must set `VIDEO_DB_API_KEY` using **either** method:

• **Export in terminal** (before starting Claude): `export VIDEO_DB_API_KEY=your-key`
• **Project `.env` file**: Save `VIDEO_DB_API_KEY=your-key` in the project's `.env` file

Get a free API key at [console.videodb.io](https://console.videodb.io) (50 free uploads, no credit card).

**Do NOT** read, write, or handle the API key yourself. Always let the user set it.

Quick Reference

Upload media

# URL
video = coll.upload(url="https://example.com/video.mp4")

# YouTube
video = coll.upload(url="https://www.youtube.com/watch?v=VIDEO_ID")

# Local file
video = coll.upload(file_path="/path/to/video.mp4")

Transcript + subtitle

# force=True skips the error if the video is already indexed
video.index_spoken_words(force=True)
text = video.get_transcript_text()
stream_url = video.add_subtitle()

Search inside videos

from videodb.exceptions import InvalidRequestError

video.index_spoken_words(force=True)

# search() raises InvalidRequestError when no results are found.
# Always wrap in try/except and treat "No results found" as empty.
try:
    results = video.search("product demo")
    shots = results.get_shots()
    stream_url = results.compile()
except InvalidRequestError as e:
    if "No results found" in str(e):
        shots = []
    else:
        raise

Scene search

import re
from videodb import SearchType, IndexType, SceneExtractionType
from videodb.exceptions import InvalidRequestError

# index_scenes() has no force parameter — it raises an error if a scene
# index already exists. Extract the existing index ID from the error.
try:
    scene_index_id = video.index_scenes(
        extraction_type=SceneExtractionType.shot_based,
        prompt="Describe the visual content in this scene.",
    )
except Exception as e:
    match = re.search(r"id\s+([a-f0-9]+)", str(e))
    if match:
        scene_index_id = match.group(1)
    else:
        raise

# Use score_threshold to filter low-relevance noise (recommended: 0.3+)
try:
    results = video.search(
        query="person writing on a whiteboard",
        search_type=SearchType.semantic,
        index_type=IndexType.scene,
        scene_index_id=scene_ind