feat(highcharts): implement waveform-audio

[github-actions]

Implementation: waveform-audio - python/highcharts

Implements the python/highcharts version of waveform-audio.

File: plots/waveform-audio/implementations/python/highcharts.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 "Speech Waveform · waveform-audio · python · highcharts · anyplot.ai" in dark ink — clearly readable. X-axis label "Time (seconds)" and Y-axis label "Amplitude" in dark INK text, proportionally sized. Tick labels (Y: −1.5 to 1.5 at 0.5 intervals; X: 0 to 1.75 at 0.25 intervals) in INK_SOFT — all readable. Subtle ~15% grid lines. Zero reference line clearly visible. The waveform renders as two distinct "mountain" lobes in brand green #009E73 with semi-transparent fill (0.35 opacity): first syllable between ~0.15–0.65 s peaking at ~0.65 amplitude, second between ~0.85–1.55 s peaking at ~0.55. Silence and near-zero noise floor clearly visible in the gaps. All text readable against the light background — no light-on-light failures.

Dark render (plot-dark.png): Warm near-black background (#1A1A17). Title in light #F0EFE8 ink, clearly visible. Axis labels and tick labels in #B8B7B0 INK_SOFT — fully readable. Subtle grid lines (rgba(240,239,232,0.15)). Zero reference line visible. Waveform in identical brand green #009E73 — data colors are unchanged from the light render; only chrome elements have flipped. Same two-syllable structure and shape as in the light render. All text readable against the dark background — no dark-on-dark failures detected.

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

Score: 84/100

Category	Score	Max
Visual Quality	28	30
Design Excellence	10	20
Spec Compliance	15	15
Data Quality	14	15
Code Quality	10	10
Library Mastery	7	10
Total	84	100

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set; both renders readable; minor deduction for y-axis tick labels appearing slightly small at thumbnail scale
• VQ-02: No Overlap (6/6) — No overlapping text or data elements in either render
• VQ-03: Element Visibility (5/6) — Waveform clearly visible with semi-transparent fill; minor deduction: y-axis auto-extends to ±1.5 while data peaks at ~0.65, so the signal occupies only ~43% of vertical space
• VQ-04: Color Accessibility (2/2) — Single series in CVD-safe brand green #009E73; no red-green conflict
• VQ-05: Layout & Canvas (4/4) — Canvas gate passed (3200×1800); good margins; no overflow or clipping
• VQ-06: Axis Labels & Title (2/2) — X: "Time (seconds)" with units; Y: "Amplitude" (normalized scale implied); title correct
• VQ-07: Palette Compliance (2/2) — First series #009E73; background #FAF8F1/#1A1A17; all chrome tokens theme-correct in both renders

Design Excellence (10/20)

• DE-01: Aesthetic Sophistication (4/8) — Well-configured defaults: Imprint palette, theme tokens, semi-transparent fill. No distinctive design decisions that elevate beyond a configured default.
• DE-02: Visual Refinement (3/6) — Legend disabled for single series, subtle 15%-opacity grid, generous margins, zero reference line add up to above-default refinement. Top/right spines not explicitly removed, but Highcharts defaults to no top/right axis lines.
• DE-03: Data Storytelling (3/6) — The waveform naturally shows the two-syllable story; the zero reference line aids interpretation. No deliberate visual hierarchy — syllable regions not annotated or emphasized.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct: filled area waveform symmetric around zero using AreaSeries with threshold:0
• SC-02: Required Features (4/4) — Semi-transparent fill, zero reference line, time x-axis, normalized amplitude y-axis all present
• SC-03: Data Mapping (3/3) — X: time in seconds (0–2 s); Y: normalized amplitude (−1 to +1 range)
• SC-04: Title & Legend (3/3) — Title follows {Descriptive Title} · {spec-id} · {language} · {library} · anyplot.ai format; legend correctly disabled

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) — Two syllables at different peak amplitudes, silence gaps, noise floor, amplitude envelope. Minor deduction: spec recommends min/max envelope rendering for dense waveforms; implementation uses simple stride-N decimation instead.
• DQ-02: Realistic Context (5/5) — Physically accurate speech model (130 Hz F0 + harmonics, Hanning window envelope, 44100 Hz SR). Neutral content.
• DQ-03: Appropriate Scale (4/4) — Standard audio sample rate, 2 s duration, normalized ±1 amplitude range

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear: imports → theme tokens → data → chart → series → export
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set
• CQ-03: Clean Imports (2/2) — All imports are used
• CQ-04: Code Elegance (2/2) — Clean, readable, no over-engineering, no fake UI
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html; uses ANYPLOT_THEME env var

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Correct container, HighchartsOptions, AreaSeries; follows library guide (CDN download, inline embedding, CDP viewport override)
• LM-02: Distinctive Features (3/5) — threshold:0 on AreaSeries produces bidirectional fill (Highcharts-specific); plotLines at zIndex:5 for zero reference; HTML artifact output

