acidcat

A pure-Python inspector, editor, and forensic tool for audio files and synth/DAW presets: read the metadata, decode the format structure byte by byte, flag anomalies, repair broken containers, and identify how a file was made.

Reads BPM, key, duration, tags, and format info from WAV, AIFF, MP3, FLAC, OGG, Opus, M4A, MIDI, and Serum presets. Also structurally decodes Bitwig (.bwpreset/.bwclip), Native Instruments (Massive/Absynth/Kontakt/NKS/KORE), Vital, NCW, SoundFont (SF2/SF3), tracker modules (MOD/XM/IT), MP4, VST FXP, ReCycle RX2, and RMID containers via inspect. Beyond reading: repair and validate fix and check container structure (stale sizes, offset tables, counts, pad bytes) without touching a byte of audio, and audit gives a forensic verdict (structure, integrity, hidden data, and the writing tool). One pure-Python dependency (mutagen); the native inspect walkers need nothing. Optional librosa analysis for BPM/key detection and ML feature extraction.

Also ships per-library SQLite indexes (acidcat index) tracked in a small global registry, plus an MCP server (acidcat-mcp) so an LLM can query your whole collection across libraries by bpm, key, tags, or full-text.

Install

Python 3.10+.

pip install acidcat              # core + mutagen, one dependency
pip install acidcat[analysis]    # + librosa BPM/key detection + features
pip install acidcat[tui]         # + the interactive terminal inspector
pip install acidcat[mcp]         # + MCP server (acidcat-mcp, stdio)
pip install acidcat[mcp-http]    # + MCP streamable-HTTP transport
pip install acidcat[crypto]      # + AES for encrypted Wii disc extraction
pip install acidcat[all]         # everything

From a checkout, swap acidcat for -e .:

git clone https://github.com/hed0rah/acidcat.git
cd acidcat
pip install -e ".[all]"

Quick Start

# single file -- instant metadata
acidcat kick_808.wav
acidcat loop.mp3
acidcat pad.flac

# pipe from stdin
cat file.wav | acidcat
curl https://example.com/loop.mp3 | acidcat -

# JSON output for piping
acidcat kick_808.wav --json | jq .BPM

# deep analysis with librosa
acidcat kick_808.wav --deep

# scan a mixed-format directory
acidcat scan ~/Samples/Breaks -n 200

Supported Formats

Format anatomy

Interactive datasheets for the formats acidcat dissects, each drawn byte by byte: hover a field to light its exact bytes and read the decode, click a field for its table. The RIFF/WAVE family, MP3, FLAC, Ogg, MP4, MIDI, the trackers, the sampler and synth-preset formats, and more, with the history and edge-case notes behind each.

Browse them at hed0rah.github.io/audio_files_anatomy -- a good start is the WAV / RIFF page, which walks the container, the fmt/data/smpl/acid chunks byte by byte, and the whole RIFF-to-BWF-to-RF64-to-Wave64 family.

Commands

Common flags

Three words are reserved and mean the same thing everywhere:

--output-format FMT   table / json / csv, whichever the command supports
--json                shorthand for --output-format json
--csv                 shorthand for --output-format csv
-o, --output FILE     write to a file instead of stdout
-q, --quiet           suppress progress
-v, --verbose         extra detail

-f still works as a deprecated alias for --output-format and warns. It was the old spelling of --format, which now belongs to the file-format axis.

Rendering support varies: most commands do table/json/csv, inspect does table/json, dump does hex/json. scan and features default to csv, and write it to a file rather than stdout unless you ask otherwise.

Not global, though they look it: --has is on scan and survey; --deep is on info and index; -n/--num defaults to 500 on scan/detect/features but 5 on similar.

Environment

Exit codes

Every verb answers with the same three codes, following grep and diff, so a script can branch without knowing which verb it called:

The distinction that matters in practice is 1 vs 2. validate returns 2 on a format it does not model, rather than 0, so a gate cannot pass a file it never examined:

acidcat validate track.wav && ship track.wav      # only ships a checked, clean file
acidcat locate disk.img --json | acidcat carve disk.img --batch - -o out/ \
  || echo "nothing recovered"                    # a real answer either way

A bounded run is not a failed one. When a read window, a list cap or a filter stops a verb short, it says so on stderr and exits by what it actually found. scan DIR -n 5 that hits the cap still exits 0; the sentence naming the cap is on stderr so it cannot corrupt the records on stdout. Silence is the claim of completeness: a caveat appears only when a bound was actually reached, never as a standing note that one exists.

