Building a Carnatic Music Practice App

I want to build an app to practice my carnatic music. Where I can set the speed, like 33bpm (1 note per beat, 2 notes per beat, 4 notes per beat). The practice routines can be different ragams (scales). I want to pick a base pitch (like D is Sa). Basically the things listed here https://www.shivkumar.org/music/varnams/index.html

I want to be able to sing to the app (pick ragam, composition (like sarali varisai 2 etc), bpm, speed) and after i'm done i should be able to see which notes I got wrong and where I was off beat

Now let me create the Zustand store.

Now let me create the audio modules.

Since this is a new project, I need to understand your preferences before designing the architecture. Let me ask a few key questions.

Now let me create the practice engine hook and UI components.

Now let me create the UI components.

User has answered your questions: "What platform do you want to build this for?"="Web app (Recommended)", "How should the app guide you during practice?"="Visual notation + audio (Recommended)", "What level of pitch detection accuracy do you need?"="Cent-level precision", "Do you want to include gamakas (ornamentations) in the analysis?"="No - plain notes only (Recommended)". You can now continue with the user's answers in mind.

Now let me create the main App component.

Let me install the dependencies and verify everything works.

The user wants:

Web app
Visual notation + audio (tanpura drone, reference tones)
Cent-level precision (can show sharp/flat within a note)
No gamaka detection (plain notes only)

Now I need to design the architecture. Let me launch a Plan agent to help design this, and also think about the technical approach myself.

Key components:

Frontend: React or vanilla JS web app
Audio Input: Web Audio API + pitch detection library (like pitchy, pitchfinder, or ml5.js)
Audio Output: Web Audio API for tanpura drone + reference tones
Music Data: JSON structures for ragams, compositions (sarali varisai etc.)
Analysis: Compare detected pitches with expected notes, calculate timing accuracy

Let me create a comprehensive plan.

Now I have a clear picture. Let me design the architecture for this Carnatic music practice web app.

>npx tsc --noEmit 2>&1

Exit code 2
src/audio/PitchDetector.ts(2,21): error TS6133: 'Swara' is declared but its value is never read.
src/audio/PitchDetector.ts(67,42): error TS2345: Argument of type 'Float32Array<ArrayBufferLike>' is not assignable to parameter of type 'Float32Array<ArrayBuffer>'.
  Type 'ArrayBufferLike' is not assignable to type 'ArrayBuffer'.
    Type 'SharedArrayBuffer' is not assignable to type 'ArrayBuffer'.
      Types of property '[Symbol.toStringTag]' are incompatible.
        Type '"SharedArrayBuffer"' is not assignable to type '"ArrayBuffer"'.
src/hooks/usePracticeEngine.ts(8,1): error TS6133: 'SWARA_CENTS' is declared but its value is never read.

I have gathered sufficient information for the architecture design. Let me now synthesize all the research into a comprehensive design document.

---

# Carnatic Music Practice App - Architecture Design

## Executive Summary

This document presents a complete architecture for a client-side Carnatic music practice web application. The app enables students to practice fundamental exercises (Sarali Varisai, Janta Varisai, Dhatu Varisai, Melsthayi Varisai, and Alankarams) with real-time pitch detection, visual notation display, tanpura drone accompaniment, and post-practice feedback.

---

## 1. Overall Architecture

### 1.1 High-Level Component Diagram

```
+------------------------------------------------------------------+
|                        React Application                          |
+------------------------------------------------------------------+
|                                                                    |
|  +----------------+  +------------------+  +-------------------+   |
|  | Settings Panel |  | Notation Display |  | Feedback Panel    |   |
|  | - Base Pitch   |  | - Swara Grid     |  | - Accuracy Report |   |
|  | - BPM          |  | - Moving Cursor  |  | - Timing Graph    |   |
|  | - Gati         |  | - Current Swara  |  | - Wrong Notes     |   |
|  | - Ragam        |  +------------------+  +-------------------+   |
|  +----------------+           |                    ^               |
|         |                     v                    |               |
|         v            +------------------+          |               |
|  +----------------+  | Practice Engine  |----------+               |
|  | Exercise       |  | - Scheduler      |                          |
|  | Selector       |  | - State Machine  |                          |
|  +----------------+  +------------------+                          |
|                              |                                     |
+------------------------------|-------------------------------------+
                               v
+------------------------------------------------------------------+
|                      Audio System Layer                           |
+------------------------------------------------------------------+
|                                                                    |
|  +-------------------+  +--------------------+  +---------------+  |
|  | Tanpura Drone     |  | Reference Melody   |  | Pitch         |  |
|  | - Oscillators     |  | - Note Playback    |  | Detector      |  |
|  | - Harmonics       |  | - Sample Trigger   |  | - Mic Input   |  |
|  | - LFO Modulation  |  +--------------------+  | - Analysis    |  |
|  +-------------------+                          +---------------+  |
|         |                        |                     |           |
|         v                        v                     v           |
|  +----------------------------------------------------------+     |
|  |                    Web Audio API Context                  |     |
|  |  - AudioContext                                           |     |
|  |  - MediaStreamSource (microphone)                         |     |
|  |  - AnalyserNode                                           |     |
|  |  - OscillatorNode, GainNode, BiquadFilterNode             |     |
|  +----------------------------------------------------------+     |
|                                                                    |
+------------------------------------------------------------------+
```

### 1.2 Data Flow

```
User Input (Settings)
        |
        v
+------------------+
| Configuration    |-----> Base Pitch (Hz), BPM, Gati, Ragam
| Store (Zustand)  |
+------------------+
        |
        v
+------------------+      +------------------+
| Exercise Data    |----->| Practice Engine  |
| (JSON Static)    |      | (Scheduler)      |
+------------------+      +------------------+
                                  |
                    +-------------+-------------+
                    |             |             |
                    v             v             v
            +----------+   +-----------+  +-----------+
            | Visual   |   | Audio     |  | Expected  |
            | Cursor   |   | Reference |  | Note      |
            | Position |   | (if on)   |  | Register  |
            +----------+   +-----------+  +-----------+
                                               |
                                               v
+------------------+                   +----------------+
| Mic Input        |------------------>| Pitch Detector |
| (Web Audio API)  |                   | (pitchy)       |
+------------------+                   +----------------+
                                               |
                                               v
                                       +----------------+
                                       | Hz to Swara    |
                                       | Mapper         |
                                       +----------------+
                                               |
                                               v
                                       +----------------+
                                       | Comparison &   |
                                       | Recording      |
                                       +----------------+
                                               |
                                               v
                                       +----------------+
                                       | Feedback       |
                                       | Generator      |
                                       +----------------+
```

---

## 2. Data Structures

### 2.1 Core Types (TypeScript)

