videodb

Files (23)

• .env.example
• SKILL.md
• api-reference.md · reference/
• capture-reference.md · reference/
• capture.md · reference/
• editor-reference.md · reference/
• editor.md · reference/
• generative.md · reference/
• indexing-reference.md · reference/
• indexing.md · reference/
• index-reference.md · reference/legacy/
• index.md · reference/legacy/
• search.md · reference/legacy/
• migration.md · reference/
• rtstream-reference.md · reference/
• rtstream.md · reference/
• sandbox-reference.md · reference/
• sandbox.md · reference/
• search-reference.md · reference/
• search.md · reference/
• streaming.md · reference/
• use-cases.md · reference/
• ws_listener.py · scripts/

SKILL.md (first lines)

# VideoDB: setup and the Python SDK

VideoDB runs video work on its servers: ingest, understand, index, search, clip, subtitle, compose, stream. This skill covers setup and the Python SDK. Five smaller skills cover the common jobs and should be used first when they match:

| Job | Skill |
|---|---|
| Find a moment, ask a video, count what appears | `video-search` |
| Clips, highlight reels, vertical cuts, MP4s | `video-clips` |
| Transcripts, subtitles, translation | `video-subtitles` |
| Music, overlays, captions, compositions | `video-edit` |
| Cameras, live streams, meetings, screen capture | `video-live` |

## Which path

1. **VideoDB connector tools present** (names such as `upload_media`, `search_video`, `generate_clip`): use them. This is the path in Claude chat on web, desktop and mobile, and in Cowork. No install, no API key.
2. **No VideoDB tools, but you have a shell** (Claude Code, Cowork, any agent that can run Python): ask for the VideoDB API key in one friendly line (free at https://console.videodb.io, $20 of credits, no card). When the user gives it, save it yourself to the project's `.env` (Setup, below), never print it, and continue with the SDK. In Claude Code, `/mcp` then authorizing the bundled videodb server also works.
3. **No VideoDB tools and no shell**: you are in Claude chat. Reply with only this, adapted to the request: "VideoDB isn't connected yet. Open Settings → Connectors, find VideoDB, click Connect and log in (free, no card). Then send this request again and I'll take it from there." Do not mention API keys, `.env`, shells, Claude Code or `/mcp` here; none of them apply in chat, and a key pasted into chat cannot be used because nothing runs code there.

The SDK path is also the only path for code, scripts, notebooks, desktop capture, AI generation, dubbing and sandbox compute, which the connector does not do. Talking to the user: never write "index", "indexed" or "indexing" in a reply; say "searchable".

Long connector jobs return `status: processing`. The reply carries an `output_url` and names the tool to poll (`poll_with`, or `retry_with` on older servers). Call that tool with the `output_url` until it is `done`; several `processing` replies in a row are normal (a 10-minute YouTube upload takes about five), and a `done` reply with an empty result means poll once more. Never re-run the write; that starts a second job.

## Outputs

- **Stream URL**, playable at `https://console.videodb.io/player?url={STREAM_URL}`; connector tools also return a `player_url`
- Search results with timestamps and playable evidence
- Generated assets: subtitles, audio, images, clips
- Event and alert payloads for live streams
- Desktop session summaries and searchable timelines

## Running Python code

**CRITICAL:** Always `cd` to the user's project directory before running Python code. This ensures `load_dotenv(".env")` finds the correct `.env` file.

```python
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:

```bash
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

```bash
pip install "videodb[capture]>=0.5.0" python-dotenv
```

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

```bash
pip install "videodb>=0.5.0" python-dotenv
```

The `>=0.5.0` pin matters — the understand/index/ask/aggregate APIs do not exist in earlier versions.

### 2. Configure API key

Ask the user for their VideoDB API key in one line: free at https://console.videodb.io, $20 of free credits, no credit card. When they give it to you, in chat or any other way, save it for them and keep going:

- Write `VIDEO_DB_API_KEY=<key>` to the project's `.env` (create the file if needed) and make sure `.env` is listed in `.gitignore`.
- Never print, echo, log or commit the key, and never send it anywhere except through the SDK.
- If they prefer to set it themselves, `export VIDEO_DB_API_KEY=<key>` in the terminal also works.

Tell them what you saved and where, without repeating the key.

### 3. Authorize the hosted MCP server (Claude Code plugin only)

The plugin bundles the hosted MCP server at `https://mcp.videodb.io/mcp`, which is
authorized separately from the SDK key above. Tell the user to run `/mcp`, select
**videodb**, and complete browser authorization with their VideoDB account. Verify with
"list my VideoDB collections".

The MCP tools need no local Python install and no API key. Skip this step when the skill
was installed with `npx skills add` or is running outside Claude Code — there is no MCP
server in that case, and the SDK path above is the only one available.

## Quick Reference

### Upload media

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

### Understand → index → retrieve (default path)

From video-db/skills, MIT.