ARU Metadata Parser

Parse audio file metadata from common ARUs including the AudioMoth

This package aims to provide support for parsing metadata from common ARU (autonomous recording unit) audio files. Currently, AudioMoth metadata from firmware versions up to at least 1.8.1 are supported.

Please use Issues to report failures in metadata parsing, and to request parsing for other metadata formats.

Installation:

The package is available on PyPI and can be installed with PIP:

pip install aru_metadata_parser

Usage

Efficiently parse recording times from file paths

The ARUFileTimestampParser class parses times stamps from file names created by AudioMoth, Song Meter, OwlSense, and Swift recorders. It tries all known formats automatically before falling back to fuzzy date parsing. It also caches the last successful strategy for efficient parsing of many file names.

If you find an ARU file name pattern that does not work, please open an issue with an example of the naming pattern and how file names are generated (e.g., what hardware or software).

from aru_metadata_parser import parse
parser = parse.ARUFileTimestampParser(filename_timezone="UTC", output_timezone="US/Eastern")
datetimes = [parser.parse(f) for f in files]

Timezone handling

• filename_timezone: the timezone the recorder used when constructing its filename (e.g. "UTC", "US/Eastern"). If None, returns a naive datetime object.
• output_timezone: timezone to convert the result to. Requires filename_timezone to be set (except for Swift, which embeds UTC offset in the filename).
• Timezone strings must be valid pytz timezone names (see pytz.all_timezones).

Parse AudioMoth WAV file metadata

Reads and parses metadata from the WAV header of an AudioMoth recording. Returns a dictionary with keys including gain_setting, battery_state, recording_start_time, device_id, and (for firmware >=1.4.0) temperature_C:

from aru_metadata_parser import parse
# extract AudioMoth recording metadata from a file
metadata = parse.parse_audiomoth_metadata_from_path("audiomoth_recording.WAV")

# From an already-loaded metadata dictionary
metadata_dict = 
metadata = parse.parse_audiomoth_metadata(metadata_dict)

Advanced usage

Use underlying parser function:

Optionally specify the recorder type. If no recorder_type is specified, it tries each available strategy then fuzzy matching.

from aru_metadata_parser import parse

# Auto-detect recorder type
dt = parse.parse_aru_file_start_time("SMM03873_20220719_000000.wav")

# Specify recorder type explicitly
dt = parse.parse_aru_file_start_time(
    "SMM03873_20220719_000000.wav",
    recorder_type="songmeter",         # one of: 'audiomoth', 'songmeter', 'owlsense', 'swift'
    filename_timezone="US/Eastern",    # timezone the recorder used when naming the file
    output_timezone="UTC",             # convert result to this timezone
)

Recorder-specific parsing

AudioMoth — supports both hex filenames (old firmware) and human-readable filenames (new firmware):

# New firmware (human-readable)
dt = parse.audiomoth_start_time("20200404_102500.WAV")

# With timezone info
dt = parse.audiomoth_start_time("20200404_102500.WAV", filename_timezone="UTC", output_timezone="US/Eastern")

# Old firmware (hexadecimal filename, always UTC)
dt = parse.audiomoth_start_time("5E886A48.WAV", filename_timezone="UTC")

Song Meter (SM2/3/4, Mini, Micro) — filename pattern: SMM03873_20220719_000000.wav:

dt = parse.songmeter_start_time("SMM03873_20220719_000000.wav")
dt = parse.songmeter_start_time("SMM03873_20220719_000000.wav", filename_timezone="US/Eastern", output_timezone="UTC")

OwlSense — filename pattern: OWL_123456_2022-07-19_T00-00-00.WAV:

dt = parse.owlsense_start_time("OWL_123456_2022-07-19_T00-00-00.WAV")
dt = parse.owlsense_start_time("OWL_123456_2022-07-19_T00-00-00.WAV", filename_timezone="UTC", output_timezone="US/Eastern")

Swift — filename pattern: SwiftOne_20220719_000000_-0400.wav (UTC offset embedded in filename):

dt = parse.swift_start_time("SwiftOne_20220719_000000_-0400.wav")
dt = parse.swift_start_time("SwiftOne_20220719_000000_-0400.wav", output_timezone="UTC")

Contribution:

We use Poetry for development, with black formatting and pytest testing. Contributions to the code base are welcome.

License and attribution:

This package is provided under the MIT Open-source license.

Suggested citation:

Lapp, Syunkova, and Kitzes, 2023. ARU Metadata Parser v0.1.0. github.com/kitzeslab/aru_metadata_parser.