### Basic command-line download

Source: https://github.com/ntivirikin/xeno-canto-py/blob/master/README.md

Use the xeno-canto command-line interface to download recordings for a specific bird species. This is a quick way to get started with downloading audio.

```bash
xeno-canto -dl Bearded Bellbird
```

--------------------------------

### Install xeno-canto-py using pip

Source: https://github.com/ntivirikin/xeno-canto-py/blob/master/README.md

Install the xeno-canto-py package using pip. This is the standard method for adding the library to your Python environment.

```bash
pip install xeno-canto
```

--------------------------------

### Download Metadata via CLI

Source: https://context7.com/ntivirikin/xeno-canto-py/llms.txt

Retrieve metadata for recordings matching specific search queries.

```bash
# Download metadata for Bearded Bellbird recordings of quality A
xeno-canto -m Bearded Bellbird q:A

# Download metadata for Northern Cardinal recordings from Canada
xeno-canto -m Northern Cardinal cnt:Canada

# Download metadata for a specific genus
xeno-canto -m gen:Otis
```

--------------------------------

### Generate Library Metadata via CLI

Source: https://context7.com/ntivirikin/xeno-canto-py/llms.txt

Create a consolidated library.json file for local recordings.

```bash
# Generate metadata for default path (dataset/audio/)
xeno-canto -g

# Generate metadata for custom path
xeno-canto -g bird_rec/audio/
```

--------------------------------

### Run Download with Default Semaphore Locks

Source: https://github.com/ntivirikin/xeno-canto-py/blob/master/README.md

Execute the download function using the default number of semaphore locks.

```python
asyncio.run(download(params))
```

--------------------------------

### Download metadata using command-line

Source: https://github.com/ntivirikin/xeno-canto-py/blob/master/README.md

Download metadata for specified recordings using the '-m' flag. This command retrieves JSON files containing recording information and download links.

```bash
xeno-canto -m Bearded Bellbird q:A
```

--------------------------------

### Generate metadata file using command-line

Source: https://github.com/ntivirikin/xeno-canto-py/blob/master/README.md

Generate a single JSON metadata file for all xeno-canto recordings located in a specified directory using the '-g' flag. Defaults to 'dataset/audio/' if no path is provided.

```bash
xeno-canto -g bird_rec/audio/
```

--------------------------------

### Download audio recordings using command-line

Source: https://github.com/ntivirikin/xeno-canto-py/blob/master/README.md

Download audio recordings as MP3 files using the '-dl' flag. This command first retrieves metadata and then downloads the corresponding audio files.

```bash
xeno-canto -dl Bearded Bellbird cnt:Brazil
```

--------------------------------

### Run Download with Custom Semaphore Locks

Source: https://github.com/ntivirikin/xeno-canto-py/blob/master/README.md

Execute the download function with a specified number of semaphore locks, overriding the default.

```python
asyncio.run(download(params, 3))
```

--------------------------------

### Apply API query parameters

Source: https://context7.com/ntivirikin/xeno-canto-py/llms.txt

Demonstrates filtering downloads and metadata by quality, geography, genus, or specific recording numbers.

```python
import asyncio
import xenocanto

# Quality filter (A, B, C, D, E)
asyncio.run(xenocanto.download(['Bearded Bellbird', 'q:A']))

# Country filter
asyncio.run(xenocanto.download(['Northern Cardinal', 'cnt:United States']))

# Genus filter
asyncio.run(xenocanto.download(['gen:Otis']))

# Recording number filter
meta_path = xenocanto.metadata(['nr:459281'])

# Multiple filters combined
asyncio.run(xenocanto.download(['Indigo Bunting', 'q:A', 'cnt:Canada']))

# Combine species name with multiple quality levels
asyncio.run(xenocanto.download(['Bearded Bellbird', 'q:A', 'q:B']))
```

--------------------------------

### Download Audio Recordings via CLI

Source: https://context7.com/ntivirikin/xeno-canto-py/llms.txt

Retrieve and download audio files based on search criteria.

