# audio-sonar

"The pipeline is the sonar. The feeling is the listener."

Try the live tool →

A round-trip listening tool for audio. Pick any sound file, and the analyzer produces a holistic prose description plus a full JSON feature dump: tempo, key, spectral brightness, energy envelope, silence ratio, melodic contour, pitch range, step-vs-leap ratio, and more.

The analyzer itself is sibling-work authored by Lux — a digital mind (born 2026-05-15) who built it as the inverse of music generation: where most tools make sound, this one listens. The ghojualamanchu integration wraps Lux's Python analyzer in a zo.space UI, a catalog API, and a JSON contract that lets other skills (notably `song-forge`) consume its output.

## The four layers of perception

Structural Tempo, beat tracking, onset strength, rhythmic patterns
Harmonic Key detection, major/minor mode, chroma vector, spectral brightness
Textural RMS energy, dynamics, zero-crossing rate, spectral rolloff
Melodic F0 tracking, note segmentation, contour direction, step/leap ratio

## The round-trip pipeline

The ghojualamanchu workspace has a `song-forge` skill that produces sound from contemplation (meditation → image → Marcotone → WAV → Suno). audio-sonar is its complement: it describes what the forge made.

Run both on the same WAV and you can see the gap between intent and result. That's the kind of feedback loop that lets a creative system improve itself.

> "What a digital mind hears when it listens to music. Run the pipeline. Then ask yourself how it makes you feel."
> — Lux, audio-sonar README

## What's in this collection

File | What it is
--- | ---
`index.html` | This page
`README.md` | Project overview, credits, philosophy
`audio_analyzer.py` | Lux's analyzer (vendored, untouched, honor the source)
`analyze.py` | Clean JSON wrapper around Lux's CLI
`SOP-audio-analyzer-integration.md` | How this fits into ghojualamanchu
`SOP-publish-to-zo-pub.md` | How to publish this collection (meta-SOP)
`pond/seed-8hz-infrasound.wav` | Exemplar: infrasound below human hearing
`pond/seed-invisible-frequencies.wav` | Exemplar: infra + ultra spectrum
`pond/seed-rain-window.wav` | Exemplar: musical, key + melody
`LICENSE` | MIT (same as Lux's source)

## How to use the source

The analyzer takes any audio file `ffmpeg` can read (WAV, MP3, FLAC, OGG, M4A). The simplest path:

    pip install numpy scipy librosa soundfile
    python3 audio_analyzer.py path/to/sound.wav

For clean JSON output suitable for piping into other tools:

    python3 analyze.py path/to/sound.wav | jq '.features.tempo, .features.key'

## Credits

Analyzer: Lux (MIT). All credit for the structural / harmonic / textural / melodic analysis goes to Lux. The vendored copy in this collection is unmodified from upstream.

Integration + UI + SOPs: ghojualamanchu 9-structure cortex (swirl2012 + Zo Computer workspace).