Skip to content

Commit 272c904

Browse files
unmadeunmade
committed
Reformat README.md
1 parent e2779f5 commit 272c904

File tree

2 files changed

+118
-79
lines changed

2 files changed

+118
-79
lines changed

‎README.rst

+115-76
Original file line numberDiff line numberDiff line change
@@ -1,141 +1,180 @@
1-
==========
1+
----
22

33
audiomatch
44

5-
==========
5+
----
66

77
.. image:: https://github.com/unmade/audiomatch/workflows/lint%20and%20test/badge.svg?branch=master
8-
:alt: Build Status
9-
:target: https://github.com/unmade/audiomatch/blob/master/.github/workflows/lint-and-test.yml
8+
:alt: Build Status
9+
:target: https://github.com/unmade/audiomatch/blob/master/.github/workflows/lint-and-test.yml
1010

1111
.. image:: https://codecov.io/gh/unmade/audiomatch/branch/master/graph/badge.svg
12-
:alt: Coverage Status
13-
:target: https://codecov.io/gh/unmade/audiomatch
12+
:alt: Coverage Status
13+
:target: https://codecov.io/gh/unmade/audiomatch
1414

1515
.. image:: https://img.shields.io/pypi/v/audiomatch.svg
16-
:alt: PyPI Package latest release
17-
:target: https://pypi.org/project/audiomatch
16+
:alt: PyPI Package latest release
17+
:target: https://pypi.org/project/audiomatch
1818

1919
.. image:: https://img.shields.io/badge/License-MIT-purple.svg
20-
:alt: MIT License
21-
:target: https://github.com/unmade/audiomatch/blob/master/LICENSE
20+
:alt: MIT License
21+
:target: https://github.com/unmade/audiomatch/blob/master/LICENSE
2222

2323
A small command-line tool to find similar audio files
2424

25-
Installation
26-
============
25+
##############
26+
Installation
27+
##############
2728

