metamoth package

Metamoth: A Python package for parsing AudioMoth metadata.

Metamoth is a Python package for parsing metadata from AudioMoth recordings. It provides a function to parse the metadata from a WAV file and returns an object with the metadata as attributes.

metamoth.parse_metadata(path: Union[PathLike, str]) → AMMetadata

Parse the metadata from an AudioMoth recording.

Parameters

path : PathLike

Returns

Metadata

Parse metadata from the recording at path. The metadata is returned as a AMMetadata object.

Submodules

metamoth.artist module

Functions for reading the artist chunk from a WAV file.

metamoth.artist.get_am_artist(wav: BinaryIO, chunk: Chunk) → Optional[str]

Get the artist string from the WAV file.

Parameters

wavBinaryIO

The WAV file.

chunkChunk

The RIFF chunk, which is the root chunk.

Returns

str

The artist string. If the artist is not found, returns None.

metamoth.audio module

Audio file utilities.

metamoth.audio.is_riff(path: Union[PathLike, str]) → bool

Return True if path is a RIFF file.

An RIFF file is a IFF file with the RIFF chunk ID. The RIFF chunk ID is the first 4 bytes of the file.

Parameters

path : PathLike

Returns

bool

metamoth.audio.is_wav(path: Union[PathLike, str]) → bool

Return True if path is a WAV file.

A WAV file is a RIFF file with the WAVE chunk ID. The WAVE chunk ID is the 8th byte of the file.

Parameters

path : PathLike

Returns

bool

metamoth.audio.is_wav_filename(filename: Union[PathLike, str]) → bool

Return True if filename is a WAV file.

metamoth.chunks module

Parse a RIFF file into chunks and subchunks.

This module is based on the RIFF specification: https://www.loc.gov/preservation/digital/formats/fdd/fdd000001.shtml

The RIFF file format is a container format for storing data in tagged chunks. Each chunk consists of a 4-byte chunk ID, a 4-byte little-endian chunk size, and the chunk data. The chunk data is padded with a null byte if the chunk size is odd.

The RIFF file format is used for storing audio and video data. The RIFF file format is also used for storing other types of data, such as text, images, and metadata.

class metamoth.chunks.Chunk(chunk_id: str, size: int, position: int, identifier: ~typing.Optional[str] = None, subchunks: ~typing.List[~metamoth.chunks.Chunk] = <factory>)

Bases: object

A chunk of a RIFF file.

Parameters

chunk_idstr

The chunk ID.

position: int

The position of the chunk in the file.

chunk_sizeint

The chunk size.

subchunksList[Chunk]

The subchunks of the chunk.

chunk_id: str

identifier: Optional[str] = None

position: int

size: int

subchunks: List[Chunk]

metamoth.chunks.parse_into_chunks(riff: BinaryIO) → Chunk

Return the RIFF file chunk and subchunks.

Parameters

riffBinaryIO

Open file object of the RIFF file.

Returns

Chunk

metamoth.comments module

Functions for reading the comment chunk of an AudioMoth WAV file.

metamoth.comments.get_am_comment(wav: BinaryIO, chunk: Chunk) → str

Return the comment from the WAV file.

Parameters

wavBinaryIO

Open file object of the WAV file.

chunkChunk

The RIFF chunk info, which is the root chunk. Should include the LIST chunk as a subchunk.

Returns

comment : str

metamoth.config module

Module with AudioMoth configuration classes for different versions.

class metamoth.config.Config1_0(time: int = 0, gain: int = 2, clock_band: int = 4, clock_divider: int = 2, acquisition_cycles: int = 2, oversample_rate: int = 16, sample_rate: int = 48000, sleep_duration: int = 0, record_duration: int = 60, enable_led: bool = True, active_start_stop_periods: bool = False, start_stop_period: ~typing.List[~metamoth.config.StartStopPeriod] = <factory>)

Bases: object

AudioMoth configuration for version 1.0.

Also valid for version 1.0.1

acquisition_cycles: int = 2

active_start_stop_periods: bool = False

clock_band: int = 4

clock_divider: int = 2

enable_led: bool = True

gain: int = 2

oversample_rate: int = 16

record_duration: int = 60

sample_rate: int = 48000

sleep_duration: int = 0

start_stop_period: List[StartStopPeriod]

time: int = 0

class metamoth.config.Config1_1_0(time: int = 0, gain: int = 2, clock_divider: int = 4, acquisition_cycles: int = 16, oversample_rate: int = 1, sample_rate: int = 384000, sample_rate_divider: int = 8, sleep_duration: int = 0, record_duration: int = 60, enable_led: bool = True, active_start_stop_periods: bool = False, start_stop_period: ~typing.List[~metamoth.config.StartStopPeriod] = <factory>)