Score Caps Applied

• None — no caps triggered

Strengths

• Perfect spec compliance: filled area waveform with semi-transparent fill, zero reference line, and correct time/amplitude axes
• Full theme adaptation — all chrome tokens properly branch on ANYPLOT_THEME; both renders pass readability checks
• AreaSeries with threshold:0 correctly produces bidirectional fill from zero — a Highcharts-specific feature well-suited to waveform visualization
• Realistic synthetic speech data: physically accurate F0+harmonics with Hanning amplitude envelope producing two clearly separated voiced syllables
• All font sizes explicitly set per the style guide; clean KISS code with seed=42

Weaknesses

• Design lacks visual distinction: DE-01/DE-02/DE-03 are at or just above default — no visual hierarchy, no emphasis technique (annotations, highlighted peaks, shaded syllable regions), reads as a configured default rather than a crafted visualization
• Y-axis auto-extends to ±1.5 while data peaks at ~0.65 — waveform occupies only ~43% of vertical space, making the signal appear small; tighten to e.g. min: -0.8, max: 0.8 or clip to min: -1.0, max: 1.0 to better frame actual dynamics
• Spec explicitly calls for min/max envelope rendering to avoid aliasing; implementation uses stride-N decimation (every 29th sample) which can miss transient peaks at syllable onsets/offsets
• No visual hierarchy: even a single shaded region highlighting each syllable, or plotBands marking the voiced segments, would substantially improve storytelling (DE-03)

Issues Found

1. DE-01/DE-02/DE-03 BELOW TARGET: Design excellence is capped at configured defaults (4/8 + 3/6 + 3/6 = 10/20)
   • Fix: Add plotBands shading the two voiced syllable regions (e.g. subtle rgba(0,158,115,0.08) fills) to create visual hierarchy without obscuring the waveform. Alternatively add vertical plotLines at syllable boundaries. Consider reducing top/right chart border by setting plotBorderWidth: 0 explicitly.
2. VQ-03 Y-AXIS TOO WIDE: Data at ~65% of max amplitude but y-axis extends to ±1.5
   • Fix: Set min: -1.0, max: 1.0 (matching the normalized amplitude range in the spec) or min: -0.8, max: 0.8 to zoom into the actual data range
3. DQ-01 DECIMATION: Simple stride-N downsampling instead of min/max envelope
   • Fix: Replace raw[::step][:n_display] with a min/max envelope: for each display bin compute np.max(abs(raw[i*step:(i+1)*step])) and keep ±max to preserve peak amplitude fidelity

AI Feedback for Next Attempt

