Correct MIDI Studio V2 playback contract for rendered preview and future real MIDI synthesis - PR_26146_004-midi-studio-v2-real-playback-foundation

Author: ToolboxAid

docs/dev/reports/PR_26146_004-midi-studio-v2-real-playback-foundation_validation.md

@@ -0,0 +1,43 @@
+# PR_26146_004-midi-studio-v2-real-playback-foundation Validation
+
+## Scope
+
+- Repaired MIDI Studio V2 playback messaging so `.mid` files are treated as musical instruction data, not browser-playable audio.
+- Updated rendered preview behavior to use browser media playback only for manifest-owned rendered OGG/MP3/WAV targets.
+- Added explicit live MIDI synthesis status: `NOT IMPLEMENTED` until a real shared JavaScript MIDI parser/synth/instrument path exists.
+- Preserved first-class Workspace V2 tool scope and did not add MIDI input, recording, fallback songs, DAW editing, piano-roll editing, or fake playback.
+
+## Playback Contract
+
+- Manifest root `music.songs` stores song metadata.
+- `sourceMidi` points to a `.mid` musical instruction file.
+- `rendered` targets point to runtime audio assets that may be previewed through browser `Audio`.
+- Future real MIDI playback requires shared `src/` MIDI parser, synth, and instrument rendering capability before the tool can claim live MIDI playback.
+
+## Status Behavior
+
+- Rendered preview success logs `OK Rendered preview started ...`.
+- Instruction-only playback attempts log `WARN Live MIDI synthesis not implemented.`.
+- Songs without rendered targets fail with `FAIL No rendered audio target ... and no live MIDI engine is available ...`.
+
+## Validation
+
+- PASS: `node --check tests/playwright/tools/MidiStudioV2.spec.mjs`
+- PASS: `node --check tools/midi-studio-v2/js/MidiStudioV2App.js`
+- PASS: `node --check tools/midi-studio-v2/js/services/MidiPlaybackService.js`
+- PASS: `node --check tools/midi-studio-v2/js/controls/PlaybackControl.js`
+- PASS: `npx.cmd playwright test tests/playwright/tools/MidiStudioV2.spec.mjs --project=playwright --workers=1 --reporter=line`
+- PASS: `npx.cmd playwright test tests/playwright/tools/WorkspaceManagerV2.spec.mjs --project=playwright --workers=1 --reporter=line -g "registers Workspace Manager V2 from the tools index"`
+- PASS: `git diff --check`
+
+## Environment Notes
+
+- Initial Playwright Chromium install attempt failed when writing to the default user cache path.
+- Retried Chromium install with `PLAYWRIGHT_BROWSERS_PATH` set to `%TEMP%\ms-playwright`.
+- A TLS validation error was resolved by adding `NODE_OPTIONS=--use-system-ca`.
+- Targeted Playwright validation was run only after Chromium was available.
+
+## Explicit Skips
+
+- SKIP: full samples smoke test. Samples alignment is out of scope for this docs/tool repair.
+- SKIP: full Workspace V2 suite. Only the touched registration/handoff test was required and run.

tests/playwright/tools/MidiStudioV2.spec.mjs

@@ -57,6 +57,22 @@ const validManifest = {
           notes: "Short encounter loop."
         },
         tags: ["combat"]
+      },
+      {
+        id: "source-only",
+        name: "Source Only",
+        sourceMidi: "assets/music/midi/source-only.mid",
+        instrumentSet: "General MIDI",
+        rendered: {},
+        defaultRuntimeFormat: "ogg",
+        loop: { enabled: false },
+        director: {
+          mood: "mysterious",
+          intensity: "low",
+          usage: ["debug"],
+          notes: "Instruction-only MIDI with no rendered preview target."
+        },
+        tags: ["instruction-only"]
       }
     ]
   }
