Metadata-Version: 2.4
Name: yt-music-id
Version: 1.0.0
Summary: Identify music from any segment of a YouTube video using Shazam
Project-URL: Homepage, https://github.com/yourname/yt-music-id
Project-URL: Repository, https://github.com/yourname/yt-music-id
Project-URL: Issues, https://github.com/yourname/yt-music-id/issues
Author: Rex
License-Expression: MIT
License-File: LICENSE
Keywords: audio,identification,music,shazam,youtube
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.9
Requires-Dist: shazamio>=0.8.0
Requires-Dist: yt-dlp>=2023.1.1
Description-Content-Type: text/markdown

# yt-music-id

Identify music from any segment of a YouTube video. Point it at a URL and a time range — it'll pull the audio, slice the clip, and Shazam it.

## Install

```bash
pip install yt-music-id
```

**Prerequisites:** [ffmpeg](https://ffmpeg.org/) must be installed and on your PATH.

## Usage

### CLI

```bash
# By start + end time
yt-music-id "https://youtube.com/watch?v=xyz" --start 1:23 --end 1:45

# By start + duration (seconds)
yt-music-id "https://youtube.com/watch?v=xyz" --start 0:30 --duration 15

# Just start time (defaults to 10s clip)
yt-music-id "https://youtube.com/watch?v=xyz" --start 2:00

# Auto-split long segments (recommended for anything >15s)
yt-music-id "https://youtube.com/watch?v=xyz" --start 7:00 --end 8:00 --multi

# Raw JSON output
yt-music-id "https://youtube.com/watch?v=xyz" --start 1:00 --end 1:20 --json

# Keep extracted audio files
yt-music-id "https://youtube.com/watch?v=xyz" --start 1:00 --keep-files
```

### Python API

```python
import asyncio
from yt_music_id import download_audio, extract_segment, identify_music, print_match

async def find_song():
    # Download audio
    path, title, duration = download_audio(
        "https://youtube.com/watch?v=xyz", "/tmp/raw"
    )

    # Extract a segment (7:00 to 7:15)
    extract_segment(path, "/tmp/clip.mp3", start=420, duration=15)

    # Identify
    result = await identify_music("/tmp/clip.mp3")

    # Print result
    if result.get("track"):
        print_match(result["track"], video_title=title)

asyncio.run(find_song())
```

## Options

| Flag | Description |
|------|-------------|
| `--start TIME` | Start time (required). Formats: `1:30`, `90`, `0:01:30` |
| `--end TIME` | End time. Mutually exclusive with `--duration` |
| `--duration SEC` | Duration in seconds. Default: 10 |
| `--multi` | Auto-split long segments into 10s overlapping chunks for better accuracy |
| `--json` | Output raw Shazam JSON instead of formatted text |
| `--keep-files` | Don't delete temp audio files after identification |

## Tips

- **5-15 seconds** is the sweet spot for Shazam recognition
- Use `--multi` for anything over 15 seconds — it auto-chops into overlapping 10s slices
- Works best when the music is prominent (less dialogue/SFX over it)
- Some montage videos use original/custom music that won't be in Shazam's database
- Requires `ffmpeg` on PATH — install via `brew install ffmpeg`, `apt install ffmpeg`, or [ffmpeg.org](https://ffmpeg.org/download.html)

## License

MIT
