Metadata-Version: 2.4
Name: music_stain
Version: 0.1.6
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# Stain

Fast audio fingerprinting for Python

## Install
```bash
pip install music-stain
```

## Usage
```python
fp = music_stain.PyFingerprinter()
hashes = fp.fingerprint_file("song.wav")

for h in hashes:
    print(f"{h.hash} @ {h.time}")
```

## API

**`PyFingerprinter()`** - Create fingerprinter  
**`.fingerprint_file(path) -> list[PyHash]`** - Returns fingerprint hashes

**`PyHash`**  
**`.hash: int`** - Fingerprint hash value  
**`.time: int`** - Time offset (frames)

## Matching Example

**Build database:**
```python
db = {}
for h in fp.fingerprint_file("song.wav"):
    db.setdefault(h.hash, []).append(("song_id", h.time))
```

**Match query:**
```python
matches = {}
for h in fp.fingerprint_file("query.wav"):
    if h.hash in db:
        for song_id, db_time in db[h.hash]:
            offset = db_time - h.time
            matches[(song_id, offset)] = matches.get((song_id, offset), 0) + 1

best = max(matches.items(), key=lambda x: x[1])
print(f"Matched: {best[0][0]} with {best[1]} hits")
```

## Formats

WAV, MP3, FLAC, OGG, M4A, etc.

## License

MIT
