Package: xeno-canto
xeno-canto API Wrapperxeno-canto-py is an API wrapper designed to help users download xeno-canto.org recordings and associated information in an efficient manner. Download requests are processed concurrently using theasyncio,aiohttpandaiofileslibraries to optimize retrieval time. The wrapper also offers delete and metadata generation functions for recording library management.Created to aid in data collection and filtering for the training of machine learning models.Installationxeno-canto-py is available onPyPiand can be downloaded with the package managerpipto install xeno-canto-py.pipinstallxeno-cantoThe package can then be used straight from the command-line:xeno-canto-dlBeardedBellbirdOr imported into an existing Python project:importxenocantoFor users who want more control over the wrapper, navigate to your desired file location in a terminal window and then clone the repository with the following command:gitclonehttps://github.com/ntivirikin/xeno-canto-pyThe only file required for operation isxenocanto.py, so feel free to remove the others or movexenocanto.pyto another working directory.WARNING:Please exercise caution usingtest.pyas executing the tests viaunittestor other test harness will delete anydatasetfolder in the working directory following completion of the tests.UsageThe xeno-canto-py wrapper supports the retrieval of metadata and audio from the xeno-canto database, as well as library management functions such as deletion of recordings matching input tags, removal of folders with an insufficient amount of audio recordings and generation of a single JSON metadata file for a given path containing xeno-canto audio recordings. Examples of command usage are given below.Metadata Downloadxeno-canto -m [parameters]Downloads metadata as a series of JSON files and returns the path to the metadata folder.Example: Metadata retrieval for Bearded Bellbird recordings of quality Axeno-canto -m Bearded Bellbird q:AAudio Recording Downloadxeno-canto -dl [parameters]Retrieves the metadata for the request and uses it to download audio recordings as MP3s from the database.Example: Download Bearded Bellbird recordings from the country of Brazilxeno-canto -dl Bearded Bellbird cnt:BrazilDelete Recordingsxeno-canto -del [parameters]Delete recordings withANYof the parameters given as input.Example: DeleteALLquality D recordings andALLrecordings from Brazilxeno-canto -del q:D cnt:BrazilPurge FoldersRemoves any folders within thedataset/audio/directory that have less recordings than the input valuenum.xeno-canto -p [num]Example: Remove recording folders with less than 10 recordings (not inclusive)xeno-canto -p 10Generate MetadataGenerates metadata for the xeno-canto database recordings at the input path, defaulting todataset/audio/within the working directory if none is given.xeno-canto -g [path]Example: Generate metadata for the recordings located inbird_rec/audio/within the working directoryxeno-canto -g bird_rec/audio/parametersare given in tag:value form in accordance with the API search guidelines. For help in building search terms, consult thexeno-canto API guideand thisarticle. The only exception is when providing English bird names as an argument to the delete function, which must be preceded withen:and have all spaces be replaced with underscores.Directory StructureFiles are saved in the working directory under the folderdataset/. Metadata and audio recordings are separated intometadata/andaudio/folders by request information and bird species respectively. For example:dataset/
    - audio/
        - Indigo Bunting/
            - 14325.mp3
        - Northern Cardinal/
            - 8273.mp3
    - metadata/
        - library.json
        - IndigoBuntingcnt_Canada/
            - page1.json
        - NorthernCardinalq_A/
            - page1.jsonMetadata is retrieved as a JSON file and contains information on each of the audio recordings matching the request parameters provided as input. The metadata also contains the download links used to retrieve the audio recordings. Thelibrary.jsonfile is generated by running the metadata generation command-g.Error 503If an Error 503 is given when attempting a recording download, try passing a value lower than 4 as the num_chunks value in download(filt, num_chunks). This can either be done by changing the default value in the function definition fordownload(filt, num_chunks), or by passing a value intodownload(params)in the body ofmain()as shown below.# Running with default 4 locks on semaphoreasyncio.run(download(params))# Running with 3 locks rather than defaultasyncio.run(download(params,3))Alternatively, you can try experimenting with higher values for num_chunks to see some performance improvements.ContributingAll pull requests are welcome! If any issues are found, please do not hesitate to bring them to my attention.AcknowledgementsThank you to the team at xeno-canto.org and all its contributors for putting together such an amazing database.LicenseMIT