feat(highcharts): implement piano-roll-midi

[github-actions]

Implementation: piano-roll-midi - python/highcharts

Implements the python/highcharts version of piano-roll-midi.

File: plots/piano-roll-midi/implementations/python/highcharts.py

Parent Issue: #4565

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): Warm off-white #FAF8F1 background — correct light surface. Bold title "piano-roll-midi · python · highcharts · anyplot.ai" clearly readable in dark INK. Subtitle "C – Am – F – G · 8 measures of 4/4 · velocity-colored dynamics" in INK_SOFT below the title. X-axis "Beats (quarter notes)" and Y-axis "Pitch" labels readable. Tick labels (note names C3–C5 on Y, beat numbers 0–32 on X) in INK_SOFT — all readable. Horizontal bars (xrange) velocity-mapped from teal (piano/60) through amber/orange (mezzo/93) to crimson/red (forte/127). Melody bars widest (pointWidth=44, white borders), bass bars tallest (pointWidth=52, dark borders, 0.9 opacity), harmony bars smallest (pointWidth=30, 0.6 opacity). Alternating black-key row shading is subtle and clearly visible. Beat gridlines with stronger measure boundaries at beats 0/4/8…/32. Velocity colorbar at right edge with forte/127, mezzo/93, piano/60 labels. Chord labels (C, C, Am, Am, F, F, G, G) above the plot area. Issue: chord label "Am" at beat 10 (y=148) overlaps the subtitle text area (y=126, 38px font, bottom ≈y=145) creating a visual collision where "Am" appears immediately before "C – Am – F – G…". Legibility verdict: PASS (all text readable; chord/subtitle overlap is visual noise, not a readability failure).

Dark render (plot-dark.png): Warm near-black #1A1A17 background — correct dark surface. Title, axis labels, and tick labels all render in light #F0EFE8/#B8B7B0 tones against the dark background — clearly readable with no dark-on-dark failures. Data colors are identical to the light render (teal/amber/crimson velocity gradient is theme-independent as required). Black-key row shading uses rgba(255,255,255,0.07) — subtly visible against dark background. Beat gridlines use GRID token rgba(240,239,232,0.15). Legend items, colorbar labels, and chord labels all readable in #B8B7B0. Legibility verdict: PASS (no dark-on-dark failures detected; all chrome elements correctly flip to light tones).

Score: 87/100

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

Visual Quality (25/30)

• VQ-01: Text Legibility (7/8) — Font sizes at style-guide defaults (title 66px, axis 56px, ticks 44px). Readable in both themes. Minor deduction for chord labels sitting very tight against the subtitle.
• VQ-02: No Overlap (4/6) — Chord labels "Am" at beats 10 and 14 (y=148, 32px font) overlap with the subtitle text (y=126, 38px font, bottom ≈y=145); both occupy the same y band AND same horizontal x range, causing "Am" to appear immediately before "C – Am – F – G…".
• VQ-03: Element Visibility (6/6) — All note bars clearly visible. Velocity gradient cleanly encodes dynamics. Alternating row shading appropriately subtle. Role differentiation via pointWidth clearly distinguishable.
• VQ-04: Color Accessibility (2/2) — Velocity colormap teal→amber→crimson is CVD-safe; three perceptually distinct stops, not solely red-green.
• VQ-05: Layout & Canvas (3/4) — Canvas 3200×1800 correct. Generous margins. Title ≈75% width — expected. Minor deduction for tight chord-label/subtitle vertical spacing.
• VQ-06: Axis Labels & Title (2/2) — Correct title format. "Beats (quarter notes)" and "Pitch" descriptive with note name categories on Y.
• VQ-07: Palette Compliance (1/2) — Backgrounds #FAF8F1/#1A1A17 correct; chrome tokens correctly applied. Violations: (1) continuous velocity colormap is custom teal→amber→crimson instead of required imprint_seq/imprint_div — reversed imprint_div (#4467A3 at vel=60 → #AE3030 at vel=127) would satisfy both spec semantics and palette policy; (2) categorical legend colors (#d94040 Melody, #2a7a8a Bass, #c0a030 Harmony) don't follow Imprint palette — first series must use #009E73.

Design Excellence (14/20)

