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

git clone https://github.com/hed0rah/acidcat.git
cd acidcat
pip install -e .                # core + mutagen (WAV/AIFF/MIDI/Serum/MP3/FLAC/OGG/Opus/M4A)
pip install -e .[analysis]      # + librosa BPM/key detection + features
pip install -e .[mcp]           # + MCP server (acidcat-mcp, stdio)
pip install -e .[mcp-http]      # + MCP streamable-HTTP transport (acidcat-mcp --transport http)
pip install -e .[crypto]        # + AES for encrypted Wii disc extraction
pip install -e .[all]           # everything

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 -f 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

Global Flags

-f, --format FMT                Output format (default varies by command)
-o, --output FILE               Write output to file
-q, --quiet                     Suppress progress output
-v, --verbose                   Extra detail
-n, --num N                     Max files to scan (default: 500)
--has CHUNKS                    Filter by chunk IDs (comma-separated)
--deep                          Include librosa analysis

Most commands accept table, json, and csv (default table, but scan and features default to csv). Two differ: inspect is table/json, and dump is hex/json.

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 (PhotoRec for audio)

Find audio in a raw blob, cut it out, and make odd codecs playable. Four verbs chain like coreutils: locate (find) -> carve (cut) -> convert (transcode), with extract for known banks. Full workflow in docs/recovery.md.

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

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

# 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

License

MIT