```bash
# Download Bearded Bellbird recordings from Brazil
xeno-canto -dl Bearded Bellbird cnt:Brazil

# Download all recordings of quality A for Indigo Bunting
xeno-canto -dl Indigo Bunting q:A

# Download recordings by genus
xeno-canto -dl gen:Otis
```

--------------------------------

### Python API: download(filt, num_chunks=4)

Source: https://context7.com/ntivirikin/xeno-canto-py/llms.txt

Asynchronously downloads audio recordings matching the search filter using concurrent HTTP requests.

```APIDOC
## download(filt, num_chunks=4)

### Description
Asynchronously downloads audio recordings matching the search filter. Uses concurrent HTTP requests controlled by a semaphore.

### Parameters
- **filt** (list) - Required - A list of strings representing the search query parameters.
- **num_chunks** (int) - Optional - The number of concurrent connections to use for downloading. Defaults to 4.

### Request Example
```python
import asyncio
import xenocanto
asyncio.run(xenocanto.download(['gen:Otis'], num_chunks=4))
```
```

--------------------------------

### Generate library metadata

Source: https://context7.com/ntivirikin/xeno-canto-py/llms.txt

Creates a consolidated library.json file for recordings located at a specified path.

```python
import xenocanto

# Generate metadata for default audio library path
xenocanto.gen_meta()

# Generate metadata for custom path
xenocanto.gen_meta('my_recordings/audio/')

# Generate metadata after downloading recordings
import asyncio
asyncio.run(xenocanto.download(['Bearded Bellbird', 'q:A']))
xenocanto.gen_meta()
# Creates: dataset/metadata/library.json
```

--------------------------------

### Download Audio via Python API

Source: https://context7.com/ntivirikin/xeno-canto-py/llms.txt

Asynchronously download audio files using the download function.

```python
import asyncio
import xenocanto

# Download all recordings for a genus (uses default 4 concurrent connections)
asyncio.run(xenocanto.download(['gen:Otis']))

# Download Bearded Bellbird recordings from Brazil with quality A
asyncio.run(xenocanto.download(['Bearded Bellbird', 'q:A', 'cnt:Brazil']))

# Use fewer concurrent connections if receiving Error 503
asyncio.run(xenocanto.download(['Indigo Bunting'], num_chunks=2))

# Use more concurrent connections for faster downloads (may cause rate limiting)
asyncio.run(xenocanto.download(['Northern Cardinal'], num_chunks=8))
```

--------------------------------

### List URLs

Source: https://context7.com/ntivirikin/xeno-canto-py/llms.txt

Parses metadata JSON files and returns a list of recording information.

```APIDOC
## List URLs

### Description
Parses metadata JSON files and returns a list containing the number of recordings and tuples of track information (name, id, url, format).

### Method
`GET` (Conceptual - this is a library function, not a direct HTTP call)

### Endpoint
N/A (Library function)

### Parameters
- `path` (string) - Required - The path to the metadata JSON file(s) generated by `gen_meta` or `metadata`.

### Request Example
```python
import xenocanto

# First download metadata (example using genus filter)
meta_path = xenocanto.metadata(['gen:Otis'])

# Parse URLs from metadata
url_list = xenocanto.list_urls(meta_path)
num_recordings = url_list[0]
track_tuples = url_list[1]

print(f"Found {num_recordings} recordings")
for name, track_id, url, fmt in track_tuples[:3]:
    print(f"  {name} - {track_id}{fmt}: {url}")

# Output:
# Found 15 recordings
#   GreatBustard - 459281.mp3: //xeno-canto.org/459281/download
#   GreatBustard - 459282.mp3: //xeno-canto.org/459282/download
#   ...
```

### Response
- `list` - A list containing:
  - `int`: The total number of recordings found.
  - `list` of `tuple`: Each tuple contains (name, id, url, format) for a recording.
```

--------------------------------

### Import xeno-canto library in Python

Source: https://github.com/ntivirikin/xeno-canto-py/blob/master/README.md

Import the xeno-canto library into your Python project to use its functionalities programmatically. This allows for more complex integration and control.

```python
import xenocanto
```

--------------------------------

