Metadata-Version: 2.4
Name: soundaudit
Version: 0.1.0
Summary: Music library health scanner and metadata repair tool
Project-URL: Homepage, https://github.com/nnunodev/soundaudit
Project-URL: Repository, https://github.com/nnunodev/soundaudit
Project-URL: Issues, https://github.com/nnunodev/soundaudit/issues
Author-email: Nuno <nnunodev@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Keywords: audio,duplicates,flac,metadata,music
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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
Requires-Python: >=3.10
Requires-Dist: mutagen>=1.47
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.31
Requires-Dist: rich>=13.0
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: textual>=0.58
Requires-Dist: typer>=0.12
Requires-Dist: xxhash>=3.4
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Requires-Dist: types-requests>=2.31; extra == 'dev'
Provides-Extra: fingerprint
Requires-Dist: pyacoustid>=1.3; extra == 'fingerprint'
Description-Content-Type: text/markdown

# SoundAudit

A Python-based music library health scanner and metadata repair tool for FLAC/MP3/OGG/M4A collections.

> ⚠️ **Beta — work in progress.** Expect rough edges and breaking changes. Back up your library before using the tag writeback features (`fix --apply`, `resolve --auto-write`).

## What It Does

SoundAudit scans your music library, extracts metadata, fingerprints audio, resolves canonical tags via MusicBrainz, detects transcodes and duplicates, then writes corrections back to your files all via terminal UI or scriptable CLI.

**Supported formats:** FLAC, MP3, M4A, OGG, WAVE, APE

| Feature | |
|---------|---|
| Parallel incremental directory scanning | ✅ |
| Content-hash duplicate detection | ✅ |
| AcoustID fingerprinting + fuzzy duplicates | ✅ |
| Spectral transcode detection (fake-FLAC) | ✅ |
| MusicBrainz metadata resolver | ✅ |
| Tag writeback with original backup | ✅ |
| Interactive TUI + JSON/CSV/Markdown export | ✅ |

## Quick Start

```bash
# Install from PyPI
pip install soundaudit

# Or install from source with uv
uv pip install -e ".[dev]"

# Launch the interactive TUI
soundaudit tui

# Scan your library
soundaudit scan ~/Music --workers 4

# Re-scan only changed files (near-instant)
soundaudit scan ~/Music

# Resolve MusicBrainz metadata + preview fixes
soundaudit resolve
soundaudit fix --fields artist,album,title,year

# Write corrected tags to files
soundaudit fix --apply

# Reports
soundaudit report                              # summary
soundaudit report --missing-tags               # incomplete metadata
soundaudit report --duplicates                 # duplicate groups with keeper recommendations
soundaudit report --transcodes                 # suspected fake-FLAC
soundaudit report --corrupt                    # unreadable files
soundaudit report --duplicates -o dups.json    # export to JSON

# Analysis passes (on already-scanned data)
soundaudit analyze --duplicates                # content-hash dups
soundaudit analyze --acoustid                  # fingerprint dups
soundaudit analyze --transcodes --workers 4    # spectral fake-FLAC detection
```

## Requirements

- **Python 3.10+**
- **ffmpeg** — required for spectral transcode detection (`analyze --transcodes`)
- **fpcalc** (chromaprint) — optional, for AcoustID fingerprinting (`analyze --acoustid`)

## Hash Strategies

| Strategy | Speed | Use Case |
|----------|-------|----------|
| `head-only` (default) | Fastest | Daily scans, slow/network storage |
| `head-tail` | Fast | Better collision resistance |
| `full` | Slow | Bit-perfect deduplication |
| `none` | Instant | Tag-only scanning |

## Configuration

Create `config.yaml` in your platform config directory (e.g. `~/.config/soundaudit/config.yaml` on Linux, `~/Library/Application Support/soundaudit/config.yaml` on macOS, `%APPDATA%\soundaudit\config.yaml` on Windows) or pass `--config`:

```yaml
scan:
  paths:
    - ~/Music
  extensions: [".flac", ".mp3", ".m4a"]
  workers: 4
  hash_strategy: head-only

fingerprinting:
  enabled: false
  fpcalc_path: /usr/bin/fpcalc
  api_key: "your-acoustid-key"

resolvers:
  rate_limit: 1.0
  retry_count: 3
```

```bash
soundaudit scan --config config.yaml
soundaudit tui --config config.yaml
```

Default database and logs are stored in platform-standard directories (e.g. `~/.local/share/soundaudit/` on Linux).

## Performance

- **Slow storage (network-attached, USB):** Use `--hash-strategy head-only`. Full-file hashing over high-latency storage is dramatically slower.
- **Incremental scans:** Unchanged files are skipped by mtime — subsequent scans are near-instant.
- **Parallel extraction:** Uses `ThreadPoolExecutor`; overhead is hidden by I/O latency on slow storage.

## License

MIT
