{"id":13825546,"url":"https://github.com/unmade/audiomatch","last_synced_at":"2025-04-12T23:34:50.334Z","repository":{"id":58462853,"uuid":"251577100","full_name":"unmade/audiomatch","owner":"unmade","description":"Find similar audio files easily","archived":false,"fork":false,"pushed_at":"2024-11-19T22:23:07.000Z","size":145,"stargazers_count":147,"open_issues_count":2,"forks_count":14,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-04T03:09:05.086Z","etag":null,"topics":["audio-fingerprinting","chromaprint","command-line","cython","duplicate-detection","python","sound-analysis"],"latest_commit_sha":null,"homepage":null,"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/unmade.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-03-31T10:59:03.000Z","updated_at":"2025-03-25T12:20:19.000Z","dependencies_parsed_at":"2023-01-17T19:45:16.672Z","dependency_job_id":null,"html_url":"https://github.com/unmade/audiomatch","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unmade%2Faudiomatch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unmade%2Faudiomatch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unmade%2Faudiomatch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unmade%2Faudiomatch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unmade","download_url":"https://codeload.github.com/unmade/audiomatch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248647259,"owners_count":21139081,"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":["audio-fingerprinting","chromaprint","command-line","cython","duplicate-detection","python","sound-analysis"],"created_at":"2024-08-04T09:01:23.127Z","updated_at":"2025-04-12T23:34:50.294Z","avatar_url":"https://github.com/unmade.png","language":"Python","readme":"----\n\naudiomatch\n\n----\n\n.. image:: https://github.com/unmade/audiomatch/workflows/lint%20and%20test/badge.svg?branch=master\n   :alt: Build Status\n   :target: https://github.com/unmade/audiomatch/blob/master/.github/workflows/lint-and-test.yml\n\n.. image:: https://codecov.io/gh/unmade/audiomatch/branch/master/graph/badge.svg\n   :alt: Coverage Status\n   :target: https://codecov.io/gh/unmade/audiomatch\n\n.. image:: https://img.shields.io/pypi/v/audiomatch.svg\n   :alt: PyPI Package latest release\n   :target: https://pypi.org/project/audiomatch\n\n.. image:: https://img.shields.io/badge/License-MIT-purple.svg\n   :alt: MIT License\n   :target: https://github.com/unmade/audiomatch/blob/master/LICENSE\n\nA small command-line tool to find similar audio files\n\n##############\n Installation\n##############\n\nFirst, install the Chromaprint_ fingerprinting library by Lukáš\nLalinský. (The library itself depends on an FFT library, but it's smart\nenough to use an algorithm from software you probably already have\ninstalled; see the Chromaprint page for details.)\n\nThen you can install this library:\n\n.. code:: bash\n\n   pip install audiomatch\n\nTo perform tasks quickly, *audiomatch* requires a C compiler and Python\nheaders to be installed. You can skip the compilation by setting the\n``AUDIOMATCH_NO_EXTENSIONS`` environment variable:\n\n.. code:: bash\n\n   AUDIOMATCH_NO_EXTENSIONS=1 pip install audiomatch\n\nYou can avoid installing all these libraries on your computer and run\neverything in Docker:\n\n.. code:: bash\n\n   docker run --rm -v \"$(pwd)\":/tmp fdooch/audiomatch \"/tmp/*\"\n\n############\n Quickstart\n############\n\nSuppose we have a directory with Nirvana songs:\n\n.. code:: bash\n\n   $ ls demo\n   All Apologies (In Utero).m4a           Dumb (Unplugged in NYC).m4a\n   All Apologies (Unplugged in NYC).m4a   Pennyroyal Tea (In Utero).m4a\n   Dumb (In Utero).m4a                    Pennyroyal Tea (Solo Acoustic).mp3\n   Dumb (Radio Appearance, 1991).mp3      Pennyroyal Tea (Unplugged in NYC).m4a\n\nLet's find out which files sound similar:\n\n.. code:: bash\n\n   $ audiomatch --length 300 ./demo\n   These files sound similar:\n\n   ./demo/All Apologies (In Utero).m4a\n   ./demo/All Apologies (Unplugged in NYC).m4a\n\n   ---\n\n   ./demo/Dumb (In Utero).m4a\n   ./demo/Dumb (Unplugged in NYC).m4a\n\n   ---\n\n   ./demo/Pennyroyal Tea (In Utero).m4a\n   ./demo/Pennyroyal Tea (Solo Acoustic).mp3\n   ./demo/Pennyroyal Tea (Unplugged in NYC).m4a\n\n*Note #1: Input audio files should be at least 10 seconds long.*\n\n*Note #2: In some rare cases, false positives are possible.*\n\nWhat's happening here is that *audiomatch* takes all audio files from\nthe directory and compares them with each other.\n\nYou can also compare a file with another file, a file and a directory,\nor a directory with another directory. If you need to, you can provide\nglob-style patterns, but don't forget to quote them, because otherwise\nthe shell will expand it for you. For example, let's compare all\n``.mp3`` files with ``.m4a`` files:\n\n.. code:: bash\n\n   $ audiomatch \"./demo/*.mp3\" \"./demo/*.m4a\"\n   These files sound similar:\n\n   ../demo/Pennyroyal Tea (Solo Acoustic).mp3\n   ../demo/Pennyroyal Tea (Unplugged in NYC).m4a\n\nThis time, *audiomatch* took all files with the ``.mp3`` extension and\ncompared them with all files with the ``.m4a`` extension.\n\nNote how there is no In Utero version in the output. The reason it is\npresent in the previous output is because it is actually similar to the\nUnplugged version, and then the transitive law applies: if ``a = b`` and\n``b = c``, then ``a = c``.\n\n**********\n --length\n**********\n\nThe ``--length`` option specifies how many seconds to take for analysis\nfrom the song. The default value is 120, and it is good enough to find\nexactly the same song, but maybe in different quality. However, for more\ncomplicated cases like the same song played in a different tempo, the\nmore input we have, the more accurate results are.\n\n*************\n --extension\n*************\n\nBy default, ``audiomatch`` looks for files with ``.m4a``, ``.mp3``,\n``.caf`` extensions. In theory, audio formats supported by ffmpeg_ are\nalso supported by *audiomatch*. You can tell *audiomatch* to look for a\nspecific format by using the ``--extension`` flag:\n\n.. code:: bash\n\n   $ audiomatch -e .ogg -e .wav ./demo\n   Not enough input files.\n\nIndeed, we tried to compare files with ``.ogg`` and ``.wav`` extensions,\nbut there are no such files in the demo directory.\n\n############\n Motivation\n############\n\nI play guitar and do recordings from time to time, mainly with Voice\nMemos on iPhone. Over the years, I have hundreds of recordings like\nthat, and I thought it would be cool to find all the similar ones and\nsee how I have progressed over the years.\n\nThat's why I wrote this library.\n\n############\n References\n############\n\n-  Chromaprint_ and pyacoustid_ libraries\n-  `Example: How to compare fingerprints`_\n-  `Example: How to compare shifted fingerprints`_ (note: the code is a\n   little bit weird)\n-  `Explanation: How to compare fingerprints`_\n-  `Popcount in Python with benchmarks`_\n\n.. _chromaprint: https://github.com/acoustid/chromaprint\n\n.. _example: how to compare fingerprints: https://gist.github.com/lalinsky/1132166\n\n.. _example: how to compare shifted fingerprints: https://medium.com/@shivama205/audio-signals-comparison-23e431ed2207\n\n.. _explanation: how to compare fingerprints: https://groups.google.com/forum/#!msg/acoustid/Uq_ASjaq3bw/kLreyQgxKmgJ\n\n.. _ffmpeg: http://ffmpeg.org\n\n.. _popcount in python with benchmarks: http://www.valuedlessons.com/2009/01/popcount-in-python-with-benchmarks.html\n\n.. _pyacoustid: https://github.com/beetbox/pyacoustid\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funmade%2Faudiomatch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funmade%2Faudiomatch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funmade%2Faudiomatch/lists"}