nc-murray/spectrogram-reconstruction

1# CLAUDE.md2 3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.4 5## Project6 7Python CLI tool (`specrec`) that reconstructs audio from spectrogram images using the Griffin-Lim algorithm. The core technical contribution is a round-trip accuracy characterization: generate synthetic audio → render spectrogram image → parse image → reconstruct audio → measure fidelity. All demos use programmatically-generated synthetic audio — do not use or reference any real investigation spectrograms.8 9## Commands10 11```bash12# Install (editable, with uv or pip)13uv pip install -e ".[dev]"14# or15pip install -e ".[dev]"16 17# Run CLI18specrec reconstruct --input IMAGE_PATH --output AUDIO_PATH19specrec test --type tone|speech_like [--output-dir DIR]20specrec evaluate --input IMAGE_PATH --reference AUDIO_PATH21specrec demo   # full synthetic round-trip, saves to examples/synthetic_demo/22 23# Tests24pytest25pytest tests/test_image_parser.py   # run a single test file26pytest -k "test_inversion"          # run by name pattern27 28# Lint29ruff check src/ tests/30```31 32## Architecture33 34**Data flow:**35 36```37synthesizer.py   →   image_parser.py   →   reconstructor.py   →   evaluator.py38(audio → PNG)        (PNG → magnitude)     (magnitude → wav)      (metrics)39```40 41**Module responsibilities:**42 43- `synthesizer.py` — generates test signals (`generate_test_tone`, `generate_test_speech_like`) and renders them as spectrogram PNGs via matplotlib (`audio_to_spectrogram_image`)44- `image_parser.py` — inverts a colormap-rendered spectrogram image back to a linear amplitude 2D array; the hardest module (see colormap inversion below)45- `reconstructor.py` — thin wrapper around `librosa.griffinlim()`; input must be linear amplitude (not dB)46- `evaluator.py` — runs the round-trip test at multiple `n_iter` values; computes spectral convergence (Frobenius norm ratio, lower = better) and SNR (dB, higher = better)47- `visualizer.py` — side-by-side waveform/spectrogram comparison plots and accuracy-vs-iterations curves48- `cli.py` — Click entry point wiring the above49 50**Colormap inversion (key implementation detail in `image_parser.py`):**51 52Build a 256-entry LUT per colormap by sampling `matplotlib.cm.get_cmap(name)(np.linspace(0, 1, 256))`. For each image pixel, find the nearest LUT entry by Euclidean distance in RGB space. Use `scipy.spatial.cKDTree` or numpy broadcasting for performance. Supported colormaps: `jet`, `viridis`, `greys`/`gray`, `magma`, `plasma`, `inferno`.53 54**Default signal processing parameters:**55- Sample rate: 22050 Hz56- FFT size: 2048, hop length: 51257- dB range: −80 to 0 dB58- Griffin-Lim iterations: 60 (default); test at [10, 30, 60, 100]59 60**Test requirements:**61- `test_image_parser.py`: colormap round-trip on synthetic gradients; assert mean absolute error < 0.05 on [0, 1] scale62- `test_reconstructor.py`: reconstruct from a programmatic magnitude spectrogram; verify non-silent output of correct length63- `test_evaluator.py`: assert spectral convergence decreases monotonically as `n_iter` increases64 65## Build order66 67Follow the sequence in `PROJECT_BRIEF.md`: synthesizer → image_parser → reconstructor → evaluator → cli → visualizer → colormap sensitivity test → notebook → README. Each step is independently testable before moving to the next.68