VideoDB Video Search and Editing

What it does

When your agent uses it

• Searching a video or recording for the moment something was said
• Cutting clips from search results and returning playable links
• Adding subtitles, overlays or dubbing to a video
• Monitoring an RTSP camera feed with real-time alerts
• Capturing a desktop session and summarizing it afterward

Example prompts

• “Upload ./demo/walkthrough.mp4 and find every moment where pricing is discussed.”
• “Add translated subtitles to this video and burn them in.”
• “Connect to the RTSP feed at rtsp://cam.local/stream and alert me when someone enters the frame.”
• “Start a desktop capture session and summarize it when I stop.”

Requirements

• Python with the VideoDB SDK
• A VideoDB API key set as VIDEO_DB_API_KEY
• Pre-approved tools (allowed-tools): Read, Grep, Glob, Bash(python:*)

Workflow steps

2 steps, taken from the step headings in SKILL.md.

1. 1Install SDK
2. 2Configure API key

What it can do on your machine

Read from SKILL.md and the folder at commit 2d515e4. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • Read
  • Grep
  • Glob
  • Bash(python:*)

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Ships 1 file in scripts/ (Python), which the agent can run.

  Shell commands in SKILL.md call:

  • python
  • pip

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Hosts in commands or code, which the agent is likely to contact:

  • youtube.com

  Also links to:

  • console.videodb.io

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names these keys or tokens, usually read from environment variables:

  • VIDEO_DB_API_KEY

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

VideoDB Video Search and Editing loads about 3.5k tokens when it runs. Until then it costs about 113 tokens; SKILL.md has 994 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~113

When it runs · the whole SKILL.md, loaded when a task matches

~3.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

• NoteMentions a .env fileSKILL.md:61

  load_dotenv(".env")

• NoteMentions a .env fileSKILL.md:69

  2. Project's `.env` file in current directory

• NoteMentions a .env fileSKILL.md:80

  load_dotenv(".env")

• NoteMentions a .env fileSKILL.md:110

  - **Project `.env` file**: Save `VIDEO_DB_API_KEY=your-key` in the project's `.env` file

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from affaan-m/ECC at commit 2d515e4, republished under its MIT licence (© affaan-m). 994 words, ~3,498 tokens.

name

videodb

description

Ingest, index, search, edit, and monitor video and audio with the VideoDB Python SDK — upload from files, URLs, or RTSP feeds, build spoken and scene indexes with timestamped search and playable clips, transcode and reframe, do timeline edits (subtitles, overlays, dubbing), and run real-time alerts on live streams or desktop capture. Use when working with video search, transcription, clipping, transcoding, streaming, or live video alerts.

allowed-tools

Read, Grep, Glob, Bash(python:*)

metadata.origin

ECC

argument-hint

[task description]

from dotenv import load_dotenv
load_dotenv(".env")

import videodb
conn = videodb.connect()

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

pip install "videodb[capture]" python-dotenv

pip install videodb python-dotenv

# 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")

# 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()

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

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_index_id,
        score_threshold=0.3,
    )
    shots = results.get_shots()
    stream_url = results.compile()
except InvalidRequestError as e:
    if "No results found" in str(e):
        shots = []
    else:
        raise

from videodb.timeline import Timeline
from videodb.asset import VideoAsset, TextAsset, TextStyle

timeline = Timeline(conn)
timeline.add_inline(VideoAsset(asset_id=video.id, start=10, end=30))
timeline.add_overlay(0, TextAsset(text="The End", duration=3, style=TextStyle(fontsize=36)))
stream_url = timeline.generate_stream()

from videodb import TranscodeMode, VideoConfig, AudioConfig

# Change resolution, quality, or aspect ratio server-side
job_id = conn.transcode(
    source="https://example.com/video.mp4",
    callback_url="https://example.com/webhook",
    mode=TranscodeMode.economy,
    video_config=VideoConfig(resolution=720, quality=23, aspect_ratio="16:9"),
    audio_config=AudioConfig(mute=False),
)

from videodb import ReframeMode

# Always prefer reframing a short segment:
reframed = video.reframe(start=0, end=60, target="vertical", mode=ReframeMode.smart)

# Async reframe for full-length videos (returns None, result via webhook):
video.reframe(target="vertical", callback_url="https://example.com/webhook")

# Presets: "vertical" (9:16), "square" (1:1), "landscape" (16:9)
reframed = video.reframe(start=0, end=60, target="square")

# Custom dimensions
reframed = video.reframe(start=0, end=60, target={"width": 1280, "height": 720})

image = coll.generate_image(
    prompt="a sunset over mountains",
    aspect_ratio="16:9",
)

from videodb.exceptions import AuthenticationError, InvalidRequestError

try:
    conn = videodb.connect()
except AuthenticationError:
    print("Check your VIDEO_DB_API_KEY")

try:
    video = coll.upload(url="https://example.com/video.mp4")
except InvalidRequestError as e:
    print(f"Upload failed: {e}")

import json
import os
import time
from pathlib import Path

events_dir = Path(os.environ.get("VIDEODB_EVENTS_DIR", Path.home() / ".local" / "state" / "videodb"))
events_file = events_dir / "videodb_events.jsonl"
events = []

if events_file.exists():
    with events_file.open(encoding="utf-8") as handle:
        for line in handle:
            try:
                events.append(json.loads(line))
            except json.JSONDecodeError:
                continue

transcripts = [e["data"]["text"] for e in events if e.get("channel") == "transcript"]
cutoff = time.time() - 300
recent_visual = [
    e for e in events
    if e.get("channel") == "visual_index" and e["unix_ts"] > cutoff
]

© affaan-m, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 11 other files (scripts) in skills/videodb of affaan-m/ECC.

• SKILL.md
• reference/api-reference.md
• reference/capture-reference.md
• reference/capture.md
• reference/editor.md
• reference/generative.md
• reference/rtstream-reference.md
• reference/rtstream.md
• reference/search.md
• reference/streaming.md
• reference/use-cases.md
• scripts/ws_listener.py

Open the folder on GitHubat commit 2d515e4

Used in 3 other repositories

We found 8 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 3 other GitHub owners. This page covers the copy in affaan-m/ECC, which our catalogue first saw on October 9, 2026.

• loulanyue/awesome-claude-notesskills/videodbdocs/tr/skills/videodb+4 more
• hashgraph-online/awesome-codex-pluginsplugins/Colin4k1024/tsp/skills/videodb
• tpavanipradeep/everything-claude-codeskills/videodb