Annotations: handling labelled audio data

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

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

Generating annotations

# 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)
#> [[1]]
#> An object of class "Annotation"
#> Slot "file":
#> [1] "example.wav"
#> 
#> Slot "metadata":
#> $confidence
#> [1] 0.8
#> 
#> 
#> Slot "start":
#> [1] 27
#> 
#> Slot "end":
#> [1] 33
#> 
#> Slot "low":
#> [1] 0
#> 
#> Slot "high":
#> [1] Inf
#> 
#> Slot "source":
#> [1] "BirdNet-Analyzer"
#> 
#> Slot "type":
#> [1] "birdnet-detection"
#> 
#> Slot "value":
#> [1] "sparrow"

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

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