spektra-cli

Find out what is actually in your music library: files sold as lossless that were made from an MP3, CDs upsampled to hi-res, corrupt or truncated tracks, and the same song sitting in four folders in three formats.

spektra-cli is the command-line half of Spektra, a Windows desktop spectrum analyzer. Same analysis engine, no window, machine readable output. It is a self-contained native binary, so this package needs no .NET runtime.

Install

npm install -g spektra-cli

Or run it without installing:

npx spektra-cli audit ~/Music

ffmpeg is required

Decoding is done by ffmpeg, which this package does not bundle. Install it separately and make sure ffmpeg and ffprobe are on your PATH:

winget install ffmpeg          # Windows
brew install ffmpeg            # macOS
sudo apt install ffmpeg        # Debian, Ubuntu

ffmpeg is run as a separate process, never linked or bundled. The one command that works without it is manifest, which only lists files.

Commands

spektra-cli report <file|folder> ...   Bandwidth verdict per file.
spektra-cli scan <folder>              Compact bandwidth scan of a library.
spektra-cli check <file|folder> ...    Integrity check (corruption, missing data).
spektra-cli audit <file|folder> ...    Bandwidth and integrity together (cached).
spektra-cli dupes <folder> ...         Find duplicate songs across folders and formats.
spektra-cli manifest <folder>          List a folder with type chips (no decoding).
spektra-cli inventory <folder>         Tags and embedded cover art per file.
spektra-cli loudness <file|folder> ... Loudness (LUFS), true peak, and dynamics.
spektra-cli diff <fileA> <fileB>       Compare two files: align, spectral diff, null test.
spektra-cli image <file>               Render the spectrogram to a PNG.

Add --json or --csv to any command for machine-readable output:

spektra-cli scan ~/Music --csv > library.csv

Exit code 1 means findings (a transcode, an upsample, or corruption; an honest lossy file is fine), 2 a setup error, 0 a clean run, so a check fits straight into a script or a continuous integration job:

spektra-cli audit ~/Music || echo "something in there is not what it claims"

Full reference with sample output: docs/cli.md.

Where these files come from

Every version after the first is published straight from the repository's release workflow, which means npm shows a provenance attestation linking the tarball you install to the exact commit and workflow run that produced it. npm audit signatures verifies it. Nothing here is built or uploaded from anyone's laptop.

Platforms

Prebuilt binaries cover Windows x64, Linux x64 (glibc), and macOS on both Intel and Apple silicon. npm installs only the one your machine can run.

Windows on ARM gets the x64 build and runs it under emulation. Alpine and other musl systems are not covered: the Linux build needs glibc, and spektra-cli says so rather than failing at the loader. No Linux ARM build yet, so a Raspberry Pi or an ARM server needs a build from source.

Accuracy, and your files

spektra-cli only reads. It never renames, moves, deletes or rewrites a file.

Its verdicts are evidence, not proof: a bandwidth verdict infers an encoder's low-pass from the spectrum, and an honest recording with nothing up high (a dark master, an old tape source, a spoken-word transfer) can look much like a transcode. dupes matches acoustically, so two different masters of one song may not pair. Scripting a delete off --json is exactly the use these reports are for, and it is also the use that loses music: read the reason a row gives, and keep a backup.

License

PolyForm Perimeter 1.0.1. Free to use, including at work; you may not use it to build a competing product. Not an Open Source Initiative approved license, so a dependency scanner set to allow only approved licenses will flag it.

As that license says, the software comes as is, with no warranty of any kind, and the author is not liable for any damages arising from its use, lost or deleted files included.