> ## 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.

# Event Detection Patterns

> Events are reusable detection rules that define what to look for in video. Create once, attach to any index, and receive alerts when conditions match.

## Quick Example

<CodeGroup>
  ```python Python theme={null}
  import videodb

  conn = videodb.connect()

  # Create a reusable event
  event_id = conn.create_event(
      event_prompt="Detect when a person enters a restricted area",
      label="intrusion_detected"
  )

  # Attach to a scene index
  scene_index.create_alert(
      event_id=event_id,
      callback_url="https://your-backend.com/alerts"
  )
  ```

  ```javascript Node.js theme={null}
  import { connect } from 'videodb';

  const conn = connect();

  // Create a reusable event
  const eventId = await conn.createEvent(
      "Detect when a person enters a restricted area",
      "intrusion_detected"
  );

  // Attach to a scene index
  await sceneIndex.createAlert(
      eventId,
      "https://your-backend.com/alerts"
  );
  ```
</CodeGroup>

***

## Events vs Alerts

| Concept   | What It Is                      | Scope                   |
| :-------- | :------------------------------ | :---------------------- |
| **Event** | Detection rule (prompt + label) | Account-level, reusable |
| **Alert** | Wiring between event and index  | Index-specific          |

Think of events as templates. Create them once, then wire them to multiple indexes via alerts.

***

## Creating Events

### Basic Event

<CodeGroup>
  ```python Python theme={null}
  event_id = conn.create_event(
      event_prompt="Detect when someone falls down",
      label="fall_detected"
  )
  ```

  ```javascript Node.js theme={null}
  const eventId = await conn.createEvent(
      "Detect when someone falls down",
      "fall_detected"
  );
  ```
</CodeGroup>

### Event Prompt Best Practices

The `event_prompt` is what the AI uses to evaluate each indexed scene. Be specific:

```python theme={null}
# Too vague - will trigger on many scenes
event_prompt = "Detect anything unusual"

# Better - specific condition
event_prompt = "Detect when a vehicle runs a red light"

# Best - specific with context
event_prompt = "Detect when a vehicle enters the intersection while the traffic light is red"
```

***

## Detection Patterns by Use Case

### Security & Safety

<CodeGroup>
  ```python Python theme={null}
  # Intrusion detection
  conn.create_event(
      event_prompt="Detect when a person enters the warehouse after hours",
      label="after_hours_entry"
  )

  # Fall detection
  conn.create_event(
      event_prompt="Detect when a person falls or collapses",
      label="fall_detected"
  )

  # Unauthorized access
  conn.create_event(
      event_prompt="Detect when someone accesses the server room without a badge",
      label="unauthorized_access"
  )
  ```

  ```javascript Node.js theme={null}
  // Intrusion detection
  await conn.createEvent(
      "Detect when a person enters the warehouse after hours",
      "after_hours_entry"
  );

  // Fall detection
  await conn.createEvent(
      "Detect when a person falls or collapses",
      "fall_detected"
  );

  // Unauthorized access
  await conn.createEvent(
      "Detect when someone accesses the server room without a badge",
      "unauthorized_access"
  );
  ```
</CodeGroup>

### Retail & Operations

<CodeGroup>
  ```python Python theme={null}
  # Queue detection
  conn.create_event(
      event_prompt="Detect when more than 5 people are waiting in line",
      label="queue_long"
  )

  # Spill detection
  conn.create_event(
      event_prompt="Detect liquid spills on the floor",
      label="spill_detected"
  )

  # Shelf monitoring
  conn.create_event(
      event_prompt="Detect when a shelf appears empty or low on products",
      label="shelf_empty"
  )
  ```

  ```javascript Node.js theme={null}
  // Queue detection
  await conn.createEvent(
      "Detect when more than 5 people are waiting in line",
      "queue_long"
  );

  // Spill detection
  await conn.createEvent(
      "Detect liquid spills on the floor",
      "spill_detected"
  );

  // Shelf monitoring
  await conn.createEvent(
      "Detect when a shelf appears empty or low on products",
      "shelf_empty"
  );
  ```
</CodeGroup>

### Traffic & Transportation