Three concrete improvements: (1) Tighten the y-axis to min: -1.0, max: 1.0 (spec normalized range) so the waveform fills the vertical canvas. (2) Replace stride-N decimation with a min/max envelope: split into n_display bins, take the signed max-amplitude sample from each bin, which preserves peak fidelity and matches the spec's explicit note about anti-aliasing for dense waveforms. (3) Add visual hierarchy via Highcharts plotBands — shade the two voiced syllable time ranges with a very subtle rgba(0,158,115,0.07) fill to make the data story immediately clear and lift DE-03 to 4+.

Verdict: REJECTED

[github-actions]

🔧 Repair Attempt 1/4

Applied fixes based on AI review feedback.

Status: Repair completed, re-triggering review...

---

🤖 impl-repair

[claude]

AI Review - Attempt 2/3

Image Description

Light render (plot-light.png): The plot renders on a warm off-white #FAF8F1 background. The title "Speech Waveform · waveform-audio · python · highcharts · anyplot.ai" is displayed in bold dark ink at the top, spanning approximately 75% of the canvas width. A lighter subtitle below describes the acoustic content. The waveform is rendered as a filled area series in brand green #009E73 with 40% fill opacity, symmetrically expanding above and below the zero axis. Two semi-transparent green syllable bands highlight the voiced regions (0.15–0.65 s and 0.85–1.55 s), with a clear silence gap visible between them. A horizontal zero reference line is cleanly rendered. X-axis shows "Time (seconds)" with ticks every 0.25 s; Y-axis shows "Amplitude" ranging from -0.8 to 0.8. All text (title, subtitle, axis labels, tick labels) is clearly readable against the light background. Legibility verdict: PASS.

Dark render (plot-dark.png): The same plot on a warm near-black #1A1A17 background. The title and subtitle shift to light cream tones, axis labels and tick labels switch to #B8B7B0 (INK_SOFT dark token). The waveform data color remains identical — brand green #009E73 — confirming data color immutability across themes. The syllable bands are slightly more saturated against the dark background but still tasteful. The zero reference line is visible. No dark-on-dark text failures — all labels are clearly distinguishable against the near-black surface. Legibility verdict: PASS.

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

Score: 89/100

Category	Score	Max
Visual Quality	29	30
Design Excellence	13	20
Spec Compliance	14	15
Data Quality	15	15
Code Quality	10	10
Library Mastery	8	10
Total	89	100

Visual Quality (29/30)

• VQ-01: Text Legibility (7/8) — All text explicitly sized and readable in both themes; title fontsize dynamically scaled to prevent overflow; minor deduction as subtitle at 40px sits at the low end
• VQ-02: No Overlap (6/6) — No text collisions; syllable bands do not obscure labels; zero line doesn't compete with data
• VQ-03: Element Visibility (6/6) — Min/max envelope rendering of 3000 display points gives a clean, dense waveform without aliasing; fill opacity 0.40 provides good transparency; zero line clearly visible
• VQ-04: Color Accessibility (2/2) — Single series in brand green #009E73; CVD-safe; no red-green encoding
• VQ-05: Layout & Canvas (4/4) — Canvas confirmed 3200×1800 (gate passed); margins generous (bottom=130, left=155); nothing clipped
• VQ-06: Axis Labels & Title (2/2) — "Time (seconds)" and "Amplitude" are descriptive; normalized amplitude implied by ±0.8 range
• VQ-07: Palette Compliance (2/2) — First series = #009E73; backgrounds #FAF8F1 / #1A1A17 correct; all chrome tokens theme-adaptive

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) — Syllable band overlays are a genuine design choice that adds narrative context; subtitle adds acoustic context; dynamic title scaling shows attention to detail; the overall layout is professional but still within standard area-chart conventions
• DE-02: Visual Refinement (4/6) — Semi-transparent fill (0.40 opacity), subtle grid lines with low-opacity tokens, and a clean zero reference line all exceed the baseline; no heavy chart frame; Highcharts default clean axis presentation retained
• DE-03: Data Storytelling (4/6) — Syllable bands immediately highlight the voiced speech regions; the silence gap is visually obvious; subtitle reinforces the narrative; could benefit from amplitude annotations or a more explicit callout