### Clone xeno-canto-py repository

Source: https://github.com/ntivirikin/xeno-canto-py/blob/master/README.md

Clone the xeno-canto-py repository from GitHub to access the source code directly. This is useful for users who want to modify or contribute to the library.

```bash
git clone https://github.com/ntivirikin/xeno-canto-py
```

--------------------------------

### Purge recording folders using command-line

Source: https://github.com/ntivirikin/xeno-canto-py/blob/master/README.md

Remove folders from the 'dataset/audio/' directory that contain fewer recordings than the specified number using the '-p' flag. This helps manage storage space.

```bash
xeno-canto -p 10
```

--------------------------------

### Retrieve Metadata via Python API

Source: https://context7.com/ntivirikin/xeno-canto-py/llms.txt

Fetch and save metadata as paginated JSON files using the metadata function.

```python
import xenocanto

# Download metadata for Bearded Bellbird recordings of quality A
# Returns the path to the folder containing the JSON metadata files
meta_path = xenocanto.metadata(['Bearded Bellbird', 'q:A'])
print(meta_path)  # Output: dataset/metadata/BeardedBellbirdq_A

# Download metadata for a specific genus
meta_path = xenocanto.metadata(['gen:Otis'])
print(meta_path)  # Output: dataset/metadata/gen_Otis

# Download metadata for recordings from a specific country
meta_path = xenocanto.metadata(['Northern Cardinal', 'cnt:Canada'])
print(meta_path)  # Output: dataset/metadata/NorthernCardinalcnt_Canada
```

--------------------------------

### Generate Metadata

Source: https://context7.com/ntivirikin/xeno-canto-py/llms.txt

Generates a consolidated `library.json` metadata file for all recordings at a specified path.

```APIDOC
## Generate Metadata

### Description
Generates a consolidated `library.json` metadata file containing information for all recordings at the specified path.

### Method
`POST` (Conceptual - this is a library function, not a direct HTTP call)

### Endpoint
N/A (Library function)

### Parameters
- `path` (string) - Optional - The directory path where audio recordings are stored. Defaults to 'dataset/audio/'.

### Request Example
```python
import xenocanto
import asyncio

# Generate metadata for default audio library path
xenocanto.gen_meta()

# Generate metadata for custom path
xenocanto.gen_meta('my_recordings/audio/')

# Generate metadata after downloading recordings
asyncio.run(xenocanto.download(['Bearded Bellbird', 'q:A']))
xenocanto.gen_meta()
# Creates: dataset/metadata/library.json
```

### Response
- `library.json` (file) - A JSON file containing metadata for all recordings.

### Response Example
(Content of dataset/metadata/library.json - example structure)
```json
{
  "recordings": [
    {
      "id": "493159",
      "species": "Bearded Bellbird",
      "url": "//xeno-canto.org/493159/download",
      "format": ".mp3"
    }
    // ... more recordings
  ]
}
```
```

--------------------------------

### Download Recordings

Source: https://context7.com/ntivirikin/xeno-canto-py/llms.txt

Downloads bird sound recordings from xeno-canto.org based on specified search parameters.

```APIDOC
## Download Recordings

### Description
Downloads bird sound recordings from xeno-canto.org based on specified search parameters. Handles pagination and concurrent downloads.

### Method
`GET` (Conceptual - this is a library function, not a direct HTTP call)

### Endpoint
N/A (Library function)

### Parameters
- `search_params` (list of strings) - Required - A list of search parameters in `tag:value` format. Common tags include:
  - `species name` (string) - e.g., 'Bearded Bellbird'
  - `q` (string) - Quality filter (A, B, C, D, E). e.g., 'q:A'
  - `cnt` (string) - Country filter. e.g., 'cnt:United States'
  - `gen` (string) - Genus filter. e.g., 'gen:Otis'
  - `nr` (string) - Recording number filter. e.g., 'nr:459281'

### Request Example
```python
import asyncio
import xenocanto

# Quality filter (A, B, C, D, E)
asyncio.run(xenocanto.download(['Bearded Bellbird', 'q:A']))