```typescript
// Base pitch mapping - semitones from C4
type PitchName = 'C' | 'C#' | 'D' | 'D#' | 'E' | 'F' | 'F#' | 'G' | 'G#' | 'A' | 'A#' | 'B';

interface AppSettings {
  basePitch: PitchName;        // Sa maps to this note
  basePitchHz: number;         // Calculated Hz (e.g., C4 = 261.63 Hz)
  bpm: number;                 // 20-120
  gati: 1 | 2 | 4;             // Notes per beat
  selectedRagam: string;       // Ragam ID (e.g., 'mayamalavagowla')
  tanpuraEnabled: boolean;
  referenceMelodyEnabled: boolean;
  tanpuraVolume: number;       // 0-1
  referenceVolume: number;     // 0-1
}

// Swara definitions
type SwaraName = 'S' | 'R1' | 'R2' | 'R3' | 'G1' | 'G2' | 'G3' | 
                 'M1' | 'M2' | 'P' | 'D1' | 'D2' | 'D3' | 
                 'N1' | 'N2' | 'N3';

// Octave indicators
type Octave = 'mandra' | 'madhya' | 'tara'; // lower, middle, upper

interface Swara {
  name: SwaraName;
  octave: Octave;
  centsFromSa: number;  // Relative to madhya Sa
}

// Ragam definition
interface Ragam {
  id: string;
  name: string;
  melakartha: number;  // 1-72, null for janya ragas
  arohana: SwaraName[];
  avarohana: SwaraName[];
  swaras: SwaraName[]; // All swaras used
}

// Exercise notation
interface NotationSymbol {
  swara: SwaraName | null;  // null for rest
  octave: Octave;
  duration: number;         // in beats (e.g., 1, 0.5, 0.25)
  isExtended: boolean;      // For "dheergam" (held notes marked with ",")
}

interface Exercise {
  id: string;
  name: string;
  category: 'sarali' | 'janta' | 'dhatu' | 'melsthayi' | 'alankaram';
  ragam: string;            // Ragam ID
  talam: string;            // e.g., 'adi'
  notation: NotationSymbol[];
  description?: string;
}

// Practice session data
interface NoteEvent {
  expectedSwara: Swara | null;
  detectedHz: number | null;
  detectedSwara: Swara | null;
  centsError: number;       // Deviation in cents
  timestamp: number;        // ms from start
  expectedTime: number;     // ms when note should have been sung
  timingError: number;      // ms deviation
  clarity: number;          // 0-1 from pitch detector
}

interface PracticeSession {
  exerciseId: string;
  settings: AppSettings;
  startTime: number;
  events: NoteEvent[];
  completed: boolean;
}

interface FeedbackReport {
  sessionId: string;
  overallAccuracy: number;        // 0-100%
  pitchAccuracy: number;          // 0-100%
  timingAccuracy: number;         // 0-100%
  problematicNotes: {
    swara: Swara;
    occurrences: number;
    avgCentsError: number;
    avgTimingError: number;
  }[];
  timeline: {
    time: number;
    expected: SwaraName;
    actual: SwaraName | null;
    correct: boolean;
  }[];
}
```

### 2.2 Swara Frequency Ratios (Just Intonation for Carnatic)

```typescript
// Cents from Sa for each swarasthana
// Based on traditional Carnatic ratios (22 shruti system approximation)
const SWARA_CENTS: Record<SwaraName, number> = {
  'S':   0,
  'R1':  90,    // 256/243 - Shuddha Rishabha (16/15 = 112 cents is also used)
  'R2':  182,   // 10/9 or 9/8 - Chatushruti Rishabha  
  'R3':  294,   // 32/27 - Shatshruti Rishabha (overlaps G1)
  'G1':  294,   // Same position as R3
  'G2':  386,   // 5/4 - Sadharana Gandhara (overlaps R3 in some contexts)
  'G3':  408,   // 81/64 - Antara Gandhara
  'M1':  498,   // 4/3 - Shuddha Madhyama
  'M2':  590,   // 45/32 or 729/512 - Prati Madhyama
  'P':   702,   // 3/2 - Panchama (fixed)
  'D1':  792,   // 128/81 - Shuddha Dhaivata
  'D2':  884,   // 5/3 - Chatushruti Dhaivata
  'D3':  996,   // 16/9 - Shatshruti Dhaivata (overlaps N1)
  'N1':  996,   // Same position as D3
  'N2':  1088,  // 9/5 - Kaisiki Nishada
  'N3':  1110,  // 15/8 - Kakali Nishada
};

// Alternative using Western equal temperament (for comparison)
const SWARA_CENTS_ET: Record<SwaraName, number> = {
  'S':   0,
  'R1':  100,
  'R2':  200,   // R2 = G1
  'R3':  300,   // R3 = G2
  'G1':  200,
  'G2':  300,
  'G3':  400,
  'M1':  500,
  'M2':  600,
  'P':   700,
  'D1':  800,
  'D2':  900,   // D2 = N1
  'D3':  1000,  // D3 = N2
  'N1':  900,
  'N2':  1000,
  'N3':  1100,
};
```

### 2.3 Ragam Definitions

```typescript
const RAGAMS: Record<string, Ragam> = {
  'mayamalavagowla': {
    id: 'mayamalavagowla',
    name: 'Mayamalavagowla',
    melakartha: 15,
    arohana: ['S', 'R1', 'G3', 'M1', 'P', 'D1', 'N3'],
    avarohana: ['N3', 'D1', 'P', 'M1', 'G3', 'R1', 'S'],
    swaras: ['S', 'R1', 'G3', 'M1', 'P', 'D1', 'N3']
  },
  'shankarabharanam': {
    id: 'shankarabharanam',
    name: 'Shankarabharanam',
    melakartha: 29,
    arohana: ['S', 'R2', 'G3', 'M1', 'P', 'D2', 'N3'],
    avarohana: ['N3', 'D2', 'P', 'M1', 'G3', 'R2', 'S'],
    swaras: ['S', 'R2', 'G3', 'M1', 'P', 'D2', 'N3']
  },
  'kalyani': {
    id: 'kalyani',
    name: 'Kalyani',
    melakartha: 65,
    arohana: ['S', 'R2', 'G3', 'M2', 'P', 'D2', 'N3'],
    avarohana: ['N3', 'D2', 'P', 'M2', 'G3', 'R2', 'S'],
    swaras: ['S', 'R2', 'G3', 'M2', 'P', 'D2', 'N3']
  },
  // ... more ragams can be added
};
```

### 2.4 Exercise Data Structure

```typescript
// Example: Sarali Varisai 1
const SARALI_VARISAI_1: Exercise = {
  id: 'sarali-1',
  name: 'Sarali Varisai 1',
  category: 'sarali',
  ragam: 'mayamalavagowla',
  talam: 'adi',
  notation: [
    // Ascending: s r g m | p d n S
    { swara: 'S', octave: 'madhya', duration: 1, isExtended: false },
    { swara: 'R1', octave: 'madhya', duration: 1, isExtended: false },
    { swara: 'G3', octave: 'madhya', duration: 1, isExtended: false },
    { swara: 'M1', octave: 'madhya', duration: 1, isExtended: false },
    { swara: 'P', octave: 'madhya', duration: 1, isExtended: false },
    { swara: 'D1', octave: 'madhya', duration: 1, isExtended: false },
    { swara: 'N3', octave: 'madhya', duration: 1, isExtended: false },
    { swara: 'S', octave: 'tara', duration: 1, isExtended: false },
    // Descending: S n d p | m g r s
    { swara: 'S', octave: 'tara', duration: 1, isExtended: false },
    { swara: 'N3', octave: 'madhya', duration: 1, isExtended: false },
    { swara: 'D1', octave: 'madhya', duration: 1, isExtended: false },
    { swara: 'P', octave: 'madhya', duration: 1, isExtended: false },
    { swara: 'M1', octave: 'madhya', duration: 1, isExtended: false },
    { swara: 'G3', octave: 'madhya', duration: 1, isExtended: false },
    { swara: 'R1', octave: 'madhya', duration: 1, isExtended: false },
    { swara: 'S', octave: 'madhya', duration: 1, isExtended: false },
  ]
};
```

