abracadabra: Sound recognition in Python¶
abracadabra à la Shazam
abracadabra is sound recogniser written in Python. It is an implementation of the Shazam paper: An Industrial Strength Audio Search Algorithm.
Read the docs here or read an explanation of how it works.
What can you use it for?¶
abracadabra works like Shazam. You register songs in advance and then later you can use your computer’s microphone to identify what song is playing. It could be used (as part of another system) to:
Align multiple videos of the same event using the audio
De-duplicate your music library
Installation¶
First, clone or download this repository:
git clone https://github.com/notexactlyawe/abracadabra.git
Next, install the dependencies abracadabra relies on. On Ubuntu you can install them with the following line:
sudo apt-get install gcc portaudio19-dev python3-dev ffmpeg
Now you can use pip to install the project:
cd abracadabra
pip install .
Usage as a script¶
Installing the project through pip will install the song_recogniser script. To see all the options you can pass to the script, run the following:
song_recogniser --help
Below is an example of how you can use song_recogniser:
$ song_recogniser initialise
Initialised DB
$ song_recogniser register ~/Music/CoolArtist/AwesomeAlbum
$ song_recogniser recognise --listen # records a 10 second clip for recognition
ALSA ...
* recording
* done recording
('CoolArtist', 'AwesomeAlbum', 'SweetTrack')
Usage as a library¶
You can use abracadabra as part of your own project by using it as a library. The main modules you’ll be interested in are the recognise and settings modules.
Most functions in the library are documented. If you want to use lower-level components in your project, please take a look at the docs.
Issues and contributing¶
If you encounter an issue with abracadabra or have a suggestion for improving the project, please create an issue!
Pull requests are welcome, but please create an issue first to discuss what you intend to do.
This project is maintained by Cameron MacLeod.
Getting Started¶
Installation¶
First, create a virtual environment to install the dependencies and activate it:
virtualenv -p python3 venv
source venv/bin/activate
Next, install the pre-requisites for the Python packages. On Ubuntu, you can do this using:
sudo apt-get install gcc portaudio19-dev python3-dev ffmpeg
Now install the project with:
pip install .
If you have problems with dependency clashes, then try running the following:
pip install -r requirements.txt
pip install .
requirements.txt contains a set of dependencies that are known to work together.
Basic usage¶
abracadabra is best used as a library in other projects, but a simple script for song recognition is included. Once you’ve installed abracadabra, then the script will be available by running the following command:
song_recogniser --help
song_recogniser provides three commands that you can use.
initialise: Creates the database in which fingerprints are stored.register: Takes a file or a directory and registers it to the database.recognise: Recognises a song. Takes a filename, or listens using your computer’s microphone.
Below is an example where song_recogniser is used:
$ song_recogniser initialise
Initialised DB
$ song_recogniser register ~/Music/CoolArtist/AwesomeAlbum
$ song_recogniser recognise --listen # records a 10 second clip for recognition
ALSA ...
* recording
* done recording
('CoolArtist', 'AwesomeAlbum', 'SweetTrack')
The source code for this simple application is under abracadbra/scripts/song_recogniser.py.
abracadabra¶
Documentation¶
Pre-requisites¶
The abracadabra docs are written using Sphinx. Everything you need to work on the docs is described in docs/requirements.txt.
cd docs
virtualenv -p python3 venv
source venv/bin/activate
pip install -r requirements.txt
Building the docs¶
The docs come with a Makefile that builds the docs for you. The easiest way to get started writing the docs is to run the livehtml command.
make livehtml
This will start a live-reloading server that is accessible from localhost:8000.