@mcptoolshop/pianoai 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of @mcptoolshop/pianoai might be problematic. Click here for more details.
- package/LICENSE +21 -0
- package/README.es.md +253 -0
- package/README.fr.md +253 -0
- package/README.hi.md +253 -0
- package/README.it.md +253 -0
- package/README.ja.md +253 -0
- package/README.md +253 -0
- package/README.pt-BR.md +253 -0
- package/README.zh.md +253 -0
- package/dist/cli.d.ts +3 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +294 -0
- package/dist/cli.js.map +1 -0
- package/dist/index.d.ts +10 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +21 -0
- package/dist/index.js.map +1 -0
- package/dist/mcp-server.d.ts +3 -0
- package/dist/mcp-server.d.ts.map +1 -0
- package/dist/mcp-server.js +324 -0
- package/dist/mcp-server.js.map +1 -0
- package/dist/note-parser.d.ts +69 -0
- package/dist/note-parser.d.ts.map +1 -0
- package/dist/note-parser.js +172 -0
- package/dist/note-parser.js.map +1 -0
- package/dist/session.d.ts +101 -0
- package/dist/session.d.ts.map +1 -0
- package/dist/session.js +339 -0
- package/dist/session.js.map +1 -0
- package/dist/smoke.d.ts +2 -0
- package/dist/smoke.d.ts.map +1 -0
- package/dist/smoke.js +207 -0
- package/dist/smoke.js.map +1 -0
- package/dist/teaching.d.ts +106 -0
- package/dist/teaching.d.ts.map +1 -0
- package/dist/teaching.js +269 -0
- package/dist/teaching.js.map +1 -0
- package/dist/types.d.ts +206 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +22 -0
- package/dist/types.js.map +1 -0
- package/dist/vmpk.d.ts +21 -0
- package/dist/vmpk.d.ts.map +1 -0
- package/dist/vmpk.js +185 -0
- package/dist/vmpk.js.map +1 -0
- package/logo.svg +10 -0
- package/package.json +69 -0
package/README.hi.md
ADDED
|
@@ -0,0 +1,253 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="README.md">English</a> | <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <strong>हिन्दी</strong> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português</a>
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<p align="center">
|
|
6
|
+
<img src="logo.svg" alt="PianoAI लोगो" width="180" />
|
|
7
|
+
</p>
|
|
8
|
+
|
|
9
|
+
<h1 align="center">PianoAI</h1>
|
|
10
|
+
|
|
11
|
+
<p align="center">
|
|
12
|
+
AI-संचालित पियानो शिक्षण के लिए MCP सर्वर + CLI — MIDI के माध्यम से VMPK पर बजाता है और वॉइस फीडबैक देता है।
|
|
13
|
+
</p>
|
|
14
|
+
|
|
15
|
+
[](https://github.com/mcp-tool-shop-org/pianoai)
|
|
16
|
+
[](https://github.com/mcp-tool-shop-org/pianoai)
|
|
17
|
+
[](https://github.com/mcp-tool-shop-org/pianoai)
|
|
18
|
+
[-blue)](https://github.com/mcp-tool-shop-org/ai-music-sheets)
|
|
19
|
+
|
|
20
|
+
## यह क्या है?
|
|
21
|
+
|
|
22
|
+
एक TypeScript CLI और MCP सर्वर जो [ai-music-sheets](https://github.com/mcp-tool-shop-org/ai-music-sheets) से पियानो गाने लोड करता है, उन्हें MIDI में पार्स करता है, और वर्चुअल MIDI पोर्ट के माध्यम से [VMPK](https://vmpk.sourceforge.io/) पर बजाता है। टीचिंग इंजन मेजर बाउंड्री और मुख्य क्षणों पर इंटरजेक्शन फायर करता है, जिससे एक LLM वॉइस और aside फीडबैक के साथ लाइव पियानो शिक्षक की भूमिका निभा सकता है।
|
|
23
|
+
|
|
24
|
+
## विशेषताएँ
|
|
25
|
+
|
|
26
|
+
- **4 प्लेबैक मोड** — full, measure-by-measure, hands separate, loop
|
|
27
|
+
- **स्पीड कंट्रोल** — 0.5x धीमे अभ्यास से 2x तेज़ प्लेबैक तक, टेम्पो ओवरराइड के साथ स्टैक होता है
|
|
28
|
+
- **प्रगति ट्रैकिंग** — प्रतिशत माइलस्टोन या प्रति-मेजर पर कॉन्फ़िगर करने योग्य कॉलबैक
|
|
29
|
+
- **7 टीचिंग हुक** — console, silent, recording, callback, voice, aside, compose
|
|
30
|
+
- **वॉइस फीडबैक** — mcp-voice-soundboard इंटीग्रेशन के लिए `VoiceDirective` आउटपुट
|
|
31
|
+
- **Aside इंटरजेक्शन** — mcp-aside इनबॉक्स के लिए `AsideDirective` आउटपुट
|
|
32
|
+
- **सुरक्षित पार्सिंग** — खराब नोट्स एकत्रित `ParseWarning` के साथ सुचारू रूप से स्किप होते हैं
|
|
33
|
+
- **7 MCP टूल** — LLM के लिए रजिस्ट्री, टीचिंग नोट्स, और गाने की सिफारिशें उपलब्ध कराते हैं
|
|
34
|
+
- **नोट पार्सर** — साइंटिफिक पिच नोटेशन से MIDI और वापस
|
|
35
|
+
- **मॉक कनेक्टर** — MIDI हार्डवेयर के बिना पूर्ण टेस्ट कवरेज
|
|
36
|
+
|
|
37
|
+
## पूर्वापेक्षाएँ
|
|
38
|
+
|
|
39
|
+
1. **[loopMIDI](https://www.tobias-erichsen.de/software/loopmidi.html)** — एक वर्चुअल MIDI पोर्ट बनाएँ (जैसे, "loopMIDI Port")
|
|
40
|
+
2. **[VMPK](https://vmpk.sourceforge.io/)** — MIDI इनपुट को अपने loopMIDI पोर्ट पर सेट करें
|
|
41
|
+
3. **Node.js 18+**
|
|
42
|
+
|
|
43
|
+
## इंस्टॉल
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
npm install -g @mcptoolshop/pianoai
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## त्वरित प्रारंभ
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
# सभी गाने सूचीबद्ध करें
|
|
53
|
+
pianai list
|
|
54
|
+
|
|
55
|
+
# गाने का विवरण + टीचिंग नोट्स देखें
|
|
56
|
+
pianai info moonlight-sonata-mvt1
|
|
57
|
+
|
|
58
|
+
# VMPK के माध्यम से गाना बजाएँ
|
|
59
|
+
pianai play let-it-be
|
|
60
|
+
|
|
61
|
+
# टेम्पो ओवरराइड के साथ बजाएँ
|
|
62
|
+
pianai play basic-12-bar-blues --tempo 80
|
|
63
|
+
|
|
64
|
+
# मेजर-दर-मेजर चरणबद्ध तरीके से चलें
|
|
65
|
+
pianai play autumn-leaves --mode measure
|
|
66
|
+
|
|
67
|
+
# आधी गति से अभ्यास
|
|
68
|
+
pianai play moonlight-sonata-mvt1 --speed 0.5
|
|
69
|
+
|
|
70
|
+
# धीमा हैंड्स-सेपरेट अभ्यास
|
|
71
|
+
pianai play dream-on --speed 0.75 --mode hands
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## MCP सर्वर
|
|
75
|
+
|
|
76
|
+
MCP सर्वर LLM इंटीग्रेशन के लिए 7 टूल उपलब्ध कराता है:
|
|
77
|
+
|
|
78
|
+
| टूल | विवरण |
|
|
79
|
+
|------|--------|
|
|
80
|
+
| `list_songs` | शैली, कठिनाई, या क्वेरी के अनुसार गाने ब्राउज़/खोजें |
|
|
81
|
+
| `song_info` | पूर्ण संगीत भाषा, शिक्षण लक्ष्य, अभ्यास सुझाव प्राप्त करें |
|
|
82
|
+
| `registry_stats` | शैली और कठिनाई के अनुसार गानों की गिनती |
|
|
83
|
+
| `teaching_note` | प्रति-मेजर टीचिंग नोट, फिंगरिंग, डायनामिक्स |
|
|
84
|
+
| `suggest_song` | मानदंडों के आधार पर सिफारिश प्राप्त करें |
|
|
85
|
+
| `list_measures` | टीचिंग नोट्स + पार्स चेतावनियों के साथ मेजर का अवलोकन |
|
|
86
|
+
| `practice_setup` | किसी गाने के लिए स्पीड, मोड, और वॉइस सेटिंग्स सुझाएँ |
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
# MCP सर्वर शुरू करें (stdio ट्रांसपोर्ट)
|
|
90
|
+
pnpm mcp
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### Claude Desktop कॉन्फ़िगरेशन
|
|
94
|
+
|
|
95
|
+
```json
|
|
96
|
+
{
|
|
97
|
+
"mcpServers": {
|
|
98
|
+
"pianai": {
|
|
99
|
+
"command": "pianai-mcp"
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
## CLI कमांड
|
|
106
|
+
|
|
107
|
+
| कमांड | विवरण |
|
|
108
|
+
|--------|--------|
|
|
109
|
+
| `list [--genre <genre>]` | उपलब्ध गाने सूचीबद्ध करें, वैकल्पिक रूप से शैली द्वारा फ़िल्टर |
|
|
110
|
+
| `info <song-id>` | गाने का विवरण दिखाएँ: संगीत भाषा, टीचिंग नोट्स, संरचना |
|
|
111
|
+
| `play <song-id> [opts]` | MIDI के माध्यम से VMPK पर गाना बजाएँ |
|
|
112
|
+
| `stats` | रजिस्ट्री आँकड़े (गाने, शैलियाँ, मेजर) |
|
|
113
|
+
| `ports` | उपलब्ध MIDI आउटपुट पोर्ट सूचीबद्ध करें |
|
|
114
|
+
| `help` | उपयोग जानकारी दिखाएँ |
|
|
115
|
+
|
|
116
|
+
### प्ले विकल्प
|
|
117
|
+
|
|
118
|
+
| फ़्लैग | विवरण |
|
|
119
|
+
|--------|--------|
|
|
120
|
+
| `--port <name>` | MIDI पोर्ट नाम (डिफ़ॉल्ट: loopMIDI ऑटो-डिटेक्ट) |
|
|
121
|
+
| `--tempo <bpm>` | गाने के डिफ़ॉल्ट टेम्पो को ओवरराइड करें (10-400 BPM) |
|
|
122
|
+
| `--speed <mult>` | स्पीड मल्टीप्लायर: 0.5 = आधा, 1.0 = सामान्य, 2.0 = दोगुना |
|
|
123
|
+
| `--mode <mode>` | प्लेबैक मोड: `full`, `measure`, `hands`, `loop` |
|
|
124
|
+
|
|
125
|
+
## टीचिंग इंजन
|
|
126
|
+
|
|
127
|
+
टीचिंग इंजन प्लेबैक के दौरान हुक फायर करता है। 7 हुक इम्प्लीमेंटेशन हर उपयोग मामले को कवर करते हैं:
|
|
128
|
+
|
|
129
|
+
| हुक | उपयोग मामला |
|
|
130
|
+
|------|-------------|
|
|
131
|
+
| `createConsoleTeachingHook()` | CLI — कंसोल पर मेजर, मोमेंट्स, कम्प्लीशन लॉग करता है |
|
|
132
|
+
| `createSilentTeachingHook()` | टेस्टिंग — नो-ऑप |
|
|
133
|
+
| `createRecordingTeachingHook()` | टेस्टिंग — असर्शन के लिए इवेंट रिकॉर्ड करता है |
|
|
134
|
+
| `createCallbackTeachingHook(cb)` | कस्टम — किसी भी async कॉलबैक पर रूट करें |
|
|
135
|
+
| `createVoiceTeachingHook(sink)` | वॉइस — mcp-voice-soundboard के लिए `VoiceDirective` उत्पन्न करता है |
|
|
136
|
+
| `createAsideTeachingHook(sink)` | Aside — mcp-aside इनबॉक्स के लिए `AsideDirective` उत्पन्न करता है |
|
|
137
|
+
| `composeTeachingHooks(...hooks)` | मल्टी — क्रमिक रूप से कई हुक पर डिस्पैच करता है |
|
|
138
|
+
|
|
139
|
+
### वॉइस फीडबैक
|
|
140
|
+
|
|
141
|
+
```typescript
|
|
142
|
+
import { createSession, createVoiceTeachingHook } from "@mcptoolshop/pianoai";
|
|
143
|
+
import { getSong } from "ai-music-sheets";
|
|
144
|
+
|
|
145
|
+
const voiceHook = createVoiceTeachingHook(
|
|
146
|
+
async (directive) => {
|
|
147
|
+
// mcp-voice-soundboard के voice_speak पर रूट करें
|
|
148
|
+
console.log(`[Voice] ${directive.text}`);
|
|
149
|
+
},
|
|
150
|
+
{ voice: "narrator", speechSpeed: 0.9 }
|
|
151
|
+
);
|
|
152
|
+
|
|
153
|
+
const session = createSession(getSong("moonlight-sonata-mvt1")!, connector, {
|
|
154
|
+
teachingHook: voiceHook,
|
|
155
|
+
speed: 0.5, // आधी गति से अभ्यास
|
|
156
|
+
});
|
|
157
|
+
|
|
158
|
+
await session.play();
|
|
159
|
+
// voiceHook.directives → सभी वॉइस निर्देश जो फायर किए गए
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
### हुक कंपोज़ करना
|
|
163
|
+
|
|
164
|
+
```typescript
|
|
165
|
+
import {
|
|
166
|
+
createVoiceTeachingHook,
|
|
167
|
+
createAsideTeachingHook,
|
|
168
|
+
createRecordingTeachingHook,
|
|
169
|
+
composeTeachingHooks,
|
|
170
|
+
} from "@mcptoolshop/pianoai";
|
|
171
|
+
|
|
172
|
+
// तीनों हर इवेंट पर फायर होते हैं
|
|
173
|
+
const composed = composeTeachingHooks(
|
|
174
|
+
createVoiceTeachingHook(voiceSink),
|
|
175
|
+
createAsideTeachingHook(asideSink),
|
|
176
|
+
createRecordingTeachingHook()
|
|
177
|
+
);
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
## प्रोग्रामेटिक API
|
|
181
|
+
|
|
182
|
+
```typescript
|
|
183
|
+
import { getSong } from "ai-music-sheets";
|
|
184
|
+
import { createSession, createVmpkConnector } from "@mcptoolshop/pianoai";
|
|
185
|
+
|
|
186
|
+
const connector = createVmpkConnector({ portName: /loop/i });
|
|
187
|
+
await connector.connect();
|
|
188
|
+
|
|
189
|
+
const song = getSong("autumn-leaves")!;
|
|
190
|
+
const session = createSession(song, connector, {
|
|
191
|
+
mode: "measure",
|
|
192
|
+
tempo: 100,
|
|
193
|
+
speed: 0.75, // अभ्यास के लिए 75% गति
|
|
194
|
+
onProgress: (p) => console.log(p.percent), // "25%", "50%", आदि
|
|
195
|
+
});
|
|
196
|
+
|
|
197
|
+
await session.play(); // एक मेजर बजाता है, रुकता है
|
|
198
|
+
session.next(); // अगले मेजर पर आगे बढ़ें
|
|
199
|
+
await session.play(); // अगला मेजर बजाएँ
|
|
200
|
+
session.setSpeed(1.0); // सामान्य गति पर वापस
|
|
201
|
+
await session.play(); // पूर्ण गति पर अगला मेजर बजाएँ
|
|
202
|
+
session.stop(); // रोकें और रीसेट करें
|
|
203
|
+
|
|
204
|
+
// किसी भी पार्स चेतावनी की जाँच करें (गाने के डेटा में खराब नोट्स)
|
|
205
|
+
if (session.parseWarnings.length > 0) {
|
|
206
|
+
console.warn("कुछ नोट्स पार्स नहीं हो सके:", session.parseWarnings);
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
await connector.disconnect();
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
## आर्किटेक्चर
|
|
213
|
+
|
|
214
|
+
```
|
|
215
|
+
ai-music-sheets (लाइब्रेरी) pianai (रनटाइम)
|
|
216
|
+
┌──────────────────────┐ ┌────────────────────────────────┐
|
|
217
|
+
│ SongEntry (हाइब्रिड) │────────→│ Note Parser (सुरक्षित + सख्त) │
|
|
218
|
+
│ Registry (खोज) │ │ Session Engine (स्पीड+प्रगति) │
|
|
219
|
+
│ 10 गाने, 10 शैलियाँ │ │ Teaching Engine (7 हुक) │
|
|
220
|
+
└──────────────────────┘ │ VMPK Connector (JZZ) │
|
|
221
|
+
│ MCP Server (7 टूल) │
|
|
222
|
+
│ CLI (प्रोग्रेस बार + वॉइस) │
|
|
223
|
+
└─────────┬──────────────────────┘
|
|
224
|
+
│ MIDI
|
|
225
|
+
▼
|
|
226
|
+
┌─────────────────┐
|
|
227
|
+
│ loopMIDI → VMPK │
|
|
228
|
+
└─────────────────┘
|
|
229
|
+
|
|
230
|
+
टीचिंग हुक रूटिंग:
|
|
231
|
+
Session → TeachingHook → VoiceDirective → mcp-voice-soundboard
|
|
232
|
+
→ AsideDirective → mcp-aside इनबॉक्स
|
|
233
|
+
→ Console log → CLI टर्मिनल
|
|
234
|
+
→ Recording → टेस्ट असर्शन
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
## टेस्टिंग
|
|
238
|
+
|
|
239
|
+
```bash
|
|
240
|
+
pnpm test # 121 Vitest टेस्ट (पार्सर + सेशन + टीचिंग + वॉइस + aside)
|
|
241
|
+
pnpm smoke # 20 स्मोक टेस्ट (इंटीग्रेशन, MIDI आवश्यक नहीं)
|
|
242
|
+
pnpm typecheck # tsc --noEmit
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
मॉक VMPK कनेक्टर (`createMockVmpkConnector`) हार्डवेयर के बिना सभी MIDI इवेंट रिकॉर्ड करता है, जिससे पूर्ण टेस्ट कवरेज संभव होता है। सुरक्षित पार्सिंग फ़ंक्शन (`safeParseMeasure`) थ्रो करने के बजाय `ParseWarning` ऑब्जेक्ट एकत्र करते हैं, ताकि अगर किसी गाने में गलत नोट्स हों तो प्लेबैक सुचारू रूप से जारी रहे।
|
|
246
|
+
|
|
247
|
+
## संबंधित
|
|
248
|
+
|
|
249
|
+
- **[ai-music-sheets](https://github.com/mcp-tool-shop-org/ai-music-sheets)** — गानों की लाइब्रेरी: 10 शैलियाँ, हाइब्रिड फॉर्मेट (मेटाडेटा + संगीत भाषा + कोड-रेडी मेजर)
|
|
250
|
+
|
|
251
|
+
## लाइसेंस
|
|
252
|
+
|
|
253
|
+
MIT
|
package/README.it.md
ADDED
|
@@ -0,0 +1,253 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="README.md">English</a> | <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <strong>Italiano</strong> | <a href="README.pt-BR.md">Português</a>
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<p align="center">
|
|
6
|
+
<img src="logo.svg" alt="PianoAI logo" width="180" />
|
|
7
|
+
</p>
|
|
8
|
+
|
|
9
|
+
<h1 align="center">PianoAI</h1>
|
|
10
|
+
|
|
11
|
+
<p align="center">
|
|
12
|
+
Server MCP + CLI per l'insegnamento del pianoforte con IA — riproduce tramite VMPK via MIDI con feedback vocale.
|
|
13
|
+
</p>
|
|
14
|
+
|
|
15
|
+
[](https://github.com/mcp-tool-shop-org/pianoai)
|
|
16
|
+
[](https://github.com/mcp-tool-shop-org/pianoai)
|
|
17
|
+
[](https://github.com/mcp-tool-shop-org/pianoai)
|
|
18
|
+
[-blue)](https://github.com/mcp-tool-shop-org/ai-music-sheets)
|
|
19
|
+
|
|
20
|
+
## Cos'è questo?
|
|
21
|
+
|
|
22
|
+
Un CLI TypeScript e server MCP che carica brani per pianoforte da [ai-music-sheets](https://github.com/mcp-tool-shop-org/ai-music-sheets), li analizza in MIDI e li riproduce tramite [VMPK](https://vmpk.sourceforge.io/) attraverso una porta MIDI virtuale. Il motore didattico lancia interventi ai confini delle battute e nei momenti chiave, permettendo a un LLM di agire come insegnante di pianoforte dal vivo con feedback vocale e interjection aside.
|
|
23
|
+
|
|
24
|
+
## Funzionalità
|
|
25
|
+
|
|
26
|
+
- **4 modalità di riproduzione** — completa, battuta per battuta, mani separate, loop
|
|
27
|
+
- **Controllo della velocità** — pratica lenta a 0.5x fino a riproduzione veloce a 2x, cumulabile con override del tempo
|
|
28
|
+
- **Tracciamento dei progressi** — callback configurabili a traguardi percentuali o per battuta
|
|
29
|
+
- **7 hook didattici** — console, silent, recording, callback, voice, aside, compose
|
|
30
|
+
- **Feedback vocale** — output `VoiceDirective` per l'integrazione con mcp-voice-soundboard
|
|
31
|
+
- **Interjection aside** — output `AsideDirective` per la inbox di mcp-aside
|
|
32
|
+
- **Parsing sicuro** — le note errate vengono saltate con raccolta di `ParseWarning`
|
|
33
|
+
- **7 strumenti MCP** — espongono registro, note didattiche e raccomandazioni di brani agli LLM
|
|
34
|
+
- **Parser delle note** — notazione scientifica delle altezze da e verso MIDI
|
|
35
|
+
- **Connettore mock** — copertura completa dei test senza hardware MIDI
|
|
36
|
+
|
|
37
|
+
## Prerequisiti
|
|
38
|
+
|
|
39
|
+
1. **[loopMIDI](https://www.tobias-erichsen.de/software/loopmidi.html)** — crea una porta MIDI virtuale (es. "loopMIDI Port")
|
|
40
|
+
2. **[VMPK](https://vmpk.sourceforge.io/)** — imposta l'input MIDI sulla porta loopMIDI
|
|
41
|
+
3. **Node.js 18+**
|
|
42
|
+
|
|
43
|
+
## Installazione
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
npm install -g @mcptoolshop/pianoai
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Avvio Rapido
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
# Elenca tutti i brani
|
|
53
|
+
pianai list
|
|
54
|
+
|
|
55
|
+
# Mostra dettagli del brano + note didattiche
|
|
56
|
+
pianai info moonlight-sonata-mvt1
|
|
57
|
+
|
|
58
|
+
# Riproduci un brano tramite VMPK
|
|
59
|
+
pianai play let-it-be
|
|
60
|
+
|
|
61
|
+
# Riproduci con override del tempo
|
|
62
|
+
pianai play basic-12-bar-blues --tempo 80
|
|
63
|
+
|
|
64
|
+
# Avanza battuta per battuta
|
|
65
|
+
pianai play autumn-leaves --mode measure
|
|
66
|
+
|
|
67
|
+
# Pratica a metà velocità
|
|
68
|
+
pianai play moonlight-sonata-mvt1 --speed 0.5
|
|
69
|
+
|
|
70
|
+
# Pratica lenta a mani separate
|
|
71
|
+
pianai play dream-on --speed 0.75 --mode hands
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Server MCP
|
|
75
|
+
|
|
76
|
+
Il server MCP espone 7 strumenti per l'integrazione con LLM:
|
|
77
|
+
|
|
78
|
+
| Strumento | Descrizione |
|
|
79
|
+
|-----------|-------------|
|
|
80
|
+
| `list_songs` | Sfoglia/cerca brani per genere, difficoltà o query |
|
|
81
|
+
| `song_info` | Ottieni linguaggio musicale completo, obiettivi didattici, suggerimenti di pratica |
|
|
82
|
+
| `registry_stats` | Conteggio brani per genere e difficoltà |
|
|
83
|
+
| `teaching_note` | Nota didattica per battuta, diteggiatura, dinamiche |
|
|
84
|
+
| `suggest_song` | Ottieni una raccomandazione basata su criteri |
|
|
85
|
+
| `list_measures` | Panoramica delle battute con note didattiche + avvisi di parsing |
|
|
86
|
+
| `practice_setup` | Suggerisci velocità, modalità e impostazioni vocali per un brano |
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
# Avvia il server MCP (trasporto stdio)
|
|
90
|
+
pnpm mcp
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### Configurazione Claude Desktop
|
|
94
|
+
|
|
95
|
+
```json
|
|
96
|
+
{
|
|
97
|
+
"mcpServers": {
|
|
98
|
+
"pianai": {
|
|
99
|
+
"command": "pianai-mcp"
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
## Comandi CLI
|
|
106
|
+
|
|
107
|
+
| Comando | Descrizione |
|
|
108
|
+
|---------|-------------|
|
|
109
|
+
| `list [--genre <genre>]` | Elenca i brani disponibili, con filtro opzionale per genere |
|
|
110
|
+
| `info <song-id>` | Mostra dettagli del brano: linguaggio musicale, note didattiche, struttura |
|
|
111
|
+
| `play <song-id> [opts]` | Riproduci un brano tramite VMPK via MIDI |
|
|
112
|
+
| `stats` | Statistiche del registro (brani, generi, battute) |
|
|
113
|
+
| `ports` | Elenca le porte di output MIDI disponibili |
|
|
114
|
+
| `help` | Mostra le informazioni d'uso |
|
|
115
|
+
|
|
116
|
+
### Opzioni di Riproduzione
|
|
117
|
+
|
|
118
|
+
| Flag | Descrizione |
|
|
119
|
+
|------|-------------|
|
|
120
|
+
| `--port <name>` | Nome della porta MIDI (predefinito: rilevamento automatico loopMIDI) |
|
|
121
|
+
| `--tempo <bpm>` | Override del tempo predefinito del brano (10-400 BPM) |
|
|
122
|
+
| `--speed <mult>` | Moltiplicatore di velocità: 0.5 = metà, 1.0 = normale, 2.0 = doppio |
|
|
123
|
+
| `--mode <mode>` | Modalità di riproduzione: `full`, `measure`, `hands`, `loop` |
|
|
124
|
+
|
|
125
|
+
## Motore Didattico
|
|
126
|
+
|
|
127
|
+
Il motore didattico attiva hook durante la riproduzione. 7 implementazioni di hook coprono ogni caso d'uso:
|
|
128
|
+
|
|
129
|
+
| Hook | Caso d'uso |
|
|
130
|
+
|------|------------|
|
|
131
|
+
| `createConsoleTeachingHook()` | CLI — registra battute, momenti, completamento nella console |
|
|
132
|
+
| `createSilentTeachingHook()` | Test — nessuna operazione |
|
|
133
|
+
| `createRecordingTeachingHook()` | Test — registra gli eventi per le asserzioni |
|
|
134
|
+
| `createCallbackTeachingHook(cb)` | Personalizzato — indirizza verso qualsiasi callback asincrono |
|
|
135
|
+
| `createVoiceTeachingHook(sink)` | Voce — produce `VoiceDirective` per mcp-voice-soundboard |
|
|
136
|
+
| `createAsideTeachingHook(sink)` | Aside — produce `AsideDirective` per la inbox di mcp-aside |
|
|
137
|
+
| `composeTeachingHooks(...hooks)` | Multi — invia a più hook in serie |
|
|
138
|
+
|
|
139
|
+
### Feedback vocale
|
|
140
|
+
|
|
141
|
+
```typescript
|
|
142
|
+
import { createSession, createVoiceTeachingHook } from "@mcptoolshop/pianoai";
|
|
143
|
+
import { getSong } from "ai-music-sheets";
|
|
144
|
+
|
|
145
|
+
const voiceHook = createVoiceTeachingHook(
|
|
146
|
+
async (directive) => {
|
|
147
|
+
// Indirizza verso voice_speak di mcp-voice-soundboard
|
|
148
|
+
console.log(`[Voice] ${directive.text}`);
|
|
149
|
+
},
|
|
150
|
+
{ voice: "narrator", speechSpeed: 0.9 }
|
|
151
|
+
);
|
|
152
|
+
|
|
153
|
+
const session = createSession(getSong("moonlight-sonata-mvt1")!, connector, {
|
|
154
|
+
teachingHook: voiceHook,
|
|
155
|
+
speed: 0.5, // pratica a metà velocità
|
|
156
|
+
});
|
|
157
|
+
|
|
158
|
+
await session.play();
|
|
159
|
+
// voiceHook.directives → tutte le istruzioni vocali che sono state attivate
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
### Composizione degli hook
|
|
163
|
+
|
|
164
|
+
```typescript
|
|
165
|
+
import {
|
|
166
|
+
createVoiceTeachingHook,
|
|
167
|
+
createAsideTeachingHook,
|
|
168
|
+
createRecordingTeachingHook,
|
|
169
|
+
composeTeachingHooks,
|
|
170
|
+
} from "@mcptoolshop/pianoai";
|
|
171
|
+
|
|
172
|
+
// Tutti e tre si attivano ad ogni evento
|
|
173
|
+
const composed = composeTeachingHooks(
|
|
174
|
+
createVoiceTeachingHook(voiceSink),
|
|
175
|
+
createAsideTeachingHook(asideSink),
|
|
176
|
+
createRecordingTeachingHook()
|
|
177
|
+
);
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
## API Programmatica
|
|
181
|
+
|
|
182
|
+
```typescript
|
|
183
|
+
import { getSong } from "ai-music-sheets";
|
|
184
|
+
import { createSession, createVmpkConnector } from "@mcptoolshop/pianoai";
|
|
185
|
+
|
|
186
|
+
const connector = createVmpkConnector({ portName: /loop/i });
|
|
187
|
+
await connector.connect();
|
|
188
|
+
|
|
189
|
+
const song = getSong("autumn-leaves")!;
|
|
190
|
+
const session = createSession(song, connector, {
|
|
191
|
+
mode: "measure",
|
|
192
|
+
tempo: 100,
|
|
193
|
+
speed: 0.75, // 75% di velocità per la pratica
|
|
194
|
+
onProgress: (p) => console.log(p.percent), // "25%", "50%", ecc.
|
|
195
|
+
});
|
|
196
|
+
|
|
197
|
+
await session.play(); // riproduce una battuta, poi pausa
|
|
198
|
+
session.next(); // avanza alla battuta successiva
|
|
199
|
+
await session.play(); // riproduce la battuta successiva
|
|
200
|
+
session.setSpeed(1.0); // torna alla velocità normale
|
|
201
|
+
await session.play(); // riproduce la battuta successiva a piena velocità
|
|
202
|
+
session.stop(); // ferma e ripristina
|
|
203
|
+
|
|
204
|
+
// Controlla eventuali avvisi di parsing (note errate nei dati del brano)
|
|
205
|
+
if (session.parseWarnings.length > 0) {
|
|
206
|
+
console.warn("Alcune note non sono state analizzate:", session.parseWarnings);
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
await connector.disconnect();
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
## Architettura
|
|
213
|
+
|
|
214
|
+
```
|
|
215
|
+
ai-music-sheets (libreria) pianai (runtime)
|
|
216
|
+
┌──────────────────────┐ ┌────────────────────────────────┐
|
|
217
|
+
│ SongEntry (ibrido) │────────→│ Parser Note (sicuro + rigoroso)│
|
|
218
|
+
│ Registry (ricerca) │ │ Motore Sessione (veloc+progr) │
|
|
219
|
+
│ 10 brani, 10 generi │ │ Motore Didattico (7 hook) │
|
|
220
|
+
└──────────────────────┘ │ Connettore VMPK (JZZ) │
|
|
221
|
+
│ Server MCP (7 strumenti) │
|
|
222
|
+
│ CLI (barra progresso + voce) │
|
|
223
|
+
└─────────┬──────────────────────┘
|
|
224
|
+
│ MIDI
|
|
225
|
+
▼
|
|
226
|
+
┌─────────────────┐
|
|
227
|
+
│ loopMIDI → VMPK │
|
|
228
|
+
└─────────────────┘
|
|
229
|
+
|
|
230
|
+
Instradamento hook didattici:
|
|
231
|
+
Sessione → TeachingHook → VoiceDirective → mcp-voice-soundboard
|
|
232
|
+
→ AsideDirective → inbox mcp-aside
|
|
233
|
+
→ Log console → terminale CLI
|
|
234
|
+
→ Recording → asserzioni test
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
## Test
|
|
238
|
+
|
|
239
|
+
```bash
|
|
240
|
+
pnpm test # 121 test Vitest (parser + sessione + didattica + voce + aside)
|
|
241
|
+
pnpm smoke # 20 smoke test (integrazione, nessun MIDI necessario)
|
|
242
|
+
pnpm typecheck # tsc --noEmit
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
Il connettore VMPK mock (`createMockVmpkConnector`) registra tutti gli eventi MIDI senza hardware, garantendo copertura completa dei test. Le funzioni di parsing sicuro (`safeParseMeasure`) raccolgono oggetti `ParseWarning` invece di lanciare eccezioni, così la riproduzione continua senza interruzioni anche se un brano contiene note malformate.
|
|
246
|
+
|
|
247
|
+
## Correlati
|
|
248
|
+
|
|
249
|
+
- **[ai-music-sheets](https://github.com/mcp-tool-shop-org/ai-music-sheets)** — La libreria di brani: 10 generi, formato ibrido (metadati + linguaggio musicale + battute pronte per il codice)
|
|
250
|
+
|
|
251
|
+
## Licenza
|
|
252
|
+
|
|
253
|
+
MIT
|