warbleR: Streamline Bioacoustic Analysis

warbleR logo

warbleR is an R package for analyzing the structure of animal acoustic signals at scale. Bring your own recordings (or open-access ones from repositories like Xeno-canto, easily obtained with suwo), annotate them in a selection table, and run the whole pipeline — from file wrangling and spectrograms to acoustic measurements and similarity analyses — in batch, on as many signals as you have.

Built on top of seewave and tuneR, warbleR adds the workflow layer those packages leave to the user:

🗂️ Selection-table-driven workflows — every function loops over the signals listed in an annotation table, so one call handles one sound or ten thousand
📦 Extended selection tables — a single R object that bundles annotations and the audio clips, making analyses portable and easy to share
⚡ Parallel processing — most functions take a parallel argument to spread the work across cores
🔍 Built-in quality checks — spectrogram images and diagnostic tools let you verify each step before moving on

What can you do with it?

Task	Key functions
Inspect, convert and fix sound files	`info_sound_files()`, `check_sound_files()`, `fix_wavs()`, `mp32wav()`, `wav_2_flac()`, `split_sound_files()`, `remove_channels()`
Build and validate annotation tables	`selection_table()`, `check_sels()`, `tailor_sels()`, `cut_sels()`, `overlapping_sels()`, `consolidate()`
Create spectrograms	`spectrograms()`, `full_spectrograms()`, `color_spectro()`, `snr_spectrograms()`, `catalog()`, `phylo_spectro()`
Measure acoustic structure	`spectro_analysis()`, `mfcc_stats()`, `song_analysis()`, `freq_range()`, `sig2noise()`, `sound_pressure_level()`, `gaps()`, `wpd_features()`
Track frequency contours	`freq_ts()`, `track_freq_contour()`, `track_harmonic()`, `inflections()`
Compare signals	`cross_correlation()`, `freq_DTW()`, `multi_DTW()`, `waveform_similarity()`, `compare_methods()`
Analyze duet / chorus coordination	`test_coordination()`, `plot_coordination()`
Simulate signals	`simulate_songs()`

See the function reference for the full list.

Installation

From CRAN:

install.packages("warbleR")

Development version from GitHub (requires remotes):

remotes::install_github("maRce10/warbleR")

Quick example

The example recordings and annotations come from the NatureSounds package (installed with warbleR):

library(warbleR)

# load example long-billed hermit songs and their annotations
data(list = c("Phae.long1", "Phae.long2", "Phae.long3", "Phae.long4", "lbh_selec_table"))

# save the sound files to a temporary folder
for (i in paste0("Phae.long", 1:4)) {
  tuneR::writeWave(get(i), file.path(tempdir(), paste0(i, ".wav")))
}

# check that annotations and sound files match
check_sels(lbh_selec_table, path = tempdir())

# measure spectral and temporal parameters for every annotated signal
params <- spectro_analysis(lbh_selec_table, path = tempdir())

# pairwise acoustic similarity via spectrographic cross-correlation
xc <- cross_correlation(lbh_selec_table, path = tempdir())

Learn more

📘 Intro to warbleR — an overview of the package
📝 Annotation data format — how input annotations (selection tables) should look
🔁 All vignettes — worked examples of complete analysis workflows
📄 Original paper in Methods in Ecology and Evolution (the package has grown a lot since, so check the vignettes for current usage)

Package	What it does
seewave & tuneR	Core sound analysis and manipulation of wave objects in R
ohun	Automated detection of sound events, with tools to diagnose and optimize detection routines
suwo	Search, download and map nature media (Xeno-canto, Macaulay Library, iNaturalist, GBIF, WikiAves) — replaces warbleR’s `query_xc()` and `map_xc()`
baRulho	Quantifying habitat-induced degradation of acoustic signals, with inputs/outputs compatible with warbleR
Rraven	Data exchange between R and Raven (Cornell Lab of Ornithology), handy for using Raven as the annotation tool
dynaSpec	Dynamic spectrograms (spectrogram videos)
NatureSounds	Example recordings and annotations of animal sounds

Getting help & contributing

Found a bug or have a feature request? Please open an issue. Contributions are welcome — see the contributing guidelines.

Citation

If you use warbleR, please cite:

Araya-Salas, M. & Smith-Vidaurre, G. (2017). warbleR: an R package to streamline analysis of animal acoustic signals. Methods in Ecology and Evolution, 8, 184–191. https://doi.org/10.1111/2041-210X.12624

Please also cite tuneR and seewave if you use any function that creates spectrograms or measures acoustic parameters. You can get all citations from R with citation("warbleR").