feat(bokeh): implement waveform-audio

[github-actions]

Implementation: waveform-audio - python/bokeh

Implements the python/bokeh version of waveform-audio.

File: plots/waveform-audio/implementations/python/bokeh.py

Parent Issue: #4563

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): Warm off-white (#FAF8F1) background — correct. Title "waveform-audio · python · bokeh · anyplot.ai" in dark ink at 50pt, clearly readable. Y-axis label "Amplitude" and X-axis label "Time (seconds)" both in dark ink at 42pt. Tick labels (−1, −0.5, 0, 0.5, 1 on Y; 0–1.4 on X) in INK_SOFT at 34pt — all readable. Three waveform phases: a narrow green (#009E73) Attack region (0–0.05 s), a wide blue (#4467A3) Sustain region (0.05–1.2 s), and a cyan (#2ABCCD) Release region tapering to zero at right (1.2–1.5 s). Semi-transparent fills (alpha 0.40–0.45) with edge outline lines. Subtle phase background shading (alpha 0.09) and dashed vertical boundary lines. Zero baseline clearly visible. Phase labels "Attack", "Sustain", "Release" in italic INK_MUTED at 28pt — readable at full resolution but small. All text is readable against the light background.

Dark render (plot-dark.png): Warm near-black (#1A1A17) background — correct. Title and axis labels in light ink (#F0EFE8), clearly readable. Tick labels in INK_SOFT (#B8B7B0) — readable, no dark-on-dark failures. Phase labels in INK_MUTED (#A8A79F) — readable. Data colors are identical to the light render: same green/blue/cyan waveform phases with the same alpha fill levels. Only chrome flips between themes. Brand green #009E73 in the Attack phase is clearly visible against the dark background. All text is 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: 90/100

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

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8) — All sizes explicitly set (50pt title, 42pt axis labels, 34pt ticks, 28pt phase annotations). Readable in both themes. Minor concern: 28pt phase labels may be small on mobile (~4.7 source-px at 400 px viewport).
• VQ-02: No Overlap (6/6) — No text overlaps in either render.
• VQ-03: Element Visibility (6/6) — Min/max envelope (chunk_size=8) handles 33K dense samples cleanly. Three color-coded phases clearly distinct.
• VQ-04: Color Accessibility (2/2) — CVD-safe Imprint palette; semi-transparent fills remain distinguishable.
• VQ-05: Layout & Canvas (4/4) — Canvas gate passed. 3200×1800 with correct min_border values. Nothing cut off.
• VQ-06: Axis Labels & Title (2/2) — "Time (seconds)" with units; "Amplitude" (inherently unitless for normalized audio).
• VQ-07: Palette Compliance (1/2) — First series #009E73 ✓; backgrounds #FAF8F1/#1A1A17 ✓; chrome theme-adaptive ✓. However: uses palette positions 1, 3, 6 (#009E73, #4467A3, #2ABCCD) instead of canonical 1, 2, 3 (skips #C475FD lavender). No semantic justification for skipping position 2 — this is aesthetic cherry-picking, which the style guide explicitly prohibits ("Don't cherry-pick for aesthetic reasons").

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) — Above default (4). Intentional phase color hierarchy, clean frame removal, professional layout. Not yet at FiveThirtyEight publication level — styling follows the mandated guide more than expressing independent design vision.
• DE-02: Visual Refinement (4/6) — Above default (2). X-grid removed, Y-grid at alpha 0.15, frame outline removed, minor ticks removed. Good refinement but not every detail polished.
• DE-03: Data Storytelling (4/6) — Above default (2). Phase labels + dashed boundary lines + color-coded shading clearly guide the viewer through audio dynamics (Attack → Sustain → Release). Good visual hierarchy; not exceptional in the "immediately see the insight" sense.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct filled waveform area symmetric around zero baseline.
• SC-02: Required Features (4/4) — All features present: filled area (varea), semi-transparent fill, zero baseline (Span), min/max envelope rendering, synthetic multi-harmonic signal with amplitude envelope.
• SC-03: Data Mapping (3/3) — X: 0–1.5 s; Y: −1 to +1 (Range1d ±1.12 with buffer). 33,075 samples within 5,000–50,000 spec range.
• SC-04: Title & Legend (3/3) — Title "waveform-audio · python · bokeh · anyplot.ai" is the exact required format. Phases labeled directly via annotations — no separate legend needed.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows all aspects: attack/sustain/release envelope dynamics, tremolo modulation, multiple harmonics (fundamental + 2nd + 3rd + 5th harmonic).
• DQ-02: Realistic Context (5/5) — Musical note A3 at 220 Hz, 1.5 s clip, standard 22,050 Hz sample rate. Entirely neutral technical content.
• DQ-03: Appropriate Scale (4/4) — Amplitude normalized −1 to +1 per spec. Realistic envelope timing (5% attack, 30% release).

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear procedural: imports → 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.
• CQ-04: Code Elegance (2/2) — Clean, Pythonic. PIL crop for exact 3200×1800 sizing is a clever pattern. No fake functionality.
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html. Current API.

Library Mastery (9/10)

• LM-01: Idiomatic Usage (5/5) — Expert: varea() for dual-boundary fill, ColumnDataSource, BoxAnnotation for region shading, Span for reference lines, Label for annotations, Range1d for y-range control.
• LM-02: Distinctive Features (4/5) — BoxAnnotation and Span are genuinely Bokeh-specific (matplotlib requires axvspan/axhline workarounds). varea() for two-boundary fill is a distinctive Bokeh API. Strong Bokeh-specific usage throughout.

Score Caps Applied

• None — no caps triggered.

Strengths

• Correct idiomatic Bokeh: varea() for filled waveform, BoxAnnotation for phase shading, Span for reference lines — all distinctively Bokeh idioms applied expertly
• Full spec compliance: filled waveform symmetric around zero, min/max envelope for dense 33K-sample data, zero baseline, semi-transparent fill, synthetic multi-harmonic signal with amplitude envelope
• Strong data storytelling: Attack/Sustain/Release labels + boundary lines + color-coded shading guide the viewer through audio dynamics
• Correct theme-adaptive chrome in both renders; warm backgrounds, proper INK/INK_SOFT token application throughout

Weaknesses

• Palette canonical order violated: positions 1 (#009E73), 3 (#4467A3), 6 (#2ABCCD) used instead of canonical 1, 2, 3. The "cool progression" aesthetic rationale does not qualify as a semantic exception — fix by using positions 1, 2, 3 (adds #C475FD lavender for Sustain)
• Phase labels at 28pt may be unreadable on mobile (~4.7 source-px at 400 px viewport); consider increasing to 32–34pt to match tick label size
• Attack phase at 3.3% of total x-range (0.05 s of 1.5 s) makes its label and green region barely perceptible without zoom

Issues Found

1. VQ-07 PARTIAL: Palette positions 1, 3, 6 used instead of canonical 1, 2, 3 — skips #C475FD (lavender) at position 2 without semantic justification
   • Fix: Change COLOR_SUSTAIN from #4467A3 (position 3) to #C475FD (position 2), and COLOR_RELEASE from #2ABCCD (position 6) to #4467A3 (position 3)

AI Feedback for Next Attempt

Fix the palette order: use Imprint positions 1→3 in canonical order (#009E73 → #C475FD → #4467A3) for the three phases. The "cool progression" argument is an aesthetic cherry-pick the style guide disallows. Optionally increase phase label font size from 28pt to 32–34pt for better mobile readability.

Verdict: APPROVED