audfprint

By default, audfprint stores time in the bottom 14 bits of each database entry. This means tracks longer than approximately 6 minutes (2^14 * 0.023s) will have aliased time offsets.

To support longer tracks, increase the --maxtimebits value:

• Example: --maxtimebits 16 increases the range to ~25 minutes at 11 kHz.

Trade-off: Increasing --maxtimebits reduces the number of bits available to store the track ID. This reduces the total number of unique tracks the database can distinguish (e.g., the default 14 bits allows for 2^18 = 262k tracks; increasing bits reduces this capacity).

Merge into an existing database

Use merge to add the contents of one database into another existing database.

python audfprint.py merge --dbase fpdbase.pklz fpdbase0.pklz

Create a new database from multiple existing ones

Use newmerge to combine two or more existing databases into a brand new database file.

python audfprint.py newmerge --dbase fpdbase_new.pklz fpdbase.pklz fpdbase0.pklz

Use dpwe_matcher.py to identify query soundfiles against an existing database.

Usage: ./dpwe_matcher.py <queries.list> <db> <matches.out>

• <queries.list>: A text file containing the paths to the query soundfiles.
• <db>: The directory containing the database created by dpwe_builder.py.
• <matches.out>: The output file where matches will be written.

Output Format: The <matches.out> file contains one line per entry in <queries.list> using a tab-separated format: <path_from_queries>\t<matching_file_from_ref>

If no match is found for a query, the second field is left blank.

./dpwe_matcher.py queries.list db matches.out

To use audfprint, you must install the required Python packages and ensure that the ffmpeg binary is installed and available in your system's PATH.

1. Install Python dependencies:

pip install -r requirements.txt

2. Verify ffmpeg installation:

ffmpeg -V

Create a new database

Use the new command to initialize a database from a set of reference audio files. Use --dbase <name> to specify the database filename.

python audfprint.py new --dbase fpdbase.pklz Nine_Lives/0*.mp3

Add tracks to an existing database

Use the add command to append more reference tracks to a database you have already created.

python audfprint.py add --dbase fpdbase.pklz Nine_Lives/1*.mp3

dpwe-audfprint runs under Python (ideally Python 2.7.3 on Ubuntu) and requires librosa and docopt. Note that librosa may also require matplotlib.

Follow these steps to set up the environment and download the source code:

# Install dependencies
pip install librosa
pip install docopt

# Download and extract the code
wget https://github.com/dpwe/audfprint/archive/master.zip
unzip master.zip
cd audfprint-master

Use dpwe_builder.py to create a fingerprint database from a list of soundfiles.

Usage: ./dpwe_builder.py <ref.list> <db>

• <ref.list>: A text file containing the paths to the reference soundfiles.
• <db>: The directory where the database will be stored.

mkdir db
./dpwe_builder.py ref.list db

Both the builder and matcher accept an optional configuration file using the -C flag. This allows you to tune the fingerprinting parameters.

Usage: ./dpwe_builder.py -C <config.txt> <ref.list> <db> ./dpwe_matcher.py -C <config.txt> <queries.list> <db> <matches.out>

Configurable Parameters:

• density: Approximate number of landmarks per second.
• fanout: Number of hashes per landmark.
• ncores: Number of CPU cores to use for multiprocessing.

Available Example Configurations:

• config.txt: density=70, fanout=8 (Default)
• config_low.txt: density=50, fanout=6 (Faster, less accurate)
• config2_high.txt: density=100, fanout=10 (Slower, more accurate)
• config2_tiny.txt: density=20, fanout=3 (Very fast/small reference database)

./dpwe_builder.py -C config.txt ref.list db

To find where a query audio fragment (e.g., a recording of music playing in the background) exists within your fingerprint database, use the match command.

python audfprint.py match --dbase fpdbase.pklz query.mp3

By default, the tool reports the matched file and the timestamp within that file where the match begins.

If you need to know the specific duration and time range that matches in both the query and the reference file (rather than just a single starting timestamp), use the --find-time-range flag with the match command.

python audfprint.py match --dbase fpdbase.pklz query.mp3 --find-time-range

Note: These time ranges are calculated by discarding a small proportion of matches at the extreme ends of the match region to avoid spurious results. This proportion is controlled by the --time-quantile option (default is 0.05, though the README text mentions 0.01 in its example context; check the CLI help for the current default).

The audfprint tool is a command-line utility for landmark-based audio fingerprinting. The general usage pattern is:

python audfprint.py <command> [options] [<file>]...

Available commands:

• new: Create a new fingerprint database.
• add: Append new files to an existing database.
• match: Identify noisy query excerpts within the database.
• precompute: Write *.fpt files containing precomputed fingerprints for input .wav files.
• merge: Combine previously created databases into an existing database.
• newmerge: Combine existing databases to create a new one.
• list: Treat input files as lists rather than audio files.
• remove: Remove entries (implied by command list).

python audfprint.py (new | add | match | precompute | merge | newmerge | list | remove) [options] [<file>]...