@mcptoolshop/pianoai 1.0.0 → 1.2.0

package/README.es.md

@@ -12,9 +12,9 @@
   Servidor MCP + CLI para enseñanza de piano con IA — reproduce a través de VMPK vía MIDI con retroalimentación por voz.
 </p>
 
-[![Tests](https://img.shields.io/badge/tests-121_passing-brightgreen)](https://github.com/mcp-tool-shop-org/pianoai)
-[![Smoke](https://img.shields.io/badge/smoke-20_passing-brightgreen)](https://github.com/mcp-tool-shop-org/pianoai)
-[![MCP Tools](https://img.shields.io/badge/MCP_tools-7-purple)](https://github.com/mcp-tool-shop-org/pianoai)
+[![Tests](https://img.shields.io/badge/tests-181_passing-brightgreen)](https://github.com/mcp-tool-shop-org/pianoai)
+[![Smoke](https://img.shields.io/badge/smoke-29_passing-brightgreen)](https://github.com/mcp-tool-shop-org/pianoai)
+[![MCP Tools](https://img.shields.io/badge/MCP_tools-8-purple)](https://github.com/mcp-tool-shop-org/pianoai)
 [![Songs](https://img.shields.io/badge/songs-10_(via_ai--music--sheets)-blue)](https://github.com/mcp-tool-shop-org/ai-music-sheets)
 
 ## ¿Qué es esto?
@@ -26,11 +26,14 @@ Un CLI en TypeScript y servidor MCP que carga canciones de piano desde [ai-music
 - **4 modos de reproducción** — completa, compás por compás, manos separadas, bucle
 - **Control de velocidad** — práctica lenta a 0.5x hasta reproducción rápida a 2x, acumulable con modificación de tempo
 - **Seguimiento de progreso** — callbacks configurables en hitos porcentuales o por compás
-- **7 hooks de enseñanza** — console, silent, recording, callback, voice, aside, compose
+- **9 hooks de enseñanza** — console, silent, recording, callback, voice, aside, sing-along, compose, live feedback
+- **Narración de canto** — nombres de notas, solfeo, contorno o sílabas hablados antes de cada compás
+- **Canto sincronizado + piano** — concurrent (sensación de dúo) o before (voz primero) mediante `--with-piano`
 - **Retroalimentación por voz** — salida `VoiceDirective` para integración con mcp-voice-soundboard
+- **Retroalimentación en vivo** — estímulo en tiempo real, consejos de dinámica y avisos de dificultad durante la reproducción
 - **Interjecciones aparte** — salida `AsideDirective` para la bandeja de mcp-aside
 - **Análisis seguro** — las notas incorrectas se omiten con `ParseWarning`s recopilados
-- **7 herramientas MCP** — exponen el registro, notas de enseñanza y recomendaciones de canciones a LLMs
+- **8 herramientas MCP** — exponen el registro, notas de enseñanza, canto guiado y recomendaciones de canciones a LLMs
 - **Analizador de notas** — notación científica de altura a MIDI y viceversa
 - **Conector simulado** — cobertura completa de tests sin hardware MIDI
 
@@ -50,30 +53,42 @@ npm install -g @mcptoolshop/pianoai
 
 ```bash
 # Listar todas las canciones
-pianai list
+pianoai list
 
 # Mostrar detalles de canción + notas de enseñanza
-pianai info moonlight-sonata-mvt1
+pianoai info moonlight-sonata-mvt1
 
 # Reproducir una canción a través de VMPK
-pianai play let-it-be
+pianoai play let-it-be
 
 # Reproducir con modificación de tempo
-pianai play basic-12-bar-blues --tempo 80
+pianoai play basic-12-bar-blues --tempo 80
 
 # Avanzar compás por compás
-pianai play autumn-leaves --mode measure
+pianoai play autumn-leaves --mode measure
 
 # Práctica a mitad de velocidad
-pianai play moonlight-sonata-mvt1 --speed 0.5
+pianoai play moonlight-sonata-mvt1 --speed 0.5
 
 # Práctica lenta con manos separadas
-pianai play dream-on --speed 0.75 --mode hands
+pianoai play dream-on --speed 0.75 --mode hands
+
+# Cantar junto — narrar nombres de notas durante la reproducción
+pianoai sing let-it-be --mode note-names
+
+# Cantar junto con solfeo, ambas manos
+pianoai sing fur-elise --mode solfege --hand both
+
+# Cantar + piano juntos (sensación de dúo)
+pianoai sing let-it-be --with-piano
+
+# Voz primero, luego piano
+pianoai sing fur-elise --with-piano --sync before
 ```
 
 ## Servidor MCP
 
-El servidor MCP expone 7 herramientas para integración con LLMs:
+El servidor MCP expone 8 herramientas para integración con LLMs:
 
 | Herramienta | Descripción |
 |-------------|-------------|
@@ -81,6 +96,7 @@ El servidor MCP expone 7 herramientas para integración con LLMs:
 | `song_info` | Obtener lenguaje musical completo, objetivos de enseñanza, sugerencias de práctica |
 | `registry_stats` | Conteo de canciones por género y dificultad |
 | `teaching_note` | Nota de enseñanza por compás, digitación, dinámicas |
+| `sing_along` | Obtener texto cantable por compás (nombres de notas, solfeo, contorno, sílabas); soporta `withPiano` para acompañamiento sincronizado |
 | `suggest_song` | Obtener una recomendación basada en criterios |
 | `list_measures` | Vista general de compases con notas de enseñanza + advertencias de análisis |
 | `practice_setup` | Sugerir velocidad, modo y configuración de voz para una canción |
@@ -95,8 +111,8 @@ pnpm mcp
 ```json
 {
   "mcpServers": {
-    "pianai": {
-      "command": "pianai-mcp"
+    "pianoai": {
+      "command": "pianoai-mcp"
     }
   }
 }
@@ -109,6 +125,7 @@ pnpm mcp
 | `list [--genre <genre>]` | Listar canciones disponibles, opcionalmente filtradas por género |
 | `info <song-id>` | Mostrar detalles de canción: lenguaje musical, notas de enseñanza, estructura |
 | `play <song-id> [opts]` | Reproducir una canción a través de VMPK vía MIDI |
+| `sing <song-id> [opts]` | Cantar junto — narrar notas durante la reproducción |
 | `stats` | Estadísticas del registro (canciones, géneros, compases) |
 | `ports` | Listar puertos de salida MIDI disponibles |
 | `help` | Mostrar información de uso |
@@ -122,9 +139,18 @@ pnpm mcp
 | `--speed <mult>` | Multiplicador de velocidad: 0.5 = mitad, 1.0 = normal, 2.0 = doble |
 | `--mode <mode>` | Modo de reproducción: `full`, `measure`, `hands`, `loop` |
 
+### Opciones de canto
+
+| Bandera | Descripción |
+|---------|-------------|
+| `--mode <mode>` | Modo de canto: `note-names`, `solfege`, `contour`, `syllables` |
+| `--hand <hand>` | Qué mano: `right`, `left`, `both` |
+| `--with-piano` | Reproducir acompañamiento de piano mientras se canta |
+| `--sync <mode>` | Sincronización voz+piano: `concurrent` (por defecto, dúo), `before` (voz primero) |
+
 ## Motor de enseñanza
 
-El motor de enseñanza dispara hooks durante la reproducción. 7 implementaciones de hooks cubren todos los casos de uso:
+El motor de enseñanza dispara hooks durante la reproducción. 9 implementaciones de hooks cubren todos los casos de uso:
 
 | Hook | Caso de uso |
 |------|-------------|
@@ -134,6 +160,8 @@ El motor de enseñanza dispara hooks durante la reproducción. 7 implementacione
 | `createCallbackTeachingHook(cb)` | Personalizado — redirige a cualquier callback asíncrono |
 | `createVoiceTeachingHook(sink)` | Voz — produce `VoiceDirective` para mcp-voice-soundboard |
 | `createAsideTeachingHook(sink)` | Aparte — produce `AsideDirective` para la bandeja de mcp-aside |
+| `createSingAlongHook(sink, song)` | Canto — narra notas/solfeo/contorno antes de cada compás |
+| `createLiveFeedbackHook(voiceSink, asideSink, song)` | Retroalimentación — estímulo, consejos de dinámica, avisos de dificultad |
 | `composeTeachingHooks(...hooks)` | Múltiple — despacha a múltiples hooks en serie |
 
 ### Retroalimentación por voz
@@ -159,6 +187,32 @@ await session.play();
 // voiceHook.directives → todas las instrucciones de voz que se dispararon
 ```
 
+### Narración de canto
+
+```typescript
+import {
+  createSingAlongHook,
+  createVoiceTeachingHook,
+  composeTeachingHooks,
+  createSession,
+} from "@mcptoolshop/pianoai";
+import { getSong } from "@mcptoolshop/ai-music-sheets";
+
+const song = getSong("let-it-be")!;
+
+// Narrar solfeo antes de cada compás, luego notas de enseñanza
+const singHook = createSingAlongHook(voiceSink, song, {
+  mode: "solfege",
+  hand: "right",
+});
+const teachHook = createVoiceTeachingHook(voiceSink);
+const combined = composeTeachingHooks(singHook, teachHook);
+
+const session = createSession(song, connector, { teachingHook: combined });
+await session.play();
+// singHook.directives → "Do... Mi... Sol" bloqueante antes de cada compás
+```
+
 ### Composición de hooks
 
 ```typescript
@@ -212,13 +266,13 @@ await connector.disconnect();
 ## Arquitectura
 
 ```
-ai-music-sheets (biblioteca)     pianai (tiempo de ejecución)
+ai-music-sheets (biblioteca)     pianoai (tiempo de ejecución)
 ┌──────────────────────┐         ┌────────────────────────────────┐
 │ SongEntry (híbrido)  │────────→│ Note Parser (seguro + estricto)│
 │ Registry (búsqueda)  │         │ Session Engine (veloc.+progreso│
-│ 10 canciones, 10 gén.│         │ Teaching Engine (7 hooks)      │
+│ 10 canciones, 10 gén.│         │ Teaching Engine (9 hooks)      │
 └──────────────────────┘         │ VMPK Connector (JZZ)          │
-                                 │ MCP Server (7 herramientas)    │
+                                 │ MCP Server (8 herramientas)    │
                                  │ CLI (barra de progreso + voz)  │
                                  └─────────┬──────────────────────┘
                                            │ MIDI
@@ -237,8 +291,8 @@ Enrutamiento de hooks de enseñanza:
 ## Testing
 
 ```bash
-pnpm test       # 121 tests con Vitest (parser + session + teaching + voice + aside)
-pnpm smoke      # 20 smoke tests (integración, sin MIDI necesario)
+pnpm test       # 181 tests con Vitest (parser + session + teaching + voice + aside + sing-along)
+pnpm smoke      # 29 smoke tests (integración, sin MIDI necesario)
 pnpm typecheck  # tsc --noEmit
 ```
 

package/README.fr.md

@@ -12,9 +12,9 @@
   Serveur MCP + CLI pour l'enseignement du piano par IA — joue via VMPK par MIDI avec retour vocal.
 </p>
 
-[![Tests](https://img.shields.io/badge/tests-121_passing-brightgreen)](https://github.com/mcp-tool-shop-org/pianoai)
-[![Smoke](https://img.shields.io/badge/smoke-20_passing-brightgreen)](https://github.com/mcp-tool-shop-org/pianoai)
-[![MCP Tools](https://img.shields.io/badge/MCP_tools-7-purple)](https://github.com/mcp-tool-shop-org/pianoai)
+[![Tests](https://img.shields.io/badge/tests-181_passing-brightgreen)](https://github.com/mcp-tool-shop-org/pianoai)
+[![Smoke](https://img.shields.io/badge/smoke-29_passing-brightgreen)](https://github.com/mcp-tool-shop-org/pianoai)
+[![MCP Tools](https://img.shields.io/badge/MCP_tools-8-purple)](https://github.com/mcp-tool-shop-org/pianoai)
 [![Songs](https://img.shields.io/badge/songs-10_(via_ai--music--sheets)-blue)](https://github.com/mcp-tool-shop-org/ai-music-sheets)
 
 ## Qu'est-ce que c'est ?
@@ -26,11 +26,14 @@ Un CLI TypeScript et un serveur MCP qui charge des morceaux de piano depuis [ai-
 - **4 modes de lecture** — complet, mesure par mesure, mains séparées, boucle
 - **Contrôle de la vitesse** — 0.5x pour la pratique lente jusqu'à 2x en lecture rapide, cumulable avec le tempo personnalisé
 - **Suivi de progression** — callbacks configurables par pourcentage ou par mesure
-- **7 hooks pédagogiques** — console, silencieux, enregistrement, callback, voix, aside, composition
+- **9 hooks pédagogiques** — console, silencieux, enregistrement, callback, voix, aside, chant accompagné, composition, live feedback
+- **Narration chantée** — noms de notes, solfège, contour ou syllabes prononcés avant chaque mesure
+- **Chant synchronisé + piano** — concurrent (sensation de duo) ou before (voix d'abord) via `--with-piano`
 - **Retour vocal** — sortie `VoiceDirective` pour l'intégration mcp-voice-soundboard
+- **Retour pédagogique en direct** — encouragements en temps réel, conseils de dynamique et avertissements de difficulté pendant la lecture
 - **Interjections aside** — sortie `AsideDirective` pour la boîte de réception mcp-aside
 - **Analyse sécurisée** — les notes invalides sont ignorées avec collecte de `ParseWarning`
-- **7 outils MCP** — exposent le registre, les notes pédagogiques et les recommandations de morceaux aux LLMs
+- **8 outils MCP** — exposent le registre, les notes pédagogiques, le chant accompagné et les recommandations de morceaux aux LLMs
 - **Analyseur de notes** — notation scientifique des hauteurs vers MIDI et inversement
 - **Connecteur mock** — couverture de test complète sans matériel MIDI
 
@@ -50,30 +53,42 @@ npm install -g @mcptoolshop/pianoai
 
 ```bash
 # Lister tous les morceaux
-pianai list
+pianoai list
 
 # Afficher les détails d'un morceau + notes pédagogiques
-pianai info moonlight-sonata-mvt1
+pianoai info moonlight-sonata-mvt1
 
 # Jouer un morceau via VMPK
-pianai play let-it-be
+pianoai play let-it-be
 
 # Jouer avec un tempo personnalisé
-pianai play basic-12-bar-blues --tempo 80
+pianoai play basic-12-bar-blues --tempo 80
 
 # Avancer mesure par mesure
-pianai play autumn-leaves --mode measure
+pianoai play autumn-leaves --mode measure
 
 # Pratique à mi-vitesse
-pianai play moonlight-sonata-mvt1 --speed 0.5
+pianoai play moonlight-sonata-mvt1 --speed 0.5
 
 # Pratique lente mains séparées
-pianai play dream-on --speed 0.75 --mode hands
+pianoai play dream-on --speed 0.75 --mode hands
+
+# Chanter ensemble — narrer les noms de notes pendant la lecture
+pianoai sing let-it-be --mode note-names
+
+# Chanter ensemble en solfège, deux mains
+pianoai sing fur-elise --mode solfege --hand both
+
+# Chanter + piano ensemble (duo)
+pianoai sing let-it-be --with-piano
+
+# Voix d'abord, puis piano
+pianoai sing fur-elise --with-piano --sync before
 ```
 
 ## Serveur MCP
 
-Le serveur MCP expose 7 outils pour l'intégration LLM :
+Le serveur MCP expose 8 outils pour l'intégration LLM :
 
 | Outil | Description |
 |-------|-------------|
@@ -81,6 +96,7 @@ Le serveur MCP expose 7 outils pour l'intégration LLM :
 | `song_info` | Obtenir le langage musical complet, les objectifs pédagogiques, les suggestions de pratique |
 | `registry_stats` | Nombre de morceaux par genre et difficulté |
 | `teaching_note` | Note pédagogique par mesure, doigtés, dynamiques |
+| `sing_along` | Obtenir le texte chantable par mesure (noms de notes, solfège, contour, syllabes) ; supporte `withPiano` pour l'accompagnement synchronisé |
 | `suggest_song` | Obtenir une recommandation selon des critères |
 | `list_measures` | Aperçu des mesures avec notes pédagogiques + avertissements d'analyse |
 | `practice_setup` | Suggérer la vitesse, le mode et les réglages vocaux pour un morceau |
@@ -95,8 +111,8 @@ pnpm mcp
 ```json
 {
   "mcpServers": {
-    "pianai": {
-      "command": "pianai-mcp"
+    "pianoai": {
+      "command": "pianoai-mcp"
     }
   }
 }
@@ -109,6 +125,7 @@ pnpm mcp
 | `list [--genre <genre>]` | Lister les morceaux disponibles, avec filtre optionnel par genre |
 | `info <song-id>` | Afficher les détails du morceau : langage musical, notes pédagogiques, structure |
 | `play <song-id> [opts]` | Jouer un morceau via VMPK par MIDI |
+| `sing <song-id> [opts]` | Chanter ensemble — narrer les notes pendant la lecture |
 | `stats` | Statistiques du registre (morceaux, genres, mesures) |
 | `ports` | Lister les ports de sortie MIDI disponibles |
 | `help` | Afficher les informations d'utilisation |
@@ -122,9 +139,18 @@ pnpm mcp
 | `--speed <mult>` | Multiplicateur de vitesse : 0.5 = moitié, 1.0 = normal, 2.0 = double |
 | `--mode <mode>` | Mode de lecture : `full`, `measure`, `hands`, `loop` |
 
+### Options de chant
+
+| Option | Description |
+|--------|-------------|
+| `--mode <mode>` | Mode de chant : `note-names`, `solfege`, `contour`, `syllables` |
+| `--hand <hand>` | Quelle main : `right`, `left`, `both` |
+| `--with-piano` | Jouer l'accompagnement piano en chantant |
+| `--sync <mode>` | Synchronisation voix+piano : `concurrent` (par défaut, duo), `before` (voix d'abord) |
+
 ## Moteur pédagogique
 
-Le moteur pédagogique déclenche des hooks pendant la lecture. 7 implémentations de hooks couvrent tous les cas d'usage :
+Le moteur pédagogique déclenche des hooks pendant la lecture. 9 implémentations de hooks couvrent tous les cas d'usage :
 
 | Hook | Cas d'usage |
 |------|-------------|
@@ -134,6 +160,8 @@ Le moteur pédagogique déclenche des hooks pendant la lecture. 7 implémentatio
 | `createCallbackTeachingHook(cb)` | Personnalisé — redirige vers n'importe quel callback asynchrone |
 | `createVoiceTeachingHook(sink)` | Voix — produit des `VoiceDirective` pour mcp-voice-soundboard |
 | `createAsideTeachingHook(sink)` | Aside — produit des `AsideDirective` pour la boîte de réception mcp-aside |
+| `createSingAlongHook(sink, song)` | Chant — narre les notes/solfège/contour avant chaque mesure |
+| `createLiveFeedbackHook(voiceSink, asideSink, song)` | Retour en direct — encouragements, conseils de dynamique, avertissements de difficulté |
 | `composeTeachingHooks(...hooks)` | Multi — dispatch vers plusieurs hooks en série |
 
 ### Retour vocal
@@ -177,6 +205,32 @@ const composed = composeTeachingHooks(
 );
 ```
 
+### Narration chantée
+
+```typescript
+import {
+  createSingAlongHook,
+  createVoiceTeachingHook,
+  composeTeachingHooks,
+  createSession,
+} from "@mcptoolshop/pianoai";
+import { getSong } from "@mcptoolshop/ai-music-sheets";
+
+const song = getSong("let-it-be")!;
+
+// Narrer le solfège avant chaque mesure, puis les notes pédagogiques
+const singHook = createSingAlongHook(voiceSink, song, {
+  mode: "solfege",
+  hand: "right",
+});
+const teachHook = createVoiceTeachingHook(voiceSink);
+const combined = composeTeachingHooks(singHook, teachHook);
+
+const session = createSession(song, connector, { teachingHook: combined });
+await session.play();
+// singHook.directives → "Do... Mi... Sol" bloquant avant chaque mesure
+```
+
 ## API programmatique
 
 ```typescript
@@ -212,13 +266,13 @@ await connector.disconnect();
 ## Architecture
 
 ```
-ai-music-sheets (bibliothèque)   pianai (runtime)
+ai-music-sheets (bibliothèque)   pianoai (runtime)
 ┌──────────────────────┐         ┌────────────────────────────────┐
 │ SongEntry (hybride)  │────────→│ Note Parser (sûr + strict)    │
 │ Registry (recherche) │         │ Session Engine (vitesse+suivi) │
-│ 10 morceaux, 10 genres│        │ Teaching Engine (7 hooks)      │
+│ 10 morceaux, 10 genres│        │ Teaching Engine (9 hooks)      │
 └──────────────────────┘         │ VMPK Connector (JZZ)          │
-                                 │ MCP Server (7 outils)          │
+                                 │ MCP Server (8 outils)          │
                                  │ CLI (barre de progression+voix)│
                                  └─────────┬──────────────────────┘
                                            │ MIDI
@@ -237,8 +291,8 @@ Routage des hooks pédagogiques :
 ## Tests
 
 ```bash
-pnpm test       # 121 tests Vitest (parser + session + teaching + voice + aside)
-pnpm smoke      # 20 tests d'intégration (pas de MIDI requis)
+pnpm test       # 181 tests Vitest (parser + session + teaching + voice + aside + chant)
+pnpm smoke      # 29 tests d'intégration (pas de MIDI requis)
 pnpm typecheck  # tsc --noEmit
 ```
 

package/README.hi.md

@@ -12,9 +12,9 @@
   AI-संचालित पियानो शिक्षण के लिए MCP सर्वर + CLI — MIDI के माध्यम से VMPK पर बजाता है और वॉइस फीडबैक देता है।
 </p>
 
-[![Tests](https://img.shields.io/badge/tests-121_passing-brightgreen)](https://github.com/mcp-tool-shop-org/pianoai)
-[![Smoke](https://img.shields.io/badge/smoke-20_passing-brightgreen)](https://github.com/mcp-tool-shop-org/pianoai)
-[![MCP Tools](https://img.shields.io/badge/MCP_tools-7-purple)](https://github.com/mcp-tool-shop-org/pianoai)
+[![Tests](https://img.shields.io/badge/tests-181_passing-brightgreen)](https://github.com/mcp-tool-shop-org/pianoai)
+[![Smoke](https://img.shields.io/badge/smoke-29_passing-brightgreen)](https://github.com/mcp-tool-shop-org/pianoai)
+[![MCP Tools](https://img.shields.io/badge/MCP_tools-8-purple)](https://github.com/mcp-tool-shop-org/pianoai)
 [![Songs](https://img.shields.io/badge/songs-10_(via_ai--music--sheets)-blue)](https://github.com/mcp-tool-shop-org/ai-music-sheets)
 
 ## यह क्या है?
@@ -26,11 +26,14 @@
 - **4 प्लेबैक मोड** — full, measure-by-measure, hands separate, loop
 - **स्पीड कंट्रोल** — 0.5x धीमे अभ्यास से 2x तेज़ प्लेबैक तक, टेम्पो ओवरराइड के साथ स्टैक होता है
 - **प्रगति ट्रैकिंग** — प्रतिशत माइलस्टोन या प्रति-मेजर पर कॉन्फ़िगर करने योग्य कॉलबैक
-- **7 टीचिंग हुक** — console, silent, recording, callback, voice, aside, compose
+- **9 टीचिंग हुक** — console, silent, recording, callback, voice, aside, sing-along, compose, live feedback
+- **सिंग-अलॉंग नैरेशन** — प्रत्येक मेजर से पहले नोट नाम, सोलफेज, कॉन्टूर, या सिलेबल बोले जाते हैं
+- **सिंक्रोनाइज़्ड गायन + पियानो** — concurrent (डुएट फ़ील) या before (पहले वॉइस) `--with-piano` के माध्यम से
+- **लाइव टीचिंग फीडबैक** — प्लेबैक के दौरान रीयल-टाइम प्रोत्साहन, डायनामिक्स टिप्स, और कठिनाई चेतावनियाँ
 - **वॉइस फीडबैक** — mcp-voice-soundboard इंटीग्रेशन के लिए `VoiceDirective` आउटपुट
 - **Aside इंटरजेक्शन** — mcp-aside इनबॉक्स के लिए `AsideDirective` आउटपुट
 - **सुरक्षित पार्सिंग** — खराब नोट्स एकत्रित `ParseWarning` के साथ सुचारू रूप से स्किप होते हैं
-- **7 MCP टूल** — LLM के लिए रजिस्ट्री, टीचिंग नोट्स, और गाने की सिफारिशें उपलब्ध कराते हैं
+- **8 MCP टूल** — LLM के लिए रजिस्ट्री, टीचिंग नोट्स, सिंग-अलॉंग, और गाने की सिफारिशें उपलब्ध कराते हैं
 - **नोट पार्सर** — साइंटिफिक पिच नोटेशन से MIDI और वापस
 - **मॉक कनेक्टर** — MIDI हार्डवेयर के बिना पूर्ण टेस्ट कवरेज
 
@@ -50,30 +53,42 @@ npm install -g @mcptoolshop/pianoai
 
 ```bash
 # सभी गाने सूचीबद्ध करें
-pianai list
+pianoai list
 
 # गाने का विवरण + टीचिंग नोट्स देखें
-pianai info moonlight-sonata-mvt1
+pianoai info moonlight-sonata-mvt1
 
 # VMPK के माध्यम से गाना बजाएँ
-pianai play let-it-be
+pianoai play let-it-be
 
 # टेम्पो ओवरराइड के साथ बजाएँ
-pianai play basic-12-bar-blues --tempo 80
+pianoai play basic-12-bar-blues --tempo 80
 
 # मेजर-दर-मेजर चरणबद्ध तरीके से चलें
-pianai play autumn-leaves --mode measure
+pianoai play autumn-leaves --mode measure
 
 # आधी गति से अभ्यास
-pianai play moonlight-sonata-mvt1 --speed 0.5
+pianoai play moonlight-sonata-mvt1 --speed 0.5
 
 # धीमा हैंड्स-सेपरेट अभ्यास
-pianai play dream-on --speed 0.75 --mode hands
+pianoai play dream-on --speed 0.75 --mode hands
+
+# सिंग अलॉंग — प्लेबैक के दौरान नोट नाम नैरेट करें
+pianoai sing let-it-be --mode note-names
+
+# सोलफेज के साथ सिंग अलॉंग, दोनों हाथ
+pianoai sing fur-elise --mode solfege --hand both
+
+# सिंग + पियानो एक साथ (डुएट फ़ील)
+pianoai sing let-it-be --with-piano
+
+# पहले वॉइस, फिर पियानो
+pianoai sing fur-elise --with-piano --sync before
 ```
 
 ## MCP सर्वर
 
-MCP सर्वर LLM इंटीग्रेशन के लिए 7 टूल उपलब्ध कराता है:
+MCP सर्वर LLM इंटीग्रेशन के लिए 8 टूल उपलब्ध कराता है:
 
 | टूल | विवरण |
 |------|--------|
@@ -82,6 +97,7 @@ MCP सर्वर LLM इंटीग्रेशन के लिए 7 टू
 | `registry_stats` | शैली और कठिनाई के अनुसार गानों की गिनती |
 | `teaching_note` | प्रति-मेजर टीचिंग नोट, फिंगरिंग, डायनामिक्स |
 | `suggest_song` | मानदंडों के आधार पर सिफारिश प्राप्त करें |
+| `sing_along` | प्रति-मेजर गाने योग्य टेक्स्ट (नोट नाम, सोलफेज, कॉन्टूर, सिलेबल) प्राप्त करें; `withPiano` सपोर्ट |
 | `list_measures` | टीचिंग नोट्स + पार्स चेतावनियों के साथ मेजर का अवलोकन |
 | `practice_setup` | किसी गाने के लिए स्पीड, मोड, और वॉइस सेटिंग्स सुझाएँ |
 
@@ -95,8 +111,8 @@ pnpm mcp
 ```json
 {
   "mcpServers": {
-    "pianai": {
-      "command": "pianai-mcp"
+    "pianoai": {
+      "command": "pianoai-mcp"
     }
   }
 }
@@ -109,6 +125,7 @@ pnpm mcp
 | `list [--genre <genre>]` | उपलब्ध गाने सूचीबद्ध करें, वैकल्पिक रूप से शैली द्वारा फ़िल्टर |
 | `info <song-id>` | गाने का विवरण दिखाएँ: संगीत भाषा, टीचिंग नोट्स, संरचना |
 | `play <song-id> [opts]` | MIDI के माध्यम से VMPK पर गाना बजाएँ |
+| `sing <song-id> [opts]` | सिंग अलॉंग — प्लेबैक के दौरान नोट्स नैरेट करें |
 | `stats` | रजिस्ट्री आँकड़े (गाने, शैलियाँ, मेजर) |
 | `ports` | उपलब्ध MIDI आउटपुट पोर्ट सूचीबद्ध करें |
 | `help` | उपयोग जानकारी दिखाएँ |
@@ -122,9 +139,18 @@ pnpm mcp
 | `--speed <mult>` | स्पीड मल्टीप्लायर: 0.5 = आधा, 1.0 = सामान्य, 2.0 = दोगुना |
 | `--mode <mode>` | प्लेबैक मोड: `full`, `measure`, `hands`, `loop` |
 
+### सिंग विकल्प
+
+| फ़्लैग | विवरण |
+|--------|--------|
+| `--mode <mode>` | सिंग-अलॉंग मोड: `note-names`, `solfege`, `contour`, `syllables` |
+| `--hand <hand>` | कौन सा हाथ: `right`, `left`, `both` |
+| `--with-piano` | गायन के दौरान पियानो संगत बजाएँ |
+| `--sync <mode>` | वॉइस+पियानो सिंक: `concurrent` (डिफ़ॉल्ट, डुएट), `before` (पहले वॉइस) |
+
 ## टीचिंग इंजन
 
-टीचिंग इंजन प्लेबैक के दौरान हुक फायर करता है। 7 हुक इम्प्लीमेंटेशन हर उपयोग मामले को कवर करते हैं:
+टीचिंग इंजन प्लेबैक के दौरान हुक फायर करता है। 9 हुक इम्प्लीमेंटेशन हर उपयोग मामले को कवर करते हैं:
 
 | हुक | उपयोग मामला |
 |------|-------------|
@@ -134,6 +160,8 @@ pnpm mcp
 | `createCallbackTeachingHook(cb)` | कस्टम — किसी भी async कॉलबैक पर रूट करें |
 | `createVoiceTeachingHook(sink)` | वॉइस — mcp-voice-soundboard के लिए `VoiceDirective` उत्पन्न करता है |
 | `createAsideTeachingHook(sink)` | Aside — mcp-aside इनबॉक्स के लिए `AsideDirective` उत्पन्न करता है |
+| `createSingAlongHook(sink, song)` | सिंग-अलॉंग — प्रत्येक मेजर से पहले नोट नाम/सोलफेज/कॉन्टूर नैरेट करता है |
+| `createLiveFeedbackHook(voiceSink, asideSink, song)` | लाइव फीडबैक — प्रोत्साहन, डायनामिक्स टिप्स, कठिनाई चेतावनियाँ |
 | `composeTeachingHooks(...hooks)` | मल्टी — क्रमिक रूप से कई हुक पर डिस्पैच करता है |
 
 ### वॉइस फीडबैक
@@ -177,6 +205,32 @@ const composed = composeTeachingHooks(
 );
 ```
 
+### सिंग-अलॉंग नैरेशन
+
+```typescript
+import {
+  createSingAlongHook,
+  createVoiceTeachingHook,
+  composeTeachingHooks,
+  createSession,
+} from "@mcptoolshop/pianoai";
+import { getSong } from "@mcptoolshop/ai-music-sheets";
+
+const song = getSong("let-it-be")!;
+
+// प्रत्येक मेजर से पहले सोलफेज नैरेट करें, फिर टीचिंग नोट्स बोलें
+const singHook = createSingAlongHook(voiceSink, song, {
+  mode: "solfege",
+  hand: "right",
+});
+const teachHook = createVoiceTeachingHook(voiceSink);
+const combined = composeTeachingHooks(singHook, teachHook);
+
+const session = createSession(song, connector, { teachingHook: combined });
+await session.play();
+// singHook.directives → प्रत्येक मेजर से पहले ब्लॉकिंग "Do... Mi... Sol"
+```
+
 ## प्रोग्रामेटिक API
 
 ```typescript
@@ -212,13 +266,13 @@ await connector.disconnect();
 ## आर्किटेक्चर
 
 ```
-ai-music-sheets (लाइब्रेरी)       pianai (रनटाइम)
+ai-music-sheets (लाइब्रेरी)       pianoai (रनटाइम)
 ┌──────────────────────┐         ┌────────────────────────────────┐
 │ SongEntry (हाइब्रिड) │────────→│ Note Parser (सुरक्षित + सख्त) │
 │ Registry (खोज)       │         │ Session Engine (स्पीड+प्रगति)  │
-│ 10 गाने, 10 शैलियाँ  │         │ Teaching Engine (7 हुक)        │
+│ 10 गाने, 10 शैलियाँ  │         │ Teaching Engine (9 हुक)        │
 └──────────────────────┘         │ VMPK Connector (JZZ)          │
-                                 │ MCP Server (7 टूल)            │
+                                 │ MCP Server (8 टूल)            │
                                  │ CLI (प्रोग्रेस बार + वॉइस)    │
                                  └─────────┬──────────────────────┘
                                            │ MIDI
@@ -237,8 +291,8 @@ ai-music-sheets (लाइब्रेरी)       pianai (रनटाइम)
 ## टेस्टिंग
 
 ```bash
-pnpm test       # 121 Vitest टेस्ट (पार्सर + सेशन + टीचिंग + वॉइस + aside)
-pnpm smoke      # 20 स्मोक टेस्ट (इंटीग्रेशन, MIDI आवश्यक नहीं)
+pnpm test       # 181 Vitest टेस्ट (पार्सर + सेशन + टीचिंग + वॉइस + aside + सिंग-अलॉंग)
+pnpm smoke      # 29 स्मोक टेस्ट (इंटीग्रेशन, MIDI आवश्यक नहीं)
 pnpm typecheck  # tsc --noEmit
 ```