# Platform · VideoDB

> A distributed data format that unlocks random access to video frames.

VideoDB built a distributed data format for machine understanding of the visual world. It sits as a logical layer on top of your existing files and spreads the work across as many machines as you give it. Every video primitive in your workflow, from transcoding to search, runs on top.

Canonical: https://videodb.io/platform · Paper: https://arxiv.org/abs/2608.08075 · Docs: https://docs.videodb.io

## The pipeline: six stages around the distributed data format

Three distributed processing stages write into the format; three scalable serving stages read from it.

1. **Transcoding** (distributed, batch and realtime): MP4, archives, S3; RTSP, live cameras; screens and audio. Transcoded once, in parallel. Addressable by frame.
2. **Frames** (distributed extraction and sampling): sample at any rate, tile for models, across the whole archive at once.
3. **Annotation** (distributed pipelines, hosted and enterprise models): any model as an analyzer, with human checks. Built for massive scale.

**The distributed data format**: files stay in storage, VideoDB builds a logical layer on top. Episodes, metadata and indexes, persistent and timestamped to the frame. Scoped to a user, an agent or a workspace. Every stage above writes to it. Every stage below reads from it.

4. **Retrieval** (scalable engine, sub-second): semantic and metadata queries, filters and aggregations, frame access in milliseconds. Every result is an evidence stream: people watch it, agents process the frames.
5. **Streaming** (scalable engine, one stream per query): `ws://events/agent-42`, `sse://text/answer`, `frames://run-0412@30fps`, `hls://cdn/stream-x.m3u8`. One live stream per query, to a screen, a model or an agent.
6. **Runtime** (agents run on top): agent loops, tool calls and webhooks, harness and observability. Bring your agents or use ours.

Use one API. Run in our cloud or yours. Start building: https://console.videodb.io/auth

- **Right architecture**: flexible temporal boundary of retrieved clips. The question decides the window.
- **High speed**: 500 ms to get clips, or direct access to frames.
- **Low cost**: no re-encoding, by design.

Compliance: SOC 2 Type II, GDPR, ISO 27001, zero data retention.

## Quickstart

Get your API key at https://console.videodb.io, upload a file, index it, search it, play the evidence.

- `pip install videodb` or `npm install videodb` (Python and Node)
- `npx skills add video-db/skills` (coding agents)

```python
from videodb import connect

conn = connect()                      # 1. get your API key at console.videodb.io
coll = conn.get_collection()

video = coll.upload(url="s3://lab/run-0412.mp4")    # 2. upload a file

u = video.understand(analyzers=[{"type": "vlm", "name": "scene",
    "config": {"prompt": "What happens, and with what result?"}}])
u.wait_until_complete()
idx = video.index(name="scene", source=u.get_analyzer("scene"))   # 3. index

res = video.semantic_search(query="the gripper drops the bottle",   # 4. search
    index_ids=[idx.index_id], top_k=5)
for shot in res.get_shots():
    print(shot.start, shot.end, shot.metadata)

stream = res.compile()                # 5. the evidence, as a playable stream
```

Quickstart notebook: https://colab.research.google.com/github/video-db/videodb-cookbook/blob/main/quickstart/VideoDB%20Quickstart.ipynb · Docs: https://docs.videodb.io