README.md

---
title: Murderer Detector
emoji: 🔪
sdk: gradio
sdk_version: 6.0.1
app_file: app.py
pinned: false
license: apache-2.0
short_description: Detect suspicious individuals lurking behind you with AI!
---

# 🔪 Murderer Detector

[![Gradio](https://img.shields.io/badge/Gradio-6.0.1-orange)](https://gradio.app/)
[![Python](https://img.shields.io/badge/Python-3.10+-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)

> **WARNING:** This app uses HIGHLY ADVANCED AI TECHNOLOGY to detect potential murderers lurking behind you!

## What is This?

A humorous real-time person detection app that detects suspicious individuals lurking **behind** you. Built with Gradio 6.0.1 and YOLOv8.

**This is for funs.** No actual threat detection occurs. Don't call the cops on your roommates.

## Features

- **Real-time webcam streaming** with unified display (no separate input/output)
- **Smart user detection** - filters out the user (largest person) and only flags people behind them
- **Person detection** with YOLOv8-nano
- **Hilarious single-line labels** with emojis and threat percentages:
  - 🥣 SERIAL BREAKFAST SKIPPER (87%)
  - 📚 DANGEROUS BOOK READER (92%)
  - 🛏️ FITTED SHEET FOLDER (76%)
  - ☕ NOTORIOUS TEA DRINKER (95%)
  - 🔌 OWNS MULTIPLE USB-C CABLES (83%)
  - ...and 15 more!
- **Color-coded threat levels** (red/orange/yellow based on percentage)
- **Large, readable text** optimized for webcam viewing
- **Running suspect count** in header

## Quick Start

### Run Locally

```bash
# Install dependencies
pip install -r requirements.txt

# Run the app (includes share=True for instant public URL)
python app.py
```

The app will launch at http://localhost:7860 and provide a public shareable link!

### Deploy to Hugging Face Spaces

1. Create a new Space on Hugging Face
2. Upload these files:
   - `app.py`
   - `requirements.txt`
   - `README.md`
3. Your app will automatically deploy!

## For Developers

This app is intentionally structured to be easily modified for **serious computer vision applications**. The code is organized into clear modules:

### Architecture

```
PersonDetector      → Detection Module (swap YOLO for any model)
MurdererClassifier  → Classification Logic (replace with real ML)
FrameAnnotator      → Annotation Layer (customize visuals)
MurdererDetector    → Main Pipeline (orchestrates everything)
```

### Modify for Serious Use Cases

**Security Monitoring:**

- Replace `MurdererClassifier` with anomaly detection
- Add action recognition (violence, falls, intrusions)
- Integrate alerts and logging

**PPE Detection:**

- Modify `PersonDetector` to detect helmets, vests, masks
- Add compliance scoring in `MurdererClassifier`
- Update annotations to show violations

**Customer Analytics:**

- Track people counting and dwell time
- Add age/gender classification
- Generate heatmaps in `FrameAnnotator`

**Social Distancing:**

- Calculate distances between detected persons
- Flag violations with visual warnings
- Log statistics over time

### Key Components

**app.py:53** - `PersonDetector.detect_persons()` - Swap detection models here

**app.py:127** - `MurdererClassifier.classify()` - Replace with real ML inference

**app.py:183** - `FrameAnnotator.annotate_frame()` - Customize visualization

**app.py:342** - `MurdererDetector._filter_user()` - Logic to exclude the user (largest person)

All classes are well-documented with inline comments explaining modification points.

## Technical Details

- **Detection**: YOLOv8-nano (fast, lightweight, ~6MB model)
- **Streaming**: Gradio 6.x Image streaming with unified input/output
- **Processing**: Real-time with OpenCV
- **User Filtering**: Excludes largest person (assumed to be the user)
- **Deployment**: Optimized for Hugging Face Spaces with share=True enabled

## How to Use

1. **Run the app** - It launches with a public shareable link
2. **Enable webcam** - Click the webcam button in the interface
3. **Position someone behind you** - The app needs at least 2 people (you + someone behind you)
4. **Watch the detection** - Only people behind you get flagged as "threats"
5. **Share the link** - Use the Gradio share link to show friends

**Note:** If you're the only person in frame, nothing will be detected (by design!)

## License

Apache 2.0 - Use this code for anything! Education, commercial projects, world domination, etc.

## Credits

Built with:

- [Gradio 6.0.1](https://gradio.app/) for the UI and streaming
- [Ultralytics YOLOv8](https://github.com/ultralytics/ultralytics) for person detection
- Excessive amounts of coffee and true crime documentaries

## Contributing

Found a funnier label? Want to improve the detection? Open a PR!

Ideas for improvements:

- More emoji labels (currently 20, could add 50+)
- Sound effects when new suspects appear
- Threat level history/tracking
- Better user filtering (depth detection, face recognition)
- Multiple webcam angles
- Export "suspect reports" as PDF
- Multiple language support

---

**Remember:** The real murderers are the friends we made along the way. Stay safe out there! 🔪