# Country filter
asyncio.run(xenocanto.download(['Northern Cardinal', 'cnt:United States']))

# Genus filter
asyncio.run(xenocanto.download(['gen:Otis']))

# Recording number filter
xenocanto.metadata(['nr:459281']) # Note: This example uses metadata, but download can also use 'nr'

# Multiple filters combined
asyncio.run(xenocanto.download(['Indigo Bunting', 'q:A', 'cnt:Canada']))

# Combine species name with multiple quality levels
asyncio.run(xenocanto.download(['Bearded Bellbird', 'q:A', 'q:B']))
```

### Response
N/A (Library function, downloads files to local storage. No direct HTTP response.)
```

--------------------------------

### Python API: purge(num)

Source: https://context7.com/ntivirikin/xeno-canto-py/llms.txt

Removes audio folders containing fewer than the specified number of recordings.

```APIDOC
## purge(num)

### Description
Removes audio folders containing fewer than the specified number of recordings.

### Parameters
- **num** (int) - Required - The minimum threshold of recordings required to keep a folder.

### Request Example
```python
import xenocanto
xenocanto.purge(10)
```
```

--------------------------------

### Purge Folders via CLI

Source: https://context7.com/ntivirikin/xeno-canto-py/llms.txt

Remove species folders that do not meet the minimum recording count.

```bash
# Remove folders with fewer than 10 recordings
xeno-canto -p 10

# Remove folders with fewer than 50 recordings
xeno-canto -p 50
```

--------------------------------

### Delete recordings using command-line

Source: https://github.com/ntivirikin/xeno-canto-py/blob/master/README.md

Delete recordings that match any of the provided parameters using the '-del' flag. This is useful for cleaning up local audio libraries.

```bash
xeno-canto -del q:D cnt:Brazil
```

--------------------------------

### Parse metadata and list URLs

Source: https://context7.com/ntivirikin/xeno-canto-py/llms.txt

Extracts recording information including IDs and download URLs from metadata JSON files.

```python
import xenocanto

# First download metadata
meta_path = xenocanto.metadata(['gen:Otis'])

# Parse URLs from metadata
url_list = xenocanto.list_urls(meta_path)
num_recordings = url_list[0]
track_tuples = url_list[1]

print(f"Found {num_recordings} recordings")
for name, track_id, url, fmt in track_tuples[:3]:
    print(f"  {name} - {track_id}{fmt}: {url}")
```

--------------------------------

### Python API: metadata(filt)

Source: https://context7.com/ntivirikin/xeno-canto-py/llms.txt

Retrieves metadata for recordings matching the search filter and saves it as paginated JSON files.

```APIDOC
## metadata(filt)

### Description
Retrieves metadata for recordings matching the search filter and saves it as paginated JSON files.

### Parameters
- **filt** (list) - Required - A list of strings representing the search query parameters (e.g., species name, quality, genus, country).

### Request Example
```python
import xenocanto
meta_path = xenocanto.metadata(['Bearded Bellbird', 'q:A'])
```

### Response
- **Returns** (string) - The path to the folder containing the saved JSON metadata files.
```

--------------------------------

### Metadata Search

Source: https://context7.com/ntivirikin/xeno-canto-py/llms.txt

Downloads metadata for recordings matching the specified search parameters.

```APIDOC
## Metadata Search

### Description
Downloads metadata for recordings matching the specified search parameters and returns the path to the saved metadata file.

### Method
`GET` (Conceptual - this is a library function, not a direct HTTP call)

### Endpoint
N/A (Library function)

### Parameters
- `search_params` (list of strings) - Required - A list of search parameters in `tag:value` format. Common tags include:
  - `species name` (string) - e.g., 'Bearded Bellbird'
  - `q` (string) - Quality filter (A, B, C, D, E). e.g., 'q:A'
  - `cnt` (string) - Country filter. e.g., 'cnt:United States'
  - `gen` (string) - Genus filter. e.g., 'gen:Otis'
  - `nr` (string) - Recording number filter. e.g., 'nr:459281'

### Request Example
```python
import xenocanto

