feat(pygal): implement spectrogram-mel

[github-actions]

Implementation: spectrogram-mel - python/pygal

Implements the python/pygal version of spectrogram-mel.

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

Parent Issue: #4672

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): The plot displays a mel-spectrogram on a warm off-white #FAF8F1 background. The x-axis shows time from 0.0 to 3.0 seconds with seven evenly-spaced tick labels; the y-axis shows mel-scaled frequency from 100 Hz to 8.0 kHz with labels at 100, 200, 500, 1.0k, 2.0k, 4.0k, and 8.0k. A colorbar on the right side is labeled "dB" and spans from 0 at the top to −80 at the bottom. The spectrogram uses the inferno colormap (deep purple for low-energy regions, orange-yellow for high-energy peaks). Six musical note annotations (C4, E4, G4, C5, G4, E4) appear as white-text labels with dual-ring circle markers at the onset of each note in the 330–524 Hz band. The horizontal bands of energy clearly show the C-major arpeggio rising and falling. All text (title, axis labels, tick labels, colorbar values, note names) is clearly readable against the light background in dark ink.
Legibility verdict: PASS

Dark render (plot-dark.png): Identical spectrogram structure on a near-black #1A1A17 background. The title, axis labels ("Frequency (Hz)", "Time (s)"), tick labels, colorbar values, and note annotations are all rendered in light-colored ink and remain clearly readable against the dark surface. The data colors (inferno colormap gradient from deep purple to yellow) are visually identical between both renders — only the background and chrome text colors flip. No dark-on-dark failures observed; all text is legible.
Legibility verdict: PASS

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

Score: 80/100

Category	Score	Max
Visual Quality	26	30
Design Excellence	12	20
Spec Compliance	15	15
Data Quality	15	15
Code Quality	8	10
Library Mastery	4	10
Total	80	100

