README.md

metadata

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

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

# 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 for the UI and streaming
• Ultralytics YOLOv8 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! 🔪