feat(plotnine): implement waveform-audio

[github-actions]

Implementation: waveform-audio - python/plotnine

Implements the python/plotnine version of waveform-audio.

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

Parent Issue: #4563

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): Warm off-white background (#FAF8F1). The plot shows a three-phase audio waveform rendered as filled ribbons: a short Attack section (green #009E73, alpha=0.85) at the left onset, a wide Sustain section (blue #4467A3, alpha=0.65) occupying the main body, and a tapering Release section (lavender #C475FD, alpha=0.55) at the right. Dashed vertical lines mark the phase boundaries at 0.05s and 1.1s. A horizontal zero-line provides the amplitude reference. Phase labels "Attack", "Sustain", "Release" appear as small italic annotations in their respective Imprint colors at the top of each phase region. X-axis shows "Time (seconds)" from 0.00 to 1.50; Y-axis shows "Amplitude" from -1.0 to 1.0. All text is clearly readable against the light background (title, axis labels, tick labels). Phase annotations are slightly small but legible at full resolution.

Dark render (plot-dark.png): Near-black background (#1A1A17). The data colors are identical to the light render — same green Attack, blue Sustain, lavender Release fills with same alpha values. Title, axis labels, and tick labels flip to light ink (#F0EFE8 / #B8B7B0), all clearly readable against the dark surface. Phase annotation labels in their Imprint colors (green/blue/lavender) remain visible against the dark background with no dark-on-dark issues. Zero-line and phase dividers are visible. No unreadable elements in the dark render.

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

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

Visual Quality (28/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set (title=12pt, axis_title=10pt, tick=8pt). Phase annotation labels (size=3.0mm ≈ 8.5pt) are slightly small — readable at full resolution but tight at mobile scale.
• VQ-02: No Overlap (6/6) — No overlapping text or data elements in either render.
• VQ-03: Element Visibility (6/6) — Dense waveform handled with min/max envelope rendering. Ribbon fills clearly visible at appropriate alpha values per phase.
• VQ-04: Color Accessibility (2/2) — Imprint palette CVD-safe hues. Good contrast.
• VQ-05: Layout & Canvas (4/4) — Canvas gate passed (3200×1800). Waveform fills the plot area well. No clipping. Balanced margins.
• VQ-06: Axis Labels & Title (2/2) — X: "Time (seconds)" with units. Y: "Amplitude" (normalized range implicit from axis scale).
• VQ-07: Palette Compliance (1/2) — First series (Attack) correctly uses #009E73. However, Sustain uses pos-3 (#4467A3) and Release uses pos-2 (#C475FD) — non-canonical order 1→3→2 without semantic justification. Backgrounds and chrome are correct.

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) — Above well-configured default. Phase-based coloring with differentiated alphas, direct phase labels, and boundary dividers show clear design intent. Not yet at publication-ready level.
• DE-02: Visual Refinement (4/6) — theme_minimal() removes top/right spines. Y-axis-only grid at ~15% opacity. Axis lines and ticks explicitly styled with INK_SOFT tokens.
• DE-03: Data Storytelling (4/6) — Clear ADSR story through phase colors, labels, and dividers. Visual hierarchy guides the viewer through the audio dynamics.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct waveform: geom_ribbon as filled area mirrored above/below zero.
• SC-02: Required Features (4/4) — All features present: filled area, semi-transparent fills, zero-line, time x-axis, amplitude y-axis (-1 to +1), min/max envelope rendering, synthetic audio data with harmonics and envelope.
• SC-03: Data Mapping (3/3) — Time on x-axis (0–1.5s), normalized amplitude on y-axis (-1.0 to 1.0).
• SC-04: Title & Legend (3/3) — Title: "waveform-audio · python · plotnine · anyplot.ai" — correct. No legend; phases labeled via direct annotations.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows all aspects: attack onset, sustained oscillation with vibrato, release decay, amplitude envelope, harmonic content (2nd, 3rd, 5th harmonics).
• DQ-02: Realistic Context (5/5) — A3 musical note (220Hz fundamental) with harmonics, amplitude envelope, vibrato, and noise floor. Neutral topic.
• DQ-03: Appropriate Scale (4/4) — 22050Hz sample rate, 1.5s duration, normalized amplitude — all physically realistic for audio.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Clean Imports → Data → Plot → Save structure. No functions or classes.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set.
• CQ-03: Clean Imports (2/2) — All imports are used.
• CQ-04: Code Elegance (2/2) — Clean, readable code. No fake interactivity.
• CQ-05: Output & API (1/1) — Saves as plot-{THEME}.png with correct dpi/dimensions.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Good idiomatic plotnine: geom_ribbon + aes(fill="phase", alpha="phase") with scale_fill_manual + scale_alpha_manual. Layer composition is well-executed.
• LM-02: Distinctive Features (3/5) — Uses geom_ribbon with dual aesthetic mapping (fill + alpha to same categorical variable) — distinctly ggplot/plotnine grammar idiom.

Score Caps Applied

• None applied — all caps thresholds avoided.

Strengths

• Phase-based waveform coloring with Imprint palette creates clear Attack/Sustain/Release visual storytelling
• Min/max envelope rendering correctly handles dense waveform aliasing as specified
• Perfect spec compliance — filled ribbon, zero line, proper axes, synthetic audio data with harmonics and envelope
• All theme tokens wired correctly: both light and dark renders are fully readable with correct backgrounds and text colors
• Code quality is exemplary: seed set, clean imports, KISS structure, correct output API

Weaknesses

• VQ-07: Palette order is non-canonical — Sustain uses pos-3 (#4467A3) and Release uses pos-2 (#C475FD) giving order 1→3→2 instead of canonical 1→2→3; no strong semantic reason for the swap. Fix: assign Attack=pos-1 (#009E73), Sustain=pos-2 (#C475FD), Release=pos-3 (#4467A3), or document a clear semantic justification.
• VQ-01/DE-01: Phase annotation labels (size=3.0mm) are slightly small in both renders — increase to size=3.5–4.0 for better mobile legibility and visual impact.
• DE-01: Design could be elevated further — consider adding a smoothed amplitude envelope outline (geom_line on a smoothed min/max average) on top of the ribbon, or refining the alpha values to better reveal the oscillation pattern inside the dense ribbon.
• DE-02: Minor — the phase divider lines (geom_vline) could use slightly more weight contrast to better frame the phase boundaries.

Issues Found

1. VQ-07 MINOR: Non-canonical Imprint palette order (1→3→2) without semantic justification.
   • Fix: Use canonical order — phase_colors = {"Attack": IMPRINT_PALETTE[0], "Sustain": IMPRINT_PALETTE[1], "Release": IMPRINT_PALETTE[2]}
2. VQ-01 / DE-01 MINOR: Phase annotation text too small.
   • Fix: Change size=3.0 to size=3.5 or size=4.0 in all three annotate("text", ...) calls.

AI Feedback for Next Attempt

Fix the palette order to canonical 1→2→3 for Attack/Sustain/Release phases. Increase phase annotation text size from 3.0 to 3.5–4.0. For design elevation, consider layering a smoothed envelope line over the ribbon fills to highlight the amplitude contour, and slightly increase the geom_vline size/alpha for clearer phase boundary markers.

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): Warm off-white background (#FAF8F1) with a three-phase audio waveform rendered as filled ribbon areas. Attack phase (narrow, ~0–0.05 s) in Imprint green (#009E73) at α=0.85, Sustain phase (dominant, ~0.05–1.1 s) in Imprint lavender (#C475FD) at α=0.65, and Release phase (~1.1–1.5 s) in Imprint blue (#4467A3) at α=0.55, all mirrored symmetrically around a zero reference line. Small italic phase-label annotations ("Attack", "Sustain", "Release") appear at y≈0.90 in their respective colors. Dashed vertical boundary lines mark the Attack→Sustain and Sustain→Release transitions. X-axis tick labels (0.00–1.50 s), y-axis tick labels (−1.00–1.00), axis labels, and title are all clearly readable against the light background. No dark-on-light failures observed. Legibility verdict: PASS.

Dark render (plot-dark.png): Near-black background (#1A1A17). The three ribbon phases display in identical data colors — same Imprint green, lavender, and blue — confirming the data palette is theme-independent. Title and axis labels render in light ink (#F0EFE8), tick labels in secondary ink (#B8B7B0). Zero reference line appears in warm muted gray (INK_MUTED in dark mode). Phase annotations are rendered in their respective palette colors and remain legible against the dark surface. Grid lines are subtle. No dark-on-dark failures; all text is readable against the warm near-black background. Legibility verdict: PASS.

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

Score: 86/100

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

Visual Quality (29/30)

• VQ-01: Text Legibility (8/8) — All sizes explicitly set (title=12pt, axis_title=10pt, axis_text=8pt, legend=8pt); result is well-proportioned in both themes; no overflow or imbalance
• VQ-02: No Overlap (6/6) — No text/data collisions in either render
• VQ-03: Element Visibility (6/6) — Min/max envelope downsampling (chunk_size=64) correctly represents dense waveform data without aliasing; ribbons clearly visible
• VQ-04: Color Accessibility (2/2) — Green/lavender/blue Imprint triplet is CVD-safe with sufficient hue separation
• VQ-05: Layout & Canvas (4/4) — Canvas gate passed; waveform fills the canvas well; margins balanced
• VQ-06: Axis Labels & Title (1/2) — X-axis "Time (seconds)" is complete; Y-axis "Amplitude" is descriptive but missing a unit qualifier (e.g. "(normalized)" or "[-1, 1]"); tick labels on y-axis do show the scale, but the label alone is 1-point territory
• VQ-07: Palette Compliance (2/2) — Attack=#009E73 (Imprint position 1), Sustain=#C475FD (position 2), Release=#4467A3 (position 3); backgrounds correct (#FAF8F1 light / #1A1A17 dark); chrome adapts correctly in both renders

Design Excellence (11/20)

• DE-01: Aesthetic Sophistication (5/8) — Clearly above a configured default: phase-based ribbon segmentation with intentional Imprint color assignment and per-phase alpha variation (0.85/0.65/0.55) reflects real audio dynamics. Phase boundary markers add polish. Not quite at "strong design / FiveThirtyEight-level" (6), but noticeably purposeful
• DE-02: Visual Refinement (3/6) — Y-axis-only grid at α=0.15 is correctly subtle; x-grid suppressed; theme_minimal() base removes excess spines; axis lines explicitly coloured. Above minimal (2), but generous whitespace and tighter typographic hierarchy would lift this further
• DE-03: Data Storytelling (3/6) — Phase colour narrative (Attack→Sustain→Release) tells the ADSR envelope story; visual emphasis is present through the dominant lavender Sustain region versus narrow Attack and decaying Release. Phase annotation labels at size=3.5 mm are too small to function as strong narrative anchors — viewer must already know what Attack/Sustain/Release mean rather than being guided to that insight

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct waveform as filled ribbon symmetric around zero
• SC-02: Required Features (4/4) — Filled area (geom_ribbon with ymin/ymax), semi-transparent fill (alpha), horizontal zero reference line (geom_hline), time on x-axis, amplitude on y-axis, min/max envelope for dense data — all present
• SC-03: Data Mapping (3/3) — Time (0–1.5 s) on x, amplitude (−1 to +1) on y, full data range shown
• SC-04: Title & Legend (3/3) — Title is exactly waveform-audio · python · plotnine · anyplot.ai; no legend shown (replaced by inline annotations — acceptable for this plot type)

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) — Demonstrates attack envelope, sustained oscillation with vibrato, harmonic content, amplitude decay, and noise — strong coverage. Slightly docked because the phase-segmented approach foregrounds narrative at the mild expense of showing the pure waveform characteristics (e.g. visible harmonic beating is obscured by dense aliasing at this zoom)
• DQ-02: Realistic Context (5/5) — 220 Hz fundamental (A3 note) with 2nd/3rd/5th harmonics, 22 050 Hz sample rate, 1.5 s duration, vibrato at 5 Hz — all real-world plausible audio engineering values
• DQ-03: Appropriate Scale (4/4) — Normalized amplitude [−1, 1], realistic duration, proper sample rate; np.clip ensures no artificial clipping artefacts

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear: imports → theme tokens → data generation → plot → save; no functions or classes
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set
• CQ-03: Clean Imports (2/2) — All imported symbols (including scale_alpha_manual) are actually used
• CQ-04: Code Elegance (2/2) — Appropriate complexity; no fake UI; the min/max chunking loop is clear and purposeful
• CQ-05: Output & API (1/1) — plot.save(f"plot-{THEME}.png", dpi=400, width=8, height=4.5, units="in") — correct

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Fluent ggplot2 grammar: geom_ribbon(aes(ymin=..., ymax=..., fill=..., alpha=...)) with scale_fill_manual + scale_alpha_manual for a dual aesthetic map is idiomatic and correct. annotate(), geom_hline(), geom_vline() layered naturally. Minor gap: the library's geom_smooth / stat_summary could have been considered for envelope; using explicit downsampling is pragmatic but slightly less idiomatic
• LM-02: Distinctive Features (3/5) — Combining geom_ribbon with simultaneous fill + alpha aesthetic mappings driven by a single categorical variable (phase) demonstrates a plotnine/ggplot2 feature (multi-aesthetic aes binding) that is genuinely harder to replicate cleanly in matplotlib or seaborn

Score Caps Applied

• None

Strengths

• Three-phase color segmentation (Attack/Sustain/Release) with Imprint palette positions 1–3 in correct order creates an informative, visually purposeful waveform
• Min/max envelope downsampling (chunk_size=64) correctly avoids aliasing on the 22 050 Hz signal — spec-compliant and technically sound
• All theme tokens properly adapted for both light and dark renders with no dark-on-dark failures
• Realistic synthetic audio data (220 Hz + harmonics + vibrato + noise) at standard 22 050 Hz sample rate

Weaknesses

• Y-axis label reads "Amplitude" without a unit/range qualifier; change to "Amplitude (normalized)" or "Amplitude [-1, 1]" to earn full VQ-06 points
• Phase annotation labels use size=3.5 (≈ 10 pt) which is too small for annotations at this canvas size and especially cramped for the narrow Attack region at x≈0.025; increase to size=5–6 and consider repositioning or adding a small arrow/callout for clarity
• Design Excellence loses points due to the annotation labels being too small to function as strong narrative anchors — the phase story is told by color but not reinforced by legible text emphasis

Issues Found

1. VQ-06 LOW (1/2): Y-axis label missing unit/range qualifier
   • Fix: Change labs(y="Amplitude") to labs(y="Amplitude (normalized)")
2. DE-03 MODERATE (3/6): Phase annotation labels too small to carry narrative weight
   • Fix: Increase annotation size from 3.5 to 5–6; consider moving labels slightly below the top of the waveform (e.g. y=0.80) where there is more visual space; alternatively add a small background rect or slightly bolder style

AI Feedback for Next Attempt

Two targeted fixes would push this to ~90: (1) change the y-axis label to "Amplitude (normalized)" for full VQ-06 credit; (2) increase the phase annotation text size from 3.5 to ~5–6 and optionally reposition them slightly lower (y≈0.80) so they read more clearly — especially "Attack" which is crammed into a 0.05 s window. The three-phase Imprint color design and min/max envelope approach are excellent; keep them unchanged.

Verdict: APPROVED