Bases: object

AudioMoth configuration for version 1.1.0.

acquisition_cycles: int = 16

active_start_stop_periods: bool = False

clock_divider: int = 4

enable_led: bool = True

gain: int = 2

oversample_rate: int = 1

record_duration: int = 60

sample_rate: int = 384000

sample_rate_divider: int = 8

sleep_duration: int = 0

start_stop_period: List[StartStopPeriod]

time: int = 0

class metamoth.config.Config1_2_0(time: int = 0, gain: int = 2, clock_divider: int = 4, acquisition_cycles: int = 16, oversample_rate: int = 1, sample_rate: int = 384000, sleep_duration: int = 0, record_duration: int = 60, enable_led: bool = True, active_start_stop_periods: bool = False, start_stop_period: ~typing.List[~metamoth.config.StartStopPeriod] = <factory>, timezone: int = 0)

Bases: object

AudioMoth configuration for version 1.2.0.

acquisition_cycles: int = 16

active_start_stop_periods: bool = False

clock_divider: int = 4

enable_led: bool = True

gain: int = 2

oversample_rate: int = 1

record_duration: int = 60

sample_rate: int = 384000

sleep_duration: int = 0

start_stop_period: List[StartStopPeriod]

time: int = 0

timezone: int = 0

class metamoth.config.Config1_2_1(time: int = 0, gain: int = 2, clock_divider: int = 4, acquisition_cycles: int = 16, oversample_rate: int = 1, sample_rate: int = 384000, sleep_duration: int = 0, record_duration: int = 60, enable_led: bool = True, active_start_stop_periods: bool = False, start_stop_period: ~typing.List[~metamoth.config.StartStopPeriod] = <factory>, timezone: int = 0, enable_battery_check: bool = False, disable_battery_level_display: bool = False)

Bases: object

AudioMoth configuration for version 1.2.1.

acquisition_cycles: int = 16

active_start_stop_periods: bool = False

clock_divider: int = 4

disable_battery_level_display: bool = False

enable_battery_check: bool = False

enable_led: bool = True

gain: int = 2

oversample_rate: int = 1

record_duration: int = 60

sample_rate: int = 384000

sleep_duration: int = 0

start_stop_period: List[StartStopPeriod]

time: int = 0

timezone: int = 0

class metamoth.config.Config1_2_2(time: int = 0, gain: int = 2, clock_divider: int = 4, acquisition_cycles: int = 16, oversample_rate: int = 1, sample_rate: int = 384000, sample_rate_divider: int = 8, sleep_duration: int = 0, record_duration: int = 60, enable_led: bool = True, active_start_stop_periods: bool = False, start_stop_period: ~typing.List[~metamoth.config.StartStopPeriod] = <factory>, timezone_hours: int = 0, enable_battery_check: bool = False, disable_battery_level_display: bool = False, timezone_minutes: int = 0)

Bases: object

AudioMoth configuration for version 1.2.2.

Also valid for version 1.3.0.

acquisition_cycles: int = 16

active_start_stop_periods: bool = False

clock_divider: int = 4

disable_battery_level_display: bool = False

enable_battery_check: bool = False

enable_led: bool = True

gain: int = 2

oversample_rate: int = 1

record_duration: int = 60

sample_rate: int = 384000

sample_rate_divider: int = 8

sleep_duration: int = 0

start_stop_period: List[StartStopPeriod]

time: int = 0

timezone_hours: int = 0

timezone_minutes: int = 0

class metamoth.config.Config1_4_0(time: int = 0, gain: int = 2, clock_divider: int = 4, acquisition_cycles: int = 16, oversample_rate: int = 1, sample_rate: int = 384000, sample_rate_divider: int = 8, sleep_duration: int = 5, record_duration: int = 55, enable_led: bool = True, active_start_stop_periods: bool = False, start_stop_period: ~typing.List[~metamoth.config.StartStopPeriod] = <factory>, timezone_hours: int = 0, enable_low_voltage_cutoff: bool = False, disable_battery_level_display: bool = False, timezone_minutes: int = 0, disable_sleep_record_cycle: bool = False, earliest_recording_time: int = 0, latest_recording_time: int = 0, lower_filter_freq: int = 0, higher_filter_freq: int = 0, amplitude_threshold: int = 0)

Bases: object

AudioMoth configuration for version 1.4.0.

Also valid for version 1.4.1, 1.4.2, 1.4.3, 1.4.4,

acquisition_cycles: int = 16

active_start_stop_periods: bool = False

amplitude_threshold: int = 0

clock_divider: int = 4

disable_battery_level_display: bool = False

