https://github.com/lukafilipxvic/pyzam
Recognize and Visualise Songs in Your CLI
https://github.com/lukafilipxvic/pyzam
cli music music-recognition python pyzam shazam
Last synced: 10 months ago
JSON representation
Recognize and Visualise Songs in Your CLI
- Host: GitHub
- URL: https://github.com/lukafilipxvic/pyzam
- Owner: lukafilipxvic
- License: mit
- Created: 2023-06-22T04:57:03.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2025-06-12T10:54:02.000Z (about 1 year ago)
- Last Synced: 2025-09-02T06:32:40.821Z (10 months ago)
- Topics: cli, music, music-recognition, python, pyzam, shazam
- Language: Python
- Homepage:
- Size: 191 MB
- Stars: 69
- Watchers: 3
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
Pyzam is a free CLI music recognition tool for audio and mixtapes in Python.
## Installation
### Dependencies
Pyzam requires [ffmpeg](https://git.ffmpeg.org/ffmpeg.git 'Download ffmpeg') installed.
### Installation
Using uv (recommended):
```bash
uv tool run pyzam --speaker
```
Using pip:
```bash
$ 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:
```bash
uv tool run pyzam --speaker
```
Using pip:
```bash
# 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"
```
```bash
# 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.