VideoDB Documentation
Real‑Time Interface — Quick‑Start
This guide expands the earlier quick start examples with a deeper look at the RTStream, RTStreamSceneIndex, and Event APIs.
It also summarises how you can tune scene extraction and frame sampling so that your real‑time pipelines stay both cost‑efficient and semantically rich.
1 Connecting a live stream
# assume you already have `conn = videodb.connect(api_key="...")`
coll = conn.get_collection()
rtstream = coll.connect_rtstream(
name="Mumbai CCTV",
rtsp_url="rtsp://user:pass@1.1.1.1:554/mystream"
)
The returned RTStream object represents the persistent ingest pipeline from your camera or encoder.
Core attributes
attribute
type
description
name
str
Friendly label you supplied at creation
collection_id
str
The parent collection (useful for multi‑tenant setups)
status
str
connected, stopped, etc.
id
str
Unique identifier for the live stream
There are no rows in this table
Key RTStream methods
method
purpose
start() / stop()
Toggle ingest on the server side
generate_stream(start, end)
Get an HLS/MP4 URL for an arbitrary clip window (in seconds)
list_scene_indexes() / get_scene_index(id)
Inspect existing scene indices linked to this stream.
There are no rows in this table
2 Indexing scenes in real time
scene_index = rtstream.index_scenes(
extraction_type=SceneExtractionType.time_based, # or shot_based
extraction_config={"time": 2, "frame_count": 5},
prompt="Describe the scene and highlight congestion",
name="traffic_monitor"
)
Full parameter reference
parameter
default
description
extraction_type
SceneExtractionType.time_based
Selects the segmentation algorithm — time‑based ( only supported for now )
extraction_config
{"time":2, "frame_count":5}
Algorithm‑specific knobs (see below)
prompt
"Describe the scene"
Text sent to the vision‑LLM for every scene
name
None
Label for this index; handy when you maintain multiple indices
There are no rows in this table
Frame‑sampling knobs
extraction_type
key
meaning
time_based
time
Seconds per scene chunk (e.g. 10 s)
frame_count
fixed number of frames per chunk
select_frames
Pick specific positions: ["first","middle","last"]
There are no rows in this table
3 Working with RTStreamSceneIndex
The object returned by index_scenes() exposes real‑time analytics utilities.
Table 6
method
what it does
(start=None, end=None, page=1, page_size=100)
Paginate through raw scene records (timestamp & description)
start() / stop()
Enable/disable the index without deleting it
(event_id, callback_url)
Subscribe an alert to a pre‑defined Event
list_alerts()
Enumerate alert subscriptions
(alert_id) / disable_alert(alert_id)
Toggle alert delivery
There are no rows in this table
4 Defining reusable Events
conn.create_event() registers a server‑side rule that can be reused across multiple streams or indices.
event_id = conn.create_event(
event_prompt="Detect pedestrians crossing the zebra",
label="human_detection"
)
Event fields
field
required
notes
event_prompt
✔︎
Natural‑language condition evaluated by the vision model
label
✔︎
Slug used in alert payloads & dashboards
There are no rows in this table
5 End‑to‑end sample
rtstream = coll.connect_rtstream("Mumbai CCTV", rtsp_url=RTSP_URL)
scene_idx = rtstream.index_scenes(prompt="Summarise traffic")
# Generic pedestrian detector, reused in multiple places
ped_event = conn.create_event("Detect pedestrians", label="pedestrian")
alert_id = scene_idx.create_alert(ped_event, callback_url="https://api.example.com/webhooks/ped")
① ingests frames → ② generates per‑scene embeddings + text → ③ evaluates pedestrian rule → ④ fires a webhook in <1 s.
6 Next steps & notebooks
For deeper, domain‑specific recipes clone or run the published Colab notebooks:
Want to print your doc?
This is not the way.
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
CtrlP
) instead.