> ## Documentation Index > Fetch the complete documentation index at: https://docs.videodb.io/llms.txt > Use this file to discover all available pages before exploring further. # Core Concepts in 5 Minutes > The entire VideoDB mental model in one scroll - perception, memory, and action for AI agents. ## The Problem AI agents can reason about text brilliantly. But show them a 30-minute meeting recording and ask "what did the client say about pricing?" - they fail. Video files are opaque blobs. Your agent can't query them, can't search them, can't get timestamped answers from them. ## The Platform Loop Every VideoDB workflow follows the same pattern: ``` See → Understand → Act ``` | Stage | What Happens | Returns | | :- | :- | :- | | **See** | Ingest from files, streams, or desktop capture | `Video`, `RTStream`, or `CaptureSession` | | **Understand** | Create analyzers, reusable artifacts, and indexes. | Retrieval-ready video context | | **Act** | Trigger alerts. Compose edits. Export streams. | Webhooks, playable URLs, downloadable files | ## Quick Example ```python theme={null} import videodb conn = videodb.connect() # SEE: Ingest coll = conn.get_collection() video = coll.upload(url="https://example.com/meeting.mp4") # UNDERSTAND: Create a transcript artifact and index it understanding = video.understand( analyzers=[{"type": "spoken_words", "name": "transcript"}] ) understanding.wait_until_complete() transcript = understanding.get_analyzer("transcript") index = video.index(name="meeting_transcript", source=transcript) index.wait_until_complete() # RETRIEVE: Search the completed index results = video.semantic_search( query="pricing discussion", index_ids=[index.index_id], top_k=5, ) # ACT: Use the results for shot in results.get_shots(): print(f"{shot.start}s - {shot.end}s") shot.play() # Playable proof ``` *** ## See: Three Input Types | Source | Method | Returns | | :- | :- | :- | | **Files** | `coll.upload(url="...")` | `Video` | | **Live streams** | `coll.connect_rtstream(url="...", name="Camera")` | `RTStream` | | **Desktop capture** | `conn.create_capture_session(...)` | `CaptureSession` → `RTStream` | ```python theme={null} # Files coll = conn.get_collection() video = coll.upload(url="https://youtube.com/watch?v=...") # Live RTSP rtstream = coll.connect_rtstream(url="rtsp://camera.local/stream", name="Camera") # Desktop capture cap = conn.create_capture_session(end_user_id="user_123") ``` Videos index completed analyzer artifacts. RTStreams continuously index a VLM output descriptor. *** ## Understand: Indexes Are Everything Indexes are what transform opaque media into searchable knowledge. You create them with prompts. ### Spoken Index Transcribes audio and makes it searchable: ```python theme={null} understanding = video.understand( analyzers=[{"type": "spoken_words", "name": "transcript"}] ) understanding.wait_until_complete() transcript = understanding.get_analyzer("transcript") spoken_index = video.index(name="spoken", source=transcript) spoken_index.wait_until_complete() ``` ### Visual Index Understands what's happening on screen: ```python theme={null} understanding = video.understand( analyzers=[ { "type": "vlm", "name": "scene", "config": {"prompt": "Describe key activities and events"}, } ] ) understanding.wait_until_complete() scene = understanding.get_analyzer("scene") visual_index = video.index(name="visual", source=scene) visual_index.wait_until_complete() ``` ### Multiple Indexes Create different perspectives on the same media: ```python theme={null} # Same video, different questions understanding = video.understand( analyzers=[ { "type": "vlm", "name": "safety", "config": {"prompt": "Identify safety violations"}, }, { "type": "vlm", "name": "summary", "config": {"prompt": "Summarize each segment"}, }, ] ) understanding.wait_until_complete() safety_index = video.index(name="safety", source=understanding.get_analyzer("safety")) summary_index = video.index(name="summary", source=understanding.get_analyzer("summary")) safety_index.wait_until_complete() summary_index.wait_until_complete() ``` Indexes are additive when they reuse an existing artifact. A new analyzer perspective requires another Understand run; remove old indexes without affecting others. *** ## Search Returns Evidence Search returns timestamps and playable links - not just "found" but verifiable. ```python theme={null} results = video.semantic_search( query="product demo", index_ids=[visual_index.index_id], top_k=5, ) for shot in results.get_shots(): print(f"{shot.start}s - {shot.end}s") # Timestamps shot.play() # Play it to verify ``` Every result maps to a playable moment. Your agent can cite its sources. *** ## Act: Events, Alerts, Editing ### Trigger on conditions ```python theme={null} # Continuously understand and index the live VLM output before attaching an alert. live_understanding = rtstream.understand( segmentation={"type": "time", "window": "5s"}, analyzers=[ { "type": "vlm", "name": "scene", "sampling": {"frame_count": 2}, "config": {"prompt": "Describe visible activity, including on-screen deadlines and due dates."}, } ], store=True, ) index = rtstream.index( name="live_scene", source=live_understanding.outputs["scene"], use_for=["semantic"], ) # Create a reusable event event_id = conn.create_event( event_prompt="Detect when a deadline or due date is visible", label="visible_deadline" ) # Wire it to an index. Replace this placeholder with a public endpoint in production. index.create_alert(event_id=event_id, callback_url="https://example.com") ``` ### Compose with code ```python theme={null} from videodb.editor import Timeline, Track, Clip, VideoAsset timeline = Timeline(conn) track = Track() track.add_clip(0, Clip(asset=VideoAsset(id=video.id), duration=30)) timeline.add_track(track) stream_url = timeline.generate_stream() ``` *** ## Objects at a Glance | Object | What It Represents | | :- | :- | | `Connection` | Your authenticated session | | `Collection` | Container for organizing media | | `Video` | Uploaded video | | `RTStream` | Live stream (RTSP or capture) | | `Index` | Searchable interpretation layer | | `SearchResult` | Query results with shots | | `Shot` | Single timestamped match | | `Event` | Reusable detection rule | | `Alert` | Event + delivery config | | `Timeline` | Programmatic edit composition | *** ## Next Steps Try it hands-on Deep dive with examples All objects and relationships How indexing and retrieval work This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.