README.md

# virittaa

A command-line tool that analyzes audio files to detect `BPM` and `Key` tags.

## Features

* Detect BPM and Key of audio files
* Write detected BPM and Key to metadata tags
* Save track metadata to a database
* Query the database by artist, key, BPM range, or regex

## Building

To build the project, run:

```sh
cargo build --release
```

## Usage

```sh
./target/release/virittaa [OPTIONS] [PATH]...
```

### Arguments

*   `[PATH]...`: One or more files or directories to analyze. Not required when using database query flags.

### Options

*   `-w`, `--write`: Write detected BPM and Key to audio file metadata.
*   `-f`, `--force`: Re-analyze files even if they already have BPM/Key tags.
*   `-j`, `--jobs <JOBS>`: Number of threads to use (0 = all cores).
*   `-S`, `--save`: Save track reports (artist, track, BPM, key) to the database.
*   `-l`, `--list`: List all track reports stored in the database.
*   `--query <KEY>`: Look up a track report by exact artist - track key.
*   `-s`, `--search <PATTERN>`: Search track reports by regex pattern (matched against key, artist, track, BPM, key).
*   `-a`, `--artist <PREFIX>`: Find tracks by artist name prefix (uses database index).
*   `--key <PREFIX>`: Find tracks by key prefix (uses database index).
*   `--bpm <MIN> <MAX>`: Find tracks with BPM in the given range (uses database index).
*   `--db-path <PATH>`: Path to the database directory (default: `~/.local/share/virittaa`).
*   `-h`, `--help`: Print help information.
*   `-V`, `--version`: Print version information.

### Examples

```sh
# Analyze a single file
./target/release/virittaa /path/to/track.mp3

# Analyze a directory and write metadata tags
./target/release/virittaa --write /path/to/music/

# Re-analyze files that already have tags
./target/release/virittaa --force --write /path/to/music/

# Limit to 4 threads
./target/release/virittaa -j 4 /path/to/music/

# Analyze and save reports to database
./target/release/virittaa --save /path/to/music/

# Write tags and save to database with custom path
./target/release/virittaa -w --save --db-path ~/my_library /path/to/music/

# List all tracks in the database
./target/release/virittaa --list

# Look up a specific track
./target/release/virittaa --query "Aphex Twin - Xtal"

# Search by regex
./target/release/virittaa --search 'weed'
./target/release/virittaa --search '^Aphex'

# Find all tracks by an artist (indexed, fast prefix scan)
./target/release/virittaa --artist 'Aphex Twin'

# Find all tracks in a key (indexed)
./target/release/virittaa --key 'C Major'

# Find tracks with BPM between 120 and 140 (indexed range query)
./target/release/virittaa --bpm 120 140
```