In edwbaker/SonicScrewdriveR: Bioacoustic Analysis and Publication Tools

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

library(sonicscrewdriver)

Managing labelled audio data in R with SonicScrewdriveR

Setting annotation boundaries

SonicScrewdriveR provides a set of functionality to read, generate, manage and write label data for audio files. This Annotation class is used to consistently handle annotations to audio files. Annotations are delimited in the time domain (seconds) and frequency domain (Hz).

a1 <- annotation(
  start = 0,
  end = 1
)

a2 <- annotation(
  low = 0,
  high = 1000
)

Inf can be used as a value to end or high to indicate that the annotation extends to the limits of the file.

a3 <- annotation(
  start = 0,
  end = Inf
)

a4 <- annotation(
  low = 0,
  high = Inf
)

Handling metadata

Objects of the Annotation class have inbuilt character slots for storing the file name (file) and the source, type and value of the annotation. A list slot metadata is provided for storing additional metadata.

The file, source, type and value slots are used by SonicScrewdriveR. For example, the merge_annotations function uses these slots to appropriately merge overlapping annotations.

When using tools from SonicScrewdriveR these slots may be pre-populated. The example below creates an Annotation object equivalent to one generated by the function birdNetAnalyse.

a5 <- annotation(
  start=27,
  end=30,
  file = "example.wav",
  source = "BirdNet-Analyzer",
  type = "birdnet-detection",
  value = "sparrow",
  metadata = list(
    confidence = 0.9
  )
)

Reading annotations

From audioblast database

# Fetch annotations from audioBlast as `Annotation` objects
a <- audioblast("data", "annomate", source="bio.acousti.ca", id=10754, output="Annotations")

Generating annotations

Using BirdNET

# Analyse sound files using BirdNET-Analyzer
f <- system.file("extdata", "AUDIOMOTH.WAV", package="sonicscrewdriver")
annotations <- birdNetAnalyse(f, output="Annotation")

Merging annotations

The merge_annotations function can be used to merge overlapping annotations. The function will merge annotations with overlapping time extents with the same file, type, value and optionally source slots.

a <- list(
  annotation(
    start=27,
    end=30,
    file = "example.wav",
    source = "BirdNet-Analyzer",
    type = "birdnet-detection",
    value = "sparrow",
    metadata = list(
      confidence = 0.9
    )
  ),
  annotation(
    start=30,
    end=33,
    file = "example.wav",
    source = "BirdNet-Analyzer",
    type = "birdnet-detection",
    value = "sparrow",
    metadata = list(
      confidence = 0.8
    )
  )
)

merge_annotations(a)

The two annotations in the list a overlap in time and have the same file, type and value slots. The merge_annotations function has merged these into a single annotation with the time extent from 27 to 33 seconds.

Writing annotations

Audacity label file

# Convert the annotations to an Audacity label file
writeAudacityLabels(annotations, "birdnet_annotations.txt")

edwbaker/SonicScrewdriveR documentation built on June 10, 2025, 3:15 a.m.