Re-evaluate Session Musician: stacked stem-note draft + melody contour with honest confidence bands

[slittycode]

Summary

Re-shapes the Session Musician panel so its pitch/note output is honest about what the field can and can't do. The architecture docs are clear: polyphonic full-mix audio-to-MIDI for dense electronic music is unsolved, and what we ship today is best-effort monophonic stem extraction + a Gemini stem listening read. The UI now reflects that without paternalism — the producer gets every signal that exists, each labelled with what it is and what to do with it.

What changed

One panel, two stacked blocks. The old PITCH/NOTE ↔ MELODY toggle is gone. Block A (Stem note draft) and Block B (Melody contour) both render simultaneously when their data exists. Each block has its own Preview and Download with distinct filenames (track-analysis-stems.mid, track-analysis-melody.mid) so Ableton drag-and-drop is unambiguous.

One shared preview controller. usePreviewController() is called exactly once in SessionMusicianPanel; the returned PreviewController is passed down to both <MidiControlsRow> instances. Starting a preview on Block B automatically stops Block A — one remote control, not two.

Confidence becomes plain-language guidance. A four-band ladder replaces the bare percentage:

Band	Range	Label	What the producer should do
Solid	≥ 80%	Solid scaffold	"Notes look reliable. Expect light cleanup in Ableton's piano roll."
Workable	50–79%	Workable draft	"Most notes are in the right ballpark. Plan to redraw the trickiest bars."
Rough	25–49%	Rough sketch	"Pitch tracking caught the general shape. Treat this as a rhythm grid more than note truth."
Unreliable	< 25%	Unreliable	"The pitch detector wasn't confident. Use the pitch range and most-played notes as scale hints — don't trust specific notes."

Pill text format: Workable draft · 72% — label tells you what to do, number lets you audit why.

Block A render-state precedence (load-bearing). Defined in services/sessionMusician/renderState.ts:

1. pitchNoteMode === 'off' → absent (stale cached notes can't sneak back onto the screen)
2. requested but transcriptionDetail missing → requested-but-unavailable
3. missing payload, not requested → absent
4. notes.length === 0 → ran-with-no-result
5. non-torchcrepe method → legacy (wins over fallback — re-analyze is the actionable fix)
6. fullMixFallback === true → full-mix-fallback
7. otherwise → stem-aware

Each non-nominal state replaces the band pill with a stronger notice and hides controls that don't apply (stem filter, confidence slider).

"What stays useful" footer. Even at Unreliable, three signals carry: pitch range (tells you MIDI track range / synth tuning), top-played notes (scale hint), average note length (rhythmic feel). Rendered as chips below the piano roll across all data-bearing states.

Stem listening notes (Gemini) moves to its own component. StemListeningNotesPanel lifts the JSX out of AnalysisResults and renders adjacent to Session Musician inside a local space-y-4 wrapper so the two panels read as a paired suite. hasStemListeningNotesContent now powers the StickyNav inclusion, the render gate, and the off-state cross-link copy in one place. Renamed in the nav from "Stem Summary" to "Stem Notes."

Off-state has three variants based on data availability — melody present, no melody + listening notes present, or neither. All variants qualify melody as "when available" because melodyDetail is None on three real code paths (analyze.py:1189, analyze_fast.py:141, analyze_rhythm.py:438).

App toggle copy tightened to match the new panel structure without overpromising what stays available when stem mode is off.

File map

Pure helpers (apps/ui/src/services/sessionMusician/):

• confidenceBand.ts — band ladder + pill formatter
• noteConversion.ts — transcription/melody → display-note converters
• stemListeningNotes.ts — hasStemListeningNotesContent helper used in three places
• renderState.ts — deriveNoteDraftRenderState + isLegacyTranscriptionMethod

Shared React pieces (apps/ui/src/components/sessionMusician/):

• PianoRollCanvas.tsx, QuantizeControls.tsx, ConfidenceBandBadge.tsx, MidiControlsRow.tsx, usePreviewController.ts

Block components in the same directory:

• NoteDraftBlock.tsx (Block A), MelodyContourBlock.tsx (Block B)

Heavy edits:

• SessionMusicianPanel.tsx — drops the toggle / sourceMode state, orchestrates the two blocks, owns the preview controller and off-state banner
• AnalysisResults.tsx — wraps the two panels in section-musician-suite, replaces the inline stem-summary JSX with <StemListeningNotesPanel>, renames the nav label

Light edits:

• App.tsx — toggle description copy
• Three e2e specs — assert the new track-analysis-stems.mid filename for the Block A download

Tests

• 331 unit tests pass. Rewrote sessionMusicianPanel.test.ts (dropped the brittle useState call-count mocking pattern). Added new suites: confidenceBand, noteConversion, stemListeningNotes, renderState, stemListeningNotesPanel.
• 46 smoke tests pass (1 skipped — live Gemini). Extended upload-phase1-midi.spec.ts with shared-preview mutual-exclusion, per-block downloads with distinct filenames, and slider-filtered-to-zero hiding the Download.
• No backend changes — every field used here already existed in the contract.

Verify

cd apps/ui
npm run verify

Plan

Full design rationale, render-state matrix, UI copy library, and decision history live in .claude/plans/re-evaluate-asa-s-session-musician-sharded-balloon.md.

🤖 Generated with Claude Code

[slittycode]

Verdict: APPROVE (posted as COMMENT — can't approve own PR)

Summary

Decomposes a 700+ line monolith into focused block components, replaces the per-mode toggle with two simultaneously rendered blocks, and adds an honest confidence ladder with plain-language guidance. Phase 1 data is read-only throughout. All 331 unit tests pass.

Findings

Worth considering (neither is blocking):

MelodyContourBlock.tsx:100–102 — Melody pitch range renders as raw MIDI integers ("MIDI range: 48 – 79"). Block A shows note names ("Range: C3 – G5") via pitchRange.minName/maxName. MelodyDetail.pitchRange has no name fields, so the fix is calling midiToNoteName() (already available via noteConversion.ts). The label correctly says "MIDI range:" so it isn't lying, just inconsistent with Block A.

QuantizeControls.tsx:30 — Grid buttons are missing type="button". Every other interactive button in the component tree (MidiControlsRow, SessionMusicianPanel, NoteDraftBlock stem filter) has it. Won't cause real problems in this SPA but breaks internal consistency.

Test results

331 passed / 0 failed. New suites: renderState (16), confidenceBand (18), noteConversion (16), stemListeningNotes (7), stemListeningNotesPanel (7). sessionMusicianPanel.test.ts covers the six Block A render states, Block B melody states, off-state banner variants, and simultaneous rendering. Smoke suite extended with shared-preview mutual-exclusion, per-block filenames, and slider-filtered-to-zero.

Phase boundary check

Clean. types.ts is not in this diff. Phase 1 fields are read by NoteDraftBlock, MelodyContourBlock, and the renderState/noteConversion helpers but never written. Confidence band and display note conversions produce new local objects; they don't mutate phase1. hasStemListeningNotesContent reads the Gemini envelope only to gate UI visibility, not to override any measurement.

---

Generated by Claude Code