disable_sleep_record_cycle: bool = False

earliest_recording_time: int = 0

enable_led: bool = True

enable_low_voltage_cutoff: bool = False

gain: int = 2

higher_filter_freq: int = 0

latest_recording_time: int = 0

lower_filter_freq: int = 0

oversample_rate: int = 1

record_duration: int = 55

sample_rate: int = 384000

sample_rate_divider: int = 8

sleep_duration: int = 5

start_stop_period: List[StartStopPeriod]

time: int = 0

timezone_hours: int = 0

timezone_minutes: int = 0

class metamoth.config.Config1_5_0(time: int = 0, gain: int = 2, clock_divider: int = 4, acquisition_cycles: int = 16, oversample_rate: int = 1, sample_rate: int = 384000, sample_rate_divider: int = 8, sleep_duration: int = 5, record_duration: int = 55, enable_led: bool = True, active_start_stop_periods: bool = False, start_stop_period: ~typing.List[~metamoth.config.StartStopPeriod] = <factory>, timezone_hours: int = 0, enable_low_voltage_cutoff: bool = False, disable_battery_level_display: bool = False, timezone_minutes: int = 0, disable_sleep_record_cycle: bool = False, earliest_recording_time: int = 0, latest_recording_time: int = 0, lower_filter_freq: int = 0, higher_filter_freq: int = 0, amplitude_threshold: int = 0, require_acoustic_configuration: bool = False, battery_level_display_type: ~metamoth.enums.BatteryLevelDisplayType = BatteryLevelDisplayType.BATTERY_LEVEL, minimum_amplitude_threshold_duration: int = 0)

Bases: object

AudioMoth configuration for version 1.5.0.

acquisition_cycles: int = 16

active_start_stop_periods: bool = False

amplitude_threshold: int = 0

battery_level_display_type: BatteryLevelDisplayType = 1

clock_divider: int = 4

disable_battery_level_display: bool = False

disable_sleep_record_cycle: bool = False

earliest_recording_time: int = 0

enable_led: bool = True

enable_low_voltage_cutoff: bool = False

gain: int = 2

higher_filter_freq: int = 0

latest_recording_time: int = 0

lower_filter_freq: int = 0

minimum_amplitude_threshold_duration: int = 0

oversample_rate: int = 1

record_duration: int = 55

require_acoustic_configuration: bool = False

sample_rate: int = 384000

sample_rate_divider: int = 8

sleep_duration: int = 5

start_stop_period: List[StartStopPeriod]

time: int = 0

timezone_hours: int = 0

timezone_minutes: int = 0

class metamoth.config.Config1_6_0(time: int = 0, gain: int = 2, clock_divider: int = 4, acquisition_cycles: int = 16, oversample_rate: int = 1, sample_rate: int = 384000, sample_rate_divider: int = 8, sleep_duration: int = 5, record_duration: int = 55, enable_led: bool = True, active_start_stop_periods: bool = True, start_stop_period: ~typing.List[~metamoth.config.StartStopPeriod] = <factory>, timezone_hours: int = 0, enable_low_voltage_cutoff: bool = True, disable_battery_level_display: bool = False, timezone_minutes: int = 0, disable_sleep_record_cycle: bool = False, earliest_recording_time: int = 0, latest_recording_time: int = 0, lower_filter_freq: int = 0, higher_filter_freq: int = 0, amplitude_threshold: int = 0, require_acoustic_configuration: bool = False, battery_level_display_type: ~metamoth.enums.BatteryLevelDisplayType = BatteryLevelDisplayType.BATTERY_LEVEL, minimum_trigger_duration: int = 0, enable_amplitude_threshold_decibel_scale: bool = False, amplitude_threshold_decibels: int = 0, enable_amplitude_threshold_percentage_scale: bool = False, amplitude_threshold_percentage_mantissa: int = 0, amplitude_threshold_percentage_exponent: int = 0, enable_energy_saver_mode: bool = False, disable_48_hz_dc_blocking_filter: bool = False)

Bases: object

AudioMoth configuration for version 1.6.0.

acquisition_cycles: int = 16

active_start_stop_periods: bool = True

amplitude_threshold: int = 0

amplitude_threshold_decibels: int = 0

amplitude_threshold_percentage_exponent: int = 0

amplitude_threshold_percentage_mantissa: int = 0

battery_level_display_type: BatteryLevelDisplayType = 1

clock_divider: int = 4

disable_48_hz_dc_blocking_filter: bool = False

disable_battery_level_display: bool = False

disable_sleep_record_cycle: bool = False

earliest_recording_time: int = 0

enable_amplitude_threshold_decibel_scale: bool = False

