Metadata-Version: 2.4
Name: khvgm
Version: 1.0.0
Summary: Fast, concurrent soundtrack downloader and search CLI for KHInsider
Author-email: liskadi <njdrecov@gmail.com>
License-Expression: MIT
Keywords: khinsider,soundtrack,downloader,vgm,audio,cli
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
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
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.0.0
Requires-Dist: mutagen>=1.46.0
Dynamic: license-file

# KHVGM

Concurrent CLI and Python library for searching and downloading soundtracks from [KHInsider](https://downloads.khinsider.com/).

Instead of scraping each track page one by one, `khvgm` unpacks the inline audio player script on the album page to resolve all track URLs in a single request, then streams files concurrently using `.part` temporary files.

## Installation

Requires Python 3.10+.

```bash
pip install khvgm
```

For local development from source:

```bash
pip install -e .
```

## Usage

```bash
# Download an album by ID or full URL
khvgm minecraft
khvgm https://downloads.khinsider.com/game-soundtracks/album/minecraft

# Prefer FLAC with MP3 fallback, using 6 workers into a custom folder
khvgm minecraft ./music/Minecraft -f flac,mp3 -w 6

# Inspect album info and tracklist without downloading
khvgm --info minecraft

# Filter by disc or track numbers and skip artwork scans
khvgm minecraft --disc 1 --no-images
khvgm minecraft --tracks 1-5,10 --no-images

# Search KHInsider
khvgm --search minecraft
```

## Options

| Option | Description |
| :--- | :--- |
| `soundtrack` | Album slug (`minecraft`), full album URL, or search query |
| `output_dir` | Destination directory (defaults to album title) |
| `-f, --format FORMATS` | Comma-separated format preference (e.g. `flac,mp3`) |
| `-s, --search` | Search for soundtracks |
| `-i, --info` | Print album metadata and track table without downloading |
| `-w, --workers N` | Concurrent download threads (default: `4`) |
| `--disc DISCS` | Filter discs (e.g. `1` or `1,3` or `1-2`) |
| `--tracks RANGE` | Filter tracks (e.g. `1-5,10`) |
| `--no-images` | Skip album artwork and scans |
| `--images-only` | Download only album artwork and scans |
| `--disc-subfolders` | Put multi-disc tracks into `Disc 1/`, `Disc 2/` subdirectories |
| `--overwrite` | Overwrite existing files |
| `--no-tags` | Skip writing missing ID3/FLAC tags |

## Library Usage

```python
from pathlib import Path
from khvgm import DownloadManager, fetch_soundtrack, search_soundtracks

results = search_soundtracks("minecraft")
album = fetch_soundtrack("minecraft")

manager = DownloadManager(workers=4)
report = manager.download_soundtrack(
    album,
    output_dir=Path("./downloads/minecraft"),
    format_order=["flac", "mp3"],
    include_images=False,
)
```
