metamoth
Metamoth is a Python package for parsing the metadata of AudioMoth files. Check the full documentation at https://metamoth.readthedocs.io.
Motivation
AudioMoth devices store valuable information in the audio file header. This includes the device ID, the date and time of recording, gain settings and battery state. The number of fields in the metadata is growing as new features are added to the AudioMoth firmware.
However, the metadata is not designed to be easily parsed in a programmatic way. The data is stored as a string comment making it difficult to retrieve the individual metadata fields. Additionally, the comment format is not well documented and changes between AudioMoth firmware versions.
This package helps by quickly parsing the metadata and returning an object containing the metadata.
Usage
The metamoth package provides a single function, parse_metadata, which parses the metadata of an AudioMoth file and returns an object containing the metadata.
from metamoth import parse_metadata
metadata = parse_metadata('path/to/file')The extracted metadata can be accessed as attributes of the object, as shown
duration = metadata.duration_s
path = metadata.path
# etc.Extracted Metadata
The metadata variable is an object (of type AMMetadata) containing the metadata of the file.
The extracted metadata contains:
path: the path of the audio file
firmware_version: the firmware version of the AudioMoth that recorded the file. Since the AudioMoth firmware version is not stored in the recording, this is an estimate and may be incorrect.
Media Information
duration_s: the duration of the file in seconds.
samplerate_hz: the sample rate of the file in Hz.
channels: the number of channels in the file.
samples: the number of audio samples in the file.
Data extracted from the AudioMoth comment string:
datetime: the date and time of the file in a datetime object.
timezone: the timezone of the file as a timezone object.
audiomoth_id: the ID of the AudioMoth that recorded the file.
battery_state_v: the battery state of the AudioMoth that recorded the file in Volts.
low_battery: a boolean indicating if the battery state is low.
gain: the gain setting of the AudioMoth that recorded the file.
comment: the full comment string in the WAV header.
The following fields are only available for some AudioMoth firmware versions. Nonetheless, they are always present in the metadata object, but may be None.
recording_state: the recording state of the AudioMoth that recorded the file.
temperature_c: the temperature of the AudioMoth in Celsius.
amplitude_threshold: information concerning the wether an amplitude threshold was used and the threshold value.
frequency_filter: information concerning the wether a frequency filter was used and the filter settings.
deployment_id: the deployment ID as set by the user.
external_microphone: a boolean indicating if an external microphone was used.
minimum_trigger_duration_s: the minimum trigger duration in seconds.
frequency_trigger: information concerning the wether a frequency trigger was used and the trigger settings.
The following table shows the fields available for each AudioMoth firmware.
version |
recording_state |
temperature_c |
amplitude_threshold |
frequency_filter |
deployment_id |
external_microphone |
minimum_trigger_duration_s |
frequency_trigger |
|---|---|---|---|---|---|---|---|---|
1.0 |
✖ |
✖ |
✖ |
✖ |
✖ |
✖ |
✖ |
✖ |
1.0.1 |
✖ |
✖ |
✖ |
✖ |
✖ |
✖ |
✖ |
✖ |
1.1.0 |
✖ |
✖ |
✖ |
✖ |
✖ |
✖ |
✖ |
✖ |
1.2.0 |
✖ |
✖ |
✖ |
✖ |
✖ |
✖ |
✖ |
✖ |
1.2.1 |
✔ |
✖ |
✖ |
✖ |
✖ |
✖ |
✖ |
✖ |
1.2.2 |
✔ |
✖ |
✖ |
✖ |
✖ |
✖ |
✖ |
✖ |
1.3.0 |
✔ |
✖ |
✖ |
✖ |
✖ |
✖ |
✖ |
✖ |
1.4.0 |
✔ |
✔ |
✔ |
✔ |
✖ |
✖ |
✖ |
✖ |
1.4.1 |
✔ |
✔ |
✔ |
✔ |
✖ |
✖ |
✖ |
✖ |
1.4.2 |
✔ |
✔ |
✔ |
✔ |
✖ |
✖ |
✖ |
✖ |
1.4.3 |
✔ |
✔ |
✔ |
✔ |
✖ |
✖ |
✖ |
✖ |
1.4.4 |
✔ |
✔ |
✔ |
✔ |
✖ |
✖ |
✖ |
✖ |
1.5.0 |
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
✖ |
✖ |
1.6.0 |
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
✖ |
1.7.0 |
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
✖ |
1.7.1 |
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
✖ |
1.8.0 |
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
1.8.1 |
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
✔ |
Supported AudioMoth Firmware Versions
In the table below you can find the supported AudioMoth firmware versions.
Firmware |
Supported |
|---|---|
1.0.0 |
✔ |
1.0.1 |
✔ |
1.1.0 |
✔ |
1.2.0 |
✔ |
1.2.1 |
✔ |
1.2.2 |
✔ |
1.3.0 |
✔ |
1.4.0 |
✔ |
1.4.1 |
✔ |
1.4.2 |
✔ |
1.4.3 |
✔ |
1.4.4 |
✔ |
1.5.0 |
✖ |
1.6.0 |
✔ |
1.7.0 |
✖ |
1.7.1 |
✖ |
1.8.0 |
✖ |
1.8.1 |
✖ |
Support for newer firmware versions is planned, see the CONTRIBUTING section if you want to help!
Performance
The metamoth package is designed to be fast. It extracts all the required information from the first few bytes and avoids loading the audio data. Thus metamoth parsing times are not affected by the size of the audio file.
The following table shows the parsing times of metamoth compared to exif tool.
File Size (MB) |
metamoth (ms) |
exiftool (ms) |
Speedup |
|---|---|---|---|
7.3 |
0.0845 |
80 |
~1000x |
44 |
0.0850 |
91.86 |
~1000x |
Installation
The metamoth package can be installed using pip:
pip install metamoth
Check the installation section of the documentation for more information.
Documentation
The documentation for the metamoth package is available at https://metamoth.readthedocs.io/en/latest/index.html.
1 maintainer
Metadata
1 maintainer
Release files for metamoth 1.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| metamoth-1.2.2.tar.gz | 49.7 MB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| metamoth-1.2.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 49.7 MB
Release files / metamoth-1.2.2.tar.gz
| Download URL | metamoth-1.2.2.tar.gz |
|---|---|
| Size | 49.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a5c74526d76ca451fbfb2e3d8f54dc150c914323c9b6c12da9fe08dafa5dcfc2
|
|
BLAKE2b-256 checksum How to use checksums |
fe06b9133998e36e1f540f40b510fcf8ca46b1a8cd766fb4e839d4f3d106c724
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.1.0 CPython/3.9.19
|
Release files / metamoth-1.2.2-py3-none-any.whl
| Download URL | metamoth-1.2.2-py3-none-any.whl |
|---|---|
| Size | 17.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bfc758b39ee61ada70338cea24c2f5addfd02dc7889f86426804f63c913bc363
|
|
BLAKE2b-256 checksum How to use checksums |
071dbe47b82f80d6c09fb5788d3ba088e13be2f4ba7f022c179bdb0702bd4963
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.1.0 CPython/3.9.19
|
Security for metamoth 1.2.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