Spec Compliance (14/15)

• SC-01: Plot Type (5/5) — Area series with threshold: 0 produces the spec-required mirrored filled waveform shape
• SC-02: Required Features (3/4) — Semi-transparent fill ✓, zero reference line ✓, time x-axis ✓, synthetic data ✓, min/max envelope rendering ✓; minor deduction: spec requires y-axis range -1.0 to +1.0 but implementation uses -0.8 to 0.8
• SC-03: Data Mapping (3/3) — X=time in seconds, Y=normalized amplitude; all data visible within the rendered range
• SC-04: Title & Legend (3/3) — Title follows {Descriptive Title} · {spec-id} · python · highcharts · anyplot.ai format; legend correctly disabled for single-series

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Two syllables with envelope shaping, harmonic structure (fundamental + 4 harmonics), silence gap, noise floor, amplitude clipping guard — all key audio waveform features demonstrated
• DQ-02: Realistic Context (5/5) — F0=130 Hz (typical male speaking voice), 44100 Hz sample rate, 2-second duration, hanning envelope per syllable — acoustically realistic and neutral
• DQ-03: Appropriate Scale (4/4) — Normalized amplitude in [-1, 1] domain; time range 0–2 seconds; standard audio sample rate

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear script, no unnecessary functions or classes
• CQ-02: Reproducibility (2/2) — np.random.seed(42) ensures deterministic data
• CQ-03: Clean Imports (2/2) — All imports actively used
• CQ-04: Code Elegance (2/2) — Min/max envelope algorithm is clear and well-commented; no fake UI
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png + plot-{THEME}.html; CDP viewport override + PIL pin ensures exact 3200×1800

Library Mastery (8/10)

• LM-01: Idiomatic Usage (5/5) — Chart(container="container"), HighchartsOptions, AreaSeries, add_series() — all idiomatic; CDN-inline embedding correct; CDP override for authoritative viewport
• LM-02: Distinctive Features (3/5) — Good use of plotBands for syllable regions and plotLines for zero reference (both Highcharts-specific features); bidirectional area fill via threshold: 0 is a Highcharts strength; could push further with e.g. navigator, boost module for dense signals, or xAxis.crosshair

Score Caps Applied

• None

Strengths

• Syllable band overlays (plotBands) are a high-quality design choice that immediately communicates speech structure to the viewer
• Min/max envelope downsampling (1500 windows × 2 samples) correctly handles the 88200-sample waveform without aliasing artifacts
• Complete theme-adaptive chrome: all INK, INK_SOFT, GRID tokens applied throughout — both renders look correct
• Both PNG and HTML artifacts saved correctly; CDP + PIL belt-and-braces ensures exact 3200×1800 output
• Acoustically realistic synthetic data (harmonics, hanning envelopes, noise floor, silence gap)

Weaknesses

• Y-axis range is ±0.8 instead of the spec-mandated ±1.0 — the waveform spec explicitly requires the normalized amplitude range to extend to ±1.0; fix: set min: -1.0, max: 1.0, tickInterval: 0.5 on y_axis
• LM-02 could be stronger — no use of Highcharts-specific advanced features beyond plotBands/plotLines; consider Highcharts Boost module or navigator for dense waveform data

Issues Found

1. SC-02 MINOR: Y-axis range ±0.8 deviates from spec requirement of ±1.0
   • Fix: chart.options.y_axis = {..., "min": -1.0, "max": 1.0, "tickInterval": 0.5, ...}

AI Feedback for Next Attempt

Fix the y-axis range to ±1.0 with tickInterval 0.5 as the spec requires. To further elevate Library Mastery, consider adding the Highcharts Boost module for the dense point series (3000 points benefit from it) or configuring a crosshair on the x-axis for the interactive HTML artifact. These are small changes that show deeper Highcharts knowledge.

Verdict: APPROVED