Skip to content

Commit e4cbaf8

Browse files
ToolboxAidToolboxAid
committed
Define MIDI Studio V2 multi-song manifest and playback requirements - PR_26146_002-midi-studio-v2-details
1 parent 233e885 commit e4cbaf8

2 files changed

Lines changed: 264 additions & 0 deletions

File tree

‎docs/dev/reports/PR_26146_002-midi-studio-v2-details_validation.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# PR_26146_002-midi-studio-v2-details Validation
2+
3+
## Changed Files
4+
5+
- `docs/pr/PR_26146_002-midi-studio-v2-details.md`
6+
- `docs/dev/reports/PR_26146_002-midi-studio-v2-details_validation.md`
7+
- `docs/dev/reports/codex_review.diff`
8+
- `docs/dev/reports/codex_changed_files.txt`
9+
10+
## Scope
11+
12+
Docs/spec only. No implementation code, runtime files, tool registration, sample JSON, generated audio assets, or engine files were changed for this PR.
13+
14+
## Validation Lanes
15+
16+
- contract documentation/static validation executed because this PR defines MIDI Studio V2 requirements and manifest examples.
17+
- runtime skipped because no runtime behavior changed.
18+
- integration skipped because no Workspace Manager V2 handoff or registration changed.
19+
- engine skipped because no audio runtime or shared parser code changed.
20+
- samples skipped because docs/spec changes do not affect samples.
21+
- recovery/UAT skipped because this PR does not modify Workspace V2 runtime or tool completion behavior.
22+
23+
## Commands
24+
25+
- `git diff --check`
26+
27+
## Results
28+
29+
- `git diff --check`: PASS
30+
- Playwright impacted: No.
31+
- No Playwright impact. This PR is docs/spec only.
32+
- Full samples smoke test: SKIP. This PR is documentation only and does not affect sample loading, shared sample framework behavior, or multiple sample runtimes.
33+
34+
## Manual Validation
35+
36+
1. Open `docs/pr/PR_26146_002-midi-studio-v2-details.md`.
37+
2. Confirm the requirements state JavaScript-driven MIDI Studio V2 scope, multiple manifest songs, `.mid` preview/import, Game Music Director mode, rendered WAV/MP3/OGG export targets, and no MIDI input/recording scope.
38+
3. Confirm the manifest examples use file/path metadata for source MIDI and rendered audio assets.
39+
4. Confirm the first-class tool lifecycle notes reference future implementation through Tool Template V2 and Workspace Manager V2 patterns.
40+
41+
Expected outcome:
42+
43+
- The spec defines future MIDI Studio V2 requirements without adding implementation code.
44+
45+
## Out Of Scope Checks
46+
47+
- Playwright was not run.
48+
- Full samples smoke test was not run.
49+
- Runtime audio behavior was not changed or validated.

‎docs/pr/PR_26146_002-midi-studio-v2-details.md‎

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
# PR_26146_002-midi-studio-v2-details
2+
3+
## Scope
4+
5+
Defines MIDI Studio V2 requirements only. This PR does not add implementation code, runtime wiring, UI files, tests, samples, or engine changes.
6+
7+
## Purpose
8+
9+
MIDI Studio V2 is a first-class Workspace V2 tool for importing, previewing, organizing, directing, and exporting game music based on `.mid` assets. The tool exists to make MIDI-authored music usable by games while keeping gameplay runtime audio predictable and inexpensive.
10+
11+
## Requirements
12+
13+
- MIDI Studio V2 must be JavaScript-driven only.
14+
- MIDI Studio V2 must support multiple MIDI songs declared in `game.manifest.json`.
15+
- MIDI Studio V2 must play imported `.mid` files for tool preview and debugging.
16+
- MIDI Studio V2 must include a Game Music Director mode for non-composers.
17+
- MIDI Studio V2 must not include MIDI input, MIDI keyboard capture, or recording scope.
18+
- MIDI Studio V2 must use manifest-owned music metadata as the persisted source of truth.
19+
- MIDI Studio V2 must support rendered export targets for WAV, MP3, and OGG.
20+
- Gameplay runtime should prefer rendered OGG or MP3 assets when live MIDI playback is too CPU-intensive.
21+
- Live MIDI playback is primarily for tools, preview, and debugging.
22+
23+
## Out Of Scope
24+
25+
- No MIDI input device support.
26+
- No recording workflow.
27+
- No DAW replacement workflow.
28+
- No runtime engine implementation.
29+
- No sample JSON alignment.
30+
- No Workspace Manager V2 registration in this PR.
31+
- No generated audio assets in this PR.
32+
33+
## Manifest Ownership
34+
35+
`game.manifest.json` owns music metadata. The manifest should store file/path-oriented references and metadata required by tools and runtime. It must not persist binary MIDI or rendered audio payloads inline, and it must not use `imageDataUrl` or equivalent data URL fields for persisted project/runtime/workspace contracts.
36+
37+
Recommended ownership boundaries:
38+
39+
- `music.songs[]` owns song identity, source MIDI path, rendered asset paths, loop metadata, tags, mood, intensity, and intended gameplay usage.
40+
- `tools.midi-studio-v2` owns tool-specific authoring preferences and selected song state when those values are part of the game manifest contract.
41+
- Workspace/toolState storage may hold active editing state, but durable song metadata should be written back to the manifest-owned music section.
42+
43+
## Recommended Manifest Schema
44+
45+
The exact runtime schema can evolve during implementation, but future work should preserve these contract principles:
46+
47+
- Multiple songs are represented as an array.
48+
- Every song has a stable `id`.
49+
- Imported MIDI source uses a path field such as `sourceMidi`.
50+
- Rendered gameplay assets use explicit path fields grouped by format.
51+
- Runtime preference is declared without hiding fallback behavior.
52+
- Tags and director metadata are manifest-owned and readable without launching the tool.
53+
54+
```json
55+
{
56+
"music": {
57+
"version": 1,
58+
"runtimePreference": "rendered",
59+
"songs": [
60+
{
61+
"id": "theme-main",
62+
"name": "Main Theme",
63+
"sourceMidi": "assets/music/midi/theme-main.mid",
64+
"rendered": {
65+
"ogg": "assets/music/rendered/theme-main.ogg",
66+
"mp3": "assets/music/rendered/theme-main.mp3",
67+
"wav": "assets/music/rendered/theme-main.wav"
68+
},
69+
"defaultRuntimeFormat": "ogg",
70+
"loop": {
71+
"enabled": true,
72+
"startSeconds": 1.2,
73+
"endSeconds": 62.4
74+
},
75+
"director": {
76+
"mood": "heroic",
77+
"intensity": "medium",
78+
"usage": ["title", "menu"],
79+
"notes": "Bright opening cue for the first player-facing screen."
80+
},
81+
"tags": ["theme", "menu", "heroic"]
82+
},
83+
{
84+
"id": "combat-light",
85+
"name": "Light Combat",
86+
"sourceMidi": "assets/music/midi/combat-light.mid",
87+
"rendered": {
88+
"ogg": "assets/music/rendered/combat-light.ogg",
89+
"mp3": "assets/music/rendered/combat-light.mp3",
90+
"wav": "assets/music/rendered/combat-light.wav"
91+
},
92+
"defaultRuntimeFormat": "ogg",
93+
"loop": {
94+
"enabled": true,
95+
"startSeconds": 0,
96+
"endSeconds": 48
97+
},
98+
"director": {
99+
"mood": "tense",
100+
"intensity": "high",
101+
"usage": ["combat", "encounter"],
102+
"notes": "Short loop for early combat encounters."
103+
},
104+
"tags": ["combat", "loop", "tense"]
105+
}
106+
]
107+
},
108+
"tools": {
109+
"midi-studio-v2": {
110+
"activeSongId": "theme-main",
111+
"directorMode": {
112+
"enabled": true,
113+
"defaultIntensity": "medium"
114+
}
115+
}
116+
}
117+
}
118+
```
119+
120+
## Alternate Compact Manifest Example
121+
122+
For small games, rendered asset entries may omit unavailable formats while keeping the source MIDI and stable song IDs.
123+
124+
```json
125+
{
126+
"music": {
127+
"version": 1,
128+
"runtimePreference": "rendered",
129+
"songs": [
130+
{
131+
"id": "ambient-cave",
132+
"name": "Ambient Cave",
133+
"sourceMidi": "assets/music/midi/ambient-cave.mid",
134+
"rendered": {
135+
"ogg": "assets/music/rendered/ambient-cave.ogg"
136+
},
137+
"defaultRuntimeFormat": "ogg",
138+
"loop": {
139+
"enabled": true
140+
},
141+
"director": {
142+
"mood": "mysterious",
143+
"intensity": "low",
144+
"usage": ["level", "exploration"]
145+
},
146+
"tags": ["ambient", "cave"]
147+
}
148+
]
149+
}
150+
}
151+
```
152+
153+
## Runtime Expectations
154+
155+
Gameplay runtime should treat rendered audio as the preferred path when live MIDI playback would be too CPU-intensive or inconsistent across browsers. Runtime selection should be explicit:
156+
157+
- Prefer `defaultRuntimeFormat` when the file exists and the browser can play it.
158+
- Prefer OGG for gameplay when supported.
159+
- Use MP3 as the broad compatibility fallback when OGG is unavailable.
160+
- Treat WAV as an export/mastering target unless a game explicitly opts into it.
161+
- Do not silently switch to live MIDI if rendered assets are missing.
162+
- Report missing rendered assets as visible validation or runtime diagnostics.
163+
164+
Live MIDI playback remains valuable for:
165+
166+
- imported `.mid` preview;
167+
- tool-side arrangement inspection;
168+
- debugging tempo, loop, and channel metadata;
169+
- export comparison against rendered targets.
170+
171+
## Game Music Director Mode
172+
173+
Game Music Director mode should help non-composers choose, organize, and prepare songs without requiring music theory or DAW knowledge.
174+
175+
Expected future capabilities:
176+
177+
- browse songs by mood, intensity, usage, and tags;
178+
- recommend title, menu, level, encounter, combat, victory, defeat, and ambient usage categories;
179+
- show whether each song has source MIDI and rendered gameplay assets;
180+
- expose loop and runtime readiness status in plain language;
181+
- support simple notes for intent and scene placement;
182+
- avoid editing workflows that imply MIDI recording or performance capture.
183+
184+
Game Music Director mode should write durable decisions to manifest-owned music metadata, not hidden local storage or disconnected tool-only state.
185+
186+
## First-Class Tool Lifecycle Notes
187+
188+
Future MIDI Studio V2 implementation should follow the First-Class Tool Lifecycle Contract from `docs/dev/PROJECT_INSTRUCTIONS.md`.
189+
190+
Implementation notes for a future PR:
191+
192+
- Create the tool under `tools/midi-studio-v2/`.
193+
- Start from `tools/_templates-v2`.
194+
- Preserve template headers, NAV, panels, accordions, status/logging, CSS wiring, JS bootstrapping, and accessibility structure.
195+
- Register through existing first-class tool patterns in `tools/index.html` and `tools/workspace-manager-v2/index.html`.
196+
- Participate in Workspace Manager V2 launch/navigation patterns.
197+
- Support dirty-state handling and save/cancel lifecycle behavior.
198+
- Validate manifest and toolState payloads before render.
199+
- Reject invalid MIDI/music metadata without partial render.
200+
- Log import, preview, export, missing file, and unsupported format failures visibly.
201+
- Keep CSS and JavaScript external.
202+
- Do not introduce an isolated persistence system.
203+
- Do not introduce an alternate launch/navigation system.
204+
205+
## Validation
206+
207+
Playwright impacted: No.
208+
209+
No Playwright impact. This PR is docs/spec only.
210+
211+
Required validation:
212+
213+
- `git diff --check`
214+
215+
Full samples smoke test is skipped because this PR changes only documentation and does not affect sample loading, shared sample framework behavior, or sample runtimes.

0 commit comments

Comments
 (0)