Skip to content

Commit 671443f

Browse files
fabbfabb
committed
feat: added epics 5-8
1 parent 161b427 commit 671443f

15 files changed

Lines changed: 854 additions & 1 deletion

‎docs/epic-5.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Epic 5: Enhance MCP `status` Command
2+
3+
## 1. Goal
4+
5+
To significantly enhance the `status` MCP command by providing a more comprehensive snapshot of the current Bitwig Studio state. This will give AI agents richer context, enabling more informed decisions and sophisticated interactions with the Bitwig environment.
6+
7+
## 2. Background
8+
9+
The existing `status` command returns minimal information (WigAI version and operational status). To allow for more intelligent agent behavior, it needs to convey key aspects of the Bitwig project, transport, selected track, selected clip slot, and selected device, including their parameters. This enhancement is inspired by the detailed information available via Bitwig's OSC interface.
10+
11+
## 3. User Stories
12+
13+
This epic will be broken down into the following stories:
14+
15+
* **Story 5.1: Core Project and Transport Status**
16+
* As an AI agent, I want to retrieve the current project name and audio engine status, so I can confirm I'm working in the correct project and that audio is active.
17+
* As an AI agent, I want to know the current transport state (playing, recording, tempo, time signature, beat/time position), so I can synchronize my actions with Bitwig's playback.
18+
* **Story 5.2: Selected Track and Project Parameters Status**
19+
* As an AI agent, I want to access global project parameters, so I can read or potentially suggest modifications to them.
20+
* As an AI agent, I want to get information about the currently selected track (index, name, type, mute/solo/arm status), so I can perform track-specific operations.
21+
* **Story 5.3: Selected Device Status and Parameters**
22+
* As an AI agent, I want to get information about the currently selected device (track context, device index, name, bypass status, and its parameters), so I can understand and control the selected device.
23+
* **Story 5.4: Selected Clip Slot Status**
24+
* As an AI agent, I want to get information about the currently selected clip slot (track context, slot/scene indices, names, content status, playback/recording states), so I can interact with clips in the session view.
25+
26+
## 4. Proposed Solution
27+
28+
Modify the `StatusTool.java` to gather additional information from the Bitwig Studio API and return it in an expanded JSON structure. The MCP `status` command will no longer have a top-level `status` or `message` field from the tool's direct response; these will be handled by the MCP protocol wrapper if necessary. The `wigai_version` will remain.
29+
30+
### Proposed JSON Response for `status` Command:
31+
32+
```json
33+
{
34+
"wigai_version": "x.y.z",
35+
"project_name": "Name of the project",
36+
"audio_engine_active": true,
37+
"project_parameters": [
38+
{
39+
"index": 0, // 0-7, maps to OSC /project/param/{1-8}
40+
"exists": true, // From /project/param/{1-8}/exists
41+
"name": "Project Param 1 Name", // From /project/param/{1-8}/name
42+
"value": 0.5, // From /project/param/{1-8}/value (normalized 0.0-1.0 for consistency)
43+
"display_value": "50%" // From /project/param/{1-8}/valueStr
44+
}
45+
// ... up to 8 project parameters, only include if 'exists' is true
46+
],
47+
"transport": {
48+
"playing": false,
49+
"recording": false,
50+
"repeat_active": true,
51+
"metronome_active": false,
52+
"current_tempo": 120.0, // From /tempo/raw
53+
"time_signature": "4/4", // From /time/signature
54+
"current_beat_str": "1.1.1:0", // From /beat/str (Bitwig format: measures.beats.sixteenths:ticks)
55+
"current_time_str": "0.0.0:0" // From /time/str (e.g., H.M.S:ms or M.S.ms)
56+
},
57+
"selected_track": {
58+
"index": 0, // 0-based index of the track in the project
59+
"name": "Drums", // From /track/selected/name
60+
"type": "instrument", // From /track/selected/type (e.g., audio, instrument, hybrid, group, effect, master)
61+
"is_group": false, // From /track/selected/isGroup
62+
"muted": false, // From /track/selected/mute
63+
"soloed": false, // From /track/selected/solo
64+
"armed": true // From /track/selected/recarm
65+
},
66+
"selected_clip_slot": {
67+
"track_name": "Drums", // Name of the track this slot belongs to
68+
"track_index": 0, // Index of the track this slot belongs to
69+
"slot_index": 0, // 0-based index of the clip slot on its track
70+
"scene_index": 0, // 0-based index of the scene this slot aligns with
71+
"scene_name": "Verse 1", // Name of the scene, null if scene is unnamed or not applicable
72+
"has_content": true, // true if a clip exists in this slot, false otherwise
73+
"clip_name": "Drum Loop 1", // Name of the clip if has_content is true, null otherwise
74+
"is_playing": false,
75+
"is_recording": false,
76+
"is_playback_queued": false,
77+
"is_recording_queued": false,
78+
"is_stop_queued": false
79+
},
80+
"selected_device": {
81+
"track_name": "Drums", // Name of the track this device is on
82+
"track_index": 0, // Index of the track this device is on
83+
"index": 0, // 0-based index of the device in the track's device chain
84+
"name": "Polymer", // Name of the selected device
85+
"bypassed": false, // True if the device is currently bypassed
86+
"parameters": [ // Parameters of the selected device
87+
{
88+
"index": 0, // 0-7
89+
"name": "Oscillator Mix", // From /device/param/{1-8}/name
90+
"value": 0.75, // From /device/param/{1-8}/value (normalized 0.0-1.0)
91+
"display_value": "75%" // From /device/param/{1-8}/valueStr
92+
}
93+
// ... up to 8 device parameters, only include if accessible/exists
94+
]
95+
}
96+
}
97+
```
98+
99+
## 5. Technical Considerations
100+
101+
* The `StatusTool.java` will need to interface with various parts of the Bitwig Studio Java API (Application, Project, Transport, Track, Device, ClipLauncherSlotBank, etc.) to retrieve the required information.
102+
* Care must be taken to handle cases where information might be unavailable (e.g., no device selected, no clip slot selected, project parameters not configured). In such cases, relevant fields should be `null` or omitted where appropriate (e.g., an empty array for parameters if none exist).
103+
* The `value` for parameters should be normalized (0.0-1.0) where applicable, consistent with `get_selected_device_parameters`. `display_value` will provide the formatted string.
104+
* Indices (`track_index`, `slot_index`, `scene_index`, `device.index`) should be 0-based.
105+
* The `api-reference.md` will need to be updated to reflect these changes to the `status` command's response.
106+
107+
## 6. Acceptance Criteria
108+
109+
* The `status` MCP command returns a JSON object matching the structure defined above.
110+
* All fields in the JSON response accurately reflect the current state of Bitwig Studio.
111+
* The `StatusTool.java` correctly queries the Bitwig API for all required data points.
112+
* The `api-reference.md` is updated with the new response format for the `status` command.
113+
* The changes are thoroughly tested for various Bitwig project states (e.g., empty project, project with content, different selections).
114+
* The tool gracefully handles scenarios where parts of the requested information are not available (e.g., no device selected, an empty clip slot selected).
115+
116+
## 7. Out of Scope for this Epic
117+
118+
* Adding new MCP commands to modify these states (they are covered by other tools or future epics).
119+
* Fetching exhaustive lists of all tracks, scenes, or devices (these would be separate, more specific tools).
120+
* Real-time event streaming of state changes (this `status` command is a poll/request-response).
121+

