songid 0.1.0

Identify the song playing in any audio or video file, right from your terminal.

songid

Identify the song playing in any audio or video file, right from your terminal.

Ever download a TikTok/Instagram clip and wonder what the music is? songid extracts the audio with ffmpeg, fingerprints it, and asks Shazam's recognition service what it is.

$ songid Download.mp4
Download.mp4: SABI & MIA BOYKA — Базовый минимум (Slow Version)
  https://www.shazam.com/track/852590911/...

Works on anything ffmpeg can read: .mp4, .mkv, .webm, .mp3, .m4a, .wav, .ogg, voice memos, screen recordings…

Install

Requires Python 3.10–3.12 and ffmpeg on your PATH.

# ffmpeg (if you don't have it)
winget install Gyan.FFmpeg     # Windows
brew install ffmpeg            # macOS
sudo apt install ffmpeg        # Debian/Ubuntu

# songid — pipx or uv keeps it isolated
pipx install songid
# or, from a checkout:
uv tool install .

Why Python ≤ 3.12? The shazamio dependency ships prebuilt wheels up to 3.12; on 3.13+ it tries to compile Rust from source. uv tool install --python 3.12 . handles this for you automatically.

Usage

songid clip.mp4                      # identify one file
songid *.mp4                         # batch — one line per file
songid song.mp3 --json               # machine-readable output
songid movie.mkv -s 3600 -d 15       # sample 15s starting at the 1-hour mark

Flag	Meaning	Default
-s, --offset SEC	Start sampling this many seconds into the file	0
-d, --duration SEC	Length of the audio sample	12
--json	JSON output (keyed by file path)	off

Exit codes: 0 match found · 1 file/ffmpeg error · 2 ran fine but no match.

Tips

• No match? Try a different --offset — aim for a part where the music is loud and vocals/melody are clear, not crowd noise or talking.
• 10–15 seconds of sample is the sweet spot; more isn't better.
• Low-bitrate audio (social media rips) still matches fine — Shazam's fingerprinting is robust to compression.

How it works

1. ffmpeg decodes a short sample (mono, 44.1 kHz WAV) from your file — video streams are ignored.
2. shazamio generates a spectral fingerprint of the sample and queries Shazam's recognition API.
3. The match (title, artist, album, genre, Shazam link) is printed.

Your file never leaves your machine — only the derived audio fingerprint is sent.

Limitations

• Uses Shazam's unofficial API via shazamio; heavy batch use may get rate-limited. Be reasonable.
• Instrumental covers, live edits, and sped-up/slowed "nightcore" versions may match the altered version or nothing at all.
• Needs an internet connection.

License

MIT