Reads the annotations held in a file in the Acoustic Objects Exchange Format (AOEF), the JSON format of the soundevent Python package, in which the Whombat annotation tool (Balvanera et al. 2023) exports its projects. The predictions of a model run are read in the same way.
Details
AOEF gives each sound event a shape: a stretch of time, a box of time and frequency, a single moment, a single point, or lines and polygons drawn on the spectrogram. Each is read as the smallest range of time and frequency that holds it, which for a stretch of time or a single moment is every frequency.
A sound event can carry several tags, each a key and a value such as
dwc:scientificName and Turdus merula, while an Annotation has one
type and one value. So a sound event is read as one annotation for each
of its tags, with the key as its type, or as one annotation with no type
and no value where it has no tags. The tags of a clip, a part of a recording
annotated as a whole, are read in the same way as annotations spanning the
clip. A clip with no tags and no sound events, annotated as holding nothing,
is read as one annotation with no type and no value, so that the absence is
kept.
Who made each annotation (created_by) is its identifiedBy, by the
person's name, and when (created_on) its dateIdentified. The metadata
of each annotation holds its notes, the features measured of it, and for a
prediction its score and the tag_score of its tag. Under aoef it also
holds the identifiers and the exact shape that writeAOEF() needs to write
it back as it was, and what the file said of its recording. Sequences of
sound events are not read.
soundevent on Windows writes in the encoding of the locale rather than in UTF-8, so a file that is not UTF-8 is read as Windows-1252.
References
Balvanera SM, Mac Aodha O, Weldy MJ, Pringle H, Browning E, Jones KE (2023). “Whombat: An open-source annotation tool for machine learning development in bioacoustics.” doi:10.48550/arXiv.2308.12688 . 2308.12688, https://arxiv.org/abs/2308.12688.
