vogel-video-analyzer 0.3.0

YOLOv8-based video analysis tool for automated bird content detection, quantification, and species identification

🐦 Vogel Video Analyzer

Languages: 🇬🇧 English | 🇩🇪 Deutsch | 🇯🇵 日本語

YOLOv8-based video analysis tool for automated bird content detection and quantification.

A powerful command-line tool and Python library for analyzing videos to detect and quantify bird presence using state-of-the-art YOLOv8 object detection.

---

✨ Features

• 🤖 YOLOv8-powered Detection - Accurate bird detection using pre-trained models
• 🦜 Species Identification - Identify bird species using Hugging Face models (optional)
• 🎬 Video Annotation (v0.3.0+) - Create annotated videos with bounding boxes and species labels
  • Automatic output path generation (video.mp4 → video_annotated.mp4)
  • Multilingual species labels (English, German, Japanese)
  • High-contrast text display (34pt/38pt, black on white)
  • Audio preservation from original video
  • Flicker-free bounding boxes with detection caching
  • Batch processing support for multiple videos
• 🌍 Multilingual Support (v0.3.0+) - Bird names in English, German, and Japanese
  • 39 bird species with full translations
  • All 8 German model birds supported (kamera-linux/german-bird-classifier)
  • Display format: "EN: Hawfinch / DE: Kernbeißer / 75%"
• 📊 Detailed Statistics - Frame-by-frame analysis with bird content percentage
• 🎯 Segment Detection - Identifies continuous time periods with bird presence
• ⚡ Performance Optimized - Configurable sample rate for faster processing
• 📄 JSON Export - Structured reports for archival and further analysis
• 🗑️ Smart Auto-Delete - Remove video files or folders without bird content
• 📝 Logging Support - Structured logs for batch processing workflows
• 🌐 i18n Support - English, German, and Japanese interface translations
• 🐍 Library & CLI - Use as standalone tool or integrate into your Python projects

---

🎓 Want to Train Your Own Species Classifier?

Check out vogel-model-trainer to extract training data from your videos and build custom models for your local bird species!

Why train a custom model?

• Pre-trained models often misidentify European garden birds as exotic species
• Custom models achieve >90% accuracy for YOUR specific birds
• Train on YOUR camera setup and lighting conditions

👉 Get Started with vogel-model-trainer →

---

🚀 Quick Start

Installation

Recommended: Using Virtual Environment

# Install venv if needed (Debian/Ubuntu)
sudo apt install python3-venv

# Create virtual environment
python3 -m venv ~/venv-vogel

# Activate it
source ~/venv-vogel/bin/activate  # On Windows: ~/venv-vogel\Scripts\activate

# Install package (basic)
pip install vogel-video-analyzer

# Install with species identification support (optional)
pip install vogel-video-analyzer[species]

# Install ffmpeg for audio preservation (Ubuntu/Debian)
sudo apt install ffmpeg

Direct Installation

# Basic installation
pip install vogel-video-analyzer

# With species identification support
pip install vogel-video-analyzer[species]

Basic Usage

# Analyze a single video
vogel-analyze video.mp4

# Identify bird species
vogel-analyze --identify-species video.mp4

# Create annotated video (v0.3.0+)
vogel-analyze --identify-species --annotate-video video.mp4
# Output: video_annotated.mp4 (automatic)

# Create annotated video with multilingual labels
vogel-analyze --identify-species \
  --species-model kamera-linux/german-bird-classifier \
  --multilingual \
  --annotate-video \
  video.mp4

# Batch processing multiple videos
vogel-analyze --identify-species --annotate-video --multilingual *.mp4
# Creates: video1_annotated.mp4, video2_annotated.mp4, etc.

# Faster analysis (every 5th frame)
vogel-analyze --sample-rate 5 video.mp4

# Export to JSON
vogel-analyze --output report.json video.mp4

# Delete only video files with 0% bird content
vogel-analyze --delete-file *.mp4

# Delete entire folders with 0% bird content  
vogel-analyze --delete-folder ~/Videos/*/*.mp4

# Batch process directory
vogel-analyze ~/Videos/Birds/**/*.mp4

---

📖 Usage Examples

Command Line Interface

Basic Analysis

