Suzyxx/kenya-wildlife-monitor
Domain:
environment and energyRecord type:
software
Creator:
Suz
Host:
# kenya-wildlife-monitor
A Python application that monitors wildlife activity by reading the Bushtops YouTube
livestream from the Maasai Mara, Kenya. It detects animals using YOLOv8, generates
biodiversity events, and produces a data analysis report with insights for relevent stakeholders. Built as an IoT & Big Data course assignment.
---
## Requirements
- Python 3.9+
- ffmpeg (must be installed separately)
- Node.js (required by yt-dlp for YouTube bot detection)
Install ffmpeg on macOS:
```bash
brew install ffmpeg
```
---
## Installation
```bash
# 1. Clone the repository
git clone github.com
cd kenya-wildlife-monitor
# 2. Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows
# 3. Install dependencies
pip install -r requirements.txt
```
---
## Usage
### Live detection (headless)
```bash
caffeinate -i python -u main.py --headless
```
Runs continuously, reading frames from the Bushtops livestream every 10 seconds and writing detections to `data/observations.csv` and `data/events.csv`. Use `Ctrl+C` to stop. Data will be saved automatically to the related CSV files.
### Live detection (with display window)
```bash
python main.py
# or, to prevent interruptions during long runs:
caffeinate -i python -u main.py
```
Opens an OpenCV window showing the live frame with bounding boxes, animal names, and confidence levels. This is useful for verifying how the model is classifying animals in real time.
### Generate analysis report
```bash
python analysis.py --data data
```
Reads the collected CSVs and outputs:
- `data/hourly_summary.csv`
- `data/species_summary.csv`
- `data/report.html` — interactive dashboard with Chart.js charts
### Generate sample data (no live stream needed)
```bash
python generate_sample_data.py
```
Generates sample data to test that other components work correctly before connecting to the YouTub …