vogel-video-analyzer
Advanced tools
YOLOv26-based video analysis tool for automated bird content detection, quantification, and species identification
Languages: π¬π§ English | π©πͺ Deutsch | π―π΅ ζ₯ζ¬θͺ
YOLOv26-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 YOLOv26 object detection.
video.mp4 β video_annotated_YYYYMMDD_HHMMSS.mp4)ja_JP.utf8 and ja_JP.eucjp locales--language ja or VOGEL_LANG=ja environment variablevogel-issues for full issue lifecycle--engine hailo backend, no code changes needed--hef-model for specifying compiled HEF files--export-onnx converts .pt β .onnx for Hailo Dataflow CompilerLatest audit date: 2026-02-15
pillow version to 12.1.1See SECURITY.md for reporting and policy details.
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?
π Get Started with vogel-model-trainer β
# 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
pip install vogel-video-analyzer
# Install ffmpeg for audio preservation (Ubuntu/Debian)
sudo apt install ffmpeg
pip install vogel-video-analyzer
# Analyze a single video
vogel-analyze video.mp4
# Identify bird species
vogel-analyze --identify-species video.mp4
# Generate HTML report (v0.5.0+)
vogel-analyze --language en --identify-species --species-model kamera-linux/german-bird-classifier-v2 --species-threshold 0.80 --html-report report.html --sample-rate 15 --max-thumbnails 12 video.mp4
# View example: https://htmlpreview.github.io/?https://github.com/kamera-linux/vogel-video-analyzer/blob/main/examples/html_report_example.html
# 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-v2 \
--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.
# Combined outputs: JSON + HTML report
vogel-analyze --identify-species -o data.json --html-report report.html video.mp4
# 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
# Raspberry Pi AI HAT+ / Hailo-8 NPU (v0.5.12+)
# Install HailoRT driver first: sudo apt install hailo-all
# Then export and analyze:
vogel-analyze --export-onnx yolov8n.pt # export .pt β .onnx
# (compile .onnx β .hef with Hailo Dataflow Compiler on x86)
vogel-analyze --engine hailo --hef-model yolov8n.hef video.mp4
# 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
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
# 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).
The first time you run species identification, the model (~100-300MB) will be downloaded automatically and cached locally for future use.
π GPU Acceleration: Species identification automatically uses CUDA (NVIDIA GPU) if available, significantly speeding up inference. Falls back to CPU if no GPU is detected.
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 onlySee the Custom Model Training section for details on training your own model.
Create professionally annotated videos with bounding boxes, species labels, and custom styling:
# Basic annotation with automatic timestamped output
vogel-analyze --identify-species --annotate-video input.mp4
# Output: input_annotated_20251123_195542.mp4
# With multilingual labels and custom font size
vogel-analyze --identify-species \
--species-model kamera-linux/german-bird-classifier-v2 \
--multilingual \
--annotate-video \
--font-size 16 \
input.mp4
# With high-quality PNG flag icons (v0.4.2+)
vogel-analyze --identify-species \
--species-model kamera-linux/german-bird-classifier-v2 \
--multilingual \
--annotate-video \
--flag-dir assets/flags/ \
input.mp4
# With confidence threshold (only show birds >= 50%)
vogel-analyze --identify-species \
--species-threshold 0.5 \
--multilingual \
--annotate-video \
--font-size 18 \
input.mp4
# Batch processing multiple videos
vogel-analyze --identify-species \
--annotate-video \
--multilingual \
--font-size 16 \
*.mp4
# Creates: video1_annotated_20251123_195542.mp4, video2_annotated_20251123_195545.mp4, etc.
# Fast processing with sample rate
vogel-analyze --identify-species \
--sample-rate 30 \
--annotate-video \
--font-size 14 \
input.mp4
Features:
--font-size 12-24, default: 20)--species-threshold 0.0-1.0, default: 0.0)Label Display Format:
π¬π§ European Robin
π©πͺ Rotkehlchen
π―π΅ γ¨γΌγγγγ³γγγͺ
73%
Create compressed videos by skipping segments without bird activity:
# Basic summary with default settings
vogel-analyze --create-summary video.mp4
# Output: video_summary.mp4
# Custom thresholds
vogel-analyze --create-summary \
--skip-empty-seconds 5.0 \
--min-activity-duration 1.0 \
video.mp4
# Custom output path (single video only)
vogel-analyze --create-summary \
--summary-output custom_summary.mp4 \
video.mp4
# Batch processing multiple videos
vogel-analyze --create-summary *.mp4
# Creates: video1_summary.mp4, video2_summary.mp4, etc.
# Combine with faster processing
vogel-analyze --create-summary \
--sample-rate 10 \
video.mp4
Features:
--skip-empty-seconds (default: 3.0) - Minimum duration of bird-free segments to skip--min-activity-duration (default: 2.0) - Minimum duration of bird activity to keep<original>_summary.mp4How it works:
Example Output:
π Analyzing video for bird activity: video.mp4...
π Analyzing 18000 frames at 30.0 FPS...
β
Analysis complete - 1250 frames with birds detected
π Bird activity segments identified
π Segments to keep: 8
β±οΈ Original duration: 0:10:00
β±οΈ Summary duration: 0:02:45
π Compression: 72.5% shorter
π¬ Creating summary video: video_summary.mp4...
β
Summary video created successfully
π video_summary.mp4
Supported Languages:
Supported Birds (German Model):
All 8 birds from kamera-linux/german-bird-classifier-v2:
Performance Tips:
--sample-rate 30 for 4K videos (analyzes every 30th frame)--sample-rate 5-10 for HD videos (balance speed vs accuracy)Requirements:
# Install ffmpeg for audio preservation (Ubuntu/Debian)
sudo apt install ffmpeg
# 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
from vogel_video_analyzer import VideoAnalyzer
# Initialize analyzer (basic)
analyzer = VideoAnalyzer(
model_path="yolo26n.pt",
threshold=0.3
)
# Initialize analyzer with species identification
analyzer = VideoAnalyzer(
model_path="yolo26n.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
from vogel_video_analyzer import VideoAnalyzer
# Initialize analyzer
analyzer = VideoAnalyzer(
model_path="yolo26n.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'])}")
Automatically verify that recorded videos actually contain birds:
vogel-analyze --threshold 0.5 --delete-file recordings/**/*.mp4
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
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
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")
| Option | Description | Default | Values |
|---|---|---|---|
--model | YOLO model to use | yolo26n.pt | Any YOLO model |
--threshold | Bird detection confidence | 0.3 | 0.0 - 1.0 |
--sample-rate | Analyze every Nth frame | 5 | 1 - β |
--output | Save JSON report | - | File path |
--delete-file | Auto-delete 0% videos | False | Flag |
--delete-folder | Auto-delete 0% folders | False | Flag |
--log | Enable logging | False | Flag |
| Option | Description | Default | Values |
|---|---|---|---|
--identify-species | Enable species identification | False | Flag |
--species-model | Hugging Face model name | kamera-linux/german-bird-classifier-v2 | Model ID |
--species-threshold | Min confidence for species label | 0.0 | 0.0 - 1.0 |
--multilingual | Show names in EN/DE/JA | False | Flag |
| Option | Description | Default | Values |
|---|---|---|---|
--annotate-video | Create annotated video | False | Flag |
--font-size | Label text size | 20 | 12 - 32 |
--flag-dir | Custom flag images directory (v0.4.2+) | Auto-detect | Directory path |
--annotate-output | Custom output path | Auto-generated | File path |
| 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 | 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 |
The analyzer searches for YOLOv26 models in this order:
models/ directory (local)config/models/ directorybatch_size=8)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
}
]
}
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.
Problem with pre-trained models:
Benefits of custom models:
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
See the vogel-model-trainer documentation for:
Contributions are welcome! We appreciate bug reports, feature suggestions, documentation improvements, and code contributions.
Please read our Contributing Guide for details on:
For security vulnerabilities, please see our Security Policy.
This project is licensed under the MIT License - see the LICENSE file for details.
Made with β€οΈ by the Vogel-Kamera-Linux Team
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
The remediated findings include organization permission bugs, stale project access after transfers, OIDC replay edge cases, audit logging gaps, and an IDOR in API token deletion.
Research
/Security News
GitHub account BufferZoneCorp published sleeper packages that later added credential theft, GitHub Actions tampering, fake go wrappers, and SSH persistence.
Research
/Security News
Socket found a malicious Intercom PHP package on Packagist using Composer plugin execution to steal credentials and spread across ecosystems.