# Analyze single video with default settings
vogel-analyze bird_video.mp4

Output:

🎬 Video Analysis Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📁 File: /path/to/bird_video.mp4
📊 Total Frames: 450 (analyzed: 90)
⏱️  Duration: 15.0 seconds
🐦 Bird Frames: 72 (80.0%)
🎯 Bird Segments: 2

📍 Detected Segments:
  ┌ Segment 1: 00:00:02 - 00:00:08 (72% bird frames)
  └ Segment 2: 00:00:11 - 00:00:14 (89% bird frames)

✅ Status: Significant bird activity detected
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Species Identification (Optional)

# Identify bird species in video
vogel-analyze --identify-species bird_video.mp4

Output:

🎬 Video Analysis Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📁 File: /path/to/bird_video.mp4
📊 Total Frames: 450 (analyzed: 90)
⏱️  Duration: 15.0 seconds
🐦 Bird Frames: 72 (80.0%)
🎯 Bird Segments: 2

📍 Detected Segments:
  ┌ Segment 1: 00:00:02 - 00:00:08 (72% bird frames)
  └ Segment 2: 00:00:11 - 00:00:14 (89% bird frames)

✅ Status: Significant bird activity detected

🦜 Detected Species:
   3 species detected

  • Parus major (Great Tit)
    45 detections (avg confidence: 0.89)
  • Turdus merula (Blackbird)
    18 detections (avg confidence: 0.85)
  • Erithacus rubecula (European Robin)
    9 detections (avg confidence: 0.82)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚠️ Experimental Feature: Pre-trained models may misidentify European garden birds as exotic species. For accurate identification of local bird species, consider training a custom model (see Custom Model Training).

Installation:

pip install vogel-video-analyzer[species]

The first time you run species identification, the model (~100-300MB) will be downloaded automatically and cached locally for future use.

Using Custom Models

You can use locally trained models for better accuracy with your specific bird species:

# Use custom model
vogel-analyze --identify-species --species-model ~/vogel-models/my-model/ video.mp4

# With custom confidence threshold (default: 0.3)
vogel-analyze --identify-species \
  --species-model ~/vogel-models/my-model/ \
  --species-threshold 0.5 \
  video.mp4

Threshold Guidelines:

• 0.1-0.2 - Maximize detections (exploratory)
• 0.3-0.5 - Balanced (recommended)
• 0.6-0.9 - High confidence only

See the Custom Model Training section for details on training your own model.

Video Annotation (v0.3.0+)

Create annotated videos with bounding boxes and species labels:

# Basic annotation with automatic output path
vogel-analyze --identify-species --annotate-video input.mp4
# Output: input_annotated.mp4

# With multilingual labels (English + German)
vogel-analyze --identify-species \
  --species-model kamera-linux/german-bird-classifier \
  --multilingual \
  --annotate-video \
  input.mp4

# Custom output path (single video only)
vogel-analyze --identify-species \
  --annotate-video \
  --annotate-output custom_output.mp4 \
  input.mp4

# Batch processing multiple videos
vogel-analyze --identify-species \
  --annotate-video \
  --multilingual \
  *.mp4
# Creates: video1_annotated.mp4, video2_annotated.mp4, etc.

# Fast processing with sample rate
vogel-analyze --identify-species \
  --sample-rate 30 \
  --annotate-video \
  input.mp4

Features:

• 📦 Bounding boxes around detected birds (green, 3px width)
• 🏷️ Multilingual species labels (EN: Hawfinch / DE: Kernbeißer / 75%)
• 🎨 High-contrast text (34pt/38pt, black on white background)
• 📍 Smart positioning (text above bird, 10px gap to avoid covering)
• 🎵 Audio preservation (automatic ffmpeg merge from original video)
• ⚡ Flicker-free animation (detection caching)
• ⏱️ Real-time progress indicator
• 📊 Automatic path generation (saves in same directory as original)

Multilingual Display Format:

EN: Hawfinch
DE: Kernbeißer
75%

Supported Languages:

• 🇬🇧 English (primary)
• 🇩🇪 German (full support, 39 species)
• 🇯🇵 Japanese (39 species, database only)

Supported Birds (German Model): All 8 birds from kamera-linux/german-bird-classifier:

