xeno-crufto/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
```

Install Python dependencies.

```
pip install -r requirements.txt
```

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 -h
usage: xeno-crufto [-h] [--api API] [--dry-run | --no-dry-run] [--query QUERY]
                   [--animal-seen {yes,no,unknown}] [--auto {yes,no,unknown}]
                   [--cnt CNT] [--date DATE] [--dvc DVC] [--en EN]
                   [--file FILE] [--file-name FILE_NAME] [--gen GEN]
                   [--group {bats,birds,grasshoppers}] [--id ID] [--lat LAT]
                   [--lng LNG] [--loc LOC] [--method METHOD] [--mic MIC]
                   [--playback-used {yes,no,unknown}] [--q Q] [--rec REC]
                   [--regnr REGNR] [--rmk RMK] [--sex {female,male,unknown}]
                   [--smp SMP] [--sp SP] [--ssp SSP]
                   [--stage {adult,juvenile,nesting,nymph,subadult,unknown}]
                   [--temperature TEMPERATURE]
                   [--type {aberrant,"alarm call","begging call",call,"calling song","courtship song","dawn song","distress call","distrubance song",drumming,duet,echolocation,"female song","flight call","flight song",imitation,"nocturnal flight call","rivalry song","searching song","social call",song,subsong,unknown}]
                   [--uploaded UPLOADED]

options:
  -h, --help            show this help message and exit
  --api API             API URL (default https://xeno-
                        canto.org/api/2/recordings)
  --dry-run, --no-dry-run
                        Print URI but don't run query (default False)
  --query QUERY         Arbitrary query string (default None)
  --animal-seen {yes,no,unknown}
                        was the recorded animal seen?
  --auto {yes,no,unknown}
                        (non-supervised) recording?
  --cnt CNT             the country where the recording was made (example:
                        brazil)
  --date DATE           the date that the recording was made (example:
                        2022-09-18)
  --dvc DVC             recording device used (example: "Panasonic RR-US300")
  --en EN               the English name of the species (example: "Great
                        Tinamou")
  --file FILE           the URL to the audio file (example: https://xeno-
                        canto.org/770944/download)
  --file-name FILE_NAME
                        the original file name of the audio file (example:
                        "XC483178-Tinamus tao_Rio Azul_1032.mp3")
  --gen GEN             the generic name of the species (example: "Rhea")
  --group {bats,birds,grasshoppers}
                        the group to which the species belongs
  --id ID               the catalogue number of the recording on xeno-canto
                        (example: 830675)
  --lat LAT             the latitude of the recording in decimal coordinates
                        (example: -26.7144)
  --lng LNG             the longitude of the recording in decimal coordinates
                        (example: -67.7537)
  --loc LOC             the name of the locality (example "Araponga, Minas
                        Gerais")
  --method METHOD       the recording method (example: "field recording")
  --mic MIC             microphone used (example: "Telinga + AT4022")
  --playback-used {yes,no,unknown}
                        was playback used to lure the animal?
  --q Q                 the current quality rating for the recording (Letters
                        A to E. Prepend > or < for better or worse than.
                        Example: ">C" for A and B.)
  --rec REC             the name of the recordist (example: "Jeff Moe")
  --regnr REGNR         registration number of specimen (when collected)
  --rmk RMK             additional remarks by the recordist
  --sex {female,male,unknown}
                        the sex of the animal
  --smp SMP             sample rate (example: 48000)
  --sp SP               the specific name (epithet) of the species (example:
                        obsoletus)
  --ssp SSP             the subspecies name (subspecific epithet) (example:
                        americana)
  --stage {adult,juvenile,nesting,nymph,subadult,unknown}
                        the life stage of the animal
  --temperature TEMPERATURE
                        temperature during recording (applicable to specific
                        groups only)
  --type {aberrant,"alarm call","begging call",call,"calling song","courtship song","dawn song","distress call","distrubance song",drumming,duet,echolocation,"female song","flight call","flight song",imitation,"nocturnal flight call","rivalry song","searching song","social call",song,subsong,unknown}
                        the sound type of the recording
  --uploaded UPLOADED   the date that the recording was uploaded to xeno-canto
                        (example: 2022-03-02)
```


# Development
To "develop", install the requirements:

```
pip install -r requirements-dev.txt
```

Then run black on the Python files for nice formatting:

```
black xeno-crufto*
```


# 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.

*Copyright &copy; 2023, Jeff Moe.*