enable_amplitude_threshold_percentage_scale: bool = False

enable_energy_saver_mode: bool = False

enable_led: bool = True

enable_low_voltage_cutoff: bool = True

gain: int = 2

higher_filter_freq: int = 0

latest_recording_time: int = 0

lower_filter_freq: int = 0

minimum_trigger_duration: int = 0

oversample_rate: int = 1

record_duration: int = 55

require_acoustic_configuration: bool = False

sample_rate: int = 384000

sample_rate_divider: int = 8

sleep_duration: int = 5

start_stop_period: List[StartStopPeriod]

time: int = 0

timezone_hours: int = 0

timezone_minutes: int = 0

class metamoth.config.Config1_7_0(time: int = 0, gain: ~metamoth.enums.GainSetting = GainSetting.AM_GAIN_MEDIUM, clock_divider: int = 4, acquisition_cycles: int = 16, oversample_rate: int = 1, sample_rate: int = 384000, sample_rate_divider: int = 8, sleep_duration: int = 5, record_duration: int = 55, enable_led: bool = True, active_start_stop_periods: bool = True, start_stop_period: ~typing.List[~metamoth.config.StartStopPeriod] = <factory>, timezone_hours: int = 0, enable_low_voltage_cutoff: bool = True, disable_battery_level_display: bool = False, timezone_minutes: int = 0, disable_sleep_record_cycle: bool = False, earliest_recording_time: int = 0, latest_recording_time: int = 0, lower_filter_freq: int = 0, higher_filter_freq: int = 0, amplitude_threshold: int = 0, require_acoustic_configuration: bool = False, battery_level_display_type: ~metamoth.enums.BatteryLevelDisplayType = BatteryLevelDisplayType.BATTERY_LEVEL, minimum_trigger_duration: int = 0, enable_amplitude_threshold_decibel_scale: bool = False, amplitude_threshold_decibels: int = 0, enable_amplitude_threshold_percentage_scale: bool = False, amplitude_threshold_percentage_mantissa: int = 0, amplitude_threshold_percentage_exponent: int = 0, enable_energy_saver_mode: bool = False, disable_48_hz_dc_blocking_filter: bool = False, enable_time_settings_from_gps: bool = False, enable_magnetic_switch: bool = False, enable_low_gain_range: bool = False)

Bases: object

AudioMoth configuration for version 1.7.0.

Also valid for version 1.7.1.

acquisition_cycles: int = 16

active_start_stop_periods: bool = True

amplitude_threshold: int = 0

amplitude_threshold_decibels: int = 0

amplitude_threshold_percentage_exponent: int = 0

amplitude_threshold_percentage_mantissa: int = 0

battery_level_display_type: BatteryLevelDisplayType = 1

clock_divider: int = 4

disable_48_hz_dc_blocking_filter: bool = False

disable_battery_level_display: bool = False

disable_sleep_record_cycle: bool = False

earliest_recording_time: int = 0

enable_amplitude_threshold_decibel_scale: bool = False

enable_amplitude_threshold_percentage_scale: bool = False

enable_energy_saver_mode: bool = False

enable_led: bool = True

enable_low_gain_range: bool = False

enable_low_voltage_cutoff: bool = True

enable_magnetic_switch: bool = False

enable_time_settings_from_gps: bool = False

gain: GainSetting = 2

higher_filter_freq: int = 0

latest_recording_time: int = 0

lower_filter_freq: int = 0

minimum_trigger_duration: int = 0

oversample_rate: int = 1

record_duration: int = 55

require_acoustic_configuration: bool = False

sample_rate: int = 384000

sample_rate_divider: int = 8

sleep_duration: int = 5

start_stop_period: List[StartStopPeriod]

time: int = 0

timezone_hours: int = 0

timezone_minutes: int = 0

