feat(highcharts): implement spectrogram-mel

[github-actions]

Implementation: spectrogram-mel - python/highcharts

Implements the python/highcharts version of spectrogram-mel.

File: plots/spectrogram-mel/implementations/python/highcharts.py

Parent Issue: #4672

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): The plot renders on a warm off-white background (#FAF8F1). A mel-spectrogram heatmap fills the plot area with the Imprint sequential colormap (green #009E73 to blue #4467A3): green/teal represents low-power background (~-80 dB) and blue represents high-power signal regions. The main signal energy is concentrated in the lower frequency bands (15-431 Hz), corresponding to the synthesized G3/C4/E4 melody, appearing as darker blue horizontal bands. Percussive transient bursts at ~3200 Hz appear as small blue spots at four time positions. Four section-label annotations ("G3 phrase", "C4 transition", "E4 peak", "C4 fadeout") are rendered in dark ink at the top of the heatmap area, separated by dashed vertical dividers. Y-axis label "Frequency (Hz, mel-scaled)" and X-axis label "Time (s)" are bold dark text. Tick labels are soft-grey. The colorbar legend on the right ("Power (dB)") runs from -80 dB to 0 dB. Subtitle is readable in soft grey. All text is clearly readable against the light background. Legibility verdict: PASS.

Dark render (plot-dark.png): The same plot on the warm near-black background (#1A1A17). The heatmap data colors are identical to the light render — only the chrome flips. Title, subtitle, axis labels, tick labels, section annotations, and colorbar labels are rendered in light cream/soft-grey tones against the dark surface. No dark-on-dark failures observed; all labels and ticks are comfortably readable. The dashed dividers are semi-transparent off-white for the dark theme. Legibility verdict: PASS.

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

Score: 86/100

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

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8) — All text readable in both themes; section labels on teal heatmap background have slightly reduced contrast vs. a plain bg, minor deduction
• VQ-02: No Overlap (6/6) — No text or element collisions
• VQ-03: Element Visibility (5/6) — Heatmap cells visible; mel-spectrogram structure is somewhat flat/teal-dominated because signal energy is narrow-band — inherent to the data, but dynamic range could be improved
• VQ-04: Color Accessibility (2/2) — Imprint sequential palette; CVD-safe; no red/green sole-signal encoding
• VQ-05: Layout & Canvas (4/4) — 3200x1800, canvas gate passed; well-proportioned margins; colorbar right-aligned
• VQ-06: Axis Labels & Title (2/2) — "Time (s)", "Frequency (Hz, mel-scaled)", "Power (dB)" all descriptive with units
• VQ-07: Palette Compliance (2/2) — imprint_seq correctly applied: minColor #009E73 to maxColor #4467A3; backgrounds #FAF8F1/#1A1A17; both renders theme-correct

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) — Musical phrase section annotations and subtitle give the chart narrative context; above default but not outstanding polish
• DE-02: Visual Refinement (4/6) — Spines removed, no grid on heatmap (appropriate), clean heatmap cell borders off; above default
• DE-03: Data Storytelling (4/6) — Section labels + dashed dividers + subtitle together tell the musical phrase story; clear focal points per phrase

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Mel-spectrogram as heatmap; correct chart type
• SC-02: Required Features (4/4) — dB scale applied; sequential colormap; time X-axis; mel Hz Y-axis; dB colorbar; n_fft=2048, hop_length=512, n_mels=128; synthesized audio data
• SC-03: Data Mapping (3/3) — X=time(s), Y=mel-scaled Hz, color=power(dB); correct
• SC-04: Title & Legend (3/3) — "spectrogram-mel · python · highcharts · anyplot.ai"; colorbar labeled "Power (dB)"

Data Quality (13/15)

• DQ-01: Feature Coverage (5/6) — Manual mel filterbank, dB conversion, vibrato, harmonics, percussive transients; comprehensive signal synthesis
• DQ-02: Realistic Context (4/5) — Musical melody at 22050 Hz, 4 s; plausible and neutral
• DQ-03: Appropriate Scale (4/4) — dB range -80 to 0; time 0-4 s; frequency up to ~5 kHz; all domain-appropriate

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — No functions or classes; linear script
• CQ-02: Reproducibility (2/2) — np.random.seed(42)
• CQ-03: Clean Imports (2/2) — All imports used
• CQ-04: Code Elegance (2/2) — Clear structure; no fake UI
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html; PIL guard for exact canvas dims

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Correct HeatmapSeries + color_axis; category-based axes; Renderer API for SVG overlays; CDN-inline pattern per guide
• LM-02: Distinctive Features (3/5) — Uses Highcharts Renderer API for custom dashed dividers and phrase-label SVG overlays; coloraxis with explicit dB stops; above default

Score Caps Applied

• None

