Metadata-Version: 2.4
Name: songid
Version: 0.1.0
Summary: Identify the song playing in any audio or video file, right from your terminal.
Project-URL: Repository, https://github.com/HakubaCode/songid
Project-URL: Issues, https://github.com/HakubaCode/songid/issues
Author: HakubaCode
License: MIT
License-File: LICENSE
Keywords: cli,ffmpeg,music,recognition,shazam
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Requires-Python: <3.13,>=3.10
Requires-Dist: shazamio>=0.6
Description-Content-Type: text/markdown

# 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.

```console
$ 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.

```bash
# 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

```bash
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](https://github.com/shazamio/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](LICENSE)
