Detect Song Bouts in Audio Recordings

Detects and analyzes song bouts using RMS amplitude thresholding with bandpass filtering.

Usage

find_bout(x, ...)

# Default S3 method
find_bout(
  x,
  wl = 1024,
  ovlp = 50,
  norm_method = c("quantile", "max"),
  rms_threshold = 0.1,
  min_duration = 0.5,
  gap_duration = 0.3,
  edge_window = 0.05,
  freq_range = c(3, 5),
  plot = TRUE,
  save_plot = FALSE,
  plot_dir = NULL,
  ...
)

# S3 method for class 'Sap'
find_bout(
  x,
  day = NULL,
  indices = NULL,
  segment_type = c("motifs", "raw"),
  cores = NULL,
  save_plot = FALSE,
  plot_percent = 10,
  wl = 1024,
  ovlp = 50,
  norm_method = c("quantile", "max"),
  rms_threshold = 0.1,
  min_duration = 0.5,
  gap_duration = 0.3,
  edge_window = 0.05,
  freq_range = c(3, 5),
  summary = FALSE,
  dry_run = FALSE,
  overwrite_metadata = FALSE,
  verbose = TRUE,
  ...
)

Arguments

x: An object to analyze, either a file path or SAP object
...: Additional arguments passed to specific methods
wl: Window length for RMS calculation (default: 1024)
ovlp: Overlap percentage between windows (default: 50)
norm_method: Method for normalizing RMS values ("quantile" or "max")
rms_threshold: Threshold for bout detection (default: 0.1)
min_duration: Minimum bout duration in seconds (default: 0.5)
gap_duration: Minimum gap between bouts (default: 0.3)
edge_window: Time window for edge effects (default: 0.05)
freq_range: Frequency range for bandpass filter (default: c(3, 5))
plot: Whether to display visualization (default: TRUE)
save_plot: Whether to save plots to file (default: FALSE)
plot_dir: Directory for saving plots
day: For SAP objects: Days to process
indices: For SAP objects: Specific indices to process
segment_type: For SAP objects: Source of data to drive bout detection. "motifs" (default) uses pre-detected motif data — only files containing at least one motif are processed, and detected bouts are validated to contain at least one motif. "raw" uses the SAP metadata directly, so every audio file in the object is scanned for bouts based on amplitude alone, with no motif requirement. Use "raw" for Scenario A (general compression) before motif detection has been run.
cores: For SAP objects: Number of processing cores
plot_percent: For SAP objects: Percentage of files to plot (default: 10)
summary: For SAP objects: Include additional statistics (default: FALSE)
dry_run: For SAP objects with segment_type = "raw": when TRUE, do not write x$bouts. Instead, report how many WAV files contain bouts. If overwrite_metadata = TRUE, remove files with no detected bouts from x$metadata.
overwrite_metadata: For SAP objects: when TRUE and dry_run = TRUE with segment_type = "raw", remove WAV files with no detected bouts from x$metadata so they are skipped in downstream processing.
verbose: For SAP objects: Print progress messages (default: TRUE)

Value

For default method: Data frame containing:

filename: Name of WAV file
selec: Bout number
start_time: Onset time
end_time: Offset time

For SAP objects: Updated object with bout information in bouts slot

Details

For WAV files:

Applies bandpass filtering to focus on vocalization frequencies
Calculates RMS envelope with specified window parameters
Detects bouts using adaptive thresholding
Handles edge cases and minimum duration constraints
Creates optional visualizations

For SAP objects:

Processes multiple recordings in parallel
Validates bouts against existing motif detections
Provides optional summary statistics
Maintains metadata relationships
Supports selective plotting

When summary = TRUE for SAP objects with motifs:

n_motifs: Count of motifs per bout
align_time: First motif time for alignment
bout_number_day: Sequential numbering
bout_gap: Time from previous bout

Examples