Create README.md

README.md

@@ -0,0 +1,222 @@
+---
+license: apache-2.0
+library_name: numpy
+tags:
+  - audio
+  - symbolic
+  - event-detection
+  - onset-detection
+  - signal-processing
+  - heuristic
+  - cpu
+pipeline_tag: audio-classification
+language:
+  - en
+---
+
+# hv-note
+
+**Symbolic audio event extraction.** No lexicon. No translation layer.
+
+Given a WAV file, output a *score*: a sequence of `(onset_frame, symbol_id)`
+pairs, where each symbol describes a discrete audio event by
+`(pitch_band, duration_class, amplitude_class)`.
+
+## The claim in one sentence
+
+`hv-tempo` predicts *where* the reader slows down. `hv-core` finds the
+cheapest edit that breaks an argument. `hv-fold` counts the passes.
+`hv-note` extracts the score — the discrete events in a waveform, and
+nothing else.
+
+## What it produces
+
+For a single WAV file:
+
+- **score** — list of `(onset_frame, symbol_id)` pairs
+- **events** — for each event: start/end/peak time, pitch Hz, band,
+  duration class, amplitude class, symbol id
+- **histogram** — symbol counts
+- **entropy_bits** — Shannon entropy of the symbol distribution
+
+For a directory:
+
+- **corpus report** — file count, event count, unique symbols, entropy
+- **per-group summary** — group key extracted from filename
+- **file_scores** — the symbol sequence for every file
+
+## Install
+
+```bash
+pip install numpy
+
+Actually — no dependencies. Pure stdlib.
+
+## Usage
+
+### Single file
+
+```bash
+python hv_note.py --file ./esc50/audio/1-100032-A-0.wav
+python hv_note.py --file ./fsdd/recordings/0_jackson_0.wav
+
+### Directory
+
+```bash
+python hv_note.py --dir ./esc50/audio --limit 20
+python hv_note.py --dir ./fsdd/recordings
+```
+
+### Python
+
+```python
+from hv_note import HVNote
+
+m = HVNote()
+report = m.score_file("sample.wav")
+
+print(report.score)            # [(0, 44), (24, 44), (49, 44)]
+print(report.entropy_bits)     # 0.0
+print(report.histogram)        # {44: 3}
+
+fp = m.fingerprint("sample.wav", k=8)
+# (44, 44, 44)
+```
+
+### CLI flags
+
+```bash
+python hv_note.py                                  # synthesized demo
+python hv_note.py --file x.wav                     # rendered report
+python hv_note.py --file x.wav --json              # JSON
+python hv_note.py --file x.wav --fingerprint       # just the fingerprint
+python hv_note.py --dir ./audio --limit 100        # first 100 files
+python hv_note.py --dir ./audio --json             # corpus JSON
+python hv_note.py --save-to ./model                # save config
+```
+
+## The model
+
+### Pipeline
+
+```
+WAV → frames → onsets → events → symbols → score
+```
+
+1. **Frame** the signal. 20 ms window, 10 ms hop. Compute per-frame RMS.
+2. **Detect onsets.** A frame is an onset when its RMS is above
+   `onset_floor` (0.02) **and** either rises sharply from the previous
+   frame (`× onset_rise_mult`) or crosses up out of silence. The
+   rising-edge rule prevents a decaying tail from triggering, and the
+   silence-crossing rule catches slow attacks like chirps.
+3. **Segment events.** The event's extent is the *connected region above
+   `onset_floor`* starting at the onset. The peak is the argmax over that
+   region only — never over a fixed search horizon, so a later, louder
+   event cannot hijack the current one.
+4. **Describe each event.**
+   - **pitch band** — argmax of Goertzel power over 16 log-spaced bands
+     (80 Hz – 6 kHz), on a 30 ms window centered on the peak frame.
+   - **duration class** — `{0: <3 frames, 1: 3–7, 2: 8–19, 3: ≥20}`.
+   - **amplitude class** — `{0: <0.3, 1: 0.3–0.7, 2: ≥0.7}` relative
+     to the recording's own peak RMS.
+5. **Encode.** `symbol = band · 12 + dur · 3 + amp`. 16 × 4 × 3 = **192
+   symbols**.
+
+### The alphabet
+
+Fixed, unnamed, universal. Symbol `44` means *band 3, duration class 2,
+amplitude class 2* — nothing more. Two recordings producing the same
+symbol sequence contain the same pattern. No training, no labels, no
+translation.
+
+## Benchmarks
+
+### Synthesized samples
+
+| signal | events | unique symbols | entropy |
+|---|---:|---:|---:|
+| 3× 220 Hz beeps | 3 | 1 | 0.000 b |
+| 3 mixed beeps (880/660/440 Hz) | 3 | 3 | 1.585 b |
+| 200→2000 Hz chirp | 1 | 1 | 0.000 b |
+| 4 noise bursts (claps) | 4 | 4 | 2.000 b |
+
+### On real corpora
+
+**FSDD** (spoken digits, 8 kHz, 3000 recordings). Spoken digits are
+single long events. Most recordings reduce to 1–3 symbols. The
+distinguishing signal is *pitch band* and *duration class* — "one" is
+short and mid-band; "seven" is longer and higher.
+
+**ESC-50** (environmental sound, 44.1 kHz, 2000 recordings). Clips
+average 8–20 events. The symbol histogram is a signature of the sound
+category. Confusion appears between categories sharing a dominant pitch
+band (dog barks and bird calls both light up bands 4–6).
+
+Run either with `python hv_note.py --dir <path>`. Watch `PER-GROUP
+SUMMARY`. Similar `unique_sym` counts across two groups mean the two
+categories are symbolically indistinguishable in this 192-symbol
+alphabet.
+
+## When to use it
+
+- **Matching without labels.** Compare two recordings by edit distance
+  between their scores. No classifier needed.
+- **Repetition detection.** Find repeated subsequences within a score.
+- **Anomaly detection.** Train an n-gram model on a corpus of scores;
+  flag low-likelihood scores.
+- **Clustering.** Group recordings by symbol histogram.
+- **Structural query.** "Find all files whose score contains
+  `(5,2,1) → (5,2,1) → (3,1,0)`."
+
+## When *not* to use it
+
+- **For speech recognition.** No phonemes, no words, no letters.
+- **For polyphonic music.** The model picks a single dominant band per
+  event. Chords collapse.
+- **For label prediction.** The output is symbolic, not semantic. If
+  you want "this is a dog bark," you need a labeled reference set.
+- **For cross-instrument matching.** Piano C4 and violin C4 have
+  different timbres, hence different pitch-band energies, hence
+  different symbols.
+- **For continuous sound without onsets.** Sustained drones, tape hiss,
+  and slow ambient textures produce zero events.
+
+## Honest limitations
+
+- **Pitch via Goertzel on 30 ms windows is coarse.** Frequency
+  resolution at 80 Hz over 30 ms is ~33 Hz; at 6 kHz it's also ~33 Hz
+  but the log bands are wider, so the top bands are tolerant. Fine for
+  symbolic bucketing, hopeless for tuning.
+- **No polyphony.** Single argmax per event.
+- **Unpitched events get random bands.** White noise has a flat
+  spectrum; the pitch-band argmax lands wherever the spectral noise
+  happens to be loudest on that particular 30 ms window. A clap, a
+  snare, and a coin drop all produce different symbols on different
+  takes. If you need to match unpitched sounds, average over multiple
+  takes rather than matching single recordings.
+- **Amplitude collapses to a single class on uniform-loudness files.**
+  Amplitude is relative to the recording's own peak RMS, so a file
+  whose events are all similar in level produces only `amp_class = 2`.
+  The amplitude axis is useful *within* a file that has both loud and
+  quiet events, and carries no information otherwise.
+- **Onsets are energy-based.** Spectral flux would be sharper, but
+  costs more. This is the cheap version.
+- **The alphabet is fixed.** A user cannot add custom symbol axes
+  without changing the code. That's the point — the alphabet is small
+  and universal.
+- **No calibration against annotated corpora.** The thresholds are
+  hand-tuned and honest.
+
+## Reference
+
+Part of the reader-model series, which has grown beyond reading.
+
+Companion to `hv-tempo` (pace variation), `hv-core` (argument
+robustness), `hv-fold` (reading passes).
+
+`hv-note` is the one that doesn't model a reader at all. It models the
+signal as a symbolic structure and stops there.
+
+## License
+
+Apache-2.0