Machine-readable output

--output-format json|csv|tsv (or --json / --csv) writes records to stdout and everything else to stderr, so a truncated run stays parseable and a summary sentence can never turn a document into Extra data.

Two compatibility rules, so scripts written against 1.0 keep working:

• A JSON object may gain new keys in any release. Consumers must ignore keys they do not recognise. Removing or renaming a key is a breaking change.
• A top-level JSON array stays an array. Verbs that emit a list of records will not be wrapped in an envelope, because jq '.[]' and [0] are the reason the list shape was chosen. Run-level facts that have no record to live on go to stderr instead.

Dependency Groups

Examples

Metadata Exploration

# what chunks exist in your sample library?
acidcat survey ~/Samples/Loops -n 5000

# walk all chunks in a specific file
acidcat chunks ~/Samples/Loops/breakbeat.wav

# hex-dump the ACID and SMPL chunks
acidcat dump ~/Samples/Loops/breakbeat.wav acid smpl

# fingerprint a whole tree, then rank the rarest structural shapes
acidcat shape ~/Samples --no-path | sort | uniq -c | sort -n

# colored objdump-x-style hex view of a file's headers and fields
acidcat od ~/Samples/Loops/breakbeat.wav

# scan only files with ACID metadata
acidcat scan ~/Samples/Loops --has acid -n 200

# scan a directory with mixed formats (WAV, MP3, FLAC, etc.)
acidcat scan ~/Samples -n 500

BPM / Key Detection

# estimate BPM/key with librosa (for files without metadata)
acidcat detect ~/Samples/OneShots

# scan with librosa fallback for missing metadata
acidcat scan ~/Samples/Loops --fallback -n 100

ML Feature Extraction

# extract 50+ audio features to CSV
acidcat features ~/Samples/Loops -n 500

Recovery / rescue

Find audio in a raw blob, cut it out, make it playable. The verbs chain like coreutils: classify (what is this) -> locate (find) -> carve (cut) -> wrap (add a header) or convert (transcode), with extract for known banks. Full workflow in docs/recovery.md.

# what am I even holding, and what should I run next
acidcat classify mystery.bin

# find the audio regions in a disk image or card dump
acidcat locate disk.img --mode aggressive --analyze

# embedded FILES: locate the regions, carve every one into a directory
acidcat locate disk.img --json | acidcat carve disk.img --batch - -o recovered/

# headerless PCM: carve it, then give it a header so it plays
acidcat locate disk.img --analyze --json \
  | acidcat carve disk.img --batch - --wrap --rate 44100 -o recovered/

# one region by hand
acidcat carve disk.img --offset 0x5d1000 --length 2048 \
  | acidcat wrap --rate 44100 --bits 16 --endian be > region.wav

# pull every sample out of a sampler bank / tracker module
acidcat extract kit.sf2 -o kit_samples/

# decode an ADPCM or mistagged WAV to plain playable PCM
acidcat convert weird.wav --to-pcm -o plain.wav

# CTF: find audio hidden under a reversible transform (XOR / rotate / nibble-swap)
acidcat locate challenge.bin --transforms

Similarity Search

Index a library with feature vectors, then find sounds like a reference:

acidcat index ~/Samples/Loops --features       # store the vectors
acidcat similar ~/Samples/kick.wav -n 10        # nearest neighbours

similar scores z-standardized cosine over the feature vectors across every registered library, filtered to the target's kind (loop / one-shot) by default (--no-kind-filter to disable). The same ranking is available to an LLM through the MCP find_similar tool -- both call one core implementation, so the CLI and MCP never drift. If the reference is not indexed, its vector is extracted live (needs [analysis]).

Libraries (per-directory indexes)

acidcat scan writes a one-off CSV. acidcat index is the persistent path: each directory you index becomes a library with its own SQLite file, and a small global registry at ~/.acidcat/registry.db lets reads fan out across every library you have registered.

By default the per-library DB lives centrally at ~/.acidcat/libraries/<label>_<hash>.db. Pass --in-tree if you'd rather have the DB travel with the data at <library>/.acidcat/index.db.

# register and index a library (label defaults to basename of DIR)
acidcat index ~/Samples/Loops --label loops
acidcat index ~/Samples/OneShots --label oneshots

