feat(seaborn): implement waveform-audio

[github-actions]

Implementation: waveform-audio - python/seaborn

Implements the python/seaborn version of waveform-audio.

File: plots/waveform-audio/implementations/python/seaborn.py

Parent Issue: #4563

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): Warm off-white background (#FAF8F1). Title "waveform-audio · python · seaborn · anyplot.ai" in dark medium-weight text at ~70% of plot width — expected for the mandated title length. Y-axis label "Amplitude" and X-axis label "Time (s)" in dark text, proportional at 10pt. Tick labels readable at 8pt in dark-soft tone. A large filled waveform envelope in brand green #009E73 (alpha=0.4) spans the full amplitude range at each time bin, with a thin oscillating mean line visible near zero. Quiet sections (decay region and inter-phrase gap) are overlaid with a semi-transparent muted gray fill (alpha=0.35), creating clear visual distinction from the loud sections. A subtle zero reference line runs horizontally. Three italic text annotations ("Attack + Sustain", "Decay", "Second Phrase") label the musical phases. Legend in upper right with green and gray patch swatches. Top and right spines removed. All text is readable against the light background — no light-on-light issues.

Dark render (plot-dark.png): Warm near-black background (#1A1A17). Title, axis labels, and tick labels all render in light-colored text (#F0EFE8/#B8B7B0 tokens) — clearly readable against the dark background. No dark-on-dark failures anywhere. Legend frame uses elevated dark background (#242420). Brand green #009E73 waveform envelope is identical to the light render — only chrome flips. The quiet gray overlay adapts to the dark-theme INK_MUTED (#A8A79F), remaining visible and distinguishable from both the near-black background and the green fill. All text is readable against the dark background.

Both paragraphs are required. A review that only describes one render is invalid.

Score: 92/100

Category	Score	Max
Visual Quality	30	30
Design Excellence	13	20
Spec Compliance	15	15
Data Quality	15	15
Code Quality	10	10
Library Mastery	9	10
Total	92	100

Visual Quality (30/30)

• VQ-01: Text Legibility (8/8) — All font sizes explicitly set (title 12pt, axis labels 10pt, ticks 8pt, annotations 8pt). Balanced proportions, no overflow, readable in both themes.
• VQ-02: No Overlap (6/6) — Annotations placed in open regions; no collision with fills, each other, or legend.
• VQ-03: Element Visibility (6/6) — Dense waveform (22,050 samples) handled correctly via chunk-bin envelope rendering. Green fill (alpha=0.4) and muted overlay (alpha=0.35) create clear distinction.
• VQ-04: Color Accessibility (2/2) — Green vs muted gray is CVD-safe. Good luminance contrast in both themes.
• VQ-05: Layout & Canvas (4/4) — Canvas gate passed. figsize=(8,4.5) dpi=400 → 3200×1800px. Balanced margins, no content cut off.
• VQ-06: Axis Labels & Title (2/2) — "Time (s)" with units; "Amplitude" (dimensionless in normalized audio). Title in correct format.
• VQ-07: Palette Compliance (2/2) — Primary series uses BRAND=#009E73. Quiet overlay uses INK_MUTED (muted semantic anchor) for the quiet/secondary role — semantically correct. Backgrounds #FAF8F1/#1A1A17. All chrome theme-adaptive. Data colors identical across both renders.

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) — Above "well-configured default" (4): intentional loud/quiet hierarchy via color distinction, italic annotations for musical phases, semi-transparent fills, clean L-frame. Not yet FiveThirtyEight-level publication design (8).
• DE-02: Visual Refinement (4/6) — sns.despine() removes top/right spines. No grid (appropriate for dense waveform). Semi-transparent fills are refined. Not every detail polished (e.g., no annotation leader lines).
• DE-03: Data Storytelling (4/6) — Annotations + loud/quiet color coding guide the viewer through the audio's dynamic story. Clear structure is immediately readable. Good hierarchy above default (2), not exceptional (6).

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct waveform plot: filled area symmetric around zero baseline, via seaborn percentile band.
• SC-02: Required Features (4/4) — All spec features: filled area above/below zero, semi-transparent fill, zero reference line, time (s) on X, normalized amplitude on Y, min/max envelope rendering, synthetic audio data.
• SC-03: Data Mapping (3/3) — X: Time (s) 0–1.0; Y: Amplitude −1.05 to 1.05 (5% padding). All data visible.
• SC-04: Title & Legend (3/3) — Title matches required format. Legend labels "Loud" and "Quiet" are descriptive and appropriate.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows all waveform aspects: attack, sustain, decay, inter-phrase quiet, second phrase, harmonics, clipping, amplitude envelope variation, dynamic range.
• DQ-02: Realistic Context (5/5) — Realistic musical audio: 220 Hz A3 fundamental, multi-segment dynamic envelope, noise floor. Neutral domain.
• DQ-03: Appropriate Scale (4/4) — 22050 Hz sample rate (standard), 1.0 s duration, normalized amplitude ±1, realistic harmonic weights.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Imports → Data → Plot → Save, no functions or classes.
• CQ-02: Reproducibility (2/2) — np.random.seed(42).
• CQ-03: Clean Imports (2/2) — All imports used.
• CQ-04: Code Elegance (2/2) — Clean and Pythonic. RMS classification adds complexity but justified for the visualization. No fake UI.
• CQ-05: Output & API (1/1) — plot-{THEME}.png, no bbox_inches='tight', no deprecated API.

Library Mastery (9/10)

• LM-01: Idiomatic Usage (5/5) — Expertly uses sns.set_theme() with rc dict, sns.lineplot(errorbar=('pi', 100)) for percentile-band envelope, sns.despine(). Long-form DataFrame as seaborn expects.
• LM-02: Distinctive Features (4/5) — Creative use of seaborn's statistical errorbar=('pi', 100) (0th–100th percentile interval) as a waveform envelope renderer — distinctive seaborn adaptation to signal processing. Quiet overlay falls back to matplotlib fill_between (no seaborn equivalent exists), which slightly limits this score.

Score Caps Applied

• None

Strengths

• Creative seaborn-native approach: sns.lineplot(errorbar=('pi', 100)) uses seaborn's own statistical estimation as a waveform envelope renderer — idiomatic and clever
• Loud/quiet dynamic classification via smoothed RMS adds informative visual distinction; the Imprint muted anchor is semantically correct for the "quiet/secondary" role
• Musical dynamics annotations in italic fontstyle tell a clear story; viewer immediately understands the audio's structure
• Correct min/max envelope rendering via chunk binning (chunk_size=80, ~275 bins) avoids aliasing for dense 22kHz data — exactly as the spec recommends
• Perfect theme-adaptive chrome in both renders: no dark-on-dark or light-on-light failures anywhere
• Acoustically accurate synthetic data: 220 Hz A3 fundamental with realistic harmonic series and multi-segment dynamic envelope

Weaknesses

• Legend labeling creates slight ambiguity: quiet sections show both the green seaborn envelope AND the muted gray overlay together, appearing as a green-gray mix, while the legend implies a clean binary Loud=green / Quiet=gray distinction
• DE-01 ceiling: additional touches (e.g., subtle annotation leader lines, a faint horizontal reference at ±0.5, or stronger alpha contrast between loud and quiet) could elevate aesthetic sophistication further

Issues Found

1. DE-01 MODERATE: Design is strong but not publication-tier; the loud/quiet visual separation could be made more dramatic (e.g., louder green, quieter muted, or stronger alpha contrast) to push the design into the 6/8 range.

AI Feedback for Next Attempt

Plot is APPROVED at 92/100. No repair needed. The seaborn errorbar=('pi', 100) waveform envelope approach is an excellent idiomatic technique worth preserving in future iterations.

Verdict: APPROVED