• DE-01: Aesthetic Sophistication (6/8) — Well above baseline: three-stop velocity gradient, role differentiation via pointWidth/opacity/border, black-key row shading via plotBands, chord labels above plot via renderer, velocity colorbar with dynamics labels — all evidence of intentional design.
• DE-02: Visual Refinement (4/6) — Subtle grid (GRID token), no visible spines (lineWidth=0), elegant alternating row banding, polished legend with elevated background and border.
• DE-03: Data Storytelling (4/6) — C–Am–F–G progression clearly visible. Velocity coloring shows dynamics immediately. Chord labels above the plot provide musical context. Clear focal point on melody notes.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — xrange chart = piano roll. Horizontal bars by pitch (Y) and time (X), length = duration.
• SC-02: Required Features (4/4) — Note names on Y-axis ✓; black-key row shading via plotBands ✓; beat/measure gridlines with stronger measure boundaries ✓; velocity colorbar with piano/mezzo/forte labels ✓; auto-fit pitch range (C3–C5) ✓.
• SC-03: Data Mapping (3/3) — X=start beat, X2=start+duration, Y=pitch, color=velocity. All fields correctly mapped.
• SC-04: Title & Legend (3/3) — Title "piano-roll-midi · python · highcharts · anyplot.ai" correct. Legend shows Melody/Bass/Harmony. Subtitle adds musical context.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows pitch, time, duration, velocity, and musical role. 70 notes across 8 measures covering all piano roll dimensions.
• DQ-02: Realistic Context (5/5) — C–Am–F–G is one of the most common pop progressions. MIDI numbers, timing, and velocities are musically realistic and educationally appropriate.
• DQ-03: Appropriate Scale (4/4) — 32 beats, 70 notes, C3–C5 range, velocity 60–127 — appropriate for a demonstration phrase.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — No functions or classes; top-level procedural code.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set; hardcoded data is fully deterministic.
• CQ-03: Clean Imports (2/2) — All imports used.
• CQ-04: Code Elegance (2/2) — Appropriate complexity; inline velocity interpolation is clear; no fake UI.
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html. Highcharts v11.4.8.

Library Mastery (8/10)

• LM-01: Idiomatic Usage (4/5) — Chart(container="container") correct; HighchartsOptions properly structured; xrange type correctly applied.
• LM-02: Distinctive Features (4/5) — xrange series type, plotBands for row shading, plotLines for beat grid, Highcharts renderer for custom colorbar and chord labels, tooltip with custom data properties — distinctive Highcharts features well utilized.

Score Caps Applied

• None

Strengths

• Full spec compliance: note names on Y-axis, alternating black-key row shading, beat/measure gridlines, velocity colorbar, auto-fit pitch range — all implemented correctly
• Sophisticated velocity colormap (teal→amber→crimson) cleanly encodes dynamics; three-stop gradient is perceptually distinct and musically conventional
• Musical role differentiation (Melody/Bass/Harmony) via distinct pointWidth, opacity, and border styling adds visual hierarchy without a separate color channel
• Chord labels (C, Am, F, G) rendered above the plot via Highcharts renderer — excellent musical storytelling touch
• Theme-adaptive chrome fully correct: PAGE_BG, INK, INK_SOFT, ELEVATED_BG, GRID tokens applied to all non-data elements; both themes readable
• Canvas pinned to exact 3200×1800 via CDP override + PIL safety net

Weaknesses

