General content based audio search scheme.
Panako is an acoustic fingerprinting system. The system is able to extract fingerprints from an audio stream, and either store those fingerprints in a database, or find a match between the extracted fingerprints and stored fingerprints. The main unique feature of Panako is audio query can be identified reliably and quickly even if it has been sped up, time stretched or pitch shifted with respect to the reference audio. For more, see Why Panako?.
This document covers installation, usage and configuration of Panako.
Panako is licensed under the GNU Affero General Public License.
Content based music search algorithms make it possible to identify a small audio fragment in a digital music archive with potentially millions of songs. Current search algorithms are able to respond quickly and reliably on an audio query, even if there is noise or other distortions present. During the last decade they have been used successfully in end user applications like digital music archive management tools, Shazam and Sound Search for Google Play – two music identification service for smartphones – and for digital rights management tools.
However, the current algorithms, as they are described in the literature, do not allow substantial changes in replay speed. The speed of the audio query needs to be the same as the reference audio for the current algorithms to work. This poses a problem, since changes in replay speed do occur commonly, they are either introduced by accident during an analog to digital conversion or are introduced deliberately.
Extensive historical music archives usually have a large diversity of analogue physical media such as wax cylinders, wire recordings, magnetic tapes and grammophone records. When these media are digitized aberrations can be introduced when using an incorrect or varying playback speed. Even when calibrated mechanical devices are used in a digitization process, the media could already have been recorded at an undesirable speed. A music search algorithm should therefore allow changes in replay speed to correctly detect duplicates in music archives.
Next to accidental speed changes, deliberate speed manipulations are sometimes introduced during radio broadcasts: occasionally songs are played a bit faster to fit into a timeslot. During a DJ-set speed changes are almost always present. To correctly identify audio in these cases as well, a music search algorithm robust against pitch shifting, time stretching and speed changes is desired.
Alternative open source music identification systems are audfprint and echoprint. However, the algorithm implemented in Panako is unique insofar that it allows such speed changes while maintaining other desired features as scalability, robustness and reliability.
The following assumes a UNIX like machine. For an installation on Windows, follow the same steps, but adapt accordingly. To get started, download the Panako software. The download contains the following folders:
panako contains the main JAR-file panako.jar with configuration files.src contains the Java source files.lib contains the dependencies (Jar-files).build contains an ant build file to compile Panako and the documentation. Use ant release to build the source and compile a Panako JAR-file.doc contains documentation for the source files, generated with javadoc.To use Panako follow the following steps:
avconv utility included in libav. avconv should be installed correctly and available on the path. Alternatively, Panako can be configured to use any utility that can pipe decoded audio streams in the format PCM, 44.1kHZ,one channel, 16bit per sample. Libav version 9 or later is advised. On a Debian like system:apt-get install libav-toolspanako directory to e.g. /opt: sudo cp panako /opt/panako. To allow easy access to Panako either add the provided startup script in panako/panako to your path, or simply copy it to a directory already in your path: cp panako/panako /usr/bin/. If this does not work, you can still call Panako using java -jar /opt/panako/panako.jar [..args]:panako.panako -v #prints version
panako stats #db infoPanako is a command line application, it can be called using panako subapplication [argument...]. For each task Panako has to perform, there is a subapplication. There are subapplications to store fingerprints, query audio fragments, monitor audio streams, and so on. Each subapplication has its own list of arguments, options, and output format that define the behavior of the subapplication.
To save some keystrokes the name of the subapplication can be shortened using a unique prefix. For example panako m file.mp3 is expanded to panako monitor file.mp3. Since both stats and store are valid subapplications the store call can be shortened to panako sto *.mp3, panako s *.mp3 gives an invalid application message.
What follows is a list of those subapplications, their arguments, and respective goal.
panako storeThe store instruction extracts fingerprints from audio tracks and stores those in the datastorage. The command expects a list of audio files, video files or a text file with a list of file names.
#Audio is converted automatically panako store audio.mp3 audio.ogg audio.flac audio.wav#The first audio stream of video containers formats is used. panako store audio.mpc audio.mp4 audio.acc audio.avi audio.ogv audio.wma#Glob characters can be practical panako store */*.mp3#A text file with audio files can be used as well #The following searches for all mp3's (recursively) and #stores them in a text file find . -name '*.mp3' > list.txt #Iterate the list panako store list.txt
panako queryThe query command extracts fingerprints from a short audio frament and tries to match the fingerprints with the database.
panako query short_audio.mp3panako statsThe stats command prints statistics about the stored fingerprints and the number of audio fragments. If an integer argument is given it keeps printing the stats every x seconds.
panako stats # print stats once
panako stats 20 # print stats every 20s @panako configThe config subapplication prints the configuration currently in use.
panako configTo override configuration values there are two options. The first option is to create a configuration file, by default at the following location: /opt/config.properties. The configuration file is a properties text file. An example configuration file should be included in this distribution at release/config.properties.
The second option to override configuration values is by adding them to the arguments of the command line call as follows:
panako subapplication CONFIG_KEY=valueFor example, if you do not want to check for duplicate files while building a fingerprint database the following can be done:
panako store file.mp3 CHECK_FOR_DUPLICATES=FALSEThe configuration values provided as a command line argument have priority over the ones in the configuration file. If there is no value configured a default is used automatically. To find out which configuration options are available and their respective functions, consult the documented example configuration file release/config.properties.
Panako supports several playlist types: M3U, PLS, and ASX. For each playlist type only the first audio stream is fetched and processed. If an video container format is given, also the first stream is handled. The supported audio formats depend on the installed libav library. To consult the list of supported formats on your system check the following.
avconv -decoders | grep -E "^A" | sort
avconv version 9.8, Copyright (c) 2000-2013 the Libav developers
built on Aug 26 2013 09:52:20 with gcc 4.4.3 (Ubuntu 4.4.3-4ubuntu5.1)
A... 8svx_exp 8SVX exponential
A... 8svx_fib 8SVX fibonacci
A... aac AAC (Advanced Audio Coding)
A... aac_latm AAC LATM (Advanced Audio Coding LATM syntax)
A... ac3 ATSC A/52A (AC-3)
A... adpcm_4xm ADPCM 4X Movie
...