warbleR
Streamline Bioacoustic Analysis
Functions aiming to facilitate the analysis of the structure of animal acoustic signals in 'R'. 'warbleR' makes use of the basic sound analysis tools from the packages 'tuneR' and 'seewave', and offers new tools for exploring and quantifying acoustic signal structure. The package allows users to organize and manipulate multiple sound files, create spectrograms of complete recordings or individual signals in different formats, run several measures of acoustic structure, and characterize different structural levels in acoustic signals (Araya-Salas and Smith-Vidaurre 2017
warbleR: Streamline Bioacoustic Analysis
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
parallelargument 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)
Related packages
| 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").