Visual Quality (26/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set; dynamic title scaling applied; axis labels, tick labels, and colorbar labels readable in both themes. Minor deduction: note annotation shadow rendering is somewhat crude.
• VQ-02: No Overlap (6/6) — Note annotations staggered at distinct time positions; no text collisions observed.
• VQ-03: Element Visibility (6/6) — Spectrogram cells clearly rendered; note markers (dual-ring circle + white label) visible against the varying spectrogram colors.
• VQ-04: Color Accessibility (1/2) — Inferno is luminance-monotonic and functional for CVD, but the Imprint palette is specifically optimized for CVD safety; partial credit.
• VQ-05: Layout & Canvas (4/4) — 3200×1800 landscape canvas; spectrogram fills the plot area well; colorbar properly positioned to the right with sensible margins.
• VQ-06: Axis Labels & Title (2/2) — X-axis "Time (s)", Y-axis "Frequency (Hz)", colorbar "dB" — all descriptive with units.
• VQ-07: Palette Compliance (0/2) — Non-compliant: uses inferno colormap for continuous data. The Imprint rules require imprint_seq (#009E73 → #4467A3) for single-polarity continuous data. The pygal library prompt explicitly states "never substitute viridis or any other named cmap". Plot backgrounds and chrome are correct, but the cmap choice disqualifies full compliance.

Design Excellence (12/20)

• DE-01: Aesthetic Sophistication (4/8) — Resembles a well-configured scientific visualization default. The dual-ring note annotation markers add intentional design polish but not enough to push above the default tier.
• DE-02: Visual Refinement (4/6) — No grid lines (appropriate for spectrogram); explicit border around the plot area; clean colorbar; balanced whitespace. Not exceptional but clearly above minimal.
• DE-03: Data Storytelling (4/6) — The six note annotations (C4, E4, G4, C5, G4, E4) actively guide the viewer through the C-major arpeggio structure. The ascending then descending energy bands tell a clear musical story.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct mel-spectrogram implementation.
• SC-02: Required Features (4/4) — Power converted to dB; x-axis time in seconds; y-axis mel-scaled Hz with tick labels at band edges; colorbar labeled in dB; n_fft=2048, hop_length=512, n_mels=128; synthesized audio (no external files).
• SC-03: Data Mapping (3/3) — Time on x-axis, mel-scaled frequency on y-axis, dB intensity as color.
• SC-04: Title & Legend (3/3) — Title is "spectrogram-mel · python · pygal · anyplot.ai"; no legend needed (single colormap + colorbar).

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows full frequency range, temporal variation, harmonic overtones, exponential amplitude envelope, and clear spectral contrast between notes.
• DQ-02: Realistic Context (5/5) — C-major arpeggio (C4→E4→G4→C5→G4→E4) is a real, neutral, comprehensible musical scenario.
• DQ-03: Appropriate Scale (4/4) — sample_rate=22050 Hz, duration=3s, correct note frequencies (C4=261.6 Hz, C5=523.3 Hz), dB range −80 to 0.

Code Quality (8/10)

• CQ-01: KISS Structure (2/3) — Class (MelSpectrogramChart) and helper function (interpolate_color) present; violates KISS. The class is architecturally necessary because pygal has no native heatmap/spectrogram type, but it adds significant complexity.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set.
• CQ-03: Clean Imports (2/2) — All imports are used (os, sys, numpy, scipy.signal, pygal internals).
• CQ-04: Code Elegance (1/2) — Functional but verbose; _plot() is ~115 lines of raw SVG node manipulation. Acceptable given the constraints.
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png, plot-{THEME}.svg, and plot-{THEME}.html correctly.

Library Mastery (4/10)

• LM-01: Idiomatic Usage (2/5) — Bypasses pygal's public API entirely; directly manipulates the internal svg.node() tree and _box coordinate system. Correct but deeply non-idiomatic — it treats pygal as an SVG framework rather than a charting library.
• LM-02: Distinctive Features (2/5) — HTML interactive output is a genuine pygal strength and is implemented. Extending pygal.graph.graph.Graph for a custom chart type is library-specific. However, the core rendering is manual SVG, not leveraging anything unique to pygal's charting capabilities.

Score Caps Applied

• None — DE-01=4 (above the ≤2 threshold required for the "correct but boring" cap).

Strengths

• Excellent spec compliance: every required feature (dB conversion, mel-scaled y-axis, colorbar, synthesized audio, correct parameters) is present and working.
• Outstanding data quality: realistic C-major arpeggio with correct note frequencies, harmonics, and exponential envelope.
• Note annotation design (dual-ring circle + text shadow) is a thoughtful data storytelling choice.
• Both themes render correctly with no dark-on-dark failures; all chrome is theme-adaptive.
• Correct canvas size (3200×1800); canvas gate passed.

Weaknesses

• [CRITICAL] Non-Imprint colormap: Implementation uses the inferno colormap instead of the required imprint_seq continuous colormap. Per the pygal library rules, interpolate manually between #009E73 and #4467A3 for the sequential color gradient (dark/low-energy → light/high-energy can be achieved by reversing the gradient: #4467A3 for low dB, #009E73 for high dB — or find the Imprint-derived gradient stops that span the full perceived luminance range). This is the primary blocking issue.
• Low library idiomatic score: The implementation bypasses pygal's public API in favour of raw svg.node() calls. Consider using pygal.Bar() or pygal.XY() with many thin bars/points as an approximation, or at minimum wrap the SVG node calls more cleanly.
• KISS violation: interpolate_color() function and MelSpectrogramChart class are necessary but push complexity above the preferred flat script style. The _plot() method (115 lines) could be split into smaller pieces, but the class itself cannot be easily removed.

Issues Found

1. VQ-07 = 0 (CRITICAL): Inferno colormap is not the Imprint imprint_seq cmap.
   • Fix: Replace the inferno_colors list with an interpolated gradient from #009E73 to #4467A3 (or reverse for low-to-high luminance mapping). Use the existing interpolate_color() helper to generate gradient stops at render time, e.g. colormap = [interpolate_color(i/(N-1), 0, 1, ["#4467A3", "#009E73"]) for i in range(N)].
2. LM-01/LM-02 LOW: Not leveraging pygal's charting strengths; mostly raw SVG.
   • Fix: If keeping the custom class approach, enhance the HTML output with pygal's built-in tooltip support to make the interactive version richer.

AI Feedback for Next Attempt

Primary fix (blocking): Replace the inferno colormap with an Imprint sequential gradient. The style guide mandates imprint_seq (#009E73 → #4467A3) for single-polarity continuous data. Since spectrogram intensity goes from low to high, use a reversed gradient — dark/desaturated for low dB, bright for high dB — interpolated manually using the existing interpolate_color() function between #4467A3 (dark-end, low energy) and #009E73 (bright-end, high energy). Keep all other aspects of the implementation as-is — the data, annotations, layout, and chrome are excellent.

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 mel-spectrogram fills the chart area from roughly x=160 to x=3000, showing time (0.0–3.0 s) on the x-axis and mel-scaled frequency (100–8.0k Hz) on the y-axis. The colormap runs from muted blue (#4467A3) at low dB to teal-green (#009E73) at high dB — harmonic bands are visible as horizontal bright-green stripes at the C-major arpeggio frequencies (below ~1 kHz). Six note annotations (C4, E4, G4, C5, G4, E4) appear as dual-ring circle markers with white text labels placed at each note onset. A colorbar on the right side is labeled "dB" with tick marks from 0 to −80. Title "spectrogram-mel · python · pygal · anyplot.ai" is dark text, clearly readable. All axis labels ("Frequency (Hz)", "Time (s)"), tick labels, colorbar labels, and note annotation text are readable against the light background. Legibility verdict: PASS.

Dark render (plot-dark.png): The same plot on a warm near-black (#1A1A17) background. Title, axis labels, and tick labels appear in light text, all readable against the dark background. The spectrogram data colors (blue → teal-green gradient) are visually identical to the light render — only the page background and text/chrome colors have flipped. The note annotation circles use hardcoded white/black rings with white text, which remain clearly visible over the spectrogram. The colorbar gradient, dB tick labels, and colorbar title "dB" are all readable. No dark-on-dark failures observed. Legibility verdict: PASS.

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

Score: 80/100

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

Visual Quality (25/30)

• VQ-01: Text Legibility (7/8) — Font sizes explicitly set (title formula, axis_label_size=56, tick_font_size=44); all text readable in both themes. Minor: tick labels could scale up slightly for sub-400px mobile crops.
• VQ-02: No Overlap (5/6) — Note annotation labels (C4, E4, G4, C5) spread across x and do not overlap each other or x-axis tick labels.
• VQ-03: Element Visibility (5/6) — Spectrogram harmonic bands clearly visible; circle markers and note labels legible over varying colormap values.
• VQ-04: Color Accessibility (1/2) — Blue (#4467A3) to teal-green (#009E73) have similar luminance levels; limited luminance contrast makes fine dB gradations hard to distinguish for low-vision or CVD users.
• VQ-05: Layout & Canvas (3/4) — Good 3200×1800 landscape proportions; colorbar well-positioned with clear margins. Slight tightness at bottom between x-axis tick labels and canvas edge.
• VQ-06: Axis Labels & Title (2/2) — Title in correct format. "Time (s)" and "Frequency (Hz)" both include units. Colorbar labeled "dB".
• VQ-07: Palette Compliance (2/2) — Colormap endpoints are Imprint palette members (#4467A3, #009E73). Backgrounds are #FAF8F1 (light) / #1A1A17 (dark). Chrome adapts correctly between themes.

Design Excellence (12/20)

• DE-01: Aesthetic Sophistication (5/8) — Custom chart class with dual-ring circle markers and text shadows on annotations shows deliberate design intent beyond pygal defaults. Colormap from Imprint palette is intentional.
• DE-02: Visual Refinement (3/6) — Clean chart area, no extraneous spines or grid lines. Spectrogram border subtly defined. Reasonable whitespace.
• DE-03: Data Storytelling (4/6) — Note annotations guide the viewer through the C-major arpeggio progression; clear narrative focal point. The horizontal harmonic bands visually confirm note onsets.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct mel-spectrogram visualization
• SC-02: Required Features (4/4) — dB scale, colorbar labeled dB, x-axis time in seconds, y-axis mel-scaled frequency with Hz labels at key bands, n_fft=2048, hop_length=512, n_mels=128 all present
• SC-03: Data Mapping (3/3) — X=time (s), Y=mel-frequency (Hz), color=power (dB)
• SC-04: Title & Legend (3/3) — Title is "spectrogram-mel · python · pygal · anyplot.ai" ✓; colorbar serves as the color legend

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) — Shows time, mel-frequency, power in dB, colorbar, note annotations. Minor: the 2-stop colormap slightly limits perceptual resolution of the intensity dimension.
• DQ-02: Realistic Context (5/5) — Synthesized C-major arpeggio is realistic, neutral, and domain-appropriate audio data
• DQ-03: Appropriate Scale (4/4) — 3 s at 22050 Hz, 128 mel bands, dB range −80 to 0 — all canonical parameters

Code Quality (7/10)

• CQ-01: KISS Structure (0/3) — Defines both a helper function (interpolate_color) and a class (MelSpectrogramChart). The "no functions/classes" rule is violated.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) ✓
• CQ-03: Clean Imports (2/2) — All imports used (os, sys, numpy, scipy, pygal)
• CQ-04: Code Elegance (2/2) — Well-structured given the complexity; no fake UI elements
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png, plot-{THEME}.svg, plot-{THEME}.html ✓

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Extends pygal.graph.graph.Graph, overrides _plot() and _compute(), uses svg.node for direct SVG construction — the idiomatic pygal extension pattern
• LM-02: Distinctive Features (3/5) — HTML export with interactive pygal SVG ✓; custom chart type extending Graph is pygal-distinctive; direct SVG node manipulation showcases library internals

Score Caps Applied

• None

Strengths

• Creative and correct use of pygal's Graph extension mechanism to implement a heatmap-style mel-spectrogram — the only viable approach given pygal's chart type limitations
• Note annotations (C4, E4, G4, C5, G4, E4) with dual-ring markers and text shadows create effective data storytelling and guide the viewer through the arpeggio
• Fully spec-compliant: dB scale, colorbar, mel-scaled frequency y-axis with Hz labels, correct STFT parameters (n_fft=2048, hop_length=512, n_mels=128)
• Both light and dark renders pass readability checks with correct Imprint palette backgrounds and theme-adaptive chrome

Weaknesses

• CQ-01: Defines both a helper function (interpolate_color) and a class (MelSpectrogramChart) — violates the flat-script "no functions/classes" rule; the interpolation logic could be inlined and the class replaced with top-level procedural code
• Two-stop colormap (#4467A3 → #009E73) reduces perceptual dynamic range; adding intermediate stops (e.g., a dark navy at 0%, teal at 50%, green at 100%) would reveal more spectral texture
• Blue-to-teal/green endpoint pair has limited luminance contrast, making low-vs-high dB differences harder to perceive, especially for CVD users; a darker blue start point or additional stops would improve accessibility (VQ-04)
• Bottom margin is slightly tight between x-axis tick labels and the canvas edge

Issues Found

1. CQ-01 VIOLATION: Defines both interpolate_color() function and MelSpectrogramChart class
   • Fix: Inline the interpolation into the drawing loop and replace the class with flat procedural code that builds the SVG directly
2. VQ-04 LOW: Blue (#4467A3) to green (#009E73) colormap has similar luminance across the range
   • Fix: Use a wider-contrast sequential gradient with a dark anchor (e.g., near-black Imprint-derived stop at the low end) for better perceptual separation

AI Feedback for Next Attempt

Remove the class and standalone function in favor of flat procedural code: inline the color interpolation and call pygal's SVG node methods at the top level. Consider adding a third color stop to the sequential colormap (e.g., dark navy → teal → brand-green) to improve luminance contrast and reveal more spectral detail. All other aspects (spec compliance, theme adaptation, annotations, canvas size, title format) are correct — preserve them.

Verdict: APPROVED