‎docs/epic-6.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Epic 6: Track Information Retrieval
2+
3+
## 1. Goal
4+
5+
To provide comprehensive MCP tools for listing all tracks within a Bitwig Studio project and retrieving detailed information about specific tracks, including the currently selected track. This will enable AI agents to have a deeper understanding of the project's track structure, individual track states, contained devices, and clip details.
6+
7+
## 2. Background
8+
9+
While the enhanced `status` command (Epic 5) provides information about the *selected* track, AI agents often need a broader view of all tracks or need to query specific tracks by name or index. This epic introduces dedicated tools for these purposes, drawing inspiration from the granular data available via OSC and the Bitwig Java API.
10+
11+
## 3. User Stories
12+
13+
* As an AI agent, I want to list all tracks in the current project with summary information (name, type, selection state, basic device list), so I can understand the overall project structure.
14+
* As an AI agent, I want to get detailed information for a specific track (by index, name, or by targeting the currently selected track), including its parameters (volume, pan, mute, solo, arm), sends, and a list of its clips with their properties (name, color, length, loop status), so I can perform targeted analysis or suggest modifications.
15+
* As an AI agent, I want to know which track is currently selected when listing all tracks, so I can easily identify the user's current focus.
16+
* As an AI agent, I want to know the parent group of a track, so I can understand its hierarchical context.
17+
18+
## 4. Proposed MCP Tools
19+
20+
### 4.1. `list_tracks`
21+
22+
* **Description:** Retrieves a list of all tracks in the project with summary information.
23+
* **Request Parameters:**
24+
* `type` (string, optional): Filter by track type (e.g., "audio", "instrument", "group", "effect", "master").
25+
* **Response Body:** An array of track objects, each containing:
26+
* `index` (integer): 0-based position in the project's main track list.
27+
* `name` (string): Name of the track.
28+
* `type` (string): Type of the track (e.g., "audio", "instrument", "hybrid", "group", "effect", "master").
29+
* `is_group` (boolean): True if the track is a group track.
30+
* `parent_group_index` (integer, nullable): 0-based index of the parent group track if this track is inside a group, `null` otherwise.
31+
* `activated` (boolean): Is the track activated.
32+
* `color` (string): Color of the track (e.g., "rgb(r,g,b)").
33+
* `is_selected` (boolean): True if this is the currently selected track.
34+
* `devices` (array of objects): Summary of devices on this track.
35+
* `index` (integer): 0-based position in this track's device chain.
36+
* `name` (string): Name of the device.
37+
* `type` (string): Type of the device (e.g. "Instrument", "AudioFX", "NoteFX").
38+
39+
### 4.2. `get_track_details`
40+
41+
* **Description:** Retrieves detailed information for a specific track.
42+
* **Request Parameters:**
43+
* `track_index` (integer, optional): 0-based index of the track.
44+
* `track_name` (string, optional): Name of the track.
45+
* `get_selected` (boolean, optional): If true, retrieves details for the currently selected track. If no parameters are provided, this defaults to `true`.
46+
* *(Note: Only one of `track_index`, `track_name`, or `get_selected` (or default behavior) should be used per call.)*
47+
* **Response Body:** A single track object containing:
48+
* All fields from the `list_tracks` response object for this track.
49+
* `volume` (float): Normalized volume (0.0-1.0).
50+
* `volume_str` (string): Formatted volume string (e.g., "-6.0 dB").
51+
* `pan` (float): Normalized pan (-1.0 to 1.0 or 0.0-1.0, needs API confirmation).
52+
* `pan_str` (string): Formatted pan string (e.g., "L 50%").
53+
* `muted` (boolean): Is the track muted.
54+
* `soloed` (boolean): Is the track soloed.
55+
* `armed` (boolean): Is the track armed for recording.
56+
* `monitor_enabled` (boolean): Is monitoring enabled.
57+
* `auto_monitor_enabled` (boolean): Is auto-monitoring enabled.
58+
* `sends` (array of objects): List of sends for the track.
59+
* `name` (string): Name of the send channel.
60+
* `volume` (float): Normalized send level.
61+
* `volume_str` (string): Formatted send level string.
62+
* `activated` (boolean): Is the send activated.
63+
* `clips` (array of objects): List of clips in the track's slots.
64+
* `slot_index` (integer): 0-based index of the clip slot (corresponds to scene index).
65+
* `scene_name` (string, nullable): Name of the scene this slot aligns with, `null` if scene is unnamed or not applicable.
66+
* `has_content` (boolean): True if the slot contains a clip.
67+
* `clip_name` (string, nullable): Name of the clip if `has_content` is true.
68+
* `clip_color` (string, nullable): Color of the clip if `has_content` is true.
69+
* `length` (string, nullable): Length of the clip (e.g., "4.0.0" for beats.beats.sixteenths or a duration format) if `has_content` is true.
70+
* `is_looping` (boolean, nullable): True if the clip is set to loop, if `has_content` is true.
71+
* `is_playing` (boolean, nullable): True if the clip in this slot is currently playing (if `has_content` is true).
72+
* `is_recording` (boolean, nullable): True if the clip in this slot is currently recording (if `has_content` is true).
73+
* `is_playback_queued` (boolean, nullable): True if playback is queued for the clip in this slot (if `has_content` is true).
74+
* `is_recording_queued` (boolean, nullable): True if recording is queued for the clip in this slot (if `has_content` is true).
75+
* `is_stop_queued` (boolean, nullable): True if a stop is queued for the clip in this slot (if `has_content` is true).
76+
77+
## 5. Technical Considerations
78+
79+
* The implementation will primarily use the Bitwig Studio Java API, specifically `TrackBank` for `list_tracks` and `CursorTrack` (potentially moved to a specific track) for `get_track_details`.
80+
* Device listing within `list_tracks` will require iterating through each track's `DeviceChain`.
81+
* Clip information for `get_track_details` will involve accessing the track's `ClipLauncherSlotBank`.
82+
* Normalization of values (volume, pan) should be consistent with other MCP tools.
83+
* Error handling for invalid track identifiers (name/index) or when a selected track is not available.
84+
* The `api-reference.md` will need to be updated with these new tools and their detailed schemas.
85+
86+
## 6. Acceptance Criteria
87+
88+
* `list_tracks` MCP command returns an accurate array of all tracks with the specified summary fields.
89+
* `list_tracks` correctly indicates the `is_selected` track.
90+
* `list_tracks` correctly lists summary device information for each track.
91+
* `get_track_details` MCP command returns accurate, detailed information for a track specified by index, name, or as the currently selected track.
92+
* `get_track_details` defaults to the selected track if no specifier is given.
93+
* `get_track_details` includes correct volume, pan, mute/solo/arm, sends, and detailed clip information (including length, loop status, and playback states).
94+
* Both tools handle edge cases gracefully (e.g., empty project, track not found).
95+
* `api-reference.md` is updated to reflect the new tools.
96+
97+
## 7. Out of Scope for this Epic
98+
99+
* Modifying track properties (these would be separate tools/epics).
100+
* Listing detailed device parameters within `list_tracks` (device summaries are sufficient here; full device details are for Epic 8 or `get_device_details`).
101+
* Real-time event streaming of track changes (these tools are poll/request-response).

0 commit comments

Comments
 (0)