Pivot MIDI Studio V2 to octave timeline editor workflow with GM instrument controls - PR_26146_028-midi-studio-v2-octave-timeline-editor

Author: ToolboxAid

docs/dev/reports/PR_26146_028-midi-studio-v2-octave-timeline-editor_validation.md

@@ -0,0 +1,67 @@
+# PR_26146_028 MIDI Studio V2 Octave Timeline Editor Validation
+
+## Status
+
+PASS
+
+## Scope Completed
+
+- Replaced the Studio primary editing surface with an octave/note timeline grid.
+- Added left-column Songs and Instruments sections.
+- Restored a MIDI Import tab and kept MIDI import controls in the Songs area.
+- Moved instrument controls into left-column instrument rows with show/hide, GM family type, instrument, mute, solo, add, and delete controls.
+- Added GM family grouping for Piano, Chromatic Percussion, Organ, Guitar, Bass, Strings, Ensemble, Brass, Reed, Pipe, Synth Lead, Synth Pad, Synth Effects, Ethnic, Percussive, and Sound Effects.
+- Rendered visible octave/note rows and beat/bar columns in the center timeline.
+- Implemented click-to-toggle note editing for the selected instrument.
+- Highlighted selected instrument notes and dimmed non-selected instrument notes.
+- Hid notes for hidden instruments and excluded hidden lanes from Preview Synth playback.
+- Preserved beat/bar playhead progression and Play/Stop behavior from visible timeline data.
+- Normalized imported local MIDI note data into editable studio arrangement lanes.
+- Preserved percussion-style Preview Synth playback for drum/percussion rows.
+- Removed the Export tab; export rendering remains out of scope.
+
+## Validation Commands
+
+- PASS: `node --check src/engine/audio/InstrumentGridParser.js`
+- PASS: `node --check src/engine/audio/PreviewInstrumentPacks.js`
+- PASS: `node --check src/engine/audio/PreviewSynthEngine.js`
+- PASS: `node --check tools/midi-studio-v2/js/MidiStudioV2App.js`
+- PASS: `node --check tools/midi-studio-v2/js/bootstrap.js`
+- PASS: `node --check tools/midi-studio-v2/js/controls/InstrumentGridControl.js`
+- PASS: `node --check tests/playwright/tools/MidiStudioV2.spec.mjs`
+- PASS: `rg --pcre2 -n "<style|on(click|change|input|submit)=|<script(?![^>]*src)" tools/midi-studio-v2/index.html; if ($LASTEXITCODE -eq 1) { exit 0 }`
+- PASS: `npx playwright test tests/playwright/tools/MidiStudioV2.spec.mjs -g "octave timeline editor is the default editable and playable Studio workflow|roadmap exists" --reporter=list --workers=1 --timeout=60000`
+- PASS: `git diff --check`
+
+## Playwright Proof Points
+
+- Octave timeline editor is visible by default on Studio.
+- Imported manifest songs populate the left Songs column.
+- Selecting manifest songs immediately updates timeline notes.
+- Left Instruments rows populate with show/hide, GM Type, Instrument, mute, solo, add, and delete controls.
+- GM Type and Instrument dropdowns update together.
+- Selecting an instrument highlights its notes.
+- Non-selected instrument notes dim.
+- Show/hide excludes hidden instrument notes from the visible timeline.
+- Octave rows render with note labels.
+- Clicking note cells toggles editable selected-instrument timeline data.
+- Playback uses visible note cell data.
+- Playhead advances by beat/bar columns.
+- Local `.midi` import normalizes parsed MIDI notes into editable timeline lanes.
+- Imported MIDI timeline data can be edited and played.
+- Play and Stop update control state and Preview Synth state.
+- Drum/percussion playback schedules percussion-style buffer events.
+
+## Coverage
+
+- `docs/dev/reports/playwright_v8_coverage_report.txt` refreshed by the targeted Playwright run.
+- `docs/dev/reports/coverage_changed_js_guardrail.txt` refreshed by the targeted Playwright run.
+- Coverage is advisory; no changed runtime JS coverage warnings were reported.
+
+## Explicit Non-Runs
+
+- Full samples smoke test was not run per request.
+- Export rendering was not implemented or validated.
+- SoundFont playback was not implemented or validated.
+- MIDI recording/input was not implemented or validated.
+

docs/dev/roadmaps/MIDI_STUDIO_V2_ROADMAP.md

