Scripts for working with the xeno-canto sound archive. https://spacecruft.org/deepcrayon/xeno-crufto

Python 100%

Find a file

Jeff Moe 8a7fa63f3c v3 usage noted		2025-05-31 12:12:50 -06:00
src/xeno_crufto	Update script for v3 API	2025-05-31 12:10:36 -06:00
.gitignore	Ignore more	2025-05-31 11:40:35 -06:00
LICENSE-APACHE	Apache 2.0	2023-09-27 11:15:09 -06:00
LICENSE-CC	CC by SA 4.0	2023-09-27 11:15:02 -06:00
pyproject.toml	Add dotenv dep	2025-05-31 12:09:48 -06:00
README.md	v3 usage noted	2025-05-31 12:12:50 -06:00

README.md

xeno-crufto

Scripts for working with the xeno-canto sound archive.

https://spacecruft.org/deepcrayon/xeno-crufto

Install

Install thusly.

Using Debian Stable (12/Bookworm).

Install thine dependencies:

sudo apt update
sudo apt install git python3-pip python3-virtualenv

Clone repo:

git clone https://spacecruft.org/deepcrayon/xeno-crufto
cd xeno-crufto/

Set up Python to taste, such as:

virtualenv env
source env/bin/activate
pip install --upgrade pip setuptools wheel
pip install -e .

Using jq isn't a requirement, but it is handy to have:

sudo apt install jq

Usage

Minimally working. Some queries work, such as:

$ xeno-crufto --cnt brazil

Help:

$ xeno-crufto --help
usage: xeno-crufto [-h] [--key KEY] [--query QUERY] [--animal-seen ANIMAL_SEEN] [--auto AUTO] [--cnt CNT] [--date DATE] [--dvc DVC] [--en EN] [--file FILE] [--file-name FILE_NAME] [--gen GEN] [--grp GRP] [--id ID] [--lat LAT]
                   [--lic LIC] [--lng LNG] [--loc LOC] [--method METHOD] [--mic MIC] [--playback-used PLAYBACK_USED] [--q Q] [--rec REC] [--regnr REGNR] [--rmk RMK] [--sex SEX] [--smp SMP] [--sp SP] [--ssp SSP] [--stage STAGE]
                   [--temp TEMP] [--time TIME] [--type TYPE] [--uploaded UPLOADED] [--url URL] [--dry-run]

Query the xeno-canto API

options:
  -h, --help            show this help message and exit
  --key KEY             Your xeno-canto API key (optional if in .env)
  --query QUERY         Search query
  --animal-seen ANIMAL_SEEN
                        Animal seen during recording
  --auto AUTO           Automatic (non-supervised) recording?
  --cnt CNT             Country where the recording was made
  --date DATE           Date that the recording was made
  --dvc DVC             Recording device used
  --en EN               English name of the species
  --file FILE           URL to the audio file
  --file-name FILE_NAME
                        Original file name of the audio file
  --gen GEN             Generic name of the species
  --grp GRP             Group to which the species belongs (birds, grasshoppers, bats)
  --id ID               Catalogue number of the recording on xeno-canto
  --lat LAT             Latitude of the recording in decimal coordinates
  --lic LIC             License URL of the recording
  --lng LNG             Longitude of the recording in decimal coordinates
  --loc LOC             Locality name
  --method METHOD       Recording method (field recording, in the hand, etc.)
  --mic MIC             Microphone used
  --playback-used PLAYBACK_USED
                        Was playback used to lure the animal?
  --q Q                 Current quality rating for the recording
  --rec REC             Name of the recordist
  --regnr REGNR         Registration number of specimen (when collected)
  --rmk RMK             Additional remarks by the recordist
  --sex SEX             Sex of the animal
  --smp SMP             Sample rate
  --sp SP               Specific name (epithet) of the species
  --ssp SSP             Subspecies name (subspecific epithet)
  --stage STAGE         Life stage of the animal (adult, juvenile, etc.)
  --temp TEMP           Temperature during recording (applicable to specific groups only)
  --time TIME           Time of day that the recording was made
  --type TYPE           Sound type of the recording
  --uploaded UPLOADED   Date that the recording was uploaded to xeno-canto
  --url URL             URL specifying the details of this recording
  --dry-run             Print the query URL without executing it

Creating a .env file with the contents of your xeno-canto API key, will allow you to run the script without having to specify the API key on the command line, such as:

KEY="abc123"

The older v2 version of the API is available using xeno-crufto2.

Development

To "develop", install the requirements:

pip install -e .[dev]

Then run black on the Python files for nice formatting:

black src/xeno_crufto/*.py

Upstream

The main upstream project.

https://xeno-canto.org

Other xeno-canto projects

The following projects are noted for further research. They all have libre licenses, are somewhat recently updated, and are in Python. Many xeno-canto software projects on Github have no licenses.

Unsupervised classification to improve the quality of a bird song. recording dataset.

https://github.com/ear-team/bambird

XenoPy: Python wrapper for Xeno-canto API 2.0. Supports multiprocessing.

https://github.com/realzza/xenopy

easybird: Python toolkit for Bird Activity Detection (BAD).

https://github.com/realzza/easybird

train bird song recognition with a xeno canto database.

https://github.com/ImeneYAHIAOUI/project_edge_ia

A Python wrapper for the Xeno Canto API.

https://github.com/NickEvans4130/xcpy

Python wrapper for the xeno-canto.org API to aid in downloading and managing recordings.

https://github.com/ntivirikin/xeno-canto-py

This python script automated downloading audio recordings of different bird calls.

https://github.com/arghyasahoo/Xeno-Canto-Downloader

A tool for getting xeno-canto bird calls and transforming them for use in TensorFlow.

https://github.com/AFairbairn/bioSong

Status

Alpha, initial development.

Disclaimer

I'm not a programmer and I know less about birds.

Copyright

Unofficial project, not related to xeno-canto.

Upstream sources under their respective copyrights.

License

Dual licensed under the Creative Commons Attribution-ShareAlike 4.0 International and the Apache 2.0 license. The content may be used under either license.