class metamoth.config.Config1_8_0(time: int = 0, gain: ~metamoth.enums.GainSetting = GainSetting.AM_GAIN_MEDIUM, clock_divider: int = 4, acquisition_cycles: int = 16, oversample_rate: int = 1, sample_rate: int = 384000, sample_rate_divider: int = 8, sleep_duration: int = 5, record_duration: int = 55, enable_led: bool = True, active_start_stop_periods: bool = True, start_stop_period: ~typing.List[~metamoth.config.StartStopPeriod] = <factory>, timezone_hours: int = 0, enable_low_voltage_cutoff: bool = True, disable_battery_level_display: bool = False, timezone_minutes: int = 0, disable_sleep_record_cycle: bool = False, earliest_recording_time: int = 0, latest_recording_time: int = 0, lower_filter_freq: int = 0, higher_filter_freq: int = 0, amplitude_threshold: int = 0, frequency_trigger_centre_frequency: int = 0, require_acoustic_configuration: bool = False, battery_level_display_type: ~metamoth.enums.BatteryLevelDisplayType = BatteryLevelDisplayType.BATTERY_LEVEL, minimum_trigger_duration: int = 0, frequency_trigger_window_length_shift: int = 0, frequency_trigger_threshold_percentage_mantissa: int = 0, frequency_trigger_threshold_percentage_exponent: int = 0, enable_amplitude_threshold_decibel_scale: bool = False, amplitude_threshold_decibels: int = 0, enable_amplitude_threshold_percentage_scale: bool = False, amplitude_threshold_percentage_mantissa: int = 0, amplitude_threshold_percentage_exponent: int = 0, enable_energy_saver_mode: bool = False, disable_48_hz_dc_blocking_filter: bool = False, enable_time_settings_from_gps: bool = False, enable_magnetic_switch: bool = False, enable_low_gain_range: bool = False, enable_frequency_trigger: bool = False, enable_daily_folders: bool = False)

Bases: object

AudioMoth configuration for version 1.8.0.

Also valid for version 1.8.1.

acquisition_cycles: int = 16

active_start_stop_periods: bool = True

amplitude_threshold: int = 0

amplitude_threshold_decibels: int = 0

amplitude_threshold_percentage_exponent: int = 0

amplitude_threshold_percentage_mantissa: int = 0

battery_level_display_type: BatteryLevelDisplayType = 1

clock_divider: int = 4

disable_48_hz_dc_blocking_filter: bool = False

disable_battery_level_display: bool = False

disable_sleep_record_cycle: bool = False

earliest_recording_time: int = 0

enable_amplitude_threshold_decibel_scale: bool = False

enable_amplitude_threshold_percentage_scale: bool = False

enable_daily_folders: bool = False

enable_energy_saver_mode: bool = False

enable_frequency_trigger: bool = False

enable_led: bool = True

enable_low_gain_range: bool = False

enable_low_voltage_cutoff: bool = True

enable_magnetic_switch: bool = False

enable_time_settings_from_gps: bool = False

frequency_trigger_centre_frequency: int = 0

frequency_trigger_threshold_percentage_exponent: int = 0

frequency_trigger_threshold_percentage_mantissa: int = 0

frequency_trigger_window_length_shift: int = 0

gain: GainSetting = 2

higher_filter_freq: int = 0

latest_recording_time: int = 0

lower_filter_freq: int = 0

minimum_trigger_duration: int = 0

oversample_rate: int = 1

record_duration: int = 55

require_acoustic_configuration: bool = False

sample_rate: int = 384000

sample_rate_divider: int = 8

sleep_duration: int = 5

start_stop_period: List[StartStopPeriod]

time: int = 0

timezone_hours: int = 0

timezone_minutes: int = 0

metamoth.enums module

Enums for the AudioMoth configurations and state.

class metamoth.enums.BatteryLevelDisplayType(value)

Bases: Enum

Battery level display type.

BATTERY_LEVEL = 1

NIMH_LIPO_BATTERY_VOLTAGE = 2

class metamoth.enums.BatteryState(value)

Bases: Enum

Battery state.

AM_BATTERY_3V6 = 1

AM_BATTERY_3V7 = 2

AM_BATTERY_3V8 = 3

AM_BATTERY_3V9 = 4

AM_BATTERY_4V0 = 5

AM_BATTERY_4V1 = 6

AM_BATTERY_4V2 = 7

AM_BATTERY_4V3 = 8

AM_BATTERY_4V4 = 9

AM_BATTERY_4V5 = 10

AM_BATTERY_4V6 = 11

AM_BATTERY_4V7 = 12

AM_BATTERY_4V8 = 13

AM_BATTERY_4V9 = 14

AM_BATTERY_FULL = 15

AM_BATTERY_LOW = 0

property volts: float

Return the battery voltage.

class metamoth.enums.ExtendedBatteryState(value)

Bases: Enum

Extended battery state.

AM_EXT_BAT_2V5 = 1

AM_EXT_BAT_2V6 = 2

AM_EXT_BAT_2V7 = 3

AM_EXT_BAT_2V8 = 4

AM_EXT_BAT_2V9 = 5

AM_EXT_BAT_3V0 = 6

AM_EXT_BAT_3V1 = 7

AM_EXT_BAT_3V2 = 8

AM_EXT_BAT_3V3 = 9

AM_EXT_BAT_3V4 = 10

AM_EXT_BAT_3V5 = 11

AM_EXT_BAT_3V6 = 12

AM_EXT_BAT_3V7 = 13

AM_EXT_BAT_3V8 = 14

