{"id":28097594,"url":"https://github.com/mbsantiago/metamoth","last_synced_at":"2025-05-13T17:24:16.388Z","repository":{"id":95613669,"uuid":"599216431","full_name":"mbsantiago/metamoth","owner":"mbsantiago","description":"Simple Python utility for parsing AudioMoth metadata","archived":false,"fork":false,"pushed_at":"2024-06-25T15:52:00.000Z","size":48600,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-12T12:08:18.192Z","etag":null,"topics":["acoustics","audiomoth","bioacoustics","metadata","pam","parser","python"],"latest_commit_sha":null,"homepage":"https://metamoth.readthedocs.io/en/latest/readme.html","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mbsantiago.png","metadata":{"files":{"readme":"README.rst","changelog":"HISTORY.rst","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-02-08T17:34:33.000Z","updated_at":"2024-06-25T15:51:59.000Z","dependencies_parsed_at":"2023-06-26T16:20:21.667Z","dependency_job_id":null,"html_url":"https://github.com/mbsantiago/metamoth","commit_stats":{"total_commits":71,"total_committers":3,"mean_commits":"23.666666666666668","dds":0.04225352112676062,"last_synced_commit":"084c43b8e6ded29ce99eb39aa8df89fef66b5e45"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mbsantiago%2Fmetamoth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mbsantiago%2Fmetamoth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mbsantiago%2Fmetamoth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mbsantiago%2Fmetamoth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mbsantiago","download_url":"https://codeload.github.com/mbsantiago/metamoth/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253991063,"owners_count":21995878,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acoustics","audiomoth","bioacoustics","metadata","pam","parser","python"],"created_at":"2025-05-13T17:24:15.827Z","updated_at":"2025-05-13T17:24:16.336Z","avatar_url":"https://github.com/mbsantiago.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"========\nmetamoth\n========\n\n.. image:: https://img.shields.io/pypi/v/metamoth.svg\n    :target: https://pypi.python.org/pypi/metamoth/\n    :alt: PyPI\n\n.. image:: https://github.com/mbsantiago/metamoth/workflows/Test/badge.svg?branch=main\n    :target: https://github.com/mbsantiago/metamoth/actions?query=workflow%3ATest\n    :alt: Test Status\n\n.. image:: https://github.com/mbsantiago/metamoth/workflows/Lint/badge.svg?branch=main\n    :target: https://github.com/mbsantiago/metamoth/actions?query=workflow%3ALint\n    :alt: Lint Status\n\n.. image:: https://codecov.io/gh/mbsantiago/metamoth/branch/main/graph/badge.svg\n    :target: https://codecov.io/gh/mbsantiago/metamoth\n    :alt: Code Coverage\n\n.. image:: https://img.shields.io/github/license/mashape/apistatus.svg\n    :target: https://pypi.python.org/pypi/metamoth/\n    :alt: License\n\n.. image:: https://pepy.tech/badge/metamoth\n    :target: https://pepy.tech/project/metamoth\n    :alt: Downloads\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n    :target: https://github.com/psf/black\n    :alt: Code Style\n\n.. image:: https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat\u0026labelColor=ef8336\n    :target: https://timothycrosley.github.io/isort/\n    :alt: Imports\n\nMetamoth is a Python package for parsing the metadata of AudioMoth_ files.\nCheck the full documentation at https://metamoth.readthedocs.io.\n\n.. _AudioMoth: https://www.openacousticdevices.info/audiomoth\n\nMotivation\n==========\n\nAudioMoth devices store valuable information in the audio file header. This\nincludes the device ID, the date and time of recording, gain\nsettings and battery state. The number of fields in the metadata is\ngrowing as new features are added to the AudioMoth firmware.\n\nHowever, the metadata is not designed to be easily parsed in a programmatic\nway. The data is stored as a string comment making it difficult to retrieve the\nindividual metadata fields. Additionally, the comment format is not well\ndocumented and changes between AudioMoth firmware versions.\n\nThis package helps by **quickly** parsing the metadata and returning an\nobject containing the metadata.\n\nUsage\n=====\n\nThe ``metamoth`` package provides a single function, ``parse_metadata``,\nwhich parses the metadata of an AudioMoth file and returns an object\ncontaining the metadata.\n\n.. code-block:: python\n\n    from metamoth import parse_metadata\n\n    metadata = parse_metadata('path/to/file')\n\nThe extracted metadata can be accessed as attributes of the object, as shown\n\n.. code-block:: python\n\n    duration = metadata.duration_s\n    path = metadata.path\n    # etc.\n\nExtracted Metadata\n------------------\n\nThe ``metadata`` variable is an object (of type `AMMetadata`_) containing the\nmetadata of the file.\n\nThe extracted metadata contains:\n\n* ``path``: the path of the audio file\n* ``firmware_version``: the firmware version of the AudioMoth that\n  recorded the file. Since the AudioMoth firmware version is not stored in the\n  recording, this is an estimate and may be incorrect.\n\nMedia Information\n\n* ``duration_s``: the duration of the file in seconds.\n* ``samplerate_hz``: the sample rate of the file in Hz.\n* ``channels``: the number of channels in the file.\n* ``samples``: the number of audio samples in the file.\n\nData extracted from the AudioMoth comment string:\n\n* ``datetime``: the date and time of the file in a datetime_ object.\n* ``timezone``: the timezone of the file as a timezone_ object.\n* ``audiomoth_id``: the ID of the AudioMoth that recorded the file.\n* ``battery_state_v``: the battery state of the AudioMoth that recorded\n  the file in Volts.\n* ``low_battery``: a boolean indicating if the battery state is low.\n* ``gain``: the gain setting of the AudioMoth that recorded the file.\n* ``comment``: the full comment string in the WAV header.\n\nThe following fields are only available for some AudioMoth firmware versions.\nNonetheless, they are always present in the metadata object, but may be\n``None``.\n\n* ``recording_state``: the recording state of the AudioMoth that recorded\n  the file.\n* ``temperature_c``: the temperature of the AudioMoth in Celsius.\n* ``amplitude_threshold``: information concerning the wether an amplitude\n  threshold was used and the threshold value.\n* ``frequency_filter``: information concerning the wether a frequency filter\n  was used and the filter settings.\n* ``deployment_id``: the deployment ID as set by the user.\n* ``external_microphone``: a boolean indicating if an external microphone was\n  used.\n* ``minimum_trigger_duration_s``: the minimum trigger duration in seconds.\n* ``frequency_trigger``: information concerning the wether a frequency trigger\n  was used and the trigger settings.\n\nThe following table shows the fields available for each AudioMoth firmware.\n\n+---------+-----------------+---------------+---------------------+------------------+---------------+---------------------+----------------------------+-------------------+\n| version | recording_state | temperature_c | amplitude_threshold | frequency_filter | deployment_id | external_microphone | minimum_trigger_duration_s | frequency_trigger |\n+=========+=================+===============+=====================+==================+===============+=====================+============================+===================+\n|   1.0   |        ✖        |       ✖       |          ✖          |        ✖         |       ✖       |          ✖          |             ✖              |         ✖         |\n+---------+-----------------+---------------+---------------------+------------------+---------------+---------------------+----------------------------+-------------------+\n|  1.0.1  |        ✖        |       ✖       |          ✖          |        ✖         |       ✖       |          ✖          |             ✖              |         ✖         |\n+---------+-----------------+---------------+---------------------+------------------+---------------+---------------------+----------------------------+-------------------+\n|  1.1.0  |        ✖        |       ✖       |          ✖          |        ✖         |       ✖       |          ✖          |             ✖              |         ✖         |\n+---------+-----------------+---------------+---------------------+------------------+---------------+---------------------+----------------------------+-------------------+\n|  1.2.0  |        ✖        |       ✖       |          ✖          |        ✖         |       ✖       |          ✖          |             ✖              |         ✖         |\n+---------+-----------------+---------------+---------------------+------------------+---------------+---------------------+----------------------------+-------------------+\n|  1.2.1  |        ✔        |       ✖       |          ✖          |        ✖         |       ✖       |          ✖          |             ✖              |         ✖         |\n+---------+-----------------+---------------+---------------------+------------------+---------------+---------------------+----------------------------+-------------------+\n|  1.2.2  |        ✔        |       ✖       |          ✖          |        ✖         |       ✖       |          ✖          |             ✖              |         ✖         |\n+---------+-----------------+---------------+---------------------+------------------+---------------+---------------------+----------------------------+-------------------+\n|  1.3.0  |        ✔        |       ✖       |          ✖          |        ✖         |       ✖       |          ✖          |             ✖              |         ✖         |\n+---------+-----------------+---------------+---------------------+------------------+---------------+---------------------+----------------------------+-------------------+\n|  1.4.0  |        ✔        |       ✔       |          ✔          |        ✔         |       ✖       |          ✖          |             ✖              |         ✖         |\n+---------+-----------------+---------------+---------------------+------------------+---------------+---------------------+----------------------------+-------------------+\n|  1.4.1  |        ✔        |       ✔       |          ✔          |        ✔         |       ✖       |          ✖          |             ✖              |         ✖         |\n+---------+-----------------+---------------+---------------------+------------------+---------------+---------------------+----------------------------+-------------------+\n|  1.4.2  |        ✔        |       ✔       |          ✔          |        ✔         |       ✖       |          ✖          |             ✖              |         ✖         |\n+---------+-----------------+---------------+---------------------+------------------+---------------+---------------------+----------------------------+-------------------+\n|  1.4.3  |        ✔        |       ✔       |          ✔          |        ✔         |       ✖       |          ✖          |             ✖              |         ✖         |\n+---------+-----------------+---------------+---------------------+------------------+---------------+---------------------+----------------------------+-------------------+\n|  1.4.4  |        ✔        |       ✔       |          ✔          |        ✔         |       ✖       |          ✖          |             ✖              |         ✖         |\n+---------+-----------------+---------------+---------------------+------------------+---------------+---------------------+----------------------------+-------------------+\n|  1.5.0  |        ✔        |       ✔       |          ✔          |        ✔         |       ✔       |          ✔          |             ✖              |         ✖         |\n+---------+-----------------+---------------+---------------------+------------------+---------------+---------------------+----------------------------+-------------------+\n|  1.6.0  |        ✔        |       ✔       |          ✔          |        ✔         |       ✔       |          ✔          |             ✔              |         ✖         |\n+---------+-----------------+---------------+---------------------+------------------+---------------+---------------------+----------------------------+-------------------+\n|  1.7.0  |        ✔        |       ✔       |          ✔          |        ✔         |       ✔       |          ✔          |             ✔              |         ✖         |\n+---------+-----------------+---------------+---------------------+------------------+---------------+---------------------+----------------------------+-------------------+\n|  1.7.1  |        ✔        |       ✔       |          ✔          |        ✔         |       ✔       |          ✔          |             ✔              |         ✖         |\n+---------+-----------------+---------------+---------------------+------------------+---------------+---------------------+----------------------------+-------------------+\n|  1.8.0  |        ✔        |       ✔       |          ✔          |        ✔         |       ✔       |          ✔          |             ✔              |         ✔         |\n+---------+-----------------+---------------+---------------------+------------------+---------------+---------------------+----------------------------+-------------------+\n|  1.8.1  |        ✔        |       ✔       |          ✔          |        ✔         |       ✔       |          ✔          |             ✔              |         ✔         |\n+---------+-----------------+---------------+---------------------+------------------+---------------+---------------------+----------------------------+-------------------+\n\n.. _datetime: https://docs.python.org/3/library/datetime.html#datetime.datetime\n.. _timezone: https://docs.python.org/3/library/datetime.html#timezone-objects\n.. _AMMetadata: https://metamoth.readthedocs.io/en/latest/metamoth.html#metamoth.metadata.AMMetadata\n\nSupported AudioMoth Firmware Versions\n=====================================\n\nIn the table below you can find the supported AudioMoth firmware versions.\n\n.. list-table:: Supported AudioMoth Firmware Versions\n   :widths: 20 20\n   :header-rows: 1\n\n   * - Firmware\n     - Supported\n   * - 1.0.0\n     - ✔\n   * - 1.0.1\n     - ✔\n   * - 1.1.0\n     - ✔\n   * - 1.2.0\n     - ✔\n   * - 1.2.1\n     - ✔\n   * - 1.2.2\n     - ✔\n   * - 1.3.0\n     - ✔\n   * - 1.4.0\n     - ✔\n   * - 1.4.1\n     - ✔\n   * - 1.4.2\n     - ✔\n   * - 1.4.3\n     - ✔\n   * - 1.4.4\n     - ✔\n   * - 1.5.0\n     - ✖\n   * - 1.6.0\n     - ✔\n   * - 1.7.0\n     - ✖\n   * - 1.7.1\n     - ✖\n   * - 1.8.0\n     - ✖\n   * - 1.8.1\n     - ✖\n\n\nSupport for newer firmware versions is planned, see the CONTRIBUTING_ section\nif you want to help!\n\n.. _CONTRIBUTING: https://github.com/mbsantiago/metamoth/blob/main/CONTRIBUTING.rst\n\nPerformance\n===========\n\nThe ``metamoth`` package is designed to be fast. It extracts\nall the required information from the first few bytes and avoids\nloading the audio data. Thus ``metamoth`` parsing times are\nnot affected by the size of the audio file.\n\nThe following table shows the parsing times of ``metamoth`` compared to `exif tool`_.\n\n+-----------------+-----------------+-----------------+-----------------+\n| File Size (MB)  | metamoth (ms)   | exiftool (ms)   | Speedup         |\n+=================+=================+=================+=================+\n| 7.3             | 0.0845          | 80              | ~1000x          |\n+-----------------+-----------------+-----------------+-----------------+\n| 44              | 0.0850          | 91.86           | ~1000x          |\n+-----------------+-----------------+-----------------+-----------------+\n\n\n.. _exif tool: https://exiftool.org/\n\nInstallation\n============\n\nThe ``metamoth`` package can be installed using ``pip``::\n\n    pip install metamoth\n\nCheck the installation section of the documentation_ for more\ninformation.\n\n.. _documentation: https://metamoth.readthedocs.io/en/latest/installation.html\n\nDocumentation\n=============\n\nThe documentation for the ``metamoth`` package is available at https://metamoth.readthedocs.io/en/latest/index.html.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmbsantiago%2Fmetamoth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmbsantiago%2Fmetamoth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmbsantiago%2Fmetamoth/lists"}