feat(letsplot): implement piano-roll-midi

[github-actions]

Implementation: piano-roll-midi - python/letsplot

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

File: plots/piano-roll-midi/implementations/python/letsplot.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 with alternating lighter (white keys, #FAF8F1) and slightly darker gray (#E4E3DC) horizontal rows correctly mirroring a piano keyboard layout. Title "piano-roll-midi · python · letsplot · anyplot.ai" in bold dark text (~80% width — expected for the mandatory long title format). X-axis label "Time (beats)" and Y-axis label "Pitch" in dark INK. Section labels (pp—Building, f—Response, pp—Restart, fff—Climax) in italic muted gray above the data area. Role labels "Melody" and "Accomp." in bold INK_SOFT on the right margin. Note rectangles colored with imprint_seq gradient: green #009E73 for low-velocity notes, transitioning to blue #4467A3 for high-velocity climax notes. Accompaniment notes appear as semi-transparent long horizontal bars in the lower register (A2–E3 range); melody notes are taller, fully opaque, with dark INK border in the upper register (D4–G5). Beat lines (subtle) and measure lines (stronger vertical lines) provide DAW-style grid. Velocity colorbar on the right with ELEVATED_BG legend frame. All text is clearly readable against the warm off-white background — no light-on-light issues.

Dark render (plot-dark.png): Warm near-black (#1A1A17) background with alternating near-black (white keys) and slightly lighter (#252522) rows correctly rendering the keyboard pattern on the dark surface. Title in light (#F0EFE8) text — clearly readable. Axis labels and tick labels in B8B7B0 light gray — readable. Section labels in A8A79F muted light gray — readable. Role labels "Melody" and "Accomp." in B8B7B0 — readable. Legend box fill is #242420 (elevated dark bg) with light text. Velocity gradient colors are identical to the light render — #009E73 green for soft notes, #4467A3 blue for loud notes; the climax at measures 7-8 is clearly visible in deep blue. No dark-on-dark failures. All title, axis labels, tick labels, and annotation text are light-colored and readable against the warm near-black background. Both renders pass theme-readability checks.

Score: 90/100

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

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set (title 16pt, axis titles 12pt, tick labels 10–11pt). Readable in both themes. Section labels (geom_text size=4 mm) and role labels (size=3.5 mm) are slightly small but readable; minor deduction for small annotation text at mobile scale.
• VQ-02: No Overlap (6/6) — No text or element overlap. Role labels placed in right margin beyond beat 32; section labels above data area.
• VQ-03: Element Visibility (5/6) — Accompaniment notes (long bars) clearly visible. Short-duration melody notes (eighth notes) appear as small rectangles — inherent to short durations, but reduces score slightly.
• VQ-04: Color Accessibility (2/2) — Imprint sequential palette (#009E73 to #4467A3) is CVD-safe. Melody vs. accompaniment distinguished by opacity and border color.
• VQ-05: Layout & Canvas (4/4) — Canvas gate passed (3200×1800 via ggsize(800,450) scale=4). Plot fills canvas well. Colorbar on right, section labels in top margin. No content cut off.
• VQ-06: Axis Labels & Title (2/2) — X-axis: "Time (beats)" with units. Y-axis: "Pitch" appropriate. Title format correct.
• VQ-07: Palette Compliance (2/2) — Continuous velocity uses imprint_seq (low=#009E73, high=#4467A3). Backgrounds: light #FAF8F1, dark #1A1A17. All chrome tokens theme-adaptive. Data colors identical across themes.

Design Excellence (15/20)

• DE-01: Aesthetic Sophistication (6/8) — Strong design: alternating black/white key rows, semantic beat/measure grid (lighter beat lines, stronger measure lines), imprint_seq velocity colormap, distinct melody/accompaniment visual hierarchy (border, opacity, height), musical dynamic labels. Clearly above defaults.
• DE-02: Visual Refinement (4/6) — Panel grid replaced with semantic beat/measure lines. Row shading added. Legend styled with ELEVATED_BG. Panel border (all 4 spines) kept — appropriate for piano roll but top/right removal would add further polish.
• DE-03: Data Storytelling (5/6) — Strong musical narrative: section labels explicitly narrate pp—Building → f—Response → pp—Restart → fff—Climax dynamic arc. Velocity gradient visually reinforces the journey from soft green notes to loud blue climax. Melody/accompaniment separation creates clear visual layers guiding the viewer.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct piano roll with horizontal note rectangles, velocity-colored, beat/measure grid, alternating key row shading.
• SC-02: Required Features (4/4) — All spec features present: note names on Y-axis (white keys only), alternating black/white key row shading, beat divisions with stronger measure lines, sequential colormap for velocity, auto-fit pitch range with margin.
• SC-03: Data Mapping (3/3) — X=time in beats, Y=pitch (MIDI→note name), bar width=duration, color=velocity. All correctly mapped.
• SC-04: Title & Legend (3/3) — Title: "piano-roll-midi · python · letsplot · anyplot.ai" — correct format. Velocity colorbar with descriptive label.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows all aspects: melody and accompaniment layers, varying note durations (eighth to whole notes), full dynamic range pp to fff, chord voicings, 8-measure progression.
• DQ-02: Realistic Context (5/5) — Realistic Cmaj→Am→F→G chord progression. MIDI note numbers correct (middle C = 60 = C4). Dynamic markings are standard musical notation. Neutral, non-controversial music theory content.
• DQ-03: Appropriate Scale (4/4) — MIDI velocity range 0-127 correctly applied (30–127 in data). MIDI note numbers accurate. 8 measures × 4 beats = 32 beats correct for 4/4 time.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Flat script: imports → tokens → data → plot → save. No functions or classes.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set.
• CQ-03: Clean Imports (2/2) — All imports used: os, shutil, numpy, pandas, lets_plot, export_ggsave.
• CQ-04: Code Elegance (2/2) — Clean, well-organized. No fake functionality.
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html. Current letsplot API. Cleanup of lets-plot-images directory.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Good idiomatic ggplot grammar: layer composition with multiple geom_rect/geom_vline/geom_text, scale_fill_gradient, coord_cartesian, theme_minimal + custom theme. layer_tooltips() is idiomatic letsplot pattern.
• LM-02: Distinctive Features (3/5) — layer_tooltips() with structured multi-line tooltip content (note name, velocity, beat range) is a distinctive letsplot capability. HTML output with interactive tooltips sets this apart from static libraries. Multiple geom layers with independent data sources is well-leveraged.

Score Caps Applied

• None applied (DE-01=6 > 2, DE-02=4 > 2, no cap triggers)

Strengths

• Authentic DAW-style alternating black/white key row shading with correct keyboard layout
• Imprint sequential colormap (#009E73 → #4467A3) correctly used for single-polarity velocity data
• Full theme-adaptive chrome — all text readable in both light and dark renders, no dark-on-dark failures
• Musical storytelling through section labels (pp—Building → fff—Climax) and velocity gradient communicating the dynamic arc
• Correct visual hierarchy: melody notes have darker border, full opacity, and taller height vs. semi-transparent accompaniment
• Custom semantic grid (subtle beat lines + stronger measure lines) replacing default panel grid
• Interactive HTML tooltips via layer_tooltips() leveraging letsplot's distinctive interactive capability
• All spec requirements met, perfect data quality with realistic Cmaj→Am→F→G progression

Weaknesses

• DE-02: Top and right spines kept (via panel_background element_rect with color=INK_SOFT) — softening or removing them would add further visual refinement; for a piano-roll the full frame is functional but slightly heavy
• LM-02: layer_tooltips() is used but the pattern is relatively straightforward; more distinctive letsplot-specific features (e.g., richer tooltip formatting or layer-specific tooltip customization) would raise this score
• VQ-01: Section annotation labels (geom_text size=4 mm) and role labels (size=3.5 mm) are slightly small — bumping to size=5 mm would improve legibility when scaled to mobile widths (~400 px)

Issues Found

None requiring repair — all deductions are minor refinements.

AI Feedback for Next Attempt

Implementation is publication-quality. If a repair is triggered for any reason: (1) increase section label and role label geom_text size from 4→5 mm and 3.5→4.5 mm respectively for better mobile legibility; (2) consider softening the panel border by setting color to a very light rgba value rather than INK_SOFT, to further reduce visual weight of the frame.

Verdict: APPROVED