AM_EXT_BAT_3V9 = 15

AM_EXT_BAT_4V0 = 16

AM_EXT_BAT_4V1 = 17

AM_EXT_BAT_4V2 = 18

AM_EXT_BAT_4V3 = 19

AM_EXT_BAT_4V4 = 20

AM_EXT_BAT_4V5 = 21

AM_EXT_BAT_4V6 = 22

AM_EXT_BAT_4V7 = 23

AM_EXT_BAT_4V8 = 24

AM_EXT_BAT_4V9 = 25

AM_EXT_BAT_FULL = 26

AM_EXT_BAT_LOW = 0

property volts: float

Return the battery voltage.

class metamoth.enums.FilterType(value)

Bases: Enum

Filter type.

BAND_PASS = 3

HIGH_PASS = 4

LOW_PASS = 2

NO_FILTER = 1

class metamoth.enums.GainSetting(value)

Bases: Enum

Gain setting.

AM_GAIN_HIGH = 4

AM_GAIN_LOW = 0

AM_GAIN_LOW_MEDIUM = 1

AM_GAIN_MEDIUM = 2

AM_GAIN_MEDIUM_HIGH = 3

class metamoth.enums.RecordingState(value)

Bases: Enum

Recording state.

FILE_SIZE_LIMITED = 2

MAGNETIC_SWITCH = 6

MICROPHONE_CHANGED = 5

RECORDING_OKAY = 1

SDCARD_WRITE_ERROR = 7

SUPPLY_VOLTAGE_LOW = 3

SWITCH_CHANGED = 4

metamoth.mediainfo module

Get media information from a WAV file.

The WAV file must be a PCM WAV file. The WAV file must have a fmt chunk and a data chunk. The WAV file must have a samplerate and channels information in the fmt chunk.

class metamoth.mediainfo.MediaInfo(samplerate_hz: int, duration_s: float, samples: int, channels: int)

Bases: object

Media information.

channels: int

Number of channels.

duration_s: float

Duration in seconds.

samplerate_hz: int

Sample rate in Hz.

samples: int

Number of samples.

metamoth.mediainfo.get_media_info(wav: BinaryIO, chunk: Chunk) → MediaInfo

Return the media information from the WAV file.

Parameters

wavBinaryIO

Open file object of the WAV file.

chunkChunk

The RIFF chunk info, which is the root chunk. Should include the fmt and data chunks as subchunks.

Returns

MediaInfo

metamoth.metadata module

Module with AM Metadata structure for different firmware versions.

This module contains the AMMetadata class and its subclasses for different firmware versions.

class metamoth.metadata.AMMetadata(path: str, firmware_version: str, samplerate_hz: int, duration_s: float, samples: int, channels: int, audiomoth_id: str, datetime: datetime, timezone: timezone, gain: GainSetting, comment: str, low_battery: bool, battery_state_v: float, recording_state: Optional[RecordingState] = RecordingState.RECORDING_OKAY, temperature_c: Optional[float] = None, amplitude_threshold: Optional[AmplitudeThreshold] = None, frequency_filter: Optional[FrequencyFilter] = None, deployment_id: Optional[int] = None, external_microphone: bool = False, minimum_trigger_duration_s: Optional[int] = None, frequency_trigger: Optional[FrequencyTrigger] = None)

Bases: CommentMetadataV6, MediaInfo, ExtraMetadata

AudioMoth recording metadata.

class metamoth.metadata.AmplitudeThreshold(enabled: bool, threshold: int)

Bases: object

Amplitude threshold applied to the recording.

enabled: bool

True if the amplitude threshold is enabled.

threshold: int

Amplitude threshold.

class metamoth.metadata.CommentMetadata(audiomoth_id: str, datetime: datetime, timezone: timezone, gain: GainSetting, comment: str, low_battery: bool, battery_state_v: float)

Bases: object

Base class for AudioMoth metadata stored in comment.

audiomoth_id: str

AudioMoth ID. This is the serial number of the AudioMoth.

battery_state_v: float

Battery state in volts.

comment: str

Full comment string.

datetime: datetime

Datetime of the recording.

gain: GainSetting

Gain setting of the AudioMoth.

low_battery: bool

True if the battery is low.

timezone: timezone

Timezone of the recording.

class metamoth.metadata.CommentMetadataV1(audiomoth_id: str, datetime: datetime, timezone: timezone, gain: GainSetting, comment: str, low_battery: bool, battery_state_v: float)

Bases: CommentMetadata

AudioMoth recording metadata in comment string.

Valid for versions 1.0, 1.0.1, 1.1.0, 1.2.0,