Strengths

• Full spec compliance: all required features present and correct (mel filterbank, dB scale, sequential colormap, time/Hz axes, colorbar)
• Musical phrase narrative annotations via Highcharts Renderer API add genuine storytelling without any fake interactivity
• Correct Imprint sequential palette applied to color_axis (minColor #009E73 to maxColor #4467A3)
• Both renders fully theme-adaptive with correct background, ink, and chrome tokens
• PIL canvas-pinning guard prevents off-by-one dimension failures; canvas exactly 3200x1800
• Clean, KISS code with deterministic seed and all imports used

Weaknesses

• Section labels are positioned at plotTop + 52px inside the heatmap area; they sit on a teal/green heatmap background which provides less contrast than a plain background — consider positioning them in the margin above the plot or using a more prominent font weight/color
• The mel spectrogram appears visually flat (predominantly mid-range teal) because signal energy is narrow-band below ~500 Hz; a narrower dB floor (e.g., -60 dB clip instead of -80 dB) would compress the colormap dynamic range and make the signal structure more visually salient

Issues Found

1. DE-01 MODERATE: Section labels positioned inside heatmap at plotTop+52px — on teal background contrast is reduced vs. above-plot placement
   • Fix: Move renderer label y-position to plotTop - 20 (above heatmap into margin) or increase label prominence
2. DQ-01 MINOR: Flat visual appearance due to wide dB floor
   • Fix: Clip at -60 dB instead of -80 dB (np.clip(mel_spec_db, -60, 0)) and update color_axis.min to -60 to improve perceptual contrast

AI Feedback for Next Attempt

The implementation is solid and spec-complete. Two targeted improvements: (1) move section label annotations above the heatmap plot area (into the margin) so they sit on the background rather than heatmap cells — use plotTop - 20 as the renderer y-coordinate; (2) change the dB clip from -80 to -60 (np.clip(mel_spec_db, -60, 0) and color_axis min: -60) to improve perceptual contrast and make the melodic structure more visually prominent.

Verdict: APPROVED

[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 "spectrogram-mel · python · highcharts · anyplot.ai" is bold and prominently placed at the top (~70% of width at 66px). A subtitle "Mel-scaled power spectrum — ascending melodic phrase G3→C4→E4→C4 with percussive transients" sits below it. Four section labels ("G3 phrase", "C4 transition", "E4 peak", "C4 fadeout") are positioned just above the heatmap area, separated by faint dashed vertical dividers. The heatmap uses the Imprint sequential colormap (brand green #009E73 → blue #4467A3), showing distinct horizontal energy bands at lower frequencies for each musical phrase. The Y-axis is labeled "Frequency (Hz, mel-scaled)" with Hz tick labels from 15 to 5387; X-axis is "Time (s)" from −0.05 to 3.76. A vertical colorbar on the right labeled "Power (dB)" spans 0 dB (top) to −60 dB (bottom). All text is clearly readable against the light background — no "light on light" failures.

Dark render (plot-dark.png): The same plot renders on a warm near-black #1A1A17 background. Title, axis labels, tick labels, and section annotations are rendered in light/warm-grey tones (#F0EFE8 / #B8B7B0) and are fully readable against the dark background. The heatmap data colors are identical to the light render — same green-to-blue gradient with the same musical energy pattern. The legend background uses #242420 (ELEVATED_BG) with #B8B7B0 border. No "dark-on-dark" failures detected. Chrome-only elements have flipped correctly; all data colors are unchanged.

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

Score: 90/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	7	10
Total	90	100

Visual Quality (30/30)

• VQ-01: Text Legibility (8/8) — All font sizes explicitly set (title 66px dynamic, subtitle 38px, axis titles 56px, ticks 44px); well-proportioned in both themes; no overflow; balanced axis labels.
• VQ-02: No Overlap (6/6) — Section labels, tick labels, and colorbar labels are all clearly separated; no collisions.
• VQ-03: Element Visibility (6/6) — Heatmap cells show full dynamic range (−60 to 0 dB); energy bands are clearly distinguishable; colsize/rowsize=1 ensures uniform cell coverage.
• VQ-04: Color Accessibility (2/2) — Imprint sequential colormap (green→blue) is perceptually uniform and CVD-safe.
• VQ-05: Layout & Canvas (4/4) — Canvas 3200×1800; plot fills ~80% of canvas; colorbar well-positioned; generous margins (top 175, bottom 150, right 255, left 215).
• VQ-06: Axis Labels & Title (2/2) — "Time (s)", "Frequency (Hz, mel-scaled)", "Power (dB)" — all descriptive with units.
• VQ-07: Palette Compliance (2/2) — Uses imprint_seq (green #009E73 → blue #4467A3) for single-polarity continuous data; backgrounds #FAF8F1/#1A1A17; full theme-adaptive chrome in both renders.

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) — Above the "well-configured default" baseline: dynamic title fontsize, Imprint colormap, section annotations, subtitle with context. Not yet FiveThirtyEight-level polish.
• DE-02: Visual Refinement (4/6) — Clean minimal chrome: gridLineWidth=0, lineWidth=0, tickLength=0. No axis spines. Tasteful legend with ELEVATED_BG border. Good whitespace.
• DE-03: Data Storytelling (4/6) — Section labels (G3 phrase / C4 transition / E4 peak / C4 fadeout) with dashed vertical dividers provide clear musical narrative; subtitle reinforces the story. Visual hierarchy guides the reader through the melodic progression.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct mel-spectrogram implemented as a heatmap with manually computed mel filter bank.
• SC-02: Required Features (4/4) — dB conversion, mel-scaled Y-axis with Hz labels, X-axis in seconds, colorbar labeled in dB, n_fft=2048, hop_length=512, n_mels=128; synthesized audio signal.
• SC-03: Data Mapping (3/3) — Time on X, mel-scaled frequency on Y, power (dB) encoded as color.
• SC-04: Title & Legend (3/3) — Title matches {spec-id} · python · highcharts · anyplot.ai format; colorbar labeled "Power (dB)".

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Synthesized audio with fundamentals + harmonics, percussive transients, and four distinct melodic phrases; covers full dynamic range.
• DQ-02: Realistic Context (5/5) — Neutral musical melody (G3→C4→E4→C4 ascending phrase) representing a realistic audio ML preprocessing scenario.
• DQ-03: Appropriate Scale (4/4) — sample_rate=22050 Hz, duration=4 s, n_mels=128, dB range −60 to 0 — all standard for audio ML pipelines. Fundamental frequencies (G3=196 Hz, C4=262 Hz, E4=330 Hz) are factually correct.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear: imports → data synthesis → mel filter bank → heatmap data → chart config → render → save. No classes or functions.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set.
• CQ-03: Clean Imports (2/2) — All imports used; no dead imports.
• CQ-04: Code Elegance (2/2) — Clean, readable code; Renderer overlay for annotations is appropriate complexity; no fake UI.
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html; current API throughout.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Uses Chart(container="container"), HighchartsOptions, HeatmapSeries, color_axis, CDP viewport override — all following the recommended highcharts-core patterns from the library guide.
• LM-02: Distinctive Features (3/5) — Highcharts Renderer API (chart.renderer.path(), chart.renderer.text(), xAxis.toPixels()) for custom SVG overlays; color_axis with custom stops and symbolHeight/symbolWidth for colorbar sizing — features specific to Highcharts.

Score Caps Applied

• None — no caps triggered.

Strengths

• Perfect spec compliance: mel filter bank computed from scratch (no librosa dependency), all required parameters (n_fft=2048, hop_length=512, n_mels=128) respected.
• Imprint sequential colormap (#009E73 → #4467A3) correctly applied to single-polarity continuous dB data.
• Section annotations with Highcharts Renderer API create genuine data storytelling — the four musical phrases are immediately identifiable.
• Fully theme-adaptive in both renders; no dark-on-dark or light-on-light failures.
• PIL safety-net pinning ensures exact 3200×1800 canvas dimensions.

Weaknesses

• The colormap direction (minColor=#009E73 at −60 dB silence, maxColor=#4467A3 at 0 dB loud) maps silence to green and loud sounds to blue — slightly counterintuitive for spectrograms where convention typically uses warmer/brighter colors for high energy. Swapping to minColor="#4467A3" / maxColor="#009E73" would feel more natural.
• First X-axis tick label shows "−0.05" (artifact of scipy's centered spectrogram windowing) — could confuse viewers expecting time to start at 0.

Issues Found

1. DE-01 MODERATE: Good design but short of FiveThirtyEight-level polish — section annotations add real value but overall aesthetic is a well-configured default.
   • Fix: Could enhance with subtle per-section background shading or more refined colorbar styling.
2. LM-02 PARTIAL: Highcharts Renderer API usage is good but could go further.
   • Fix: Could use Highcharts plotBands/plotLines for the section dividers instead of raw SVG renderer, which would be more idiomatic.

AI Feedback for Next Attempt

The implementation is strong and meets all spec requirements. For further improvement: (1) consider swapping the colormap direction so high energy (0 dB) maps to #009E73 (green, perceptually "louder") and silence maps to #4467A3 (blue); (2) use Highcharts xAxis.plotLines and plotBands for the section dividers/labels rather than the raw renderer API — this is more idiomatic and avoids the setTimeout race condition; (3) the −0.05 first tick can be clamped to 0.00 for cleaner axis presentation.

Verdict: APPROVED