birdnet_analyzer: Process audio files through BirdNET

In nationalparkservice/NSNSDAcoustics: Streamline National Park Service Bioacoustics Analysis

Process audio files through BirdNET

Description

This function allows a user to process audio files through BirdNET-Analyzer via R's system function. It is meant for Windows users and may have unexpected results on other systems. To use this function, follow the steps outlined in the NSNSDAcoustics ReadME. Please see BirdNET-Analyzer usage documentation for more details.

Usage

birdnet_analyzer(
  birdnet.version,
  birdnet.path,
  i.audio,
  o.results,
  lat = -1,
  lon = -1,
  week = -1,
  slist = NULL,
  sensitivity = 1,
  min.conf = 0.1,
  overlap = 0,
  rtype = "r",
  threads = 1,
  batchsize = 1,
  locale = "en",
  sf.thresh = 0.03,
  classifier = NULL,
  fmin = 0,
  fmax = 15000,
  skip.existing.results = FALSE
)

Arguments

birdnet.version	Character name of BirdNET GUI release you are using. Options in c('v1.1.0', 'v1.2.0', 'v1.3.x', 'v1.5.x', 'previous'). If you downloaded a BirdNET .exe installer prior to that, try putting "previous" in the birdnet.version argument. If this doesn't work, update to a new version or consider constructing the command statement by hand instead of using this function. See releases at https://github.com/kahst/BirdNET-Analyzer/releases. (NOTE: The BirdNET "release" version specified in this argument is different from the BirdNET model version. The only BirdNET model version supported by this function is model version 2.4.)
birdnet.path	Absolute path to BirdNET-Analyzer.exe installation on your machine. e.g., "C:/path/to/BirdNET-Analyzer/BirdNET-Analyzer.exe"
i.audio	Absolute path to input file or folder. If this is a file, o.results needs to be a file too.
o.results	Absolute path to output folder. For v1.1.0 and v1.2.0, if this is a file, i.audio needs to be a file too. If using a file, give it the same extension name as would be produced by your rtype value (i.e., if using rtype = 'r', ensure the file extension for o.results input is something like 'your_filename.csv'). Note: for version v1.3+, "analysis does not support specifying a specific file as output anymore".
lat	Recording location latitude. Set -1 to ignore.
lon	Recording location longitude Set -1 to ignore.
week	Week of the year when the recording was made. Values in c(1:48) (4 weeks per month). Set -1 for year-round species list.
slist	Absolute path to species list text file or folder. If only a folder is provided, species list needs to be named "species_list.txt". If lat and lon are provided, BirdNET-Analyzer will ignore this argument. See BirdNET-Analyzer for details on formatting a species list.
sensitivity	Detection sensitivity. higher values result in higher sensitivity. Values from 0.5 to 1.5. Default = 1.0.
min.conf	Minimum confidence threshold. Values from 0.01 to 0.99. Default = 0.1.
overlap	Overlap of prediction segments. Values from 0.0 to 2.9. Default = 0.0.
rtype	Output format. Values in c('table', 'audacity', 'r', 'kaleidoscope', 'csv'). Defaults to 'r', and strongly recommend using rtype 'r' if you want to use other functions in NSNSDAcoustics.
threads	Number of CPU threads.
batchsize	Number of samples to process at the same time. Defaults to 1.
locale	Locale for translated species common names. Values in c('af', 'de', 'it', ...). Defaults to 'en'.
sf.thresh	Minimum species occurrence frequency threshold for location filter. Values from 0.01 to 0.99. Defaults to 0.03.
classifier	Absolute path to custom trained classifier. Defaults to None. If set, lat, lon and locale are ignored.
fmin	Minimum frequency for bandpass filter. Defaults to 0.
fmax	Maximum frequency for bandpass filter. Defaults to 15000.
skip.existing.results	Skip files that have already been analyzed. Default = FALSE.

Details

This function was developed by the National Park Service Natural Sounds and Night Skies Division to act as a wrapper to process audio data using BirdNET. The function has been tested on BirdNET Analyzer GUI releases v1.1.x through 1.5.x. To use this function, follow the steps outlined in the NSNSDAcoustics ReadME.

Value

Saves a file of results for each audio file in results.directory. For the recommended rtype = 'r', files are csv with suffix "BirdNET.results.csv" or "BirdNET.results.r.csv", depending on your BirdNET release version. Files contain the following columns:

• filepath: Filepath for the processed audio file.

• start: Start time of detection in seconds.

• end: End time of detection in seconds.

• scientific_name: Species scientific name.

• common_name: Species common name.

• confidence: BirdNET's confidence level in this detection ranging from 0 (least confident) to 1 (most confident).

• lat: Latitude input used.

• long: Longitude input used.

• week: Week of year input used.

• overlap: Overlap input used.

• sensitivity: Sensitivity input used.

• min_conf: Minimum confidence input used.

• species_list: Species list used.

• model: BirdNET model used.

See Also

birdnet_format, birdnet_verify

Examples

## Not run: 

# Create an audio directory for this example
dir.create('example-audio-directory')

# Read in example wave files
data(exampleAudio1)
data(exampleAudio2)

# Write example waves to example audio directory
tuneR::writeWave(
  object = exampleAudio1,
  filename = 'example-audio-directory/Rivendell_20210623_113602.wav'
)
tuneR::writeWave(
  object = exampleAudio2,
  filename = 'example-audio-directory/Rivendell_20210623_114602.wav'
)

# Create a BirdNET results directory for this example
dir.create('example-results-directory')

# Create a species_list.txt file for this example and write to working directory
data(exampleSpeciesList)
write.table(
   x = exampleSpeciesList,
   file = 'species_list.txt',
   row.names = FALSE,
   col.names = FALSE,
   quote = FALSE
)

##### The following example is pseudocode ######

# Because this function calls an external program (BirdNET-Analyzer.exe),
# the example function below will not be modifiable to run for you unless
# you follow the instructions given the NSNSDAcoustics documentation here:
# https://github.com/nationalparkservice/NSNSDAcoustics/blob/main/README.md

# Run all audio data in a directory through BirdNET
birdnet_analyzer(
 birdnet.version = 'v1.5.0',
 birdnet.path = 'absolute/path/AppData/Local/Programs/BirdNET-Analyzer/BirdNET-Analyzer.exe',
 i.audio = 'absolute/path/example-audio-directory',
 o.results = 'absolute/path/example-results-directory',
 slist = 'absolute/path/species_list.txt',
)

# Delete all temporary example files when finished
unlink(x = 'example-audio-directory', recursive = TRUE)
unlink(x = 'example-results-directory', recursive = TRUE)


## End(Not run)

nationalparkservice/NSNSDAcoustics documentation built on June 13, 2025, 3:32 a.m.