Timezone is always UTC for versions 1.0 and 1.0.1. For versions 1.1.0 and 1.2.0, the an UTC hour offset can be set in the AudioMoth settings.

audiomoth_id: str

AudioMoth ID. This is the serial number of the AudioMoth.

battery_state_v: float

Battery state in volts.

comment: str

Full comment string.

datetime: datetime

Datetime of the recording.

gain: GainSetting

Gain setting of the AudioMoth.

low_battery: bool

True if the battery is low.

timezone: timezone

Timezone of the recording.

class metamoth.metadata.CommentMetadataV2(audiomoth_id: str, datetime: datetime, timezone: timezone, gain: GainSetting, comment: str, low_battery: bool, battery_state_v: float, recording_state: RecordingState)

Bases: CommentMetadata

AudioMoth recording metadata in comment string.

Valid for versions 1.2.1, 1.2.2, 1.3.0

recording_state: RecordingState

Recording state of the AudioMoth.

class metamoth.metadata.CommentMetadataV3(audiomoth_id: str, datetime: datetime, timezone: timezone, gain: GainSetting, comment: str, low_battery: bool, battery_state_v: float, recording_state: RecordingState, temperature_c: float, amplitude_threshold: AmplitudeThreshold, frequency_filter: FrequencyFilter)

Bases: CommentMetadata

AudioMoth recording metadata in comment string.

Valid for versions 1.4.0, 1.4.1, 1.4.2, 1.4.3, 1.4.4

amplitude_threshold: AmplitudeThreshold

Amplitude threshold applied to the recording.

frequency_filter: FrequencyFilter

Frequency filter applied to the recording.

recording_state: RecordingState

Recording state of the AudioMoth.

temperature_c: float

Temperature in degrees Celsius.

class metamoth.metadata.CommentMetadataV4(audiomoth_id: str, datetime: datetime, timezone: timezone, gain: GainSetting, comment: str, low_battery: bool, battery_state_v: float, recording_state: RecordingState, temperature_c: float, amplitude_threshold: AmplitudeThreshold, frequency_filter: FrequencyFilter, deployment_id: Optional[int], external_microphone: bool)

Bases: CommentMetadata

AudioMoth recording metadata in comment string.

Valid for version 1.5.0

amplitude_threshold: AmplitudeThreshold

Amplitude threshold applied to the recording.

deployment_id: Optional[int]

Deployment ID of the AudioMoth.

external_microphone: bool

True if an external microphone is connected to the AudioMoth.

frequency_filter: FrequencyFilter

Frequency filter applied to the recording.

recording_state: RecordingState

Recording state of the AudioMoth.

temperature_c: float

Temperature in degrees Celsius.

class metamoth.metadata.CommentMetadataV5(audiomoth_id: str, datetime: datetime, timezone: timezone, gain: GainSetting, comment: str, low_battery: bool, battery_state_v: float, recording_state: RecordingState, temperature_c: float, amplitude_threshold: AmplitudeThreshold, frequency_filter: FrequencyFilter, deployment_id: Optional[str], external_microphone: bool, minimum_trigger_duration_s: int)

Bases: CommentMetadata

AudioMoth recording metadata in comment string.

Valid for versions 1.6.0, 1.7.0 and 1.7.1

amplitude_threshold: AmplitudeThreshold

Amplitude threshold applied to the recording.

deployment_id: Optional[str]

Deployment ID of the AudioMoth.

external_microphone: bool

True if an external microphone is connected to the AudioMoth.

frequency_filter: FrequencyFilter

Frequency filter applied to the recording.

minimum_trigger_duration_s: int

Minimum trigger duration in seconds.

recording_state: RecordingState

Recording state of the AudioMoth.

temperature_c: float

Temperature in degrees Celsius.

class metamoth.metadata.CommentMetadataV6(audiomoth_id: str, datetime: datetime, timezone: timezone, gain: GainSetting, comment: str, low_battery: bool, battery_state_v: float, recording_state: Optional[RecordingState] = RecordingState.RECORDING_OKAY, temperature_c: Optional[float] = None, amplitude_threshold: Optional[AmplitudeThreshold] = None, frequency_filter: Optional[FrequencyFilter] = None, deployment_id: Optional[int] = None, external_microphone: bool = False, minimum_trigger_duration_s: Optional[int] = None, frequency_trigger: Optional[FrequencyTrigger] = None)

Bases: CommentMetadata

AudioMoth recording metadata in comment string.

Valid for versions 1.8.0 and 1.8.1

amplitude_threshold: Optional[AmplitudeThreshold] = None

Amplitude threshold applied to the recording.

deployment_id: Optional[int] = None

Deployment ID of the AudioMoth.

external_microphone: bool = False