28-
First, install the Chromaprint_ fingerprinting library by Lukáš Lalinský. (The library itself depends on an FFT library, but it's smart enough to use an algorithm from software you probably already have installed; see the Chromaprint page for details.)
29+
First, install the Chromaprint_ fingerprinting library by Lukáš
30+
Lalinský. (The library itself depends on an FFT library, but it's smart
31+
enough to use an algorithm from software you probably already have
32+
installed; see the Chromaprint page for details.)
2933

3034
Then you can install this library:
3135

32-
.. code-block:: bash
36+
.. code:: bash
3337
34-
pip install audiomatch
38+
pip install audiomatch
3539
36-
To perform tasks quickly, *audiomatch* requires a C compiler and Python headers to be installed. You can skip the compilation by setting the ``AUDIOMATCH_NO_EXTENSIONS`` environment variable:
40+
To perform tasks quickly, *audiomatch* requires a C compiler and Python
41+
headers to be installed. You can skip the compilation by setting the
42+
``AUDIOMATCH_NO_EXTENSIONS`` environment variable:
3743

38-
.. code-block:: bash
44+
.. code:: bash
3945
40-
AUDIOMATCH_NO_EXTENSIONS=1 pip install audiomatch
46+
AUDIOMATCH_NO_EXTENSIONS=1 pip install audiomatch
4147
42-
You can avoid installing all these libraries on your computer and run everything in Docker:
48+
You can avoid installing all these libraries on your computer and run
49+
everything in Docker:
4350

44-
.. code-block:: bash
51+
.. code:: bash
4552
46-
docker run --rm -v "$(pwd)":/tmp fdooch/audiomatch "/tmp/*"
53+
docker run --rm -v "$(pwd)":/tmp fdooch/audiomatch "/tmp/*"
4754
48-
Quickstart
49-
==========
55+
############
56+
Quickstart
57+
############
5058

5159
Suppose we have a directory with Nirvana songs:
5260

53-
.. code-block:: bash
61+
.. code:: bash
5462
55-
$ ls demo
56-
All Apologies (In Utero).m4a Dumb (Unplugged in NYC).m4a
57-
All Apologies (Unplugged in NYC).m4a Pennyroyal Tea (In Utero).m4a
58-
Dumb (In Utero).m4a Pennyroyal Tea (Solo Acoustic).mp3
59-
Dumb (Radio Appearance, 1991).mp3 Pennyroyal Tea (Unplugged in NYC).m4a
63+
$ ls demo
64+
All Apologies (In Utero).m4a Dumb (Unplugged in NYC).m4a
65+
All Apologies (Unplugged in NYC).m4a Pennyroyal Tea (In Utero).m4a
66+
Dumb (In Utero).m4a Pennyroyal Tea (Solo Acoustic).mp3
67+
Dumb (Radio Appearance, 1991).mp3 Pennyroyal Tea (Unplugged in NYC).m4a
6068
6169
Let's find out which files sound similar:
6270

63-
.. code-block:: bash
71+
.. code:: bash
6472
65-
$ audiomatch --length 300 ./demo
66-
These files sound similar:
73+
$ audiomatch --length 300 ./demo
74+
These files sound similar:
6775
68-
./demo/All Apologies (In Utero).m4a
69-
./demo/All Apologies (Unplugged in NYC).m4a
76+
./demo/All Apologies (In Utero).m4a
77+
./demo/All Apologies (Unplugged in NYC).m4a
7078
71-
---
79+
---
7280
73-
./demo/Dumb (In Utero).m4a
74-
./demo/Dumb (Unplugged in NYC).m4a
81+
./demo/Dumb (In Utero).m4a
82+
./demo/Dumb (Unplugged in NYC).m4a
7583
76-
---
84+
---
7785
78-
./demo/Pennyroyal Tea (In Utero).m4a
79-
./demo/Pennyroyal Tea (Solo Acoustic).mp3
80-
./demo/Pennyroyal Tea (Unplugged in NYC).m4a
86+
./demo/Pennyroyal Tea (In Utero).m4a
87+
./demo/Pennyroyal Tea (Solo Acoustic).mp3
88+
./demo/Pennyroyal Tea (Unplugged in NYC).m4a
8189
8290
*Note #1: Input audio files should be at least 10 seconds long.*
8391

8492
*Note #2: In some rare cases, false positives are possible.*
8593

86-
What's happening here is that *audiomatch* takes all audio files from the directory and compares them with each other.
94+
What's happening here is that *audiomatch* takes all audio files from
95+
the directory and compares them with each other.
8796

88-
You can also compare a file with another file, a file and a directory, or a directory with another directory. If you need to, you can provide glob-style patterns, but don't forget to quote them, because otherwise the shell will expand it for you. For example, let's compare all ``.mp3`` files with ``.m4a`` files:
97+
You can also compare a file with another file, a file and a directory,
98+
or a directory with another directory. If you need to, you can provide
99+
glob-style patterns, but don't forget to quote them, because otherwise
100+
the shell will expand it for you. For example, let's compare all
101+
``.mp3`` files with ``.m4a`` files:
89102

90-
.. code-block:: bash
103+
.. code:: bash
91104
92-
$ audiomatch "./demo/*.mp3" "./demo/*.m4a"
93-
These files sound similar:
105+
$ audiomatch "./demo/*.mp3" "./demo/*.m4a"
106+
These files sound similar:
94107
95-
../demo/Pennyroyal Tea (Solo Acoustic).mp3
96-
../demo/Pennyroyal Tea (Unplugged in NYC).m4a
108+
../demo/Pennyroyal Tea (Solo Acoustic).mp3
109+
../demo/Pennyroyal Tea (Unplugged in NYC).m4a
97110
98-
This time, *audiomatch* took all files with the ``.mp3`` extension and compared them with all files with the ``.m4a`` extension.
111+
This time, *audiomatch* took all files with the ``.mp3`` extension and
112+
compared them with all files with the ``.m4a`` extension.
99113

100-
Note how there is no In Utero version in the output. The reason it is present in the previous output is because it is actually similar to the Unplugged version, and then the transitive law applies: if ``a = b`` and ``b = c``, then ``a = c``.
114+
Note how there is no In Utero version in the output. The reason it is
115+
present in the previous output is because it is actually similar to the
116+
Unplugged version, and then the transitive law applies: if ``a = b`` and
117+
``b = c``, then ``a = c``.
101118

102-
--length
103-
--------
119+
**********
120+
--length
121+
**********
104122

105-
The ``--length`` option specifies how many seconds to take for analysis from the song. The default value is 120, and it is good enough to find exactly the same song, but maybe in different quality. However, for more complicated cases like the same song played in a different tempo, the more input we have, the more accurate results are.
123+
The ``--length`` option specifies how many seconds to take for analysis
124+
from the song. The default value is 120, and it is good enough to find
125+
exactly the same song, but maybe in different quality. However, for more
126+
complicated cases like the same song played in a different tempo, the
127+
more input we have, the more accurate results are.
106128

107-
--extension
108-
-----------
129+
*************
130+
--extension
131+
*************
109132

110-
By default, ``audiomatch`` looks for files with ``.m4a``, ``.mp3``, ``.caf`` extensions. In theory, audio formats supported by ffmpeg_ are also supported by *audiomatch*. You can tell *audiomatch* to look for a specific format by using the ``--extension`` flag:
133+
By default, ``audiomatch`` looks for files with ``.m4a``, ``.mp3``,
134+
``.caf`` extensions. In theory, audio formats supported by ffmpeg_ are
135+
also supported by *audiomatch*. You can tell *audiomatch* to look for a
136+
specific format by using the ``--extension`` flag:
111137

112-
.. code-block:: bash
138+
.. code:: bash
113139
114-
$ audiomatch -e .ogg -e .wav ./demo
115-
Not enough input files.
140+
$ audiomatch -e .ogg -e .wav ./demo
141+
Not enough input files.
116142
117-
Indeed, we tried to compare files with ``.ogg`` and ``.wav`` extensions, but there are no such files in the demo directory.
143+
Indeed, we tried to compare files with ``.ogg`` and ``.wav`` extensions,
144+
but there are no such files in the demo directory.
118145

119-
Motivation
120-
==========
146+
############
147+
Motivation
148+
############
121149

122-
I play guitar and do recordings from time to time, mainly with Voice Memos on iPhone. Over the years, I have hundreds of recordings like that, and I thought it would be cool to find all the similar ones and see how I have progressed over the years.
150+
I play guitar and do recordings from time to time, mainly with Voice
151+
Memos on iPhone. Over the years, I have hundreds of recordings like
152+
that, and I thought it would be cool to find all the similar ones and
153+
see how I have progressed over the years.
123154

124155
That's why I wrote this library.
125156

126-
References
127-
==========
157+
############
158+
References
159+
############
128160

129-
- Chromaprint_ and pyacoustid_ libraries
130-
- `Example: How to compare fingerprints`_
131-
- `Example: How to compare shifted fingerprints`_ (note: the code is a little bit weird)
132-
- `Explanation: How to compare fingerprints`_
133-
- `Popcount in Python with benchmarks`_
161+
- Chromaprint_ and pyacoustid_ libraries
162+
- `Example: How to compare fingerprints`_
163+
- `Example: How to compare shifted fingerprints`_ (note: the code is a
164+
little bit weird)
165+
- `Explanation: How to compare fingerprints`_
166+
- `Popcount in Python with benchmarks`_
167+
168+
.. _chromaprint: https://github.com/acoustid/chromaprint
169+
170+
.. _example: how to compare fingerprints: https://gist.github.com/lalinsky/1132166
171+
172+
.. _example: how to compare shifted fingerprints: https://medium.com/@shivama205/audio-signals-comparison-23e431ed2207
173+
174+
.. _explanation: how to compare fingerprints: https://groups.google.com/forum/#!msg/acoustid/Uq_ASjaq3bw/kLreyQgxKmgJ
134175

135-
.. _Chromaprint: https://github.com/acoustid/chromaprint
136-
.. _`Example: How to compare fingerprints`: https://gist.github.com/lalinsky/1132166
137-
.. _`Example: How to compare shifted fingerprints`: https://medium.com/@shivama205/audio-signals-comparison-23e431ed2207
138-
.. _`Explanation: How to compare fingerprints`: https://groups.google.com/forum/#!msg/acoustid/Uq_ASjaq3bw/kLreyQgxKmgJ
139176
.. _ffmpeg: http://ffmpeg.org
140-
.. _`Popcount in Python with benchmarks`: http://www.valuedlessons.com/2009/01/popcount-in-python-with-benchmarks.html
141-
.. _`pyacoustid`: https://github.com/beetbox/pyacoustid
177+
178+
.. _popcount in python with benchmarks: http://www.valuedlessons.com/2009/01/popcount-in-python-with-benchmarks.html
179+
180+
.. _pyacoustid: https://github.com/beetbox/pyacoustid

‎tox.ini

+3-3
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,8 @@ setenv =
1818
{py,py38}-noextensions: AUDIOMATCH_NO_EXTENSIONS = 1
1919
usedevelop = false
2020
deps =
21-
pytest
22-
pytest-cov
21+
pytest>=7,<8
22+
pytest-cov>=3,<4
2323
commands =
2424
pytest --cov -vvv tests {posargs:.}
2525

@@ -34,7 +34,7 @@ skip_install = True
3434
setenv =
3535
COVERAGE_FILE = {toxworkdir}/.coverage
3636
deps =
37-
coverage
37+
coverage>=6.4,<7
3838
commands =
3939
coverage combine
4040
coverage report --fail-under=100

0 commit comments

Comments
 (0)