• Blaumeise (Blue Tit)
• Grünling (European Greenfinch)
• Haussperling (House Sparrow)
• Kernbeißer (Hawfinch)
• Kleiber (Eurasian Nuthatch)
• Kohlmeise (Parus Major)
• Rotkehlchen (European Robin)
• Sumpfmeise (Marsh Tit)

Performance Tips:

• Use --sample-rate 30 for 4K videos (analyzes every 30th frame)
• Use --sample-rate 5-10 for HD videos (balance speed vs accuracy)
• Lower sample rates = more detections but slower processing
• Audio is automatically preserved from original video
• Output maintains original resolution and framerate

Requirements:

# Install species extras for multilingual support
pip install vogel-video-analyzer[species]

# Install ffmpeg for audio preservation (Ubuntu/Debian)
sudo apt install ffmpeg

Advanced Options

# Custom threshold and sample rate
vogel-analyze --threshold 0.4 --sample-rate 10 video.mp4

# Species identification with confidence tuning
vogel-analyze --identify-species --species-threshold 0.4 video.mp4
vogel-analyze --identify-species --sample-rate 10 video.mp4

# Set output language (en/de/ja, auto-detected by default)
vogel-analyze --language de video.mp4

# Delete only video files with 0% bird content
vogel-analyze --delete-file --sample-rate 5 *.mp4

# Delete entire folders with 0% bird content
vogel-analyze --delete-folder --sample-rate 5 ~/Videos/*/*.mp4

# Save JSON report and log
vogel-analyze --output report.json --log video.mp4

Python Library

from vogel_video_analyzer import VideoAnalyzer

# Initialize analyzer (basic)
analyzer = VideoAnalyzer(
    model_path="yolov8n.pt",
    threshold=0.3
)

# Initialize analyzer with species identification
analyzer = VideoAnalyzer(
    model_path="yolov8n.pt",
    threshold=0.3,
    identify_species=True
)

# Analyze video

#### Advanced Options
```bash
# Custom threshold and sample rate
vogel-analyze --threshold 0.4 --sample-rate 10 video.mp4

# Set output language (en/de, auto-detected by default)
vogel-analyze --language de video.mp4

# Delete only video files with 0% bird content
vogel-analyze --delete-file --sample-rate 5 *.mp4

# Delete entire folders with 0% bird content
vogel-analyze --delete-folder --sample-rate 5 ~/Videos/*/*.mp4

# Save JSON report and log
vogel-analyze --output report.json --log video.mp4

Python Library

from vogel_video_analyzer import VideoAnalyzer

# Initialize analyzer
analyzer = VideoAnalyzer(
    model_path="yolov8n.pt",
    threshold=0.3
)

# Analyze video
stats = analyzer.analyze_video("bird_video.mp4", sample_rate=5)

# Print formatted report
analyzer.print_report(stats)

# Access statistics
print(f"Bird content: {stats['bird_percentage']:.1f}%")
print(f"Segments found: {len(stats['bird_segments'])}")

---

🎯 Use Cases

1. Quality Control for Bird Recordings

Automatically verify that recorded videos actually contain birds:

vogel-analyze --threshold 0.5 --delete-file recordings/**/*.mp4

2. Archive Management

Identify and remove videos without bird content to save storage:

# Find videos with 0% bird content
vogel-analyze --output stats.json archive/**/*.mp4

# Delete empty video files only
vogel-analyze --delete-file archive/**/*.mp4

# Delete entire folders with 0% bird content
vogel-analyze --delete-folder archive/**/*.mp4

3. Batch Analysis for Research

Process large video collections and generate structured reports:

# Analyze all videos and save individual reports
for video in research_data/**/*.mp4; do
    vogel-analyze --sample-rate 10 --output "${video%.mp4}_report.json" "$video"
done

4. Integration in Automation Workflows

Use as part of automated recording pipelines:

from vogel_video_analyzer import VideoAnalyzer

analyzer = VideoAnalyzer(threshold=0.3)
stats = analyzer.analyze_video("latest_recording.mp4", sample_rate=5)

# Only keep videos with significant bird content
if stats['bird_percentage'] < 10:
    print("Insufficient bird content, deleting...")
    # Handle deletion
else:
    print(f"✅ Quality video: {stats['bird_percentage']:.1f}% bird content")