True if an external microphone is connected to the AudioMoth.

frequency_filter: Optional[FrequencyFilter] = None

Frequency filter applied to the recording.

frequency_trigger: Optional[FrequencyTrigger] = None

Frequency trigger metadata.

minimum_trigger_duration_s: Optional[int] = None

Minimum trigger duration in seconds.

recording_state: Optional[RecordingState] = 1

Recording state of the AudioMoth.

temperature_c: Optional[float] = None

Temperature in degrees Celsius.

class metamoth.metadata.ExtraMetadata(path: str, firmware_version: str)

Bases: object

Extra metadata.

firmware_version: str

Firmware version of the AudioMoth.

path: str

Path to the recording.

class metamoth.metadata.FrequencyFilter(type: FilterType, higher_frequency_hz: Optional[int], lower_frequency_hz: Optional[int])

Bases: object

Frequency filter applied to the recording.

higher_frequency_hz: Optional[int]

Higher filter frequency in Hz. None if no upper filter is applied.

lower_frequency_hz: Optional[int]

Lower filter frequency in Hz. None if no lower filter is applied.

type: FilterType

Filter type applied to the recording.

class metamoth.metadata.FrequencyTrigger(enabled: bool, centre_frequency_hz: int, window_length_shift: int)

Bases: object

Frequency trigger metadata.

centre_frequency_hz: int

Centre frequency in Hz.

enabled: bool

True if frequency trigger is enabled.

window_length_shift: int

Window length shift in samples.

metamoth.metadata.assemble_metadata(path: str, media_info: MediaInfo, comment_metadata: dict, artist: Optional[str]) → AMMetadata

Assemble the metadata for the recording.

Parameters

media_infodict

Media information dictionary.

metadatadict

Metadata dictionary.

artiststr

Artist string. Can be None.

Returns

metadataAMMetadataV6

Metadata object.

metamoth.metamoth module

Main module.

metamoth.metamoth.parse_metadata(path: Union[PathLike, str]) → AMMetadata

Parse the metadata from an AudioMoth recording.

Parameters

path : PathLike

Returns

Metadata

Parse metadata from the recording at path. The metadata is returned as a AMMetadata object.

metamoth.parsing module

Functions for parsing the comment string of AudioMoth recordings.

exception metamoth.parsing.MessageFormatError

Bases: Exception

Exception raised when the message format is not correct.

metamoth.parsing.db_to_amplitude(db_value: float) → int

Convert dB values to amplitude threshold value.

metamoth.parsing.parse_comment(comment: str) → dict

Parse the comment string into a dictionary of metadata.

Parameters

comment : str

Returns

metadata : dict

metamoth.parsing.parse_comment_version_1_0(comment: str) → CommentMetadataV1

Parse the comment string of 1.0 firmware.

Parameters

commentstr

The comment string.

Returns

metadata : dict

metamoth.parsing.parse_comment_version_1_0_1(comment: str) → CommentMetadataV1

Parse the comment string of 1.0.1 firmware.

Also valid for version 1.1.0.

Parameters

comment : str

Returns

metadata: CommentMetadataV1

metamoth.parsing.parse_comment_version_1_2_0(comment: str) → CommentMetadataV1

Parse the comment string of 1.2.0 firmware.

Parameters

comment : str

Returns

metadata: CommentMetadataV1

metamoth.parsing.parse_comment_version_1_2_1(comment: str) → CommentMetadataV2

Parse the comment string of 1.2.1 firmware.

Parameters

comment : str

Returns

metadata: CommentMetadataV2

metamoth.parsing.parse_comment_version_1_2_2(comment: str) → CommentMetadataV2

Parse the comment string of 1.2.2 firmware.

Also valid for version 1.3.0.

Parameters

comment : str

Returns

metadata: CommentMetadataV2

metamoth.parsing.parse_comment_version_1_4_0(comment: str) → CommentMetadataV3

Parse the comment string of 1.4.0 firmware.

Also valid for version 1.4.1.

Parameters

comment : str

Returns

metadata: CommentMetadataV3

metamoth.parsing.parse_comment_version_1_4_2(comment: str) → CommentMetadataV3

Parse the comment string of 1.4.2 firmware.

Also valid for versions 1.4.3 and 1.4.4.

Parameters

comment : str

Returns

metadata: CommentMetadataV3

metamoth.parsing.parse_comment_version_1_6_0(comment: str) → CommentMetadataV5

Parse the comment string of 1.6.0 firmware.

Parameters

comment : str

Returns

metadata: CommentMetadataV5

metamoth.parsing.percentage_to_amplitude(percentage: float) → int

Convert percentage values to amplitude threshold value.