@mcptoolshop/ai_jam_session 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.es.md

@@ -0,0 +1,212 @@
+<p align="center"><a href="README.md">English</a> | <a href="README.ja.md">日本語</a> | <strong>Español</strong> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português</a></p>
+
+<p align="center">
+  <img src="logo.png" alt="PianoAI logo" width="180" />
+</p>
+
+<h1 align="center">PianoAI</h1>
+
+<p align="center">
+  Pianista de IA con motor de audio integrado y biblioteca de 100 canciones. Servidor MCP para Claude, CLI para humanos.
+</p>
+
+[![MCP Tools](https://img.shields.io/badge/MCP_tools-15-purple)](https://github.com/mcp-tool-shop-org/ai_jam_session)
+[![Songs](https://img.shields.io/badge/songs-100_built--in-blue)](https://github.com/mcp-tool-shop-org/ai_jam_session)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](https://github.com/mcp-tool-shop-org/ai_jam_session)
+
+## Que es esto?
+
+Un piano que Claude puede tocar. PianoAI es un servidor MCP con un motor de audio integrado -- reproduce a traves de tus altavoces, sin necesidad de software externo. Claude navega una biblioteca de 100 canciones en 10 generos, elige canciones, las ensena y hace jam con ellas. Tambien funciona como CLI independiente.
+
+## Caracteristicas
+
+- **Motor de piano integrado** -- audio basado en muestras mediante `node-web-audio-api`, reproduce a traves de los altavoces
+- **Biblioteca de 100 canciones** -- clasica, jazz, pop, blues, rock, R&B, latina, cine, ragtime, new-age
+- **AI Jam Session** -- Claude analiza los acordes y la melodia de una cancion, luego crea su propia interpretacion
+- **Soporte de archivos MIDI** -- reproduce cualquier archivo `.mid`: `ai-jam-session play song.mid`
+- **Sistema de ensenanza** -- notas didacticas por compas, descripciones del lenguaje musical, recomendaciones de practica
+- **4 modos de reproduccion** -- completo, compas por compas, manos separadas, bucle
+- **Control de velocidad** -- practica lenta a 0.5x hasta rapida a 4x
+- **Controles en tiempo real** -- pausa, reanudacion, cambio de velocidad durante la reproduccion
+- **15 herramientas MCP** -- reproducir, explorar, ensenar, improvisar, importar -- todo a traves del protocolo MCP
+- **Agrega tus propias canciones** -- la herramienta `add_song` acepta JSON de SongEntry, `import_midi` convierte archivos MIDI
+- **Salida MIDI opcional** -- envia a software externo con la bandera `--midi` (requiere loopMIDI + VMPK)
+
+## Instalacion
+
+```bash
+npm install -g @mcptoolshop/ai_jam_session
+```
+
+Requiere **Node.js 18+**. Eso es todo -- sin controladores MIDI, sin puertos virtuales, sin software externo.
+
+## Inicio rapido
+
+```bash
+# Reproducir una cancion integrada
+ai-jam-session play let-it-be
+
+# Reproducir un archivo MIDI
+ai-jam-session play path/to/song.mid
+
+# Practica a media velocidad
+ai-jam-session play moonlight-sonata-mvt1 --speed 0.5
+
+# Listar todas las canciones integradas
+ai-jam-session list
+
+# Mostrar detalles de la cancion + notas didacticas
+ai-jam-session info autumn-leaves
+```
+
+### Opciones de reproduccion
+
+| Bandera | Descripcion |
+|---------|-------------|
+| `--speed <mult>` | Multiplicador de velocidad: 0.5 = mitad, 1.0 = normal, 2.0 = doble |
+| `--tempo <bpm>` | Anular el tempo predeterminado de la cancion (10-400 BPM) |
+| `--mode <mode>` | Modo de reproduccion: `full`, `measure`, `hands`, `loop` |
+| `--midi` | Enviar a software MIDI externo en lugar del motor integrado |
+
+## Servidor MCP
+
+El servidor MCP expone 15 herramientas para integracion con LLM:
+
+| Herramienta | Descripcion |
+|-------------|-------------|
+| `list_songs` | Explorar/buscar canciones por genero, dificultad o consulta |
+| `song_info` | Lenguaje musical completo, objetivos didacticos, sugerencias de practica |
+| `registry_stats` | Conteo de canciones por genero y dificultad |
+| `teaching_note` | Nota didactica por compas, digitacion, dinamicas |
+| `suggest_song` | Recomendacion basada en criterios |
+| `list_measures` | Vista general de compases con notas didacticas |
+| `practice_setup` | Sugerir velocidad, modo y configuracion para una cancion |
+| `sing_along` | Texto cantable (nombres de notas, solfeo, contorno) por compas |
+| `play_song` | Reproducir una cancion o archivo MIDI a traves de los altavoces |
+| `pause_playback` | Pausar o reanudar la cancion en reproduccion |
+| `set_speed` | Cambiar la velocidad de reproduccion durante la reproduccion |
+| `stop_playback` | Detener la cancion en reproduccion |
+| `ai_jam_session` | Obtener un brief de jam -- acordes, melodia, guia de estilo -- para improvisacion |
+| `add_song` | Agregar una nueva cancion (JSON de SongEntry) a la biblioteca |
+| `import_midi` | Convertir un archivo MIDI en SongEntry y registrarlo |
+
+### AI Jam Session
+
+La herramienta `ai_jam_session` extrae un "brief de jam" estructurado de cualquier cancion: progresion de acordes, contorno melodico y guia de estilo especifica del genero. Claude usa el brief para crear su propia interpretacion.
+
+Dos modos:
+- **Cancion especifica:** `ai_jam_session({ songId: "autumn-leaves", style: "blues" })` -- improvisar sobre Autumn Leaves, estilo blues
+- **Seleccion aleatoria por genero:** `ai_jam_session({ genre: "jazz" })` -- elegir una cancion de jazz al azar e improvisar
+
+Parametros opcionales: `mood` (alegre, melancolico, sonador, etc.), `difficulty`, `measures` (rango como "1-8").
+
+### Configuracion de Claude Desktop / Claude Code
+
+```json
+{
+  "mcpServers": {
+    "pianoai": {
+      "command": "npx",
+      "args": ["-y", "-p", "@mcptoolshop/ai_jam_session", "ai-jam-session-mcp"]
+    }
+  }
+}
+```
+
+### Plugin de Claude Code
+
+PianoAI incluye un plugin de Claude Code que agrega comandos slash y personalidades de agente:
+
+| Comando | Descripcion |
+|---------|-------------|
+| `/pianoai:teach <song>` | Iniciar una sesion de ensenanza estructurada |
+| `/pianoai:practice <song>` | Obtener un plan de practica con recomendaciones de velocidad/modo |
+| `/pianoai:explore [query]` | Explorar la biblioteca de canciones por genero, dificultad o palabra clave |
+| `/pianoai:jam <song or genre>` | Iniciar una sesion de jam -- Claude crea su propia interpretacion |
+
+Dos personalidades de agente:
+- **Profesor de Piano** -- paciente, pedagogico, se adapta al nivel del estudiante
+- **Musico de Jam** -- vibras relajadas de jam band, prioridad al groove, fomenta la experimentacion
+
+## Biblioteca de canciones
+
+100 canciones integradas en 10 generos, 3 niveles de dificultad:
+
+| Genero | Canciones | Ejemplos |
+|--------|-----------|----------|
+| Classical | 10 | Fur Elise, Clair de Lune, Moonlight Sonata, Bach Prelude in C |
+| Jazz | 10 | Autumn Leaves, Take Five, So What, Misty |
+| Pop | 10 | Imagine, Hallelujah, Piano Man, Bohemian Rhapsody |
+| Blues | 10 | Basic 12-Bar, St. Louis Blues, Stormy Monday, Thrill Is Gone |
+| Rock | 10 | Stairway Intro, Hotel California, Rocket Man, Layla Coda |
+| R&B | 10 | Superstition, Georgia On My Mind, Lean On Me, My Girl |
+| Latin | 10 | Girl from Ipanema, Besame Mucho, Oye Como Va, Wave |
+| Film | 11 | Cinema Paradiso, Moon River, Hedwig's Theme, Spirited Away |
+| Ragtime | 9 | The Entertainer, Maple Leaf Rag, Elite Syncopations |
+| New-Age | 10 | River Flows in You, Snowfall, Crystal Stream, Evening Calm |
+
+## API programatica
+
+```typescript
+import { createAudioEngine, parseMidiFile, PlaybackController } from "@mcptoolshop/ai_jam_session";
+
+const connector = createAudioEngine();
+await connector.connect();
+
+const midi = await parseMidiFile("song.mid");
+const controller = new PlaybackController(connector, midi);
+
+controller.on("noteOn", (e) => console.log(`Note: ${e.noteName}`));
+await controller.play({ speed: 0.75 });
+
+controller.pause();
+controller.setSpeed(1.5);
+await controller.resume();
+
+await connector.disconnect();
+```
+
+### Reproducir una cancion integrada
+
+```typescript
+import { getSong, createSession, createAudioEngine } from "@mcptoolshop/ai_jam_session";
+
+const connector = createAudioEngine();
+await connector.connect();
+
+const song = getSong("autumn-leaves")!;
+const session = createSession(song, connector, {
+  mode: "full",
+  speed: 0.75,
+});
+
+await session.play();
+await connector.disconnect();
+```
+
+## Arquitectura
+
+```
+MIDI files (.mid)          Built-in song library (JSON)
+       |                              |
+       v                              v
+  MIDI Parser ──────────────── Note Parser
+       |                              |
+       v                              v
+ MidiPlaybackEngine            SessionController
+       |                              |
+       └──────── PlaybackController ──┘
+                 (real-time events, hooks)
+                        |
+          ┌─────────────┼─────────────┐
+          v             v             v
+     AudioEngine   Teaching Hooks  Progress
+     (speakers)    (per-measure)   (callbacks)
+          |
+          v
+    node-web-audio-api (Rust DSP)
+```
+
+## Licencia
+
+MIT

package/README.fr.md

@@ -0,0 +1,212 @@
+<p align="center"><a href="README.md">English</a> | <a href="README.ja.md">日本語</a> | <a href="README.es.md">Español</a> | <strong>Français</strong> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português</a></p>
+
+<p align="center">
+  <img src="logo.png" alt="Logo PianoAI" width="180" />
+</p>
+
+<h1 align="center">PianoAI</h1>
+
+<p align="center">
+  Piano IA avec moteur audio integre et bibliotheque de 100 morceaux. Serveur MCP pour Claude, CLI pour les humains.
+</p>
+
+[![MCP Tools](https://img.shields.io/badge/MCP_tools-15-purple)](https://github.com/mcp-tool-shop-org/ai_jam_session)
+[![Songs](https://img.shields.io/badge/songs-100_built--in-blue)](https://github.com/mcp-tool-shop-org/ai_jam_session)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](https://github.com/mcp-tool-shop-org/ai_jam_session)
+
+## Qu'est-ce que c'est ?
+
+Un piano que Claude peut jouer. PianoAI est un serveur MCP avec un moteur audio integre -- il joue directement dans vos haut-parleurs, aucun logiciel externe requis. Claude parcourt une bibliotheque de 100 morceaux couvrant 10 genres, choisit des morceaux, les enseigne et improvise dessus. Fonctionne egalement en CLI autonome.
+
+## Fonctionnalites
+
+- **Moteur piano integre** -- audio a base d'echantillons via `node-web-audio-api`, joue dans les haut-parleurs
+- **Bibliotheque de 100 morceaux** -- classique, jazz, pop, blues, rock, R&B, latin, film, ragtime, new-age
+- **AI Jam Session** -- Claude analyse les accords et la melodie d'un morceau, puis cree sa propre interpretation
+- **Support des fichiers MIDI** -- jouez n'importe quel fichier `.mid` : `pianoai play song.mid`
+- **Systeme pedagogique** -- notes d'enseignement par mesure, descriptions du langage musical, recommandations de pratique
+- **4 modes de lecture** -- integral, mesure par mesure, mains separees, boucle
+- **Controle de la vitesse** -- de 0.5x pour la pratique lente jusqu'a 4x rapide
+- **Controles en temps reel** -- pause, reprise, changement de vitesse pendant la lecture
+- **15 outils MCP** -- jouer, parcourir, enseigner, improviser, importer -- le tout via le protocole MCP
+- **Ajoutez vos propres morceaux** -- l'outil `add_song` accepte du JSON SongEntry, `import_midi` convertit les fichiers MIDI
+- **Sortie MIDI optionnelle** -- routage vers un logiciel externe via le flag `--midi` (necessite loopMIDI + VMPK)
+
+## Installation
+
+```bash
+npm install -g @mcptoolshop/ai_jam_session
+```
+
+Necessite **Node.js 18+**. C'est tout -- pas de pilotes MIDI, pas de ports virtuels, pas de logiciel externe.
+
+## Demarrage rapide
+
+```bash
+# Jouer un morceau integre
+ai-jam-session play let-it-be
+
+# Jouer un fichier MIDI
+ai-jam-session play path/to/song.mid
+
+# Pratique a demi-vitesse
+ai-jam-session play moonlight-sonata-mvt1 --speed 0.5
+
+# Lister tous les morceaux integres
+ai-jam-session list
+
+# Afficher les details d'un morceau et les notes pedagogiques
+ai-jam-session info autumn-leaves
+```
+
+### Options de lecture
+
+| Flag | Description |
+|------|-------------|
+| `--speed <mult>` | Multiplicateur de vitesse : 0.5 = moitie, 1.0 = normal, 2.0 = double |
+| `--tempo <bpm>` | Remplacer le tempo par defaut du morceau (10-400 BPM) |
+| `--mode <mode>` | Mode de lecture : `full`, `measure`, `hands`, `loop` |
+| `--midi` | Router vers un logiciel MIDI externe au lieu du moteur integre |
+
+## Serveur MCP
+
+Le serveur MCP expose 15 outils pour l'integration avec les LLM :
+
+| Outil | Description |
+|-------|-------------|
+| `list_songs` | Parcourir/rechercher des morceaux par genre, difficulte ou requete |
+| `song_info` | Langage musical complet, objectifs pedagogiques, suggestions de pratique |
+| `registry_stats` | Nombre de morceaux par genre et difficulte |
+| `teaching_note` | Note pedagogique par mesure, doigte, dynamiques |
+| `suggest_song` | Recommandation basee sur des criteres |
+| `list_measures` | Vue d'ensemble des mesures avec notes pedagogiques |
+| `practice_setup` | Suggestion de vitesse, mode et reglages pour un morceau |
+| `sing_along` | Texte chantable (noms des notes, solfege, contour) par mesure |
+| `play_song` | Jouer un morceau ou un fichier MIDI dans les haut-parleurs |
+| `pause_playback` | Mettre en pause ou reprendre le morceau en cours |
+| `set_speed` | Changer la vitesse de lecture pendant la lecture |
+| `stop_playback` | Arreter le morceau en cours |
+| `ai_jam_session` | Obtenir un brief de jam -- accords, melodie, conseils de style -- pour l'improvisation |
+| `add_song` | Ajouter un nouveau morceau (JSON SongEntry) a la bibliotheque |
+| `import_midi` | Convertir un fichier MIDI en SongEntry et l'enregistrer |
+
+### AI Jam Session
+
+L'outil `ai_jam_session` extrait un "brief de jam" structure a partir de n'importe quel morceau : progression d'accords, contour melodique et conseils stylistiques specifiques au genre. Claude utilise ce brief pour creer sa propre interpretation.
+
+Deux modes :
+- **Morceau specifique :** `ai_jam_session({ songId: "autumn-leaves", style: "blues" })` -- improviser sur Autumn Leaves, style blues
+- **Choix aleatoire par genre :** `ai_jam_session({ genre: "jazz" })` -- choisir un morceau de jazz au hasard et improviser dessus
+
+Parametres optionnels : `mood` (enjoue, melancolique, reveur, etc.), `difficulty`, `measures` (plage comme "1-8").
+
+### Configuration Claude Desktop / Claude Code
+
+```json
+{
+  "mcpServers": {
+    "pianoai": {
+      "command": "npx",
+      "args": ["-y", "-p", "@mcptoolshop/ai_jam_session", "ai-jam-session-mcp"]
+    }
+  }
+}
+```
+
+### Plugin Claude Code
+
+PianoAI est livre avec un plugin Claude Code qui ajoute des commandes slash et des personnalites d'agent :
+
+| Commande | Description |
+|----------|-------------|
+| `/pianoai:teach <song>` | Demarrer une session d'enseignement structuree |
+| `/pianoai:practice <song>` | Obtenir un plan de pratique avec des recommandations de vitesse/mode |
+| `/pianoai:explore [query]` | Parcourir la bibliotheque par genre, difficulte ou mot-cle |
+| `/pianoai:jam <song or genre>` | Demarrer une session de jam -- Claude cree sa propre interpretation |
+
+Deux personnalites d'agent :
+- **Professeur de piano** -- patient, pedagogique, s'adapte au niveau de l'eleve
+- **Musicien de jam** -- ambiance decontractee, groove avant tout, encourage l'experimentation
+
+## Bibliotheque de morceaux
+
+100 morceaux integres couvrant 10 genres et 3 niveaux de difficulte :
+
+| Genre | Morceaux | Exemples |
+|-------|----------|----------|
+| Classique | 10 | Fur Elise, Clair de Lune, Moonlight Sonata, Bach Prelude in C |
+| Jazz | 10 | Autumn Leaves, Take Five, So What, Misty |
+| Pop | 10 | Imagine, Hallelujah, Piano Man, Bohemian Rhapsody |
+| Blues | 10 | Basic 12-Bar, St. Louis Blues, Stormy Monday, Thrill Is Gone |
+| Rock | 10 | Stairway Intro, Hotel California, Rocket Man, Layla Coda |
+| R&B | 10 | Superstition, Georgia On My Mind, Lean On Me, My Girl |
+| Latin | 10 | Girl from Ipanema, Besame Mucho, Oye Como Va, Wave |
+| Film | 11 | Cinema Paradiso, Moon River, Hedwig's Theme, Spirited Away |
+| Ragtime | 9 | The Entertainer, Maple Leaf Rag, Elite Syncopations |
+| New-Age | 10 | River Flows in You, Snowfall, Crystal Stream, Evening Calm |
+
+## API programmatique
+
+```typescript
+import { createAudioEngine, parseMidiFile, PlaybackController } from "@mcptoolshop/ai_jam_session";
+
+const connector = createAudioEngine();
+await connector.connect();
+
+const midi = await parseMidiFile("song.mid");
+const controller = new PlaybackController(connector, midi);
+
+controller.on("noteOn", (e) => console.log(`Note: ${e.noteName}`));
+await controller.play({ speed: 0.75 });
+
+controller.pause();
+controller.setSpeed(1.5);
+await controller.resume();
+
+await connector.disconnect();
+```
+
+### Jouer un morceau integre
+
+```typescript
+import { getSong, createSession, createAudioEngine } from "@mcptoolshop/ai_jam_session";
+
+const connector = createAudioEngine();
+await connector.connect();
+
+const song = getSong("autumn-leaves")!;
+const session = createSession(song, connector, {
+  mode: "full",
+  speed: 0.75,
+});
+
+await session.play();
+await connector.disconnect();
+```
+
+## Architecture
+
+```
+Fichiers MIDI (.mid)           Bibliotheque integree (JSON)
+       |                              |
+       v                              v
+  MIDI Parser ──────────────── Note Parser
+       |                              |
+       v                              v
+ MidiPlaybackEngine            SessionController
+       |                              |
+       └──────── PlaybackController ──┘
+                 (evenements temps reel, hooks)
+                        |
+          ┌─────────────┼─────────────┐
+          v             v             v
+     AudioEngine   Teaching Hooks  Progress
+     (haut-parleurs) (par mesure)  (callbacks)
+          |
+          v
+    node-web-audio-api (Rust DSP)
+```
+
+## Licence
+
+MIT

package/README.hi.md

@@ -0,0 +1,212 @@
+<p align="center"><a href="README.md">English</a> | <a href="README.ja.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></p>
+
+<p align="center">
+  <img src="logo.png" alt="PianoAI लोगो" width="180" />
+</p>
+
+<h1 align="center">PianoAI</h1>
+
+<p align="center">
+  बिल्ट-इन ऑडियो इंजन और 100 गानों की लाइब्रेरी वाला AI पियानो प्लेयर। Claude के लिए MCP सर्वर, इंसानों के लिए CLI।
+</p>
+
+[![MCP Tools](https://img.shields.io/badge/MCP_tools-15-purple)](https://github.com/mcp-tool-shop-org/ai_jam_session)
+[![Songs](https://img.shields.io/badge/songs-100_built--in-blue)](https://github.com/mcp-tool-shop-org/ai_jam_session)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](https://github.com/mcp-tool-shop-org/ai_jam_session)
+
+## यह क्या है?
+
+एक पियानो जिसे Claude बजा सकता है। PianoAI एक MCP सर्वर है जिसमें बिल्ट-इन ऑडियो इंजन है — यह आपके स्पीकर्स से बजता है, किसी बाहरी सॉफ़्टवेयर की ज़रूरत नहीं। Claude 10 शैलियों में फैली 100 गानों की लाइब्रेरी ब्राउज़ करता है, गाने चुनता है, उन्हें सिखाता है, और उन पर जैम करता है। एक स्टैंडअलोन CLI के रूप में भी काम करता है।
+
+## विशेषताएँ
+
+- **बिल्ट-इन पियानो इंजन** — `node-web-audio-api` के ज़रिए सैंपल-आधारित ऑडियो, स्पीकर्स से बजता है
+- **100 गानों की लाइब्रेरी** — क्लासिकल, जैज़, पॉप, ब्लूज़, रॉक, R&B, लैटिन, फ़िल्म, रैगटाइम, न्यू-एज
+- **AI Jam Session** — Claude किसी गाने के कॉर्ड्स और मेलोडी का विश्लेषण करता है, फिर अपनी खुद की व्याख्या बनाता है
+- **MIDI फ़ाइल सपोर्ट** — कोई भी `.mid` फ़ाइल बजाएँ: `pianoai play song.mid`
+- **शिक्षण प्रणाली** — हर मापक (measure) के लिए शिक्षण नोट्स, संगीत भाषा विवरण, अभ्यास सुझाव
+- **4 प्लेबैक मोड** — full, measure-by-measure, hands separate, loop
+- **स्पीड कंट्रोल** — 0.5x धीमे अभ्यास से 4x तेज़ तक
+- **रीयल-टाइम कंट्रोल** — प्लेबैक के दौरान पॉज़, रिज़्यूम, स्पीड बदलाव
+- **15 MCP टूल्स** — play, browse, teach, jam, import — सब MCP प्रोटोकॉल के ज़रिए
+- **अपने खुद के गाने जोड़ें** — `add_song` टूल SongEntry JSON स्वीकार करता है, `import_midi` MIDI फ़ाइलों को कनवर्ट करता है
+- **वैकल्पिक MIDI आउटपुट** — `--midi` फ़्लैग से बाहरी सॉफ़्टवेयर में भेजें (loopMIDI + VMPK आवश्यक)
+
+## इंस्टॉल करें
+
+```bash
+npm install -g @mcptoolshop/ai_jam_session
+```
+
+**Node.js 18+** ज़रूरी है। बस इतना ही — कोई MIDI ड्राइवर नहीं, कोई वर्चुअल पोर्ट नहीं, कोई बाहरी सॉफ़्टवेयर नहीं।
+
+## शुरू करें
+
+```bash
+# बिल्ट-इन गाना बजाएँ
+ai-jam-session play let-it-be
+
+# MIDI फ़ाइल बजाएँ
+ai-jam-session play path/to/song.mid
+
+# आधी स्पीड पर अभ्यास
+ai-jam-session play moonlight-sonata-mvt1 --speed 0.5
+
+# सभी बिल्ट-इन गानों की सूची देखें
+ai-jam-session list
+
+# गाने की जानकारी + शिक्षण नोट्स देखें
+ai-jam-session info autumn-leaves
+```
+
+### प्ले ऑप्शन
+
+| फ़्लैग | विवरण |
+|------|-------------|
+| `--speed <mult>` | स्पीड गुणक: 0.5 = आधी, 1.0 = सामान्य, 2.0 = दोगुनी |
+| `--tempo <bpm>` | गाने की डिफ़ॉल्ट टेम्पो ओवरराइड करें (10-400 BPM) |
+| `--mode <mode>` | प्लेबैक मोड: `full`, `measure`, `hands`, `loop` |
+| `--midi` | बिल्ट-इन इंजन की बजाय बाहरी MIDI सॉफ़्टवेयर में भेजें |
+
+## MCP सर्वर
+
+MCP सर्वर LLM इंटीग्रेशन के लिए 15 टूल्स प्रदान करता है:
+
+| टूल | विवरण |
+|------|-------------|
+| `list_songs` | शैली, कठिनाई, या क्वेरी से गाने ब्राउज़/खोजें |
+| `song_info` | पूर्ण संगीत भाषा, शिक्षण लक्ष्य, अभ्यास सुझाव |
+| `registry_stats` | शैली और कठिनाई के अनुसार गानों की गिनती |
+| `teaching_note` | हर मापक के लिए शिक्षण नोट, फ़िंगरिंग, डायनामिक्स |
+| `suggest_song` | मानदंडों के आधार पर सुझाव |
+| `list_measures` | शिक्षण नोट्स के साथ मापकों का अवलोकन |
+| `practice_setup` | किसी गाने के लिए स्पीड, मोड, और सेटिंग्स का सुझाव |
+| `sing_along` | हर मापक के लिए गाने योग्य टेक्स्ट (नोट नाम, सोलफ़ेज, कंटूर) |
+| `play_song` | स्पीकर्स से गाना या MIDI फ़ाइल बजाएँ |
+| `pause_playback` | चल रहे गाने को पॉज़ या रिज़्यूम करें |
+| `set_speed` | प्लेबैक के दौरान स्पीड बदलें |
+| `stop_playback` | चल रहे गाने को रोकें |
+| `ai_jam_session` | जैम ब्रीफ़ प्राप्त करें — कॉर्ड्स, मेलोडी, शैली मार्गदर्शन — इम्प्रोवाइज़ेशन के लिए |
+| `add_song` | लाइब्रेरी में नया गाना जोड़ें (SongEntry JSON) |
+| `import_midi` | MIDI फ़ाइल को SongEntry में बदलें और रजिस्टर करें |
+
+### AI Jam Session
+
+`ai_jam_session` टूल किसी भी गाने से एक संरचित "जैम ब्रीफ़" निकालता है: कॉर्ड प्रोग्रेशन, मेलोडी कंटूर, और शैली-विशिष्ट मार्गदर्शन। Claude इस ब्रीफ़ का उपयोग अपनी खुद की व्याख्या बनाने के लिए करता है।
+
+दो मोड:
+- **विशिष्ट गाना:** `ai_jam_session({ songId: "autumn-leaves", style: "blues" })` — Autumn Leaves पर ब्लूज़ शैली में जैम करें
+- **रैंडम शैली चयन:** `ai_jam_session({ genre: "jazz" })` — एक रैंडम जैज़ गाना चुनें और उस पर जैम करें
+
+वैकल्पिक पैरामीटर: `mood` (upbeat, melancholic, dreamy, आदि), `difficulty`, `measures` ("1-8" जैसी रेंज)।
+
+### Claude Desktop / Claude Code कॉन्फ़िगरेशन
+
+```json
+{
+  "mcpServers": {
+    "pianoai": {
+      "command": "npx",
+      "args": ["-y", "-p", "@mcptoolshop/ai_jam_session", "ai-jam-session-mcp"]
+    }
+  }
+}
+```
+
+### Claude Code प्लगइन
+
+PianoAI में एक Claude Code प्लगइन शामिल है जो स्लैश कमांड्स और एजेंट व्यक्तित्व जोड़ता है:
+
+| कमांड | विवरण |
+|---------|-------------|
+| `/pianoai:teach <song>` | एक संरचित शिक्षण सत्र शुरू करें |
+| `/pianoai:practice <song>` | स्पीड/मोड सुझावों के साथ अभ्यास योजना प्राप्त करें |
+| `/pianoai:explore [query]` | शैली, कठिनाई, या कीवर्ड से गानों की लाइब्रेरी ब्राउज़ करें |
+| `/pianoai:jam <song or genre>` | जैम सत्र शुरू करें — Claude अपनी खुद की व्याख्या बनाता है |
+
+दो एजेंट व्यक्तित्व:
+- **Piano Teacher** — धैर्यवान, शिक्षाशास्त्रीय, छात्रों के स्तर पर मिलता है
+- **Jam Musician** — आरामदेह जैम बैंड माहौल, ग्रूव-प्रधान, प्रयोग को प्रोत्साहित करता है
+
+## गानों की लाइब्रेरी
+
+10 शैलियों और 3 कठिनाई स्तरों में 100 बिल्ट-इन गाने:
+
+| शैली | गाने | उदाहरण |
+|-------|-------|---------|
+| Classical | 10 | Fur Elise, Clair de Lune, Moonlight Sonata, Bach Prelude in C |
+| Jazz | 10 | Autumn Leaves, Take Five, So What, Misty |
+| Pop | 10 | Imagine, Hallelujah, Piano Man, Bohemian Rhapsody |
+| Blues | 10 | Basic 12-Bar, St. Louis Blues, Stormy Monday, Thrill Is Gone |
+| Rock | 10 | Stairway Intro, Hotel California, Rocket Man, Layla Coda |
+| R&B | 10 | Superstition, Georgia On My Mind, Lean On Me, My Girl |
+| Latin | 10 | Girl from Ipanema, Besame Mucho, Oye Como Va, Wave |
+| Film | 11 | Cinema Paradiso, Moon River, Hedwig's Theme, Spirited Away |
+| Ragtime | 9 | The Entertainer, Maple Leaf Rag, Elite Syncopations |
+| New-Age | 10 | River Flows in You, Snowfall, Crystal Stream, Evening Calm |
+
+## प्रोग्रामैटिक API
+
+```typescript
+import { createAudioEngine, parseMidiFile, PlaybackController } from "@mcptoolshop/ai_jam_session";
+
+const connector = createAudioEngine();
+await connector.connect();
+
+const midi = await parseMidiFile("song.mid");
+const controller = new PlaybackController(connector, midi);
+
+controller.on("noteOn", (e) => console.log(`Note: ${e.noteName}`));
+await controller.play({ speed: 0.75 });
+
+controller.pause();
+controller.setSpeed(1.5);
+await controller.resume();
+
+await connector.disconnect();
+```
+
+### बिल्ट-इन गाना बजाएँ
+
+```typescript
+import { getSong, createSession, createAudioEngine } from "@mcptoolshop/ai_jam_session";
+
+const connector = createAudioEngine();
+await connector.connect();
+
+const song = getSong("autumn-leaves")!;
+const session = createSession(song, connector, {
+  mode: "full",
+  speed: 0.75,
+});
+
+await session.play();
+await connector.disconnect();
+```
+
+## आर्किटेक्चर
+
+```
+MIDI files (.mid)          Built-in song library (JSON)
+       |                              |
+       v                              v
+  MIDI Parser ──────────────── Note Parser
+       |                              |
+       v                              v
+ MidiPlaybackEngine            SessionController
+       |                              |
+       └──────── PlaybackController ──┘
+                 (real-time events, hooks)
+                        |
+          ┌─────────────┼─────────────┐
+          v             v             v
+     AudioEngine   Teaching Hooks  Progress
+     (speakers)    (per-measure)   (callbacks)
+          |
+          v
+    node-web-audio-api (Rust DSP)
+```
+
+## लाइसेंस
+
+MIT