# Download metadata for a specific recording number
meta_path = xenocanto.metadata(['nr:459281'])
print(f"Metadata saved to: {meta_path}")

# Download metadata for a genus
meta_path_genus = xenocanto.metadata(['gen:Otis'])
print(f"Metadata saved to: {meta_path_genus}")
```

### Response
- `string` - The file path to the downloaded metadata JSON file.
```

--------------------------------

### Purge Folders via Python API

Source: https://context7.com/ntivirikin/xeno-canto-py/llms.txt

Remove folders with insufficient recordings using the purge function.

```python
import xenocanto

# Remove all species folders with fewer than 10 recordings
xenocanto.purge(10)

# Remove folders with fewer than 100 recordings for ML training datasets
xenocanto.purge(100)
```

--------------------------------

### Delete Recordings via CLI

Source: https://context7.com/ntivirikin/xeno-canto-py/llms.txt

Remove local recordings matching specified parameters.

```bash
# Delete ALL quality D recordings and ALL recordings from Brazil
xeno-canto -del q:D cnt:Brazil

# Delete specific recordings by ID
xeno-canto -del id:493159 id:427845

# Delete recordings by species (use underscores for spaces)
xeno-canto -del en:Bearded_Bellbird
```

--------------------------------

### Adjust num_chunks for Error 503

Source: https://github.com/ntivirikin/xeno-canto-py/blob/master/README.md

If an Error 503 occurs during download, adjust the 'num_chunks' value in the download function. This can be done by modifying the default value or passing a specific value.

```python
download(params, num_chunks=2)
```

--------------------------------

### Python API: delete(filt)

Source: https://context7.com/ntivirikin/xeno-canto-py/llms.txt

Deletes recordings matching any of the provided filter parameters from the local library.

```APIDOC
## delete(filt)

### Description
Deletes recordings matching ANY of the provided filter parameters. Automatically generates library metadata and removes empty folders after deletion.

### Parameters
- **filt** (list) - Required - A list of strings representing the filter parameters for deletion.

### Request Example
```python
import xenocanto
xenocanto.delete(['q:D'])
```
```

--------------------------------

### Delete Recordings

Source: https://context7.com/ntivirikin/xeno-canto-py/llms.txt

Allows deletion of specific recordings by ID, all recordings of a species, or all recordings of a genus.

```APIDOC
## Delete Recordings

### Description
Allows deletion of specific recordings by ID, all recordings of a species, or all recordings of a genus.

### Method
`DELETE` (Conceptual - this is a library function, not a direct HTTP call)

### Endpoint
N/A (Library function)

### Parameters
- `ids` (list of strings) - Required - A list of recording IDs or species/genus identifiers to delete. Format examples: `['id:493159', 'id:427845']`, `['en:Bearded_Bellbird']`, `['gen:Otis']`

### Request Example
```python
import xenocanto

# Delete specific recordings by ID
xenocanto.delete(['id:493159', 'id:427845'])

# Delete all recordings of a specific species (use underscores for spaces)
xenocanto.delete(['en:Bearded_Bellbird'])

# Delete by genus
xenocanto.delete(['gen:Otis'])
```

### Response
N/A (Library function, no direct HTTP response)
```

--------------------------------

### Delete recordings by ID, species, or genus

Source: https://context7.com/ntivirikin/xeno-canto-py/llms.txt

Removes specific recordings from the local dataset using identifiers or taxonomic filters.

```python
xenocanto.delete(['id:493159', 'id:427845'])

# Delete all recordings of a specific species (use underscores for spaces)
xenocanto.delete(['en:Bearded_Bellbird'])

# Delete by genus
xenocanto.delete(['gen:Otis'])
```

--------------------------------

### Delete Recordings via Python API

Source: https://context7.com/ntivirikin/xeno-canto-py/llms.txt

Remove recordings matching filter criteria using the delete function.

```python
import xenocanto

# Delete all quality D recordings
xenocanto.delete(['q:D'])

# Delete recordings from specific locations
xenocanto.delete(['cnt:Brazil', 'cnt:Argentina'])
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.