---
log: 014
title: "ParVagues Unwrapped — the corpus you can hear"
date: 2026-06-07
task: "#81 superfeature shortlist → exploratory viz (under #64)"
tags: [tooling, dataviz, audio, mda, ux]
shareable: true
---

## Cap (what & why)
The MDA found the story (5 superfeature axes, timbre ≠ family); now make it
*explorable*. Not another scrollytelling essay (that's `corpus.html`) but an
instrument: drop all 1,485 samples into feature space, let the eye AND the ear
roam — pick the axes, recolour by lens, click a dot to hear the sample.

## Manœuvre (how)
Two layers, parsers-over-copy:
1. `build_unwrapped.py` bakes one `unwrapped.json` — reuses `feature_eda.load_matrix`
   so the matrix matches the MDA exactly, then adds the three things a scatter needs
   per file: the PCA projection (PC1–5), the KMeans timbral-cluster id, and an
   audition `.wav` path (a gitignored `_samples` symlink → Dirt-Samples). The 5
   leading PCs name themselves from their loadings, oriented by a stable anchor so
   the poles always read right. Contract test guards the baking.
2. `unwrapped.html` — zero-dep, Ship's Bridge dark, fleet family colours. Canvas
   scatter (axis-pick × 4 colour lenses × search × hover × click-to-audition) +
   four MDA panels (loading bars, RF importances, per-family beeswarm, family×cluster
   grid). Magenta reserved for the audition pulse — the *now*.

## Prise (findings / artifacts)
- `armada/tide-table/unwrapped.{py,json,html}` + `tests/test_build_unwrapped.py` (4 green).
- 1,485 samples · 36 features · 12 families · intrinsic dim 19 (90%); 5 PCs = 59% var.
- Verified headless (Playwright): no console errors, audition fires a real WAV request
  (`_samples/dr_few/005_020.WAV`), all panels populate. Served via `serve.py`, opened in FF.

## Sel (the shareable learning)
The PCA axes named themselves into *musical* qualities — Brightness, Timbre colour,
Loudness, **Envelope (kick ↔ bass)**, Tonal↔noisy — without anyone labelling them.
The kick↔bass axis the resolver struggled with literally falls out as PC4. And the
family×cluster grid is the receipt for "a folder is a loose grouping": at ARI 0.25 the
audio clusters refuse to line up with the filename families.

## Hameçon (hook)
A map of every sound I livecode with — and you can click any dot to hear it. The
machine drew the axes; turns out it drew *brightness* and *punch*.