---

⚙️ Configuration Options

Option	Description	Default	Values
--model	YOLO model to use	yolov8n.pt	Any YOLO model
--threshold	Confidence threshold	0.3	0.0 - 1.0
--sample-rate	Analyze every Nth frame	5	1 - ∞
--output	Save JSON report	-	File path
--delete	Auto-delete 0% videos	False	Flag
--log	Enable logging	False	Flag

Sample Rate Recommendations

Video FPS	Sample Rate	Frames Analyzed	Performance
30 fps	1	100% (all frames)	Slow, highest precision
30 fps	5	20%	⭐ Recommended - Good balance
30 fps	10	10%	Fast, sufficient
30 fps	20	5%	Very fast, basic check

Threshold Values

Threshold	Description	Use Case
0.2	Very sensitive	Detects distant/partially obscured birds
0.3	Standard	Balanced detection
0.5	Conservative	Only clearly visible birds
0.7	Very strict	Only perfect detections

---

🔍 Technical Details

Model Search Hierarchy

The analyzer searches for YOLOv8 models in this order:

1. models/ directory (local)
2. config/models/ directory
3. Current directory
4. Auto-download from Ultralytics (fallback)

Detection Algorithm

• Target Class: Bird (COCO class 14)
• Inference: Frame-by-frame YOLOv8 detection
• Segment Detection: Groups consecutive bird frames with max 2-second gaps
• Performance: ~5x speedup with sample-rate=5 on 30fps videos

Output Format

JSON reports include:

{
  "video_file": "bird_video.mp4",
  "duration_seconds": 15.0,
  "total_frames": 450,
  "frames_analyzed": 90,
  "bird_percentage": 80.0,
  "bird_segments": [
    {
      "start": 2.0,
      "end": 8.0,
      "detections": 36
    }
  ]
}

---

🎓 Custom Model Training

Pre-trained bird species classifiers are trained on global datasets and often misidentify European garden birds as exotic species. For better accuracy with your specific bird species, you can train a custom model.

Why Train a Custom Model?

Problem with pre-trained models:

• Identify common European birds (Kohlmeise, Blaumeise) as exotic Asian pheasants
• Low confidence scores (often <0.1)
• Trained on datasets dominated by American and exotic birds

Benefits of custom models:

• High accuracy for YOUR specific bird species
• Trained on YOUR camera setup and lighting conditions
• Confidence scores >0.9 for correctly identified birds

Quick Start

The training tools are now available as a standalone package: vogel-model-trainer

1. Install the training package:

pip install vogel-model-trainer

2. Extract bird images from your videos:

vogel-trainer extract ~/Videos/kohlmeise.mp4 \
  --folder ~/vogel-training-data/ \
  --bird kohlmeise \
  --sample-rate 3

3. Organize dataset (80/20 train/val split):

vogel-trainer organize \
  --source ~/vogel-training-data/ \
  --output ~/vogel-training-data/organized/

4. Train the model (requires ~3-4 hours on Raspberry Pi 5):

vogel-trainer train

5. Use your trained model:

vogel-analyze --identify-species \
  --species-model ~/vogel-models/bird-classifier-*/final/ \
  video.mp4

Recommended Dataset Size

• Minimum: 30-50 images per bird species
• Optimal: 100+ images per bird species
• Balance: Similar number of images for each species

Complete Documentation

See the vogel-model-trainer documentation for:

• Complete training workflow
• Iterative training for better accuracy
• Advanced usage and troubleshooting
• Performance tips and best practices

---

📚 Documentation

• GitHub Repository: vogel-video-analyzer
• Parent Project: vogel-kamera-linux
• Issue Tracker: GitHub Issues

---

🤝 Contributing

Contributions are welcome! We appreciate bug reports, feature suggestions, documentation improvements, and code contributions.

Please read our Contributing Guide for details on:

• How to set up your development environment
• Our code style and guidelines
• The pull request process
• How to report bugs and suggest features

For security vulnerabilities, please see our Security Policy.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Ultralytics YOLOv8 - Powerful object detection framework
• OpenCV - Computer vision library
• Vogel-Kamera-Linux - Parent project for automated bird observation

---

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ by the Vogel-Kamera-Linux Team