• Chord labels "Am" at beats 10 and 14 (y=148) overlap vertically with the subtitle text (y=126, 38px font, bottom ≈y=145) — fix by moving chord labels to y=168 or increasing marginTop to 180 and positioning chord labels at y=172
• Continuous velocity colormap is a custom teal→amber→crimson gradient instead of required imprint_seq/imprint_div — use reversed imprint_div stops: [[0, '#4467A3'], [0.5, theme_midpoint], [1, '#AE3030']] to satisfy both spec semantics (blue=soft, red=loud) and Imprint palette policy
• Categorical legend colors (#d94040 Melody, #2a7a8a Bass, #c0a030 Harmony) don't follow Imprint palette — assign #009E73, #C475FD, #4467A3 as the three series legend colors

Issues Found

1. VQ-02 MODERATE: Chord labels "Am" at beats 10/14 overlap vertically with the subtitle text at y=126–148
   • Fix: Move chord label y position to 168 (or increase marginTop to 180 and move chord labels to y=172)
2. VQ-07 VIOLATION: Custom velocity colormap uses non-Imprint continuous gradient
   • Fix: Replace custom _s0/_s1/_s2 with reversed imprint_div: #4467A3 (soft/piano) → theme midpoint → #AE3030 (loud/forte)
3. VQ-07 VIOLATION: Legend series colors don't follow Imprint palette
   • Fix: Use series_configs = [("Melody", "melody", "#009E73"), ("Bass", "bass", "#C475FD"), ("Harmony", "harmony", "#4467A3")]

AI Feedback for Next Attempt

Fix three issues in order of impact: (1) Move chord labels from y=148 to y=168 to clear the subtitle text zone — or increase marginTop to 180 and set chord labels at y=172. (2) Replace the custom teal→amber→crimson velocity gradient with a reversed imprint_div colormap: [[0, '#4467A3'], [0.5, '#FAF8F1' if THEME=='light' else '#1A1A17'], [1, '#AE3030']] applied as a 3-stop linear interpolation — this preserves the musical semantics (blue=soft, red=loud) while satisfying the Imprint palette policy. (3) Update series legend colors to Imprint order: Melody=#009E73, Bass=#C475FD, Harmony=#4467A3. Everything else is excellent — preserve the xrange piano roll structure, black-key plotBands, beat plotLines, renderer-based colorbar, and all theme-adaptive chrome tokens.

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): Warm off-white #FAF8F1 background. The piano roll spans 32 beats (8 measures of 4/4) on the X-axis and pitches C3–C5 on the Y-axis, with note names clearly labeled. Horizontal bars are velocity-colored using the imprint_div diverging scale: cool blue (#4467A3) for soft notes rising through a cream midpoint to deep crimson (#AE3030) for the loud G-measure climax at beats 28–31. Per-role differentiation is visible — melody bars are widest with white borders, bass bars are widest+dark-bordered, harmony bars narrower and at 60% opacity. Alternating row shading marks black piano keys (subtle ~7% dark overlay). Beat grid lines run vertically, with stronger lines at every 4-beat measure boundary. Chord annotations (C, C, Am, Am, F, F, G, G) appear above the plot area in italic INK_SOFT. A custom velocity colorbar on the right runs from forte (127, red) to piano (60, blue) with "mezzo/93" mid-label. Legend at bottom: Melody (green swatch), Bass (purple swatch), Harmony (blue swatch) all in 44px text. All primary text is clearly readable against the light background.

Dark render (plot-dark.png): Warm near-black #1A1A17 background. Same layout with theme-adaptive chrome — title, axis labels, tick labels, chord annotations, and colorbar labels all rendered in light ink (#F0EFE8/#B8B7B0). Data colors are identical to the light render — the same imprint_div blue-to-red velocity gradient appears unchanged across both themes (Imprint palette identity preserved). Legend background shifts to #242420. Alternating black-key shading at 7% white opacity is subtly visible. Harmony bars at 60% opacity appear slightly more muted on the dark surface than on light but remain distinguishable. No dark-on-dark failures — all text is readable against the near-black background. Brand elements correctly adapt.

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

Score: 94/100

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

Visual Quality (28/30)

