# BirdCount
A Python package for processing, analyzing, and counting bird calls from audio recordings.
## Features
- **Audio Cleaning**: Bandpass filtering, call detection, cropping, and spectral subtraction
- **Call Detection**: Adaptive threshold-based detection using MAD (Median Absolute Deviation)
- **Embedding Generation**: Integration with TensorFlow Hub Perch model for bird call embeddings
- **Clustering**: HDBSCAN clustering with UMAP visualization
- **PDF Reports**: Automatic generation of cleaning and clustering reports
- **Configurable**: YAML-based configuration for easy parameter tuning
## Installation
### Basic Installation
```bash
pip install birdcount
```
### With Machine Learning Dependencies
For embedding generation (requires TensorFlow):
```bash
pip install birdcount[ml]
```
### Development Installation
```bash
git clone https://github.com/seanwrowland/birdcount.git
cd birdcount
pip install -e .
```
## Google Colab
You can use BirdCount directly in Google Colab! Here's a quick example:
```python
# Install BirdCount
!pip install birdcount[ml]
# Download sample config files
!wget https://raw.githubusercontent.com/seanwrowland/birdcount/main/clean_config.yaml
!wget https://raw.githubusercontent.com/seanwrowland/birdcount/main/cluster_config.yaml
# Upload your audio files to Colab, then run:
!birdcount clean --config clean_config.yaml
!birdcount cluster --config cluster_config.yaml
```
## Quick Start
BirdCount provides two main commands for processing bird audio:
### 1. Clean Audio Files
First, clean and preprocess your audio files:
```bash
birdcount clean --config clean_config.yaml
```
This command:
- Applies bandpass filtering to isolate bird call frequencies
- Detects individual calls using adaptive thresholds
- Crops calls with padding
- Applies spectral subtraction for noise reduction
- Generates a cleaning report PDF showing the process
### 2. Cluster Audio Files
Then, cluster the cleaned audio files:
```bash
birdcount cluster --config cluster_config.yaml
```
This command:
- Generates embeddings using Google Perch model
- Performs HDBSCAN clustering
- Creates UMAP visualizations
- Generates a clustering report PDF organized by clusters
## Configuration
### Cleaning Configuration (`clean_config.yaml`)
```yaml
# Input and output directories
input_dir: "data/raw/birds"
output_dir: "outputs/cleaned"
# Bandpass filter settings
bandpass:
freq_min: 1500
freq_max: 7000
order: 6
# Call detection settings
detection:
mad_multiplier: 2.0
min_duration: 0.4
max_gap: 0.08
frame_length: 2048
hop_length: 512
# Cropping settings
cropping:
padding: 0.15
# Spectral subtraction settings
spectral_subtraction:
noise_duration: 0.1
noise_factor: 2.5
n_fft: 1024
hop_length: 256
# Report settings
report:
enabled: true
path: "outputs/cleaning_report.pdf"
# Logging settings
logging:
level: "INFO"
```
### Clustering Configuration (`cluster_config.yaml`)
```yaml
# Input and output directories
input_dir: "outputs/cleaned"
output_dir: "outputs/clustered"
# Embedding settings
embedding:
enabled: true
model_url: "https://www.kaggle.com/models/google/bird-vocalization-classifier/TensorFlow2/bird-vocalization-classifier/2"
sample_rate: 32000
target_duration: 5.0
# Clustering settings
clustering:
min_cluster_size: 3
min_samples: 2
metric: "euclidean"
umap_n_neighbors: 15
umap_min_dist: 0.1
# Report settings
report:
enabled: true
path: "outputs/cluster_report.pdf"
# Logging settings
logging:
level: "INFO"
```
## Output Structure
```
outputs/
├── cleaned/
│ ├── audio_file_1/
│ │ └── processed_calls/
│ │ ├── call_1.wav
│ │ ├── call_1_denoised.wav
│ │ ├── call_2.wav
│ │ └── call_2_denoised.wav
│ └── cleaning_report.pdf
└── clustered/
├── embeddings.pkl
├── cluster_results.pkl
└── cluster_report.pdf
```
## Reports
### Cleaning Report
The cleaning report (`cleaning_report.pdf`) includes:
- Before/after spectrograms for each file
- Call detection highlights
- Processing summary and statistics
- Configuration details
### Clustering Report
The clustering report (`cluster_report.pdf`) includes:
- UMAP visualization of clusters
- Cluster size statistics
- Spectrograms organized by cluster
- Summary of clustering results
## API Usage
```python
from birdcount import cleaning, clustering, config
# Load configuration
config_dict = config.load_config('clean_config.yaml')
# Run cleaning pipeline
cleaning.clean_audio_pipeline(config_dict)
# Run clustering pipeline
clustering.cluster_audio_pipeline(config_dict)
```
## Dependencies
### Core Dependencies
- numpy
- scipy
- librosa
- matplotlib
- seaborn
- hdbscan
- umap-learn
- scikit-learn
- pyyaml
- plotly
- pandas
- soundfile
- tqdm
### Optional ML Dependencies
- tensorflow
- tensorflow-hub
## Development
### Running Tests
```bash
pytest
```
### Code Formatting
```bash
black src/
flake8 src/
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
## Citation
If you use BirdCount in your research, please cite:
```bibtex
@software{rowland2025birdcount,
title={BirdCount: Bird call counting and analysis tool},
author={Rowland, Sean},
year={2025},
url={https://github.com/seanwrowland/birdcount}
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "birdcount",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "bird, audio, analysis, clustering, machine-learning, bioacoustics",
"author": null,
"author_email": "Sean Rowland <seanwrowland@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/26/c1/843d95d195aeb93e17eb62dcda94cbefe00f320d19f558e726cfd2eab539/birdcount-0.1.0.tar.gz",
"platform": null,
"description": "# BirdCount\n\nA Python package for processing, analyzing, and counting bird calls from audio recordings.\n\n## Features\n\n- **Audio Cleaning**: Bandpass filtering, call detection, cropping, and spectral subtraction\n- **Call Detection**: Adaptive threshold-based detection using MAD (Median Absolute Deviation)\n- **Embedding Generation**: Integration with TensorFlow Hub Perch model for bird call embeddings\n- **Clustering**: HDBSCAN clustering with UMAP visualization\n- **PDF Reports**: Automatic generation of cleaning and clustering reports\n- **Configurable**: YAML-based configuration for easy parameter tuning\n\n## Installation\n\n### Basic Installation\n\n```bash\npip install birdcount\n```\n\n### With Machine Learning Dependencies\n\nFor embedding generation (requires TensorFlow):\n\n```bash\npip install birdcount[ml]\n```\n\n### Development Installation\n\n```bash\ngit clone https://github.com/seanwrowland/birdcount.git\ncd birdcount\npip install -e .\n```\n\n## Google Colab\n\nYou can use BirdCount directly in Google Colab! Here's a quick example:\n\n```python\n# Install BirdCount\n!pip install birdcount[ml]\n\n# Download sample config files\n!wget https://raw.githubusercontent.com/seanwrowland/birdcount/main/clean_config.yaml\n!wget https://raw.githubusercontent.com/seanwrowland/birdcount/main/cluster_config.yaml\n\n# Upload your audio files to Colab, then run:\n!birdcount clean --config clean_config.yaml\n!birdcount cluster --config cluster_config.yaml\n```\n\n## Quick Start\n\nBirdCount provides two main commands for processing bird audio:\n\n### 1. Clean Audio Files\n\nFirst, clean and preprocess your audio files:\n\n```bash\nbirdcount clean --config clean_config.yaml\n```\n\nThis command:\n- Applies bandpass filtering to isolate bird call frequencies\n- Detects individual calls using adaptive thresholds\n- Crops calls with padding\n- Applies spectral subtraction for noise reduction\n- Generates a cleaning report PDF showing the process\n\n### 2. Cluster Audio Files\n\nThen, cluster the cleaned audio files:\n\n```bash\nbirdcount cluster --config cluster_config.yaml\n```\n\nThis command:\n- Generates embeddings using Google Perch model\n- Performs HDBSCAN clustering\n- Creates UMAP visualizations\n- Generates a clustering report PDF organized by clusters\n\n## Configuration\n\n### Cleaning Configuration (`clean_config.yaml`)\n\n```yaml\n# Input and output directories\ninput_dir: \"data/raw/birds\"\noutput_dir: \"outputs/cleaned\"\n\n# Bandpass filter settings\nbandpass:\n freq_min: 1500\n freq_max: 7000\n order: 6\n\n# Call detection settings\ndetection:\n mad_multiplier: 2.0\n min_duration: 0.4\n max_gap: 0.08\n frame_length: 2048\n hop_length: 512\n\n# Cropping settings\ncropping:\n padding: 0.15\n\n# Spectral subtraction settings\nspectral_subtraction:\n noise_duration: 0.1\n noise_factor: 2.5\n n_fft: 1024\n hop_length: 256\n\n# Report settings\nreport:\n enabled: true\n path: \"outputs/cleaning_report.pdf\"\n\n# Logging settings\nlogging:\n level: \"INFO\"\n```\n\n### Clustering Configuration (`cluster_config.yaml`)\n\n```yaml\n# Input and output directories\ninput_dir: \"outputs/cleaned\"\noutput_dir: \"outputs/clustered\"\n\n# Embedding settings\nembedding:\n enabled: true\n model_url: \"https://www.kaggle.com/models/google/bird-vocalization-classifier/TensorFlow2/bird-vocalization-classifier/2\"\n sample_rate: 32000\n target_duration: 5.0\n\n# Clustering settings\nclustering:\n min_cluster_size: 3\n min_samples: 2\n metric: \"euclidean\"\n umap_n_neighbors: 15\n umap_min_dist: 0.1\n\n# Report settings\nreport:\n enabled: true\n path: \"outputs/cluster_report.pdf\"\n\n# Logging settings\nlogging:\n level: \"INFO\"\n```\n\n## Output Structure\n\n```\noutputs/\n\u251c\u2500\u2500 cleaned/\n\u2502 \u251c\u2500\u2500 audio_file_1/\n\u2502 \u2502 \u2514\u2500\u2500 processed_calls/\n\u2502 \u2502 \u251c\u2500\u2500 call_1.wav\n\u2502 \u2502 \u251c\u2500\u2500 call_1_denoised.wav\n\u2502 \u2502 \u251c\u2500\u2500 call_2.wav\n\u2502 \u2502 \u2514\u2500\u2500 call_2_denoised.wav\n\u2502 \u2514\u2500\u2500 cleaning_report.pdf\n\u2514\u2500\u2500 clustered/\n \u251c\u2500\u2500 embeddings.pkl\n \u251c\u2500\u2500 cluster_results.pkl\n \u2514\u2500\u2500 cluster_report.pdf\n```\n\n## Reports\n\n### Cleaning Report\nThe cleaning report (`cleaning_report.pdf`) includes:\n- Before/after spectrograms for each file\n- Call detection highlights\n- Processing summary and statistics\n- Configuration details\n\n### Clustering Report\nThe clustering report (`cluster_report.pdf`) includes:\n- UMAP visualization of clusters\n- Cluster size statistics\n- Spectrograms organized by cluster\n- Summary of clustering results\n\n## API Usage\n\n```python\nfrom birdcount import cleaning, clustering, config\n\n# Load configuration\nconfig_dict = config.load_config('clean_config.yaml')\n\n# Run cleaning pipeline\ncleaning.clean_audio_pipeline(config_dict)\n\n# Run clustering pipeline\nclustering.cluster_audio_pipeline(config_dict)\n```\n\n## Dependencies\n\n### Core Dependencies\n- numpy\n- scipy\n- librosa\n- matplotlib\n- seaborn\n- hdbscan\n- umap-learn\n- scikit-learn\n- pyyaml\n- plotly\n- pandas\n- soundfile\n- tqdm\n\n### Optional ML Dependencies\n- tensorflow\n- tensorflow-hub\n\n## Development\n\n### Running Tests\n\n```bash\npytest\n```\n\n### Code Formatting\n\n```bash\nblack src/\nflake8 src/\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n## Citation\n\nIf you use BirdCount in your research, please cite:\n\n```bibtex\n@software{rowland2025birdcount,\n title={BirdCount: Bird call counting and analysis tool},\n author={Rowland, Sean},\n year={2025},\n url={https://github.com/seanwrowland/birdcount}\n}\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Bird call counting and analysis tool",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/seanwrowland/birdcount/issues",
"Documentation": "https://github.com/seanwrowland/birdcount#readme",
"Homepage": "https://github.com/seanwrowland/birdcount",
"Repository": "https://github.com/seanwrowland/birdcount"
},
"split_keywords": [
"bird",
" audio",
" analysis",
" clustering",
" machine-learning",
" bioacoustics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "eb1018268ea0b461ebcfce63db1824cfaa9061ac90e29909ca528f452640f160",
"md5": "f9decc02007548ecb896df8d6bd95b07",
"sha256": "d8db9e394f1daec96de62a6bed430767702b5c5930ba684a2fa0dfa82838ce88"
},
"downloads": -1,
"filename": "birdcount-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f9decc02007548ecb896df8d6bd95b07",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 18366,
"upload_time": "2025-09-02T00:35:59",
"upload_time_iso_8601": "2025-09-02T00:35:59.449544Z",
"url": "https://files.pythonhosted.org/packages/eb/10/18268ea0b461ebcfce63db1824cfaa9061ac90e29909ca528f452640f160/birdcount-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "26c1843d95d195aeb93e17eb62dcda94cbefe00f320d19f558e726cfd2eab539",
"md5": "4ef4ddd8e753e367d0f40bf9a87a24e0",
"sha256": "5202fef9fd8890d2b4b631e4d115cc6a33c4bf9dba7e4656389e6b3170719179"
},
"downloads": -1,
"filename": "birdcount-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "4ef4ddd8e753e367d0f40bf9a87a24e0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 18357,
"upload_time": "2025-09-02T00:36:00",
"upload_time_iso_8601": "2025-09-02T00:36:00.958777Z",
"url": "https://files.pythonhosted.org/packages/26/c1/843d95d195aeb93e17eb62dcda94cbefe00f320d19f558e726cfd2eab539/birdcount-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-02 00:36:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "seanwrowland",
"github_project": "birdcount",
"github_not_found": true,
"lcname": "birdcount"
}
JSON
