Pyzam 0.13.1

Recognize and Visualize Songs in Your CLI

Pyzam is a free CLI music recognition tool for audio and mixtapes in Python.

Installation

Dependencies

Pyzam requires ffmpeg installed.

Installation

Using uv (recommended):

uv tool run pyzam --speaker

Using pip:

$ pip install pyzam

Using environment.yml with Conda (installs ffmpeg for you):

conda env create -n pyzam --file=environment.yml

conda activate pyzam

Usage

Using uv:

uv tool run pyzam --speaker

Using pip:

# Listen to speaker (5 seconds by default)
pyzam --speaker

# Listen to microphone
pyzam --microphone

# Listen to audio files
pyzam --input audio_file.mp3

# Listen to audio via URL
pyzam --url "https://archive.org/download/09-hold-me-in-your-arms/02%20-%20Never%20Gonna%20Give%20You%20Up.mp3"

# Loop the recognition continously and save the logs as CSV file
pyzam --speaker -d 10 --write --loop

# Listen to mixtapes and save the logs as CSV file
pyzam --input audio_file.mp3 --duration 12 --mixtape

See pyzam --help for more options.

Options

Argument name	Description
--input	Detects from the given audio input file.
--microphone, -m	Listens to the microphone of your device.
--speaker, -s	Listens to the speaker of your device (default).
--url, -u	Detects from the given URL to an audio file.
--help, -h	Show usage, options and exit.
--duration, -d	Length of microphone or speaker recording. Max = 12 seconds.
--quiet, -q	Supresses the operation messages (i.e. Recording speaker for X seconds...).
--loop, -l	Loop the recognition process indefinitely.
--mixtape	Detects every -d seconds for a given input file, only works with --input. --write is enabled automatically.
--json, -j	Return the whole Shazamio output in JSON.
--write, -w	Writes the output of as a CSV file.

Known Limitations

Shazam API Call Limit (Error 429)

Shazam allows up to 20 requests per minute. Hence, a proxy is recommended to speed up recognition when using --mixtape.

12 Second Duration Limit per request

The maximum sample duration that Shazam allows is 12 seconds. Any audio after 12 seconds will not be recieved by Shazam.