• VQ-01: Text Legibility (6/8) — Primary labels correctly sized (title 66px, axis titles 56px, tick labels 44px, legend 44px) and readable in both themes. Chord annotations at 32px and colorbar labels (forte/mezzo/piano at 30px, values at 28px) are below the 44px floor — legible at full 3200px resolution but would struggle at mobile 400px scale.
• VQ-02: No Overlap (6/6) — No overlapping text or data elements in either render.
• VQ-03: Element Visibility (6/6) — All note bars clearly visible; velocity colorbar gradient correct; alternating key shading present in both themes.
• VQ-04: Color Accessibility (2/2) — Imprint diverging colormap with labeled anchors (forte/mezzo/piano). Role differentiation uses pointWidth + opacity as redundant encodings.
• VQ-05: Layout & Canvas (4/4) — Canvas 3200×1800 confirmed. Generous margins; no clipping observed.
• VQ-06: Axis Labels & Title (2/2) — Correct title format; X-axis "Beats (quarter notes)" includes units; Y-axis "Pitch" concise and appropriate.
• VQ-07: Palette Compliance (2/2) — imprint_div correctly applied (blue #4467A3 → PAGE_BG midpoint → red #AE3030). Backgrounds #FAF8F1/#1A1A17. First legend series (Melody) is #009E73 brand green.

Design Excellence (16/20)

• DE-01: Aesthetic Sophistication (7/8) — Genuinely sophisticated: per-note velocity color interpolation, per-role visual differentiation (pointWidth + opacity + border treatment), piano keyboard alternating row shading, custom velocity colorbar via Highcharts renderer, chord annotations above plot, informative subtitle. Well above default level.
• DE-02: Visual Refinement (5/6) — Axes cleaned (lineWidth=0, tickLength=0), credits disabled, subtle beat grid, polished legend with rounded corners/padding. Harmony opacity differentiation adds musical refinement.
• DE-03: Data Storytelling (4/6) — Chord annotations (C–Am–F–G) narrate the harmonic journey; velocity colorbar explains the dynamics arc; subtitle contextualizes the piece. Missing: no explicit focal point highlighting the climax (the high-velocity G-measure peak at beats 28–31, velocity 115–125, could be annotated or visually emphasized).

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct piano roll using xrange chart type with horizontal bars by pitch and time.
• SC-02: Required Features (4/4) — Note names on Y-axis, black/white key row alternation, beat division grid lines, stronger lines at measure boundaries, velocity colormap.
• SC-03: Data Mapping (3/3) — Start→X, pitch→Y, duration→bar width (x to x2), velocity→color. Pitch auto-fit to data range C3–C5.
• SC-04: Title & Legend (3/3) — Title matches exact required format. Legend shows Melody/Bass/Harmony with #009E73 first-series swatch.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Multiple octaves, varied durations (0.5–4.0 beats), velocity range 60–125, three musical roles, 8 measures 4/4, 68 notes.
• DQ-02: Realistic Context (5/5) — C–Am–F–G is a universally recognized, neutral chord progression. Authentic MIDI values throughout.
• DQ-03: Appropriate Scale (4/4) — 32 beats = 8 measures 4/4. MIDI 48–72 (C3–C5 centered on middle C). 68 notes within spec's 20–200 range.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Flat, linear structure; no unnecessary abstractions.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set; hardcoded notes guarantee determinism.
• CQ-03: Clean Imports (2/2) — All imports used.
• CQ-04: Code Elegance (2/2) — Clean velocity interpolation logic; inline JS for renderer is complex but unavoidable.
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html correctly.

Library Mastery (10/10)

• LM-01: Idiomatic Usage (5/5) — xrange type used correctly; chart.options API throughout; container='container'; CDP viewport override; PIL canvas pin.
• LM-02: Distinctive Features (5/5) — Highcharts renderer API for custom colorbar + chord annotations; plotBands for key shading; plotLines for beat grid; per-point color in xrange; /tmp JS cache for faster re-runs.

Score Caps Applied

• None — no caps triggered.

Strengths

• Perfect spec compliance: all five piano roll requirements (note names, key shading, beat/measure grid, velocity colormap, auto-fit range) correctly implemented
• Sophisticated per-role visual differentiation: pointWidth + opacity + border treatment provides musical hierarchy without introducing a separate color encoding channel
• Custom velocity colorbar and chord annotations built with Highcharts renderer API showcase library-specific capabilities not available in static libraries
• Correct imprint_div colormap (blue→midpoint→red) with labeled velocity anchors (forte/mezzo/piano) — both palette and design choice are correct
• Canvas 3200×1800 exact, CDP override + PIL pin in place, theme tokens correctly threaded through all chrome elements

Weaknesses

• Chord annotations (32px) and colorbar labels (forte/mezzo/piano 30px, values 28px) are below the 44px secondary-text floor — at mobile 400px scale these would be unreadably small; raise to 36–40px minimum
• No highlighted focal point or climax annotation — the high-velocity G-measure peak at beats 28–31 (velocity 115–125) is the natural climax of the piece but gets no special emphasis; a subtle annotation or slightly increased bar prominence there would elevate the storytelling score
• Harmony bars at opacity=0.6 become noticeably dimmer on the dark background; consider using theme-adaptive opacity (e.g. 0.60 light / 0.75 dark) to maintain consistent visual weight across both renders

Issues Found

1. VQ-01 MINOR: Supplementary text below 44px floor
   • Chord labels: 32px → raise to 38px minimum
   • Colorbar labels (forte/mezzo/piano): 30px → raise to 36px
   • Colorbar value labels (127/93/60): 28px → raise to 34px
2. DE-03 MODERATE: No focal point or climax emphasis
   • Consider annotating the high-velocity G-measure peak (beats 28–31) with a subtle label or a slightly thicker note border to guide the viewer's eye to the dynamic climax

AI Feedback for Next Attempt

The implementation is excellent — all spec requirements met, correct imprint_div colormap, proper theme tokens. Focus the next attempt on two targeted improvements: (1) raise supplementary annotation text sizes (chord labels to 38px, colorbar labels to 36px, colorbar values to 34px) so they pass the mobile 400px readability check; (2) add a simple text annotation near the climax notes (beat 28–31, velocity 115–125) to give the visualization a clear focal point — something like "Dynamic climax" or an arrow pointing to the forte G-measure.

Verdict: APPROVED