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

Project links

Data verified by PyPI on
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for HakubaCode from gravatar.com HakubaCode

Credits

Author: HakubaCode

GitHub Statistics

Data verified by PyPI on 
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python <3.13, >=3.10

Tags

cli ffmpeg music recognition shazam

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

songid-0.1.0.tar.gz (5.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

songid-0.1.0-py3-none-any.whl (5.6 kB view details)

Uploaded Python 3

File details

Details for the file songid-0.1.0.tar.gz.

File metadata

  • Download URL: songid-0.1.0.tar.gz
  • Upload date:
  • Size: 5.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for songid-0.1.0.tar.gz
Algorithm Hash digest
SHA256 a1a498471ddbb5126a874b41d0755f1066750ed6f9ccc25e5f952bad001e0aeb
MD5 2e669f00381c6d164564e46d81936e2d
BLAKE2b-256 55723e5d7e4d3aad2b5652010fb4c78e40208cbc9d2dc0b757b2c02de4df7a55

See more details on using hashes here.

Provenance

The following attestation bundles were made for songid-0.1.0.tar.gz:

Publisher: publish.yml on HakubaCode/songid

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file songid-0.1.0-py3-none-any.whl.

File metadata

  • Download URL: songid-0.1.0-py3-none-any.whl
  • Upload date:
  • Size: 5.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for songid-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 ebaa3ee8d0a7fbb6c9ca19adf87baef93c339bd5e9d169b805994ee0acf6d3c7
MD5 329c1ac267ccf81950467d2610b1ca0a
BLAKE2b-256 ab356667efecc9a287ebec63f28db5254d5fd7fb6b626cadeb44fc560f4dee8f

See more details on using hashes here.

Provenance

The following attestation bundles were made for songid-0.1.0-py3-none-any.whl:

Publisher: publish.yml on HakubaCode/songid

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page