virittaa

audio metadata analyzer
Log | Files | Refs | README | LICENSE

README.md (2947B)

      1 # virittaa
      2 [![builds.sr.ht status](https://builds.sr.ht/~mtmn/virittaa.svg)](https://builds.sr.ht/~mtmn/virittaa?)
      3 
      4 A command-line tool that analyzes audio files to detect `BPM` and `Key` tags.
      5 
      6 ## Features
      7 
      8 * Detect BPM and Key of audio files
      9 * Write detected BPM and Key to metadata tags
     10 * Save track metadata to a database (on by default)
     11 * Query the database by artist, key, BPM range, or regex
     12 * Import tracks from a Mixxx SQLite database
     13 
     14 ## Building
     15 
     16 To build the project, run:
     17 
     18 ```sh
     19 cargo build --release
     20 ```
     21 
     22 ## Usage
     23 
     24 ```sh
     25 ./target/release/virittaa [OPTIONS] [PATH]...
     26 ```
     27 
     28 ### Arguments
     29 
     30 *   `[PATH]...`: Files or directories to analyze. Not required when using database query flags.
     31 
     32 ### Options
     33 
     34 *   `-t`, `--write-tags`: Write detected BPM and Key to audio file metadata.
     35 *   `--no-store`: Skip saving track reports to the database.
     36 *   `-f`, `--force`: Re-analyze files that already have BPM/Key tags.
     37 *   `-j`, `--jobs <JOBS>`: Number of threads (0 = all cores).
     38 *   `-l`, `--list`: List track reports in the database.
     39 *   `--limit <N>`: Max entries to list (default: 1000, 0 = all).
     40 *   `--query <KEY>`: Look up a track by exact key.
     41 *   `-S`, `--search <PATTERN>`: Search track reports by regex.
     42 *   `-a`, `--artist <PREFIX>`: Find tracks by artist name prefix.
     43 *   `--key <PREFIX>`: Find tracks by key prefix (e.g. 'C Major', 'Am').
     44 *   `--bpm <MIN> <MAX>`: Find tracks with BPM in range MIN MAX.
     45 *   `--import-mixxx <PATH>`: Import tracks from a Mixxx SQLite database.
     46 *   `--db-path <PATH>`: Database directory (default: `~/.local/share/virittaa`).
     47 *   `-h`, `--help`: Print help information.
     48 *   `-V`, `--version`: Print version information.
     49 
     50 ### Examples
     51 
     52 ```sh
     53 # Analyze a single file (saves to DB by default)
     54 ./target/release/virittaa /path/to/track.mp3
     55 
     56 # Analyze a directory and write metadata tags
     57 ./target/release/virittaa --write-tags /path/to/music/
     58 
     59 # Re-analyze files that already have tags
     60 ./target/release/virittaa --force --write-tags /path/to/music/
     61 
     62 # Analyze without saving to the database
     63 ./target/release/virittaa --no-store /path/to/music/
     64 
     65 # Limit to 4 threads
     66 ./target/release/virittaa -j 4 /path/to/music/
     67 
     68 # Write tags and use a custom database path
     69 ./target/release/virittaa -t --db-path ~/my_library /path/to/music/
     70 
     71 # List tracks in the database (default limit: 1000)
     72 ./target/release/virittaa --list
     73 
     74 # List all tracks (no limit)
     75 ./target/release/virittaa --list --limit 0
     76 
     77 # Look up a specific track
     78 ./target/release/virittaa --query "Aphex Twin - Xtal"
     79 
     80 # Search by regex
     81 ./target/release/virittaa --search 'weed'
     82 ./target/release/virittaa --search '^Aphex'
     83 
     84 # Find all tracks by an artist
     85 ./target/release/virittaa --artist 'Aphex Twin'
     86 
     87 # Find all tracks in a key
     88 ./target/release/virittaa --key 'C Major'
     89 
     90 # Find tracks with BPM between 120 and 140
     91 ./target/release/virittaa --bpm 120 140
     92 
     93 # Import from a Mixxx database
     94 ./target/release/virittaa --import-mixxx ~/.mixxx/mixxxdb.sqlite
     95 ```