@@ -8,10 +8,10 @@
 - [x] Playable upbeat public-domain/traditional-style test song arrangement includes Lead, Bass, Chords/Pad, and Drums.
 - [x] Studio tab shows a visible track/timeline editor without opening accordions.
 - [x] Tabs organize Studio, Song Setup, Instruments, Auto-Create Parts, and Diagnostics; MIDI Import lives under Selected Song Details and export actions live in the action bar.
-- [.] Editable note/timeline grid remains the primary music studio editing surface.
+- [x] Editable note/timeline grid remains the primary music studio editing surface.
 - [x] Track volume, pan, mute, and solo controls live on instrument timeline rows.
 - [.] Song setup fields for tempo, key, style, intro, and loop.
-- [ ] MIDI import conversion to editable tracks.
+- [x] MIDI import conversion to editable tracks.
 - [ ] Rendered WAV/MP3/OGG export.
 - [ ] SoundFont and real instrument playback.
 - [ ] Auto-Create Parts helpers for generated bass, pad, arpeggio, and drums.

src/engine/audio/InstrumentGridParser.js

@@ -173,14 +173,14 @@ export class InstrumentGridParser {
   }
 
   laneNamesFor(lanes = {}) {
-    const names = DEFAULT_LANE_NAMES.slice();
+    const names = [];
     Object.keys(lanes || {}).forEach((lane) => {
       const normalized = String(lane || "").trim();
       if (normalized && !names.includes(normalized)) {
         names.push(normalized);
       }
     });
-    return names;
+    return names.length ? names : DEFAULT_LANE_NAMES.slice();
   }
 
   parseLane({ barCount, beatsPerBar, generatedSource, lane, sections, source, stepsPerBar, subdivision }) {

src/engine/audio/PreviewInstrumentPacks.js

@@ -1,23 +1,23 @@
 export const PREVIEW_INSTRUMENT_PACKS = [
   {
     id: "retro-square-lead",
-    label: "Retro Square Lead",
+    label: "Lead 1 (Square)",
     synthRole: "lead",
-    typeGroup: "Synth",
+    typeGroup: "Synth Lead",
     volume: 0.075,
     waveform: "square"
   },
   {
     id: "retro-pulse-lead",
-    label: "Retro Pulse Lead",
+    label: "Lead 2 (Sawtooth)",
     synthRole: "lead",
-    typeGroup: "Synth",
+    typeGroup: "Synth Lead",
     volume: 0.07,
-    waveform: "square"
+    waveform: "sawtooth"
   },
   {
     id: "synth-bass",
-    label: "Synth Bass",
+    label: "Synth Bass 1",
     synthRole: "bass",
     typeGroup: "Bass",
     transposeSemitones: -12,
@@ -27,53 +27,89 @@ export const PREVIEW_INSTRUMENT_PACKS = [
   {
     approximationWarning: "Keyboard preview is an approximate electric-piano style synth patch.",
     id: "preview-electric-piano",
-    label: "Preview Electric Piano",
+    label: "Electric Piano 1",
+    synthRole: "lead",
+    typeGroup: "Piano",
+    volume: 0.065,
+    waveform: "sine"
+  },
+  {
+    approximationWarning: "Piano preview is an approximate sine-based synth patch.",
+    id: "preview-acoustic-grand-piano",
+    label: "Acoustic Grand Piano",
     synthRole: "lead",
-    typeGroup: "Keyboard",
+    typeGroup: "Piano",
     volume: 0.065,
     waveform: "sine"
   },
+  {
+    approximationWarning: "Chromatic percussion preview is an approximate mallet synth patch.",
+    id: "preview-celesta",
+    label: "Celesta",
+    synthRole: "lead",
+    typeGroup: "Chromatic Percussion",
+    volume: 0.058,
+    waveform: "sine"
+  },
+  {
+    approximationWarning: "Organ preview is an approximate drawbar synth patch.",
+    id: "preview-drawbar-organ",
+    label: "Drawbar Organ",
+    synthRole: "pad",
+    typeGroup: "Organ",
+    volume: 0.052,
+    waveform: "sine"
+  },
   {
     id: "warm-pad",
     label: "Warm Pad",
     durationScale: 1.3,
     synthRole: "pad",
-    typeGroup: "Keyboard",
+    typeGroup: "Synth Pad",
     volume: 0.045,
     waveform: "sine"
   },
   {
     id: "basic-drums",
-    label: "Basic Drums",
+    label: "Standard Drum Kit",
     synthRole: "percussion",
-    typeGroup: "Percussion",
+    typeGroup: "Percussive",
     volume: 0.16,
     waveform: "noise"
   },
   {
     id: "ambient-pad",
-    label: "Ambient Pad",
+    label: "Pad 2 (Warm)",
     durationScale: 1.55,
     synthRole: "pad",
     transposeSemitones: 12,
-    typeGroup: "FX",
+    typeGroup: "Synth Pad",
     volume: 0.035,
     waveform: "sine"
   },
+  {
+    approximationWarning: "Violin preview is an approximate bowed synth patch.",
+    id: "preview-violin",
+    label: "Violin",
+    synthRole: "lead",
+    typeGroup: "Strings",
+    volume: 0.055,
+    waveform: "sine"
+  },
   {
     approximationWarning: "String preview is an approximate synth pad, not a sampled string section.",
     durationScale: 1.45,
     id: "preview-string-ensemble",
-    label: "Preview String Ensemble",
+    label: "String Ensemble 1",
     synthRole: "pad",
-    typeGroup: "Strings",
+    typeGroup: "Ensemble",
     volume: 0.04,
     waveform: "sine"
   },
   {
     approximationWarning: "Brass preview is an approximate synth brass patch.",
     id: "preview-brass-stab",
-    label: "Preview Brass Stab",
+    label: "Brass Section",
     synthRole: "lead",
     typeGroup: "Brass",
     volume: 0.07,
@@ -82,20 +118,56 @@ export const PREVIEW_INSTRUMENT_PACKS = [
   {
     approximationWarning: "Woodwind preview is an approximate breathy synth lead.",
     id: "preview-woodwind",
-    label: "Preview Woodwind",
+    label: "Clarinet",
     synthRole: "lead",
-    typeGroup: "Woodwind",
+    typeGroup: "Reed",
     volume: 0.06,
     waveform: "triangle"
   },
+  {
+    approximationWarning: "Pipe preview is an approximate flute-like synth lead.",
+    id: "preview-flute",
+    label: "Flute",
+    synthRole: "lead",
+    typeGroup: "Pipe",
+    volume: 0.055,
+    waveform: "sine"
+  },
   {
     approximationWarning: "Guitar preview is an approximate plucked synth tone.",
     id: "preview-clean-guitar",
-    label: "Preview Clean Guitar",
+    label: "Electric Guitar (Clean)",
     synthRole: "lead",
     typeGroup: "Guitar",
     volume: 0.06,
     waveform: "triangle"
+  },
+  {
+    approximationWarning: "Synth effects preview is an approximate effects patch.",
+    id: "preview-synth-fx",
+    label: "FX 1 (Rain)",
+    synthRole: "pad",
+    typeGroup: "Synth Effects",
+    volume: 0.04,
+    waveform: "sawtooth"
+  },
+  {
+    approximationWarning: "Ethnic instrument preview is an approximate plucked synth patch.",
+    id: "preview-shamisen",
+    label: "Shamisen",
+    synthRole: "lead",
+    typeGroup: "Ethnic",
+    volume: 0.055,
+    waveform: "triangle"
+  },
+  {
+    approximationWarning: "Sound effect preview is an approximate synth effect patch.",
+    id: "preview-sci-fi",
+    label: "FX 8 (Sci-Fi)",
+    synthRole: "lead",
+    typeGroup: "Sound Effects",
+    volume: 0.055,
+    waveform: "square"
   }
 ];
 

src/engine/audio/PreviewSynthEngine.js

@@ -144,6 +144,7 @@ export class PreviewSynthEngine {
     const instruments = laneSettings.instruments || {};
     const muted = laneSettings.muted || {};
     const soloed = laneSettings.soloed || {};
+    const visible = laneSettings.visible || {};
     const soloedLanes = Object.entries(soloed).filter((entry) => entry[1]).map(([lane]) => lane);
     const warnings = [];
     const warningKeys = new Set();
@@ -153,6 +154,9 @@ export class PreviewSynthEngine {
       if (!Number.isFinite(stepIndex) || stepIndex < startStep || stepIndex > endStep) {
         return;
       }
+      if (visible[event.lane] === false) {
+        return;
+      }
       if (muted[event.lane] || (soloedLanes.length && !soloedLanes.includes(event.lane))) {
         return;
       }