@@ -93,14 +109,14 @@ function installMockAudio(page) {
 async function openMidiStudio(page, routePayload = validManifest) {
   const server = await startRepoServer();
   await installMockAudio(page);
-  await page.route("**/midi-fixture.game.manifest.json", async (route) => {
+  await page.route((url) => url.pathname === "/midi-fixture.game.manifest.json", async (route) => {
     await route.fulfill({
       contentType: "application/json",
       body: JSON.stringify(routePayload)
     });
   });
   await workspaceV2CoverageReporter.start(page);
-  await page.goto(`${server.baseUrl}/tools/midi-studio-v2/index.html?manifestPath=/midi-fixture.game.manifest.json`, { waitUntil: "networkidle" });
+  await page.goto(`${server.baseUrl}/tools/midi-studio-v2/index.html?manifestPath=/midi-fixture.game.manifest.json`, { waitUntil: "domcontentloaded" });
   return server;
 }
 
@@ -112,15 +128,18 @@ test.describe("MIDI Studio V2", () => {
   test("launches and renders a valid multi-song manifest payload", async ({ page }) => {
     const server = await openMidiStudio(page);
     try {
-      await expect(page.locator("body[data-tool-id='midi-studio-v2']")).toBeVisible();
+      await expect(page.locator("body")).toHaveAttribute("data-tool-id", "midi-studio-v2");
       await expect(page.locator("[data-midi-studio-header]")).toContainText("MIDI Studio V2");
-      await expect(page.locator("#songList [data-song-id]")).toHaveCount(2);
+      await expect(page.locator("#songList [data-song-id]")).toHaveCount(3);
       await expect(page.locator('[data-song-id="theme-main"]')).toHaveAttribute("aria-pressed", "true");
       await expect(page.locator("#songSourceField")).toHaveValue("assets/music/midi/theme-main.mid");
       await expect(page.locator("#instrumentSetField")).toHaveValue("General MIDI");
       await expect(page.locator("#renderedTargets")).toContainText("theme-main.ogg");
       await expect(page.locator("#directorPanel")).toContainText("heroic");
-      await expect(page.locator("#statusLog")).toHaveValue(/OK Loaded 2 MIDI songs/);
+      await expect(page.locator("#playButton")).toHaveText("Play Rendered Preview");
+      await expect(page.locator("#playbackState")).toContainText("Live MIDI synthesis: NOT IMPLEMENTED");
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Loaded 3 MIDI songs/);
+      await expect(page.locator("#statusLog")).toHaveValue(/WARN Live MIDI synthesis not implemented\. sourceMidi is musical instruction data; rendered OGG\/MP3\/WAV targets are used for preview and gameplay audio\./);
     } finally {
       await workspaceV2CoverageReporter.stop(page);
       await server.close();
@@ -144,12 +163,13 @@ test.describe("MIDI Studio V2", () => {
     }
   });
 
-  test("shows actionable failure for a selected song with missing MIDI source", async ({ page }) => {
+  test("shows actionable failure when no rendered target and no live MIDI engine exist", async ({ page }) => {
     const server = await openMidiStudio(page);
     try {
-      await page.locator('[data-song-id="combat-light"]').click();
+      await page.locator('[data-song-id="source-only"]').click();
       await page.locator("#playButton").click();
-      await expect(page.locator("#statusLog")).toHaveValue(/FAIL Missing MIDI source for Light Combat\. Add music\.songs\[\]\.sourceMidi in game\.manifest\.json\./);
+      await expect(page.locator("#statusLog")).toHaveValue(/WARN Live MIDI synthesis not implemented\./);
+      await expect(page.locator("#statusLog")).toHaveValue(/FAIL No rendered audio target is available for Source Only, and no live MIDI engine is available\./);
       await expect(page.locator("#stopButton")).toBeDisabled();
       await expect(page.locator("#playButton")).toBeEnabled();
     } finally {
@@ -165,15 +185,15 @@ test.describe("MIDI Studio V2", () => {
       await page.locator("#playButton").click();
       await expect(page.locator("#playButton")).toBeDisabled();
       await expect(page.locator("#stopButton")).toBeEnabled();
-      await expect(page.locator("#playbackState")).toContainText("Playing preview: Main Theme");
-      await expect(page.locator("#statusLog")).toHaveValue(/OK Preview play started for Main Theme/);
+      await expect(page.locator("#playbackState")).toContainText("Playing rendered preview: Main Theme");
+      await expect(page.locator("#statusLog")).toHaveValue(/OK Rendered preview started for Main Theme: assets\/music\/rendered\/theme-main\.ogg\./);
       expect(await page.evaluate(() => window.__midiStudioAudioEvents)).toEqual([
-        { action: "play", loop: true, src: "assets/music/midi/theme-main.mid" }
+        { action: "play", loop: true, src: "assets/music/rendered/theme-main.ogg" }
       ]);
       await page.locator("#stopButton").click();
       await expect(page.locator("#stopButton")).toBeDisabled();
       await expect(page.locator("#playButton")).toBeEnabled();
-      await expect(page.locator("#playbackState")).toContainText("Stopped: Main Theme");
+      await expect(page.locator("#playbackState")).toContainText("Stopped rendered preview: Main Theme");
     } finally {
       await workspaceV2CoverageReporter.stop(page);
       await server.close();

tools/midi-studio-v2/README.md

@@ -7,7 +7,9 @@ Current scope:
 - renders multiple songs from `game.manifest.json` root `music.songs`;
 - honors `tools.midi-studio-v2.activeSongId` and `directorMode` preferences;
 - displays `.mid` source paths, instrument sets, rendered WAV/MP3/OGG targets, loop metadata, tags, and Game Music Director notes;
-- attempts browser media preview for selected `.mid` sources;
+- treats `sourceMidi` as a `.mid` instruction file path, not browser-playable audio;
+- uses browser media preview only for rendered OGG/MP3/WAV targets;
+- reports live MIDI synthesis as not implemented until shared MIDI parser/synth/instrument capability exists;
 - reports missing source paths and unsupported preview playback visibly;
 - rejects invalid payloads before render.
 
@@ -18,4 +20,9 @@ Out of scope:
 - piano-roll or DAW editing;
 - hidden fallback songs or sample data.
 
-Future `src/` follow-up: add shared MIDI parsing/synthesis/rendering capability when live MIDI preview and rendered WAV/MP3/OGG export move beyond this first usable metadata surface.
+Playback distinction:
+
+- manifest root `music.songs` stores song metadata;
+- `sourceMidi` points to a `.mid` musical instruction file;
+- `rendered` targets point to runtime audio assets that browser `Audio` may preview;
+- future real MIDI playback requires shared `src/` MIDI parser, synth, and instrument capability.

tools/midi-studio-v2/index.html

@@ -29,7 +29,7 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface V2</h2>
                 </div>
               </div>
               <div class="tools-platform-frame__topline">
-                <p class="tools-platform-frame__description">Inspect multi-song MIDI metadata, preview source files when the browser can play them, and verify rendered gameplay targets.</p>
+                <p class="tools-platform-frame__description">Inspect multi-song MIDI metadata, preview rendered audio targets, and track future live MIDI synthesis readiness.</p>
               </div>
             </div>
           </section>
@@ -70,7 +70,7 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface V2</h2>
           </button>
           <div id="songSourceContent" class="accordion-v2__content midi-studio-v2__stack">
             <div class="tool-starter__field tool-starter__field--not-editable">
-              <span>.mid source</span>
+              <span>.mid instruction source</span>
               <input id="songSourceField" type="text" readonly value="No song selected">
             </div>
             <div class="tool-starter__field tool-starter__field--not-editable">
@@ -84,12 +84,12 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface V2</h2>
       <section class="tool-starter__panel tool-starter__panel--center" aria-label="MIDI preview">
         <section class="accordion-v2 tool-starter__accordion is-open" data-accordion-v2-open="true">
           <button class="accordion-v2__header" type="button" aria-expanded="true" aria-controls="playbackContent">
-            <span>Playback Preview</span>
+            <span>Rendered Preview</span>
             <span class="accordion-v2__icon" aria-hidden="true">+</span>
           </button>
           <div id="playbackContent" class="accordion-v2__content">
             <div class="midi-studio-v2__playback-controls">
-              <button id="playButton" type="button" disabled>Play</button>
+              <button id="playButton" type="button" disabled>Play Rendered Preview</button>
               <button id="stopButton" type="button" disabled>Stop</button>
               <label class="tool-starter__toggle" for="loopToggle">
                 <input id="loopToggle" type="checkbox">

tools/midi-studio-v2/js/MidiStudioV2App.js

@@ -82,6 +82,7 @@ export class MidiStudioV2App {
     this.selectedSongId = this.payload.activeSongId;
     this.render();
     this.statusLog.ok(`Loaded ${this.payload.songs.length} MIDI song${this.payload.songs.length === 1 ? "" : "s"} from ${sourceLabel} via ${normalized.sourceKind}.`);
+    this.statusLog.warn("Live MIDI synthesis not implemented. sourceMidi is musical instruction data; rendered OGG/MP3/WAV targets are used for preview and gameplay audio.");
     return true;
   }
 
@@ -112,14 +113,17 @@ export class MidiStudioV2App {
 
   async playSelectedSong() {
     const song = this.selectedSong();
-    const result = await this.playback.play(song, { loop: this.playbackControl.loopEnabled() });
+    const result = await this.playback.playRenderedPreview(song, { loop: this.playbackControl.loopEnabled() });
     if (!result.ok) {
       this.playbackControl.setStopped(song);
+      if (result.liveMidiNotImplemented) {
+        this.statusLog.warn("Live MIDI synthesis not implemented.");
+      }
       this.statusLog.fail(result.message);
       return;
     }
     this.playbackControl.setPlaying(song);
-    this.statusLog.ok(`Preview play started for ${song.name}. Live MIDI playback is for tools, preview, and debugging; prefer rendered OGG/MP3 for gameplay.`);
+    this.statusLog.ok(`Rendered preview started for ${song.name}: ${result.path}.`);
   }
 
   stopPlayback() {

tools/midi-studio-v2/js/controls/PlaybackControl.js

@@ -24,18 +24,18 @@ export class PlaybackControl {
   setSelected(song) {
     this.playButton.disabled = !song;
     this.stopButton.disabled = true;
-    this.stateOutput.textContent = song ? `Ready: ${song.name}` : "No song selected.";
+    this.stateOutput.textContent = song ? `Rendered preview ready: ${song.name}. Live MIDI synthesis: NOT IMPLEMENTED.` : "No song selected.";
   }
 
   setPlaying(song) {
     this.playButton.disabled = true;
     this.stopButton.disabled = false;
-    this.stateOutput.textContent = `Playing preview: ${song.name}`;
+    this.stateOutput.textContent = `Playing rendered preview: ${song.name}`;
   }
 
   setStopped(song) {
     this.playButton.disabled = !song;
     this.stopButton.disabled = true;
-    this.stateOutput.textContent = song ? `Stopped: ${song.name}` : "No song selected.";
+    this.stateOutput.textContent = song ? `Stopped rendered preview: ${song.name}. Live MIDI synthesis: NOT IMPLEMENTED.` : "No song selected.";
   }
 }

tools/midi-studio-v2/js/services/MidiPlaybackService.js

@@ -6,31 +6,50 @@ export class MidiPlaybackService {
     this.activeTrackId = "";
   }
 
-  async play(song, { loop = false } = {}) {
-    const sourceMidi = String(song?.sourceMidi || "").trim();
+  renderedPreviewSource(song) {
+    const rendered = song?.rendered || {};
+    const preferredFormat = String(song?.defaultRuntimeFormat || "ogg").trim().toLowerCase();
+    const orderedFormats = [
+      preferredFormat,
+      "ogg",
+      "mp3",
+      "wav"
+    ].filter((format, index, formats) => format && formats.indexOf(format) === index);
+    for (const format of orderedFormats) {
+      const path = String(rendered[format] || "").trim();
+      if (path) {
+        return { format, path };
+      }
+    }
+    return null;
+  }
+
+  async playRenderedPreview(song, { loop = false } = {}) {
     if (!song?.id) {
       return { ok: false, message: "No MIDI song is selected." };
     }
-    if (!sourceMidi) {
+    const previewSource = this.renderedPreviewSource(song);
+    if (!previewSource) {
       return {
         ok: false,
-        message: `Missing MIDI source for ${song.name}. Add music.songs[].sourceMidi in game.manifest.json.`
+        liveMidiNotImplemented: true,
+        message: `No rendered audio target is available for ${song.name}, and no live MIDI engine is available. Add rendered OGG/MP3/WAV targets or implement shared src MIDI parser/synth/instrument capability.`
       };
     }
     if (!this.mediaTracks.isSupported()) {
       return { ok: false, message: "Media playback is unavailable in this browser." };
     }
     const trackId = `midi-studio-v2:${song.id}`;
-    this.mediaTracks.register(trackId, { loop, src: sourceMidi, volume: 1 });
+    this.mediaTracks.register(trackId, { loop, src: previewSource.path, volume: 1 });
     const played = await this.mediaTracks.play(trackId);
     if (!played) {
       return {
         ok: false,
-        message: this.mediaTracks.lastError || `MIDI preview failed for ${sourceMidi}. Browser MIDI playback may be unsupported; use rendered OGG/MP3 for gameplay.`
+        message: this.mediaTracks.lastError || `Rendered ${previewSource.format.toUpperCase()} preview failed for ${previewSource.path}.`
       };
     }
     this.activeTrackId = trackId;
-    return { ok: true, trackId };
+    return { format: previewSource.format, ok: true, path: previewSource.path, trackId };
   }
 
   stop() {