# show every registered library
acidcat index --list

# per-library stats
acidcat index --stats loops

# extract librosa features during indexing (slower, enables similarity)
acidcat index ~/Samples/Loops --label loops --features

# rebuild a library's DB from scratch
acidcat index ~/Samples/Loops --label loops --rebuild

# forget a library (registry only) vs remove it (deletes the DB file)
acidcat index --forget loops
acidcat index --remove loops

# list registered libraries whose DB file is missing on disk
acidcat index --orphans

# import a legacy <name>_tags.json into a library
acidcat index ~/Samples --label samples --import-tags old_tags.json

Nested libraries are rejected at registration time: if you've registered ~/Samples, you can't also register ~/Samples/Loops until you forget the parent.

Discovery

For users with many scattered packs, --discover walks a tree and registers every qualifying subdirectory as its own library in one pass.

# preview what would get registered (no writes)
acidcat index --discover ~/Samples --dry-run

# actually register them
acidcat index --discover ~/Samples

# tighter threshold and namespacing for a subset of your collection
acidcat index --discover /mnt/external/old_drives \
              --min-samples 50 --label-prefix "ext_"

A directory qualifies if its subtree (within --max-depth, default 3) contains at least --min-samples audio files (default 20). Non- qualifying parents are recursed into so packs nested inside catch-all folders still surface. Already-registered roots are skipped. The home directory is refused as a discover root to prevent runaway registration.

Querying

By default acidcat query fans out across every registered library and merges the results.

acidcat query --bpm 120:130 --key Am
acidcat query --tag drums --tag punchy --duration :1
acidcat query --text "dusty lofi" --limit 20
acidcat query --format mp3 --root loops
acidcat query --root loops,oneshots --bpm 128
acidcat query --bpm 128 --paths-only | xargs -I {} cp {} out/

--root accepts a label, an absolute path, or a comma-separated list. Override the registry on any command with --registry PATH or the ACIDCAT_REGISTRY environment variable.

MCP Server

acidcat-mcp is a stdio MCP server that exposes the registered libraries as structured tools. An LLM can ask "what libraries do I have?", search across them by metadata, find compatible keys via Camelot, or (with [analysis] installed) find similar samples by librosa feature cosine.

pip install -e .[mcp]            # minimum for discovery + writes
pip install -e .[analysis,mcp]   # unlock find_similar / analyze_*

Claude Desktop / Claude Code config:

{
  "mcpServers": {
    "acidcat": {
      "command": "acidcat-mcp"
    }
  }
}

Optional: pass --registry PATH on the server process or set ACIDCAT_REGISTRY if your registry lives outside the default location.

Tool tiers (each tool description starts with Fast., SLOW., or VERY SLOW. so the model self-selects):

• Fast (SQLite only): search_samples, get_sample, locate_sample, list_libraries, list_tags, list_keys, list_formats, index_stats, find_compatible
• Slow analysis (needs [analysis]): find_similar, analyze_sample, detect_bpm_key
• Index management: reindex, reindex_features, discover_libraries
• Write (marked destructive): register_library, forget_library, tag_sample, set_sample_description

The same tiers are on the wire as MCP annotations (readOnlyHint, destructiveHint, idempotentHint) for clients that branch on them programmatically. Most clients do not show annotations to the model, which is why the prefix is in the prose too.

One thing worth knowing before you point an agent at it: registering a library does not populate it. register_library and discover_libraries create the row and stop; reindex is what walks the files. A library between those two steps reports sample_count: null and answers nothing.

The skill

skills/acidcat/ is a Claude skill that teaches a model the above: which tool to reach for, what each cost tier means, the register-then-reindex sequence, and which results are lower bounds rather than totals. Install it alongside the server, from a checkout of this repository:

cp -r skills/acidcat ~/.claude/skills/

It is not part of the pip package -- a skill is instructions for a model, not importable code, and shipping it inside site-packages would put it somewhere no skill loader looks. Installing from PyPI, take it from the repository:

mkdir -p ~/.claude/skills/acidcat
curl -o ~/.claude/skills/acidcat/SKILL.md \
  https://raw.githubusercontent.com/hed0rah/acidcat/main/skills/acidcat/SKILL.md

Without it a model has only the tool descriptions, which cover each call in isolation but not the order they go in. The gap is not hypothetical: an agent given the server and no skill registered four libraries, reported success, and left four empty shells.

License

MIT