<CodeGroup>
  ```python Python theme={null}
  # Traffic violation
  conn.create_event(
      event_prompt="Detect when a vehicle runs a red light or stop sign",
      label="traffic_violation"
  )

  # Wrong-way driving
  conn.create_event(
      event_prompt="Detect a vehicle driving in the wrong direction",
      label="wrong_way"
  )

  # Congestion
  conn.create_event(
      event_prompt="Detect when traffic has stopped or is moving very slowly",
      label="congestion_detected"
  )
  ```

  ```javascript Node.js theme={null}
  // Traffic violation
  await conn.createEvent(
      "Detect when a vehicle runs a red light or stop sign",
      "traffic_violation"
  );

  // Wrong-way driving
  await conn.createEvent(
      "Detect a vehicle driving in the wrong direction",
      "wrong_way"
  );

  // Congestion
  await conn.createEvent(
      "Detect when traffic has stopped or is moving very slowly",
      "congestion_detected"
  );
  ```
</CodeGroup>

***

## Managing Events

### List Events

<CodeGroup>
  ```python Python theme={null}
  events = conn.list_events()
  for event in events:
      print(f"{event.id}: {event.label}")
  ```

  ```javascript Node.js theme={null}
  const events = await conn.listEvents();
  for (const event of events) {
      console.log(`${event.id}: ${event.label}`);
  }
  ```
</CodeGroup>

### Get Event Details

<CodeGroup>
  ```python Python theme={null}
  event = conn.get_event(event_id)
  print(f"Label: {event.label}")
  print(f"Prompt: {event.event_prompt}")
  ```

  ```javascript Node.js theme={null}
  const event = await conn.getEvent(eventId);
  console.log(`Label: ${event.label}`);
  console.log(`Prompt: ${event.eventPrompt}`);
  ```
</CodeGroup>

### Delete Event

<CodeGroup>
  ```python Python theme={null}
  conn.delete_event(event_id)
  ```

  ```javascript Node.js theme={null}
  await conn.deleteEvent(eventId);
  ```
</CodeGroup>

***

## Prompt Engineering Tips

### Be Specific About Conditions

```python theme={null}
# Weak: ambiguous threshold
"Detect crowding"

# Strong: clear threshold
"Detect when more than 10 people are visible in the frame"
```

### Include Context

```python theme={null}
# Weak: missing context
"Detect a person running"

# Strong: includes context
"Detect a person running in the parking lot (not jogging normally)"
```

### Describe What "Detected" Means

```python theme={null}
# Weak: unclear criteria
"Detect suspicious activity"

# Strong: observable criteria
"Detect when someone looks into car windows repeatedly or tries door handles"
```

***

## Event-Index Pairing

Match your event to the right index configuration:

| Detection Type       | Recommended Index Config  |
| :------------------- | :------------------------ |
| Static objects       | 1 frame per scene         |
| Motion/activity      | 3-5 frames per scene      |
| Quick events         | Short intervals (2-5s)    |
| Sustained conditions | Longer intervals (10-30s) |

***

## What You Can Build

<CardGroup cols={2}>
  <Card title="Intrusion Detection" icon="shield" href="/examples-and-tutorials/live-intelligence/intrusion-detection">
    Real-time alerts when unauthorized access is detected
  </Card>

  <Card title="Traffic Violations" icon="car" href="/examples-and-tutorials/live-intelligence/traffic-violations">
    Detect red light and stop sign violations automatically
  </Card>

  <Card title="Beep Profanity" icon="volume-x" href="/examples-and-tutorials/safety-compliance/beep-profanity">
    Audio event detection to censor inappropriate language
  </Card>

  <Card title="Copyright Detection" icon="shield-check" href="/examples-and-tutorials/safety-compliance/copyright-detection">
    Detect copyrighted content in video streams
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card icon="bell" title="Alerts and Callbacks" href="/pages/act/live-action/alerts-and-callbacks">
    Wire events to delivery channels
  </Card>

  <Card icon="webhook" title="Webhooks and Reliability" href="/pages/act/live-action/webhooks-and-reliability">
    Handle alerts at scale
  </Card>
</CardGroup>