230 lines
8.7 KiB
Markdown
230 lines
8.7 KiB
Markdown
# TECHNICAL SPECIFICATION: INSTRUMENT MANAGEMENT & DATA ISOLATION FOR MULTI-ITEM PIANO ROLL TABS
|
|
|
|
This document specifies the data architecture, state flow, and audio channel routing rules required to ensure that when a single Piano Roll Tab opens multiple `MIDIItems` simultaneously from different Tracks, modifying the instrument/synth engine for the active item applies exclusively to its parent track without affecting any other items or tracks.
|
|
|
|
---
|
|
|
|
## 1. DATA OWNERSHIP HIERARCHY
|
|
|
|
To prevent cross-track instrument configuration leakage, the system enforces **Track-Level Ownership**:
|
|
|
|
* **Track (`TrackState`):** The sole owner of synth engine configurations (`synth_engine`), assigned MIDI channel (`midi_channel`), and mixing parameters (`volume_db`, `pan`).
|
|
* **MIDI Item (`MIDIItemState`):** Contains **no** independent synth configuration parameters. An item holds only its array of notes (`source_data.notes`) and a mandatory parent reference pointer (`parent_track_id`).
|
|
|
|
```text
|
|
[ Main Session / Project State ]
|
|
│
|
|
├── Track 1 (id: "track_01", midi_channel: 0, synth_engine: "DSK_Pipa")
|
|
│ └── Item 1 (id: "item_01", parent_track_id: "track_01") ──┐
|
|
│ │
|
|
└── Track 2 (id: "track_02", midi_channel: 1, synth_engine: "None")│
|
|
└── Item 2 (id: "item_02", parent_track_id: "track_02") ──┼─► [ Piano Roll Tab Context ]
|
|
│ (Active Item Selector Dropdown)
|
|
│ ├── Selected: Item 1 -> Scope: Track 1
|
|
└── └── Inactive: Item 2 -> Scope: Track 2
|
|
|
|
```
|
|
|
|
---
|
|
|
|
## 2. MULTI-ITEM PIANO ROLL TAB STATE STRUCTURE
|
|
|
|
When a user opens one or more `MIDIItems` inside the same Piano Roll Tab, the Tab Context State maintains a list of open item IDs along with an `active_item_id` representing the item currently selected in the toolbar dropdown:
|
|
|
|
```javascript
|
|
// Tab Context state structure for a Piano Roll Tab editing multiple items
|
|
const multiItemPianoRollTabContext = {
|
|
tab_id: "tab_pianoroll_multi_editor",
|
|
title: "Piano Roll Editor",
|
|
type: "PIANO_ROLL_TAB",
|
|
|
|
// 1. Array of all MIDI Item IDs currently loaded in this Tab
|
|
open_item_ids: ["item_01", "item_02"],
|
|
|
|
// 2. ID of the item currently selected for direct editing via the Toolbar Dropdown
|
|
active_item_id: "item_01",
|
|
|
|
// 3. Dynamic Computed Context (Derived State based on active_item_id)
|
|
active_scope: {
|
|
item_id: "item_01",
|
|
parent_track_id: "track_01", // Reverse pointer to Track 1
|
|
midi_channel: 0, // Dedicated MIDI Channel for Track 1
|
|
current_synth_engine: {
|
|
type: "soundfont",
|
|
plugin_id: "dsk_asian_dreamz",
|
|
soundfont_bank: 0,
|
|
soundfont_program: 0 // Pipa
|
|
}
|
|
}
|
|
};
|
|
|
|
```
|
|
|
|
---
|
|
|
|
## 3. ISOLATED INSTRUMENT SELECTION WORKFLOW
|
|
|
|
### Step 1: User switches `active_item_id` in the Toolbar Dropdown
|
|
|
|
When the user selects `MIDI Item 2` from the Piano Roll Tab dropdown:
|
|
|
|
1. The Tab Controller receives a `SWITCH_PIANO_ROLL_ACTIVE_ITEM` event.
|
|
2. The system queries `MIDI Item 2` for its `parent_track_id` (e.g., returning `"track_02"`).
|
|
3. The controller reads the current `synth_engine` configuration directly from `Track 2`.
|
|
4. The Piano Roll Tab's Synth button label updates to reflect `Track 2`'s instrument (or displays `🎵 None (Default Synth)` if unassigned).
|
|
|
|
### Step 2: User changes the instrument in the Piano Roll Synth Menu
|
|
|
|
When the user opens the Synth menu on the Piano Roll toolbar and selects a new instrument (e.g., selecting `Vital VST3` or `Saxophone SoundFont`):
|
|
|
|
1. The UI resolves the current `active_item_id` (`"item_01"`).
|
|
2. The UI queries the parent track ID: `targetTrackId = getItemParentTrackId(active_item_id)`.
|
|
3. The system dispatches an isolated mutation action:
|
|
```javascript
|
|
dispatch({
|
|
type: "UPDATE_TRACK_SYNTH_ENGINE",
|
|
payload: {
|
|
track_id: targetTrackId, // Modifies ONLY "track_01"; "track_02" remains untouched
|
|
synth_engine: {
|
|
type: "vst3",
|
|
plugin_id: "Vital",
|
|
soundfont_bank: 0,
|
|
soundfont_program: 0
|
|
}
|
|
}
|
|
});
|
|
|
|
```
|
|
|
|
|
|
|
|
---
|
|
|
|
## 4. AUDIO CHANNEL ISOLATION
|
|
|
|
To ensure that triggering notes on `Item 1` plays the Pipa sound while `Item 2` plays the Vital patch without audio cross-talk, dedicated MIDI channels are assigned per track:
|
|
|
|
### MIDI Channel Binding Rules
|
|
|
|
| Track | MIDI Item | Parent Track ID | Dedicated MIDI Channel | Applied Instrument |
|
|
| --- | --- | --- | --- | --- |
|
|
| **Track 1** | MIDI Item 1 | `track_01` | Channel 0 | DSK_Asian_DreamZ (Pipa) |
|
|
| **Track 2** | MIDI Item 2 | `track_02` | Channel 1 | Vital.vst3 |
|
|
|
|
* **When configuring Instrument for Track 1:**
|
|
The Client SoundEngine/Wasm routes configuration changes exclusively to Channel 0:
|
|
```javascript
|
|
soundFontPlayerInstance.selectInstrument(channel = 0, bank = 0, program = 0);
|
|
|
|
```
|
|
|
|
|
|
* **When configuring Instrument for Track 2:**
|
|
The Client SoundEngine/Wasm routes configuration changes exclusively to Channel 1:
|
|
```javascript
|
|
soundFontPlayerInstance.selectInstrument(channel = 1, bank = 0, program = 56);
|
|
|
|
```
|
|
|
|
|
|
* **When previewing notes in the Piano Roll:**
|
|
* If `MIDI Item 1` is active $\rightarrow$ Dispatch `noteOn(channel = 0, pitch, velocity)`.
|
|
* If `MIDI Item 2` is active $\rightarrow$ Dispatch `noteOn(channel = 1, pitch, velocity)`.
|
|
|
|
|
|
|
|
---
|
|
|
|
## 5. CORE SERVICE IMPLEMENTATION (`pianoRollTabService.js`)
|
|
|
|
```javascript
|
|
// app/static/js/services/pianoRollTabService.js
|
|
|
|
/**
|
|
* State Manager and Dispatcher for Multi-Item Piano Roll Tabs
|
|
*/
|
|
export class PianoRollTabManager {
|
|
constructor(sessionState, soundEngine) {
|
|
this.sessionState = sessionState;
|
|
this.soundEngine = soundEngine;
|
|
}
|
|
|
|
/**
|
|
* Retrieves parent Track by Item ID
|
|
*/
|
|
getParentTrackByItemId(itemId) {
|
|
for (const track of this.sessionState.main_session.tracks) {
|
|
const item = track.items.find(i => i.id === itemId);
|
|
if (item) return track;
|
|
}
|
|
return null;
|
|
}
|
|
|
|
/**
|
|
* Updates instrument configuration from the Piano Roll Tab Toolbar
|
|
* @param {string} activeItemId - Currently selected Item ID in dropdown
|
|
* @param {Object} newSynthConfig - New Synth configuration object
|
|
*/
|
|
setInstrumentFromPianoRoll(activeItemId, newSynthConfig) {
|
|
const parentTrack = this.getParentTrackByItemId(activeItemId);
|
|
|
|
if (!parentTrack) {
|
|
console.error(`[PianoRoll] Parent Track not found for Item ID: ${activeItemId}`);
|
|
return;
|
|
}
|
|
|
|
console.log(`[PianoRoll] Applying new instrument to Track "${parentTrack.name}" (ID: ${parentTrack.id})`);
|
|
|
|
// 1. Update state exclusively on the parent Track
|
|
parentTrack.synth_engine = { ...newSynthConfig };
|
|
|
|
// 2. Resolve parent Track's dedicated MIDI Channel
|
|
const trackIndex = this.sessionState.main_session.tracks.findIndex(t => t.id === parentTrack.id);
|
|
const dedicatedMidiChannel = trackIndex % 16; // Assign channels 0-15
|
|
|
|
// 3. Dispatch instrument change to the Client Sound Engine ONLY FOR THIS CHANNEL
|
|
if (this.soundEngine) {
|
|
this.soundEngine.selectInstrument(
|
|
dedicatedMidiChannel,
|
|
newSynthConfig.soundfont_bank || 0,
|
|
newSynthConfig.soundfont_program || 0
|
|
);
|
|
}
|
|
|
|
// 4. Dispatch UI re-render event
|
|
window.dispatchEvent(new CustomEvent('DAW_STATE_UPDATED', { detail: this.sessionState }));
|
|
}
|
|
|
|
/**
|
|
* Switches the active item in the toolbar dropdown
|
|
*/
|
|
switchActiveItem(tabContext, newActiveItemId) {
|
|
tabContext.active_item_id = newActiveItemId;
|
|
|
|
const parentTrack = this.getParentTrackByItemId(newActiveItemId);
|
|
if (parentTrack) {
|
|
tabContext.active_scope = {
|
|
item_id: newActiveItemId,
|
|
parent_track_id: parentTrack.id,
|
|
current_synth_engine: parentTrack.synth_engine || { type: "none" }
|
|
};
|
|
}
|
|
|
|
return tabContext;
|
|
}
|
|
}
|
|
|
|
```
|
|
|
|
---
|
|
|
|
## 6. UI/UX SAFETY CHECKS & ERROR PREVENTION
|
|
|
|
* **Explicit Parent Track Indicators on Toolbar:**
|
|
Next to the MIDI Item dropdown, the Piano Roll toolbar explicitly displays context labels:
|
|
`[ Item Selector: MIDI Item 1 ▾ ] ── (Belongs to: Track 1)`
|
|
The Synth Selector button displays: `[ 🎵 Synth (Track 1): DSK_Pipa ▾ ]`.
|
|
* **Isolated Event Bus Mutators:**
|
|
When invoking `setTrackInstrument`, global setters such as `setAllTracksInstrument()` or `global_synth_engine` mutations are strictly forbidden. Every state mutation function requires an explicit `track_id` parameter.
|
|
* **Multi-Item Ghost Notes Rendering:**
|
|
The item selected in the dropdown (`active_item_id`) is the sole editable item. All other items listed in `open_item_ids` render automatically as read-only Ghost Notes for visual reference without mixing note data or instrument parameters. |