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.
Quick Example import videodb conn = videodb.connect() coll = conn.get_collection() rtstream = coll.get_rtstream( "rts-xxx" ) # Index visuals with a prompt scene_index = rtstream.index_visuals( prompt = "Describe activity and detect unusual behavior" , batch_config = { "type" : "time" , "value" : 5 , "frame_count" : 2 } ) # Create a reusable event event_id = conn.create_event( event_prompt = "Detect when someone enters restricted area" , label = "intrusion_detected" ) # Set up alert alert_id = scene_index.create_alert( event_id = event_id, callback_url = "https://your-backend.com/webhooks/alerts" )
Visual Indexing Convert video frames into structured descriptions using prompts.
scene_index = rtstream.index_visuals( prompt = "Describe the scene and highlight congestion" , batch_config = { "type" : "time" , "value" : 5 , "frame_count" : 2 }, name = "traffic_monitor" , ws_connection_id = ws.connection_id # optional, for real-time events )
batch_config Options Field Type Description typestr Only "time" is supported valueint Window size in seconds frame_countint Frames to extract per window
Examples: # Every 5 seconds, extract 2 frames { "type" : "time" , "value" : 5 , "frame_count" : 2 } # Every 10 seconds, extract 5 frames { "type" : "time" , "value" : 10 , "frame_count" : 5 }
Managing Indexes # List all indexes indexes = rtstream.list_scene_indexes() # Get specific index scene_index = rtstream.get_scene_index(index_id) # Poll scenes scenes = scene_index.get_scenes( start = 0 , end = None , page = 1 , page_size = 100 )
Audio Indexing Extract insights from audio tracks:
audio_index = rtstream.index_audio( prompt = "Identify key speakers and main topics" , batch_config = { "type" : "word" , "value" : 50 } )
Audio batch_config Type Value Description "word"count Segment every N words "sentence"count Segment every N sentences "time"seconds Segment every N seconds
Transcription Real-time speech-to-text:
# Start transcription rtstream.start_transcript( ws_connection_id = ws.connection_id) # Stop transcription rtstream.stop_transcript( mode = "graceful" ) # Poll transcripts transcript = rtstream.get_transcript( start = 0 , page = 1 , page_size = 100 )
Search Query indexed content with natural language:
results = rtstream.search( query = "white car moving fast" , score_threshold = 0.5 ) for shot in results.shots: print ( f "Match at { shot.start } : { shot.text } " ) shot.play() # Opens in browser
Search Results Each shot contains:
Attribute Description startStart timestamp endEnd timestamp textContent description search_scoreRelevance score (0-1) stream_urlPlayback URL
Stream Generation Use generate_stream() to create a playable stream for a time range. You can optionally pass player_config to attach metadata to a shareable player URL.
# Generate stream with player metadata player_url = rtstream.generate_stream( start = 1711000000 , end = 1711003600 , player_config = { "title" : "Live Feed Recording" , "description" : "Camera 1 - Front entrance" , "slug" : "cam1-front" } ) # generate_stream() returns the player_url # Both URLs are also stored on the instance print (rtstream.player_url) # Shareable player URL (same as return value) print (rtstream.stream_url) # Raw HLS stream URL (.m3u8)
player_url vs stream_url URL Format Use case player_urlhttps://console.videodb.io/player?v=...Shareable link with built-in player UI stream_urlhttps://stream.videodb.io/.../.m3u8Raw HLS stream for custom players (HLS.js, Video.js)
generate_stream() returns player_url and stores both URLs on the instance. Use player_url for sharing and embedding, stream_url for custom player integrations.player_config Key Type Description titlestr Title displayed in the player descriptionstr Description for the player page slugstr URL-friendly slug for the player link
player_config is optional. When provided, the player URL includes the metadata for sharing.Embed Code After generating a stream, you can produce embeddable HTML:
# Generate embed code (requires generate_stream() first) rtstream.generate_stream( start = start_ts, end = end_ts) embed_html = rtstream.get_embed_code()
RTStream does not support auto_generate because generate_stream() requires explicit start and end parameters.
Events and Alerts Events are reusable detection rules. Alerts wire events to indexes for notifications.
Create Event event_id = conn.create_event( event_prompt = "Detect pedestrians crossing the zebra" , label = "pedestrian_detected" )
Create Alert alert_id = scene_index.create_alert( event_id = event_id, callback_url = "https://your-backend.com/webhooks/alerts" , ws_connection_id = ws.connection_id # optional )
Alert Delivery Method Latency Use Case Webhook Under 1s Server-to-server POST WebSocket Real-time Frontend dashboards
Manage Alerts # List alerts alerts = scene_index.list_alerts() # Enable/disable scene_index.enable_alert(alert_id) scene_index.disable_alert(alert_id)
WebSocket Events Receive real-time events by passing ws_connection_id:
ws = conn.connect_websocket() await ws.connect() # Pass ws_connection_id to methods rtstream.start_transcript( ws_connection_id = ws.connection_id) # Receive events async for ev in ws.stream(): channel = ev.get( "channel" ) if channel == "transcript" : print ( f "TRANSCRIPT: { ev[ 'data' ][ 'text' ] } " ) elif channel == "scene_index" : print ( f "SCENE: { ev[ 'data' ][ 'text' ] } " ) elif channel == "alert" : print ( f "ALERT: { ev[ 'data' ] } " )
Event Channels Channel Source Content transcriptstart_transcript()Real-time speech-to-text scene_indexindex_visuals()Visual analysis audio_indexindex_audio()Audio analysis alertcreate_alert()Alert notifications
Next Steps
Stream Lifecycle Start, stop, and reconnect patterns
RTSP Ingest Connect RTSP sources
