@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.

Files changed (47) hide show
  1. package/LICENSE +21 -0
  2. package/README.es.md +253 -0
  3. package/README.fr.md +253 -0
  4. package/README.hi.md +253 -0
  5. package/README.it.md +253 -0
  6. package/README.ja.md +253 -0
  7. package/README.md +253 -0
  8. package/README.pt-BR.md +253 -0
  9. package/README.zh.md +253 -0
  10. package/dist/cli.d.ts +3 -0
  11. package/dist/cli.d.ts.map +1 -0
  12. package/dist/cli.js +294 -0
  13. package/dist/cli.js.map +1 -0
  14. package/dist/index.d.ts +10 -0
  15. package/dist/index.d.ts.map +1 -0
  16. package/dist/index.js +21 -0
  17. package/dist/index.js.map +1 -0
  18. package/dist/mcp-server.d.ts +3 -0
  19. package/dist/mcp-server.d.ts.map +1 -0
  20. package/dist/mcp-server.js +324 -0
  21. package/dist/mcp-server.js.map +1 -0
  22. package/dist/note-parser.d.ts +69 -0
  23. package/dist/note-parser.d.ts.map +1 -0
  24. package/dist/note-parser.js +172 -0
  25. package/dist/note-parser.js.map +1 -0
  26. package/dist/session.d.ts +101 -0
  27. package/dist/session.d.ts.map +1 -0
  28. package/dist/session.js +339 -0
  29. package/dist/session.js.map +1 -0
  30. package/dist/smoke.d.ts +2 -0
  31. package/dist/smoke.d.ts.map +1 -0
  32. package/dist/smoke.js +207 -0
  33. package/dist/smoke.js.map +1 -0
  34. package/dist/teaching.d.ts +106 -0
  35. package/dist/teaching.d.ts.map +1 -0
  36. package/dist/teaching.js +269 -0
  37. package/dist/teaching.js.map +1 -0
  38. package/dist/types.d.ts +206 -0
  39. package/dist/types.d.ts.map +1 -0
  40. package/dist/types.js +22 -0
  41. package/dist/types.js.map +1 -0
  42. package/dist/vmpk.d.ts +21 -0
  43. package/dist/vmpk.d.ts.map +1 -0
  44. package/dist/vmpk.js +185 -0
  45. package/dist/vmpk.js.map +1 -0
  46. package/logo.svg +10 -0
  47. 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
+ [![Tests](https://img.shields.io/badge/tests-121_passing-brightgreen)](https://github.com/mcp-tool-shop-org/pianoai)
16
+ [![Smoke](https://img.shields.io/badge/smoke-20_passing-brightgreen)](https://github.com/mcp-tool-shop-org/pianoai)
17
+ [![MCP Tools](https://img.shields.io/badge/MCP_tools-7-purple)](https://github.com/mcp-tool-shop-org/pianoai)
18
+ [![Songs](https://img.shields.io/badge/songs-10_(via_ai--music--sheets)-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
+ [![Tests](https://img.shields.io/badge/tests-121_passing-brightgreen)](https://github.com/mcp-tool-shop-org/pianoai)
16
+ [![Smoke](https://img.shields.io/badge/smoke-20_passing-brightgreen)](https://github.com/mcp-tool-shop-org/pianoai)
17
+ [![MCP Tools](https://img.shields.io/badge/MCP_tools-7-purple)](https://github.com/mcp-tool-shop-org/pianoai)
18
+ [![Songs](https://img.shields.io/badge/songs-10_(via_ai--music--sheets)-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