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.
Alerts connect events to delivery channels. Choose WebSocket for real-time dashboards or webhooks for server-to-server notifications.
Quick Example # Create alert with webhook delivery alert_id = scene_index.create_alert( event_id = event_id, callback_url = "https://your-backend.com/alerts" ) # Or with WebSocket delivery ws = conn.connect_websocket() await ws.connect() alert_id = scene_index.create_alert( event_id = event_id, ws_connection_id = ws.connection_id )
Delivery Methods Method Latency Use Case WebSocket Real-time Dashboards, live UI updates Webhook Under 1s Server-to-server, automation
You can use both simultaneously for redundancy.
Webhook Delivery Create Webhook Alert alert_id = scene_index.create_alert( event_id = event_id, callback_url = "https://your-backend.com/webhooks/alerts" )
Webhook Payload When an event triggers, you receive a POST request:
{ "event_id" : "event-3fd4174feceb6162" , "label" : "traffic_violation" , "confidence" : 0.95 , "explanation" : "A red sedan ran through the intersection while the light was red" , "timestamp" : "2024-01-15T10:30:45Z" , "start_time" : 1234.5 , "end_time" : 1238.0 , "stream_url" : "https://stream.videodb.io/v3/..." , "player_url" : "https://console.videodb.io/player?url=..." }
Payload Fields Field Type Description event_idstring ID of the triggered event labelstring Human-readable event label confidencefloat Detection confidence (0-1) explanationstring AI-generated description of what was detected timestampstring ISO 8601 timestamp start_timefloat Video timestamp where event starts (seconds) end_timefloat Video timestamp where event ends (seconds) stream_urlstring HLS stream URL for the clip player_urlstring Web player URL
WebSocket Delivery Connect and Listen ws = conn.connect_websocket() await ws.connect() # Pass connection ID when creating alerts alert_id = scene_index.create_alert( event_id = event_id, ws_connection_id = ws.connection_id ) # Listen for events async for event in ws.stream(): if event.get( "channel" ) == "alert" : print ( f "Alert: { event[ 'data' ][ 'label' ] } " ) print ( f "Confidence: { event[ 'data' ][ 'confidence' ] } " )
WebSocket Channels Channel Source Content alertEvent triggers Alert notifications transcriptstart_transcript()Real-time speech scene_indexindex_visuals()Visual analysis audio_indexindex_audio()Audio analysis
Managing Alerts List Alerts alerts = scene_index.list_alerts() for alert in alerts: print ( f " { alert.id } : { alert.event_id } - { alert.status } " )
Enable/Disable Alerts # Temporarily disable scene_index.disable_alert(alert_id) # Re-enable scene_index.enable_alert(alert_id)
Delete Alert scene_index.delete_alert(alert_id)
Dual Delivery Pattern Use both channels for critical alerts:
# WebSocket for real-time UI ws = conn.connect_websocket() await ws.connect() # Create alert with both delivery methods alert_id = scene_index.create_alert( event_id = event_id, callback_url = "https://your-backend.com/alerts" , # webhook ws_connection_id = ws.connection_id # websocket )
Benefits:
WebSocket delivers instantly to connected clients
Webhook provides reliable server-side processing
If WebSocket disconnects, webhook still works
Latency Profile Event Type Typical Latency Alert trigger Under 1s Transcript event 1-2s Visual index event 2-5s Audio index event 2-5s
Delivery Guarantees Method Guarantee Notes WebSocket At-most-once May miss events if disconnected Webhook At-least-once May receive duplicates; use idempotency
Next Steps
Webhooks and Reliability Handle webhooks at scale with idempotency
Event Detection Patterns Create effective detection rules