---

## 3. Pitch Detection Approach

### 3.1 Library Choice: pitchy

I recommend **[pitchy](https://github.com/ianprime0509/pitchy)** for the following reasons:
- Uses McLeod Pitch Method (MPM) - accurate for monophonic voices
- Returns clarity value (0-1) to filter noise
- Pure JavaScript, no WASM required
- Actively maintained
- Small bundle size

Alternative consideration: For more complex polyphonic detection or if higher accuracy is needed, **[pitchfinder](https://github.com/peterkhayes/pitchfinder)** provides multiple algorithms (YIN, AMDF, Dynamic Wavelet).

### 3.2 Hz to Swara Mapping Algorithm

```typescript
interface PitchResult {
  hz: number;
  clarity: number;
}

interface SwaraMatch {
  swara: SwaraName;
  octave: Octave;
  centsError: number;  // Negative = flat, Positive = sharp
}

class PitchToSwaraMapper {
  private basePitchHz: number;  // Hz of madhya Sa
  private ragamSwaras: SwaraName[];
  private swaraCents: Record<SwaraName, number>;
  
  constructor(basePitchHz: number, ragam: Ragam) {
    this.basePitchHz = basePitchHz;
    this.ragamSwaras = ragam.swaras;
    this.swaraCents = SWARA_CENTS;
  }
  
  /**
   * Convert Hz to cents relative to madhya Sa
   */
  private hzToCentsFromSa(hz: number): number {
    // cents = 1200 * log2(f / f_sa)
    return 1200 * Math.log2(hz / this.basePitchHz);
  }
  
  /**
   * Find the closest swara to a detected pitch
   */
  mapToSwara(pitchResult: PitchResult, minClarity: number = 0.8): SwaraMatch | null {
    if (pitchResult.clarity < minClarity) {
      return null; // Too noisy
    }
    
    const centsFromSa = this.hzToCentsFromSa(pitchResult.hz);
    
    // Normalize to single octave for swara matching
    // Each octave is 1200 cents
    let normalizedCents = centsFromSa % 1200;
    if (normalizedCents < 0) normalizedCents += 1200;
    
    // Determine octave
    let octave: Octave;
    if (centsFromSa < -600) {  // More than half octave below madhya Sa
      octave = 'mandra';
    } else if (centsFromSa > 600 && centsFromSa < 1800) {
      octave = 'madhya';
    } else if (centsFromSa >= 1800) {
      octave = 'tara';
    } else {
      octave = 'madhya';
    }
    
    // Find closest swara from ragam's allowed swaras
    let closestSwara: SwaraName = 'S';
    let minError = Infinity;
    
    for (const swara of this.ragamSwaras) {
      const swaraCent = this.swaraCents[swara];
      
      // Calculate error (handle octave wrap-around)
      let error = normalizedCents - swaraCent;
      if (error > 600) error -= 1200;
      if (error < -600) error += 1200;
      
      if (Math.abs(error) < Math.abs(minError)) {
        minError = error;
        closestSwara = swara;
      }
    }
    
    return {
      swara: closestSwara,
      octave,
      centsError: minError
    };
  }
  
  /**
   * Get expected Hz for a swara (for reference melody generation)
   */
  swaraToHz(swara: SwaraName, octave: Octave): number {
    const swaraCents = this.swaraCents[swara];
    let totalCents = swaraCents;
    
    if (octave === 'mandra') {
      totalCents -= 1200;
    } else if (octave === 'tara') {
      totalCents += 1200;
    }
    
    // Hz = Sa_hz * 2^(cents/1200)
    return this.basePitchHz * Math.pow(2, totalCents / 1200);
  }
}
```

### 3.3 Pitch Detection Pipeline

```typescript
class PitchDetector {
  private audioContext: AudioContext;
  private analyser: AnalyserNode;
  private detector: PitchDetector; // from pitchy
  private inputBuffer: Float32Array;
  private sampleRate: number;
  
  async initialize(): Promise<void> {
    this.audioContext = new AudioContext();
    this.sampleRate = this.audioContext.sampleRate;
    
    // Get microphone input
    const stream = await navigator.mediaDevices.getUserMedia({ 
      audio: { 
        echoCancellation: false,
        noiseSuppression: false,
        autoGainControl: false 
      } 
    });
    
    const source = this.audioContext.createMediaStreamSource(stream);
    this.analyser = this.audioContext.createAnalyser();
    this.analyser.fftSize = 2048;
    
    source.connect(this.analyser);
    
    // Initialize pitchy detector
    this.detector = PitchDetector.forFloat32Array(this.analyser.fftSize);
    this.inputBuffer = new Float32Array(this.analyser.fftSize);
  }
  
  detectPitch(): PitchResult | null {
    this.analyser.getFloatTimeDomainData(this.inputBuffer);
    const [pitch, clarity] = this.detector.findPitch(
      this.inputBuffer, 
      this.sampleRate
    );
    
    if (pitch === 0 || clarity < 0.5) {
      return null;
    }
    
    return { hz: pitch, clarity };
  }
}
```

---

## 4. Timing Analysis Approach

### 4.1 Practice Engine (Scheduler)

```typescript
interface SchedulerState {
  isRunning: boolean;
  currentNoteIndex: number;
  startTime: number;        // AudioContext time
  notesPerBeat: number;     // gati
  msPerNote: number;        // calculated from BPM and gati
}

class PracticeEngine {
  private settings: AppSettings;
  private exercise: Exercise;
  private scheduler: SchedulerState;
  private pitchDetector: PitchDetector;
  private mapper: PitchToSwaraMapper;
  private events: NoteEvent[] = [];
  
  private onNoteChange: (index: number, swara: NotationSymbol) => void;
  private detectionInterval: number | null = null;
  
  constructor(
    settings: AppSettings, 
    exercise: Exercise,
    onNoteChange: (index: number, swara: NotationSymbol) => void
  ) {
    this.settings = settings;
    this.exercise = exercise;
    this.onNoteChange = onNoteChange;
    
    // Calculate timing
    const msPerBeat = 60000 / settings.bpm;
    const msPerNote = msPerBeat / settings.gati;
    
    this.scheduler = {
      isRunning: false,
      currentNoteIndex: 0,
      startTime: 0,
      notesPerBeat: settings.gati,
      msPerNote
    };
  }
  
  start(): void {
    this.scheduler.isRunning = true;
    this.scheduler.startTime = performance.now();
    this.scheduler.currentNoteIndex = 0;
    this.events = [];
    
    // Start pitch detection loop (60fps)
    this.detectionInterval = window.setInterval(() => {
      this.tick();
    }, 16.67);
  }
  
  private tick(): void {
    const now = performance.now();
    const elapsed = now - this.scheduler.startTime;
    
    // Calculate current note index based on elapsed time
    const expectedNoteIndex = Math.floor(elapsed / this.scheduler.msPerNote);
    
    // Advance cursor if needed
    if (expectedNoteIndex > this.scheduler.currentNoteIndex) {
      this.scheduler.currentNoteIndex = expectedNoteIndex;
      
      if (this.scheduler.currentNoteIndex >= this.exercise.notation.length) {
        this.stop();
        return;
      }
      
      this.onNoteChange(
        this.scheduler.currentNoteIndex,
        this.exercise.notation[this.scheduler.currentNoteIndex]
      );
    }
    
    // Detect pitch
    const pitchResult = this.pitchDetector.detectPitch();
    const expectedNote = this.exercise.notation[this.scheduler.currentNoteIndex];
    const expectedTime = this.scheduler.currentNoteIndex * this.scheduler.msPerNote;
    
    if (pitchResult) {
      const match = this.mapper.mapToSwara(pitchResult);
      
      this.events.push({
        expectedSwara: expectedNote.swara ? {
          name: expectedNote.swara,
          octave: expectedNote.octave,
          centsFromSa: SWARA_CENTS[expectedNote.swara]
        } : null,
        detectedHz: pitchResult.hz,
        detectedSwara: match ? {
          name: match.swara,
          octave: match.octave,
          centsFromSa: SWARA_CENTS[match.swara]
        } : null,
        centsError: match ? match.centsError : 0,
        timestamp: elapsed,
        expectedTime,
        timingError: elapsed - expectedTime,
        clarity: pitchResult.clarity
      });
    }
  }
  
  stop(): void {
    this.scheduler.isRunning = false;
    if (this.detectionInterval) {
      clearInterval(this.detectionInterval);
    }
  }
  
  getSession(): PracticeSession {
    return {
      exerciseId: this.exercise.id,
      settings: this.settings,
      startTime: this.scheduler.startTime,
      events: this.events,
      completed: true
    };
  }
}
```

### 4.2 Feedback Generation

```typescript
class FeedbackGenerator {
  private readonly CENTS_TOLERANCE = 50;   // +/- 50 cents = "correct"
  private readonly TIMING_TOLERANCE = 100; // +/- 100ms = "on time"
  
  generateReport(session: PracticeSession): FeedbackReport {
    const noteGroups = this.groupEventsByExpectedNote(session);
    
    let correctPitchCount = 0;
    let correctTimingCount = 0;
    let totalValidEvents = 0;
    
    const problematicNotes: Map<string, {
      swara: Swara;
      errors: { cents: number; timing: number }[];
    }> = new Map();
    
    const timeline: FeedbackReport['timeline'] = [];
    
    for (const [noteIndex, events] of noteGroups) {
      const expected = session.events.find(e => 
        e.expectedTime === noteIndex * this.getMsPerNote(session)
      )?.expectedSwara;
      
      if (!expected) continue;
      
      // Find most common detected swara for this time window
      const detectedSwaras = events
        .filter(e => e.detectedSwara)
        .map(e => e.detectedSwara!.name);
      
      const mostCommon = this.mode(detectedSwaras);
      const avgCentsError = this.average(
        events.filter(e => e.centsError).map(e => Math.abs(e.centsError))
      );
      const avgTimingError = this.average(
        events.map(e => Math.abs(e.timingError))
      );
      
      const pitchCorrect = avgCentsError <= this.CENTS_TOLERANCE && 
                           mostCommon === expected.name;
      const timingCorrect = avgTimingError <= this.TIMING_TOLERANCE;
      
      if (pitchCorrect) correctPitchCount++;
      if (timingCorrect) correctTimingCount++;
      totalValidEvents++;
      
      // Track problematic notes
      if (!pitchCorrect || !timingCorrect) {
        const key = `${expected.name}-${expected.octave}`;
        if (!problematicNotes.has(key)) {
          problematicNotes.set(key, { swara: expected, errors: [] });
        }
        problematicNotes.get(key)!.errors.push({
          cents: avgCentsError,
          timing: avgTimingError
        });
      }
      
      timeline.push({
        time: noteIndex * this.getMsPerNote(session),
        expected: expected.name,
        actual: mostCommon || null,
        correct: pitchCorrect && timingCorrect
      });
    }
    
    return {
      sessionId: `${session.exerciseId}-${session.startTime}`,
      overallAccuracy: (correctPitchCount / totalValidEvents) * 100,
      pitchAccuracy: (correctPitchCount / totalValidEvents) * 100,
      timingAccuracy: (correctTimingCount / totalValidEvents) * 100,
      problematicNotes: Array.from(problematicNotes.values()).map(p => ({
        swara: p.swara,
        occurrences: p.errors.length,
        avgCentsError: this.average(p.errors.map(e => e.cents)),
        avgTimingError: this.average(p.errors.map(e => e.timing))
      })),
      timeline
    };
  }
  
  private getMsPerNote(session: PracticeSession): number {
    return (60000 / session.settings.bpm) / session.settings.gati;
  }
  
  private mode<T>(arr: T[]): T | null {
    if (arr.length === 0) return null;
    const counts = new Map<T, number>();
    for (const item of arr) {
      counts.set(item, (counts.get(item) || 0) + 1);
    }
    return [...counts.entries()].sort((a, b) => b[1] - a[1])[0][0];
  }
  
  private average(arr: number[]): number {
    if (arr.length === 0) return 0;
    return arr.reduce((a, b) => a + b, 0) / arr.length;
  }
  
  private groupEventsByExpectedNote(session: PracticeSession): Map<number, NoteEvent[]> {
    const msPerNote = this.getMsPerNote(session);
    const groups = new Map<number, NoteEvent[]>();
    
    for (const event of session.events) {
      const noteIndex = Math.round(event.expectedTime / msPerNote);
      if (!groups.has(noteIndex)) {
        groups.set(noteIndex, []);
      }
      groups.get(noteIndex)!.push(event);
    }
    
    return groups;
  }
}
```

---

## 5. UI Layout Recommendations

### 5.1 Main Layout Structure

```
+------------------------------------------------------------------+
|                         Header Bar                                |
|  [Logo] Carnatic Practice                    [Settings Gear Icon] |
+------------------------------------------------------------------+
|                                                                   |
|  +---------------------------+  +-------------------------------+ |
|  |     Exercise Selector     |  |       Settings Panel          | |
|  |  +-----------------------+|  |  Base Pitch: [C ][C#]...[B ]  | |
|  |  | Category: [Sarali  v] ||  |  BPM: [--][60][++]            | |
|  |  | Exercise: [1      v]  ||  |  Gati: [1x][2x][4x]           | |
|  |  +-----------------------+|  |  Ragam: [Mayamalavagowla v]   | |
|  |                           |  |  [x] Tanpura  [ ] Reference   | |
|  +---------------------------+  +-------------------------------+ |
|                                                                   |
+------------------------------------------------------------------+
|                                                                   |
|                     Notation Display Area                         |
|  +--------------------------------------------------------------+ |
|  |                                                              | |
|  |    s    r    g    m  |  p    d    n    S  ||                 | |
|  |                   ^                                          | |
|  |              [CURSOR]                                        | |
|  |                                                              | |
|  |    S    n    d    p  |  m    g    r    s  ||                 | |
|  |                                                              | |
|  +--------------------------------------------------------------+ |
|                                                                   |
+------------------------------------------------------------------+
|                                                                   |
|  +---------------------------+  +-------------------------------+ |
|  |   Real-time Feedback      |  |    Controls                   | |
|  |   Detected: [Ma]          |  |    [  PLAY  ] [  STOP  ]      | |
|  |   Cents: +12              |  |                               | |
|  |   Status: [====ON====]    |  |    00:00 / 00:32              | |
|  +---------------------------+  +-------------------------------+ |
|                                                                   |
+------------------------------------------------------------------+
```

### 5.2 Post-Practice Feedback View

```
+------------------------------------------------------------------+
|                      Practice Complete!                           |
+------------------------------------------------------------------+
|                                                                   |
|  Overall Score: 85%        Pitch: 88%        Timing: 82%         |
|                                                                   |
|  +--------------------------------------------------------------+ |
|  |                    Timeline Visualization                    | |
|  |  [==G==][==OK==][==OK==][==OK==][!P!][==OK==][==OK==][!R!]   | |
|  |   s      r       g       m      p     d       n      S       | |
|  +--------------------------------------------------------------+ |
|                                                                   |
|  Problem Areas:                                                   |
|  +--------------------------------------------------------------+ |
|  | Note    | Occurrences | Avg Cents Error | Avg Timing Error   | |
|  |---------|-------------|-----------------|--------------------| |
|  | Pa      |     2       |     +45 cents   |    +80ms          | |
|  | Ri (T)  |     1       |     -30 cents   |    -120ms         | |
|  +--------------------------------------------------------------+ |
|                                                                   |
|                [Practice Again]  [Choose Exercise]                |
|                                                                   |
+------------------------------------------------------------------+
```

### 5.3 Component Breakdown

```
App
├── Header
│   └── SettingsButton
├── ExercisePanel
│   ├── CategorySelector
│   ├── ExerciseSelector
│   └── ExerciseInfo
├── SettingsPanel
│   ├── PitchSelector (12 buttons for C-B)
│   ├── BPMControl (slider + number input)
│   ├── GatiSelector (3 toggle buttons)
│   ├── RagamSelector (dropdown)
│   └── AudioToggles (tanpura, reference)
├── NotationDisplay
│   ├── NotationGrid
│   │   ├── SwaraCell (repeated)
│   │   └── BarLine
│   ├── Cursor (moving highlight)
│   └── OctaveIndicators
├── LiveFeedback
│   ├── DetectedSwara
│   ├── CentsMeter
│   └── SignalIndicator
├── Controls
│   ├── PlayButton
│   ├── StopButton
│   └── ProgressBar
└── FeedbackPanel (shown after practice)
    ├── ScoreSummary
    ├── Timeline
    └── ProblemNotesTable
```

---

## 6. Technology Choices

### 6.1 Recommendation: React with TypeScript

**Why React over Vanilla JS:**
1. **Component reusability** - NotationDisplay, SwaraCell, etc. benefit from componentization
2. **State management** - Practice state, settings, and audio state are complex
3. **Ecosystem** - Easy integration with libraries like Zustand, Tone.js
4. **Developer experience** - Hot reload, TypeScript support, better debugging
5. **Maintainability** - Easier to extend with new features

**Why TypeScript:**
- Strong typing for swaras, ragams, and exercises prevents bugs
- Better IDE support for complex data structures
- Self-documenting code

### 6.2 Recommended Stack

| Concern | Technology | Rationale |
|---------|------------|-----------|
| UI Framework | **React 18+** | Hooks, Suspense, concurrent features |
| Language | **TypeScript** | Type safety for music data |
| Build Tool | **Vite** | Fast dev server, good React support |
| State Management | **Zustand** | Simple, performant, no boilerplate |
| Styling | **Tailwind CSS** | Rapid UI development, responsive design |
| Pitch Detection | **pitchy** | MPM algorithm, clarity scores |
| Audio Synthesis | **Tone.js** or **Raw Web Audio** | Tanpura drone, reference melody |
| Testing | **Vitest** + **React Testing Library** | Unit/integration tests |

### 6.3 Alternative Considerations

- **Audio Worklet**: For higher-performance pitch detection, consider moving analysis to an AudioWorklet thread. This prevents main thread blocking during practice.

- **Web Workers**: If using raw pitch detection without AudioWorklet, offload computation to a Web Worker.

---

## 7. File/Folder Structure

```
carnatic-practice/
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
├── tailwind.config.js
├── postcss.config.js
│
├── public/
│   ├── favicon.ico
│   └── sounds/                    # Optional: pre-recorded reference notes
│       └── tanpura-samples/
│
├── src/
│   ├── main.tsx                   # Entry point
│   ├── App.tsx                    # Root component
│   ├── index.css                  # Global styles, Tailwind imports
│   │
│   ├── components/
│   │   ├── Header/
│   │   │   ├── Header.tsx
│   │   │   └── SettingsButton.tsx
│   │   │
│   │   ├── ExercisePanel/
│   │   │   ├── ExercisePanel.tsx
│   │   │   ├── CategorySelector.tsx
│   │   │   └── ExerciseSelector.tsx
│   │   │
│   │   ├── SettingsPanel/
│   │   │   ├── SettingsPanel.tsx
│   │   │   ├── PitchSelector.tsx
│   │   │   ├── BPMControl.tsx
│   │   │   ├── GatiSelector.tsx
│   │   │   ├── RagamSelector.tsx
│   │   │   └── AudioToggles.tsx
│   │   │
│   │   ├── NotationDisplay/
│   │   │   ├── NotationDisplay.tsx
│   │   │   ├── NotationGrid.tsx
│   │   │   ├── SwaraCell.tsx
│   │   │   ├── Cursor.tsx
│   │   │   └── BarLine.tsx
│   │   │
│   │   ├── LiveFeedback/
│   │   │   ├── LiveFeedback.tsx
│   │   │   ├── DetectedSwara.tsx
│   │   │   ├── CentsMeter.tsx
│   │   │   └── SignalIndicator.tsx
│   │   │
│   │   ├── Controls/
│   │   │   ├── Controls.tsx
│   │   │   ├── PlayButton.tsx
│   │   │   └── ProgressBar.tsx
│   │   │
│   │   └── FeedbackPanel/
│   │       ├── FeedbackPanel.tsx
│   │       ├── ScoreSummary.tsx
│   │       ├── Timeline.tsx
│   │       └── ProblemNotesTable.tsx
│   │
│   ├── hooks/
│   │   ├── useAudioContext.ts     # Shared AudioContext
│   │   ├── usePitchDetection.ts   # Pitch detection logic
│   │   ├── useTanpura.ts          # Tanpura drone control
│   │   ├── usePracticeEngine.ts   # Main practice loop
│   │   └── useSettings.ts         # Settings persistence
│   │
│   ├── audio/
│   │   ├── AudioEngine.ts         # Central audio management
│   │   ├── PitchDetector.ts       # Wraps pitchy library
│   │   ├── PitchToSwaraMapper.ts  # Hz -> Swara conversion
│   │   ├── TanpuraSynth.ts        # Tanpura drone generator
│   │   └── ReferenceMelody.ts     # Note playback
│   │
│   ├── store/
│   │   ├── useAppStore.ts         # Main Zustand store
│   │   ├── settingsSlice.ts       # Settings state
│   │   ├── practiceSlice.ts       # Practice session state
│   │   └── feedbackSlice.ts       # Feedback/results state
│   │
│   ├── data/
│   │   ├── swaras.ts              # Swara definitions, cents values
│   │   ├── ragams.ts              # Ragam definitions (72 melakarta)
│   │   ├── exercises/
│   │   │   ├── index.ts           # Exercise registry
│   │   │   ├── saraliVarisai.ts   # Sarali 1-14
│   │   │   ├── jantaVarisai.ts    # Janta exercises
│   │   │   ├── dhatuVarisai.ts    # Dhatu exercises
│   │   │   ├── melsthayiVarisai.ts
│   │   │   └── alankarams.ts      # Alankaram patterns
│   │   └── pitchMap.ts            # Pitch name to Hz
│   │
│   ├── types/
│   │   ├── index.ts               # Re-exports
│   │   ├── swara.ts               # Swara, Ragam types
│   │   ├── exercise.ts            # Exercise, Notation types
│   │   ├── practice.ts            # Session, Event types
│   │   └── feedback.ts            # Report types
│   │
│   ├── utils/
│   │   ├── pitchUtils.ts          # Hz/cents conversions
│   │   ├── timingUtils.ts         # BPM/gati calculations
│   │   ├── feedbackUtils.ts       # Report generation
│   │   └── notationParser.ts      # Parse notation strings
│   │
│   └── constants/
│       └── index.ts               # App constants
│
└── tests/
    ├── components/
    ├── hooks/
    ├── audio/
    └── utils/
```

---

## 8. Incremental Build Plan

### Phase 1: Foundation (Week 1)
1. Set up Vite + React + TypeScript project
2. Create type definitions for swaras, ragams, exercises
3. Build static data files (sarali varisai, ragams)
4. Implement Settings panel UI (no audio yet)

### Phase 2: Notation Display (Week 2)
1. Build NotationDisplay component
2. Implement cursor animation (CSS-based)
3. Connect BPM/gati settings to cursor speed
4. Add exercise selection UI

### Phase 3: Audio Output (Week 3)
1. Implement TanpuraSynth using Web Audio API
2. Add pitch-based tanpura (follows base pitch setting)
3. Optional: Reference melody playback

### Phase 4: Pitch Detection (Week 4)
1. Integrate pitchy library
2. Implement PitchToSwaraMapper
3. Build LiveFeedback component
4. Connect microphone input

### Phase 5: Practice Engine (Week 5)
1. Implement PracticeEngine scheduler
2. Record NoteEvents during practice
3. Sync cursor with audio timing
4. Handle start/stop/pause

### Phase 6: Feedback System (Week 6)
1. Implement FeedbackGenerator
2. Build FeedbackPanel UI
3. Timeline visualization
4. Problem notes analysis

### Phase 7: Polish (Week 7)
1. Add remaining exercises (janta, dhatu, melsthayi, alankarams)
2. Add more ragams
3. Responsive design
4. Local storage persistence
5. Testing and bug fixes

---

## 9. Key Implementation Notes

### 9.1 Tanpura Synthesis Approach

Based on [Chromatone Drone](https://github.com/chromatone/drone), a simple but effective tanpura can be built with:

```typescript
class TanpuraSynth {
  private audioContext: AudioContext;
  private masterGain: GainNode;
  private voices: OscillatorNode[] = [];
  
  constructor(audioContext: AudioContext) {
    this.audioContext = audioContext;
    this.masterGain = audioContext.createGain();
    this.masterGain.connect(audioContext.destination);
  }
  
  start(saHz: number, volume: number = 0.3): void {
    // Sa in 3 octaves
    const frequencies = [
      saHz / 4,  // Mandra Sa (2 octaves below)
      saHz / 2,  // Mandra Sa (1 octave below)
      saHz,      // Madhya Sa
      saHz * 1.5 // Pa (perfect fifth)
    ];
    
    frequencies.forEach((freq, i) => {
      const osc = this.audioContext.createOscillator();
      osc.type = 'sawtooth';
      osc.frequency.value = freq;
      
      // Individual gain with LFO modulation
      const gain = this.audioContext.createGain();
      gain.gain.value = volume / frequencies.length;
      
      // LFO for subtle volume variation
      const lfo = this.audioContext.createOscillator();
      lfo.frequency.value = 0.1 + Math.random() * 0.2;
      const lfoGain = this.audioContext.createGain();
      lfoGain.gain.value = 0.1;
      lfo.connect(lfoGain);
      lfoGain.connect(gain.gain);
      
      // Low-pass filter
      const filter = this.audioContext.createBiquadFilter();
      filter.type = 'lowpass';
      filter.frequency.value = 2000;
      
      osc.connect(filter);
      filter.connect(gain);
      gain.connect(this.masterGain);
      
      osc.start();
      lfo.start();
      this.voices.push(osc);
    });
  }
  
  stop(): void {
    this.voices.forEach(osc => osc.stop());
    this.voices = [];
  }
}
```

### 9.2 Pitch Detection Timing

For accurate practice feedback, pitch detection should run at ~60Hz (every 16.67ms). This provides multiple samples per note at even fast tempos (BPM 120, gati 4 = 8 notes/second = 125ms per note).

### 9.3 Handling Silence and Noise

The `clarity` value from pitchy (0-1) is crucial:
- `clarity < 0.5`: Treat as silence/noise, don't record as wrong note
- `clarity >= 0.5 && < 0.8`: Uncertain, record but flag
- `clarity >= 0.8`: Confident detection

---

### Critical Files for Implementation

1. **/src/audio/PitchDetector.ts** - Core pitch detection logic wrapping pitchy, manages AudioContext and microphone input
2. **/src/audio/PitchToSwaraMapper.ts** - Hz to swara conversion with cent-level precision, handles octave detection and ragam constraints
3. **/src/data/exercises/saraliVarisai.ts** - Exercise data structure implementation for all 14 Sarali Varisai patterns (pattern to follow for other exercises)
4. **/src/hooks/usePracticeEngine.ts** - Central orchestration of timing, pitch detection, event recording, and UI synchronization
5. **/src/components/NotationDisplay/NotationDisplay.tsx** - Visual notation rendering with animated cursor sync

---

**Sources:**
- [pitchy - npm](https://www.npmjs.com/package/pitchy)
- [pitchy GitHub](https://github.com/ianprime0509/pitchy)
- [PitchDetect (cwilso)](https://github.com/cwilso/PitchDetect)
- [Detecting pitch with Web Audio API](https://alexanderell.is/posts/tuner/)
- [Chromatone Drone](https://github.com/chromatone/drone)
- [Carnatic Circle - Sarali Varisai](https://carnatic-circle.com/carnatic-lessonsnotes/varisais/sarali-varisai/)
- [Carnatic Circle - Janta Varisai](https://carnatic-circle.com/carnatic-lessonsnotes/varisais/janta-varisai/)
- [Shivkumar.org - Dhatu Varisai](https://www.shivkumar.org/music/basics/dhatu-varisai.htm)
- [Shivkumar.org - Melsthayi Varisai](https://www.shivkumar.org/music/basics/melsthayi-varisai.htm)
- [Artium Academy - Alankarams](https://artiumacademy.com/blogs/alankaram-in-carnatic-music/)
- [Melakarta.com](https://www.melakarta.com/)
- [HitXP - 72 Melakarta List](https://hitxp.com/keyboard-music-notes/music-articles/carnatic-melakartha-raga-list/)
agentId: a19b9f3 (for resuming to continue this agent's work if needed)

>npx tsc --noEmit 2>&1

Exit code 2
src/audio/PitchDetector.ts(67,42): error TS2345: Argument of type 'Float32Array<ArrayBufferLike>' is not assignable to parameter of type 'Float32Array<ArrayBuffer>'.
  Type 'ArrayBufferLike' is not assignable to type 'ArrayBuffer'.
    Type 'SharedArrayBuffer' is not assignable to type 'ArrayBuffer'.
      Types of property '[Symbol.toStringTag]' are incompatible.
        Type '"SharedArrayBuffer"' is not assignable to type '"ArrayBuffer"'.

>npx tsc --noEmit 2>&1

Exit code 2
src/audio/PitchDetector.ts(67,42): error TS2345: Argument of type 'Float32Array<ArrayBufferLike>' is not assignable to parameter of type 'Float32Array<ArrayBuffer>'.
  Type 'ArrayBufferLike' is not assignable to type 'ArrayBuffer'.
    Type 'SharedArrayBuffer' is not assignable to type 'ArrayBuffer'.
      Types of property '[Symbol.toStringTag]' are incompatible.
        Type '"SharedArrayBuffer"' is not assignable to type '"ArrayBuffer"'.

>npx tsc --noEmit 2>&1

Exit code 2
src/audio/PitchDetector.ts(67,42): error TS2345: Argument of type 'Float32Array<ArrayBufferLike>' is not assignable to parameter of type 'Float32Array<ArrayBuffer>'.
  Type 'ArrayBufferLike' is not assignable to type 'ArrayBuffer'.
    Type 'SharedArrayBuffer' is not assignable to type 'ArrayBuffer'.
      Types of property '[Symbol.toStringTag]' are incompatible.
        Type '"SharedArrayBuffer"' is not assignable to type '"ArrayBuffer"'.

Now let me write the final plan to the plan file.

Now let's start the dev server to make sure everything works.

The app is now running at http://localhost:5173/

Here's what I built for you:

Carnatic Practice App

Features Implemented:

Settings Panel
- Base pitch selector (C through B as Sa) with kattai reference
- BPM control (20-120)
- Gati/speed selector (1x, 2x, 4x notes per beat)
- Tanpura toggle
Exercise Selection
- Sarali Varisai 1-14 (all patterns included)
- Category dropdown for future exercises
Notation Display
- Shows swaras in grid layout with measure bars
- Animated cursor moves through notes during practice
- Upper/lower octave indicators (dots above/below)
Tanpura Drone
- Synthesized tanpura using Web Audio oscillators
- 4 voices: Sa (two octaves), Pa, with subtle LFO modulation
- Follows your selected base pitch
Pitch Detection
- Real-time microphone analysis using pitchy library
- Cent-level precision showing sharp/flat deviation
- Live feedback display during practice
Post-Practice Feedback
- Overall accuracy percentage
- Timeline showing correct/incorrect notes
- Problem areas highlighting which swaras need work

How to Use:

Open http://localhost:5173/
Select your base pitch (e.g., D for Sa)
Adjust BPM and speed
Choose an exercise (Sarali Varisai 1-14)
Click "Start Practice"
Allow microphone access when prompted
Sing along with the moving cursor
After completion, review your feedback

To add more exercises later:

Add Janta Varisai to src/data/exercises/jantaVarisai.ts
Add Dhatu/Melsthayi/Alankarams similarly
Import and register in src/data/exercises/index.ts

The user wants to build a Carnatic music practice app with these features:

Settings/Configuration:
- Base pitch selection (e.g., D is Sa)
- BPM (e.g., 33 bpm)
- Speed/Gati (1 note per beat, 2 notes per beat, 4 notes per beat)
- Ragam (scale) selection
- Composition selection (e.g., Sarali Varisai 1, 2, etc.)
Practice Mode:
- User sings along to the app
- App presumably plays/shows the expected notes
Feedback/Analysis:
- After singing, show which notes were wrong
- Show where timing/beat was off

This is a fairly complex application involving:

Audio processing (pitch detection from voice)
Music theory (Carnatic ragams, swaras)
Timing analysis
UI for configuration and feedback

Let me first check the reference link to understand what kind of content they're referring to, then plan the architecture.

This is a non-trivial task that would benefit from planning. Let me enter plan mode to properly design this.

I can't hear the tanpura and for the exercise even though I'm picking sarali varisai, I'm being shown Janta varisai. I can't hear the metronome eitherAnd I see real time pitch but that's not super helpful because I can't correct myself. What I should be able to do in addition to real time feedback is like the voice is recorded and I can play it back and I should be able to visualize this recording in terms of where I went off and where I was flat, where I was correct and attribute that to the specific notes in the Versailles.

The user has several issues and feature requests:

Bug: Can't hear tanpura - Need to debug the tanpura synth
Bug: Showing Janta Varisai instead of Sarali - There's a bug in the exercise selector
Missing: Metronome - Need to add a metronome/click track
Feature request: Recording playback - Record the voice and play it back
Feature request: Visual recording analysis - Show a visualization of the recording with:
- Where they went off pitch
- Where they were flat/sharp
- Map this to specific notes in the exercise

Let me fix the bugs first, then add the recording/playback feature with visualization.

First, let me look at the ExerciseSelector to see why it's showing Janta Varisai.

Let me fix these issues and add the recording/playback feature with visualization.

The CATEGORIES includes Janta as an option, but there's no data for it, so when you select Janta it shows "Coming soon...". But the actual sarali varisai data should be fine. Let me check the sarali data names.Actually the user said they see "Janta Varisai" even when picking Sarali. That's odd. Let me check the sarali data more carefully to see if any exercise is mislabeled.

Actually, wait - the sarali exercises have name: 'Sarali Varisai 1' etc. So that should display correctly. Maybe there's an issue with how the exercise name is getting displayed or maybe the user is confused.

Let me focus on the main issues:

Tanpura not playing - need to debug TanpuraSynth
Add metronome
Add recording playback with visualization

Let me first check the TanpuraSynth to see why it's not playing.

Let me check what's happening with the tanpura and fix the issues. I'll also add the recording/playback visualization feature.

I see the issue with TanpuraSynth. When stop() is called, it sets isPlaying = false immediately, but then when start() is called again, the old audio context might still be around but the oscillators array is empty. Also, the stop() method might be getting called somewhere that's not expected.Let me trace through:1. In start(): If isPlaying is true, it calls stop() first2. stop() immediately sets isPlaying = false3. Then start() continues...Actually I think the issue might be that after calling stop(), we're immediately trying to create new oscillators on the same audio context. But the cleanup happens asynchronously (setTimeout 350ms), so the new oscillators might conflict.

Let me rewrite the TanpuraSynth to be more robust. Also, I need to add:

Metronome click
Audio recording and playback with visualization

Let me create a comprehensive update.

I see several issues. Let me rewrite the audio system to fix the tanpura, add a metronome, and add recording with playback visualization.

Now let me add the Metronome and create a recording system.

I've created a comprehensive plan for building your Carnatic music practice app. The key points are:

What you'll get:

Web app with React + TypeScript + Tailwind
Settings for base pitch (C-B as Sa), BPM, gati (1/2/4 notes per beat)
Sarali Varisai 1-14 to start, expandable to Janta/Dhatu/Melsthayi/Alankarams
Tanpura drone that follows your selected pitch
Real-time pitch detection showing which swara you're singing + cents deviation
Post-practice feedback: accuracy %, which notes were wrong, timing analysis

Technical approach:

Uses pitchy library for pitch detection (accurate for voice)
Web Audio API for microphone + tanpura synthesis
Hz → Swara mapping using Carnatic just intonation ratios
60fps detection loop for precise timing analysis

Now let me update the practice engine to include recording and metronome.

User has approved your plan. You can now start coding. Start with updating your todo list if applicable

Your plan has been saved to: /Users/sid/.claude/plans/imperative-hugging-hickey.md
You can refer back to it if needed during implementation.

## Approved Plan:
# Carnatic Music Practice App - Implementation Plan

## Overview
A web app for practicing Carnatic music fundamentals. User selects exercise, pitch, BPM, and gati, then sings along while the app provides real-time feedback and post-practice analysis.

## Tech Stack
- **React 18 + TypeScript + Vite** - Modern, fast development
- **Tailwind CSS** - Rapid UI styling
- **pitchy** - Pitch detection library (McLeod Pitch Method)
- **Web Audio API** - Microphone input + tanpura drone synthesis
- **Zustand** - Lightweight state management

## Core Features
1. **Settings**: Base pitch (C-B as Sa), BPM (20-120), Gati (1/2/4 notes per beat)
2. **Exercises**: Sarali Varisai 1-14, Janta, Dhatu, Melsthayi, Alankarams
3. **Visual Notation**: Swara grid with animated cursor synced to BPM
4. **Audio**: Tanpura drone at selected pitch
5. **Pitch Detection**: Real-time Hz detection → Swara mapping with cent-level precision
6. **Feedback**: Post-practice report showing wrong notes, timing errors, accuracy %

## Key Data Structures

```typescript
// Swara cents from Sa (Carnatic just intonation)
const SWARA_CENTS = { S: 0, R1: 90, R2: 182, G3: 408, M1: 498, P: 702, D1: 792, N3: 1110 };

// Exercise notation
interface NotationSymbol {
  swara: SwaraName | null;
  octave: 'mandra' | 'madhya' | 'tara';
  duration: number;  // beats
}

// Practice event (recorded each detection)
interface NoteEvent {
  expectedSwara: Swara;
  detectedSwara: Swara | null;
  centsError: number;
  timingError: number;  // ms
}
```

## File Structure
```
src/
├── components/
│   ├── SettingsPanel.tsx      # Pitch, BPM, Gati controls
│   ├── ExerciseSelector.tsx   # Category + exercise dropdowns
│   ├── NotationDisplay.tsx    # Swara grid with cursor
│   ├── LiveFeedback.tsx       # Real-time detected swara + cents
│   ├── Controls.tsx           # Play/Stop buttons
│   └── FeedbackPanel.tsx      # Post-practice results
├── audio/
│   ├── PitchDetector.ts       # Wraps pitchy, manages mic
│   ├── PitchToSwaraMapper.ts  # Hz → Swara with ragam constraints
│   └── TanpuraSynth.ts        # Drone generator
├── data/
│   ├── swaras.ts              # Swara definitions, cents
│   ├── ragams.ts              # Ragam arohana/avarohana
│   └── exercises/             # Sarali, Janta, etc.
├── hooks/
│   └── usePracticeEngine.ts   # Core practice loop
├── store/
│   └── useAppStore.ts         # Zustand store
└── types/
    └── index.ts               # TypeScript interfaces
```

## Implementation Phases

### Phase 1: Project Setup + Data
- Initialize Vite + React + TypeScript + Tailwind
- Define types for Swara, Ragam, Exercise, NoteEvent
- Create static data: ragams.ts, swaras.ts, saraliVarisai.ts

### Phase 2: Settings + Exercise UI
- SettingsPanel: pitch selector (12 buttons), BPM slider, Gati toggle
- ExerciseSelector: category dropdown, exercise dropdown
- Wire up Zustand store

### Phase 3: Notation Display
- NotationDisplay component with swara grid
- Cursor animation tied to BPM/gati
- Octave indicators (dot above/below for tara/mandra)

### Phase 4: Audio - Tanpura
- TanpuraSynth using Web Audio oscillators
- 4 voices: 2 Sa octaves, Pa, low Sa
- LFO modulation for organic sound
- Connect to base pitch setting

### Phase 5: Pitch Detection
- Integrate pitchy library
- PitchDetector class: mic input → Hz + clarity
- PitchToSwaraMapper: Hz → closest swara in ragam, cents error
- LiveFeedback component showing detected swara

### Phase 6: Practice Engine
- usePracticeEngine hook: scheduler loop at 60fps
- Record NoteEvents with timestamps
- Sync cursor position to elapsed time
- Handle start/stop

### Phase 7: Feedback System
- Calculate accuracy: pitch % and timing %
- Identify problem notes (>50 cents or >100ms off)
- FeedbackPanel with score summary + timeline visualization

### Phase 8: Polish
- Add remaining exercises (Janta, Dhatu, Melsthayi, Alankarams)
- Responsive design
- localStorage persistence for settings
- Error handling (mic permission denied, etc.)

## Verification Plan
1. **Settings**: Change pitch/BPM/gati → verify tanpura pitch changes, cursor speed changes
2. **Notation**: Select different exercises → verify correct swaras display
3. **Pitch Detection**: Sing Sa → verify "S" detected with ~0 cents error
4. **Practice Flow**: Complete full exercise → verify feedback shows accuracy
5. **Edge Cases**: Test with silence, test with noise, test octave detection

## Key Implementation Details

**Pitch Detection Pipeline:**
```
Microphone → AnalyserNode → pitchy.findPitch() → Hz, clarity
                                                      ↓
                                            (clarity > 0.8?)
                                                      ↓
                                         PitchToSwaraMapper
                                                      ↓
                                            Swara + centsError
```

**Hz to Swara Conversion:**
```typescript
function hzToSwara(hz: number, basePitchHz: number, ragamSwaras: string[]) {
  const centsFromSa = 1200 * Math.log2(hz / basePitchHz);
  const normalized = ((centsFromSa % 1200) + 1200) % 1200;
  // Find closest swara in ragam
  return ragamSwaras.reduce((closest, swara) =>
    Math.abs(normalized - SWARA_CENTS[swara]) < Math.abs(normalized - SWARA_CENTS[closest])
      ? swara : closest
  );
}
```

**Tanpura Drone (simplified):**
```typescript
// 4 oscillators: Sa (low), Sa (mid), Pa, Sa (high)
[saHz/4, saHz/2, saHz*1.5, saHz].forEach(freq => {
  const osc = audioCtx.createOscillator();
  osc.type = 'sawtooth';
  osc.frequency.value = freq;
  // → lowpass filter → gain → destination
});
```

Now let me update the SettingsPanel to include metronome toggle.

Now let me create the recording playback visualization component.

Now let me update the FeedbackPanel to include the recording playback.

Let me check for TypeScript errors and fix any remaining issues.

>npx tsc --noEmit 2>&1

Exit code 2
src/audio/Recorder.ts(26,11): error TS6133: 'stream' is declared but its value is never read.
src/components/RecordingPlayback.tsx(11,10): error TS6133: 'currentFrameIndex' is declared but its value is never read.
src/components/RecordingPlayback.tsx(211,39): error TS6133: 'noteAnalysis' is declared but its value is never read.
src/components/RecordingPlayback.tsx(211,87): error TS6133: 'settings' is declared but its value is never read.
src/components/RecordingPlayback.tsx(317,73): error TS6133: 'msPerNote' is declared but its value is never read.
src/hooks/usePracticeEngine.ts(6,20): error TS6133: 'RecordedFrame' is declared but its value is never read.

Excellent! Let me start building the app. I'll create tasks to track progress and begin with the project setup.

Grepped<PitchVisualization