Dhwani

Dhwani is a precision vocal tuner engine designed specifically for Hindustani Classical Music. Unlike standard tuners that use Equal Temperament (12-TET), Dhwani uses Just Intonation relative to a base Sa, making it accurate for Indian Classical frequencies.

It functions as both a standalone Web Application and a lightweight, dependency-free Node.js Library.

🎵 For Musicians: The Web App

Dhwani is available as a free, responsive web application. It features a noise-resistant detection algorithm, a "visual tape" interface, and dark mode support.

👉 Launch Tuner: dhwani.mgks.dev

Features

• Real-time Swar Detection: Identifies the closest Hindustani note (Sa, re, Re, ga, Ga...).
• Just Intonation: Tuned to the harmonic series (e.g., Pa is exactly 1.5x Sa), not the compromised piano tuning.
• Visual Feedback: A sliding dial shows exactly how many "cents" (microtones) you are sharp or flat.
• Offline Capable: Install it as a PWA (Progressive Web App) on your phone or desktop to use without internet.

👨‍💻 For Developers: The NPM Package

You can use the core pitch detection logic of Dhwani in your own music education apps, games, or research tools. The library is "headless" (no UI), zero-dependency, and lightweight.

Installation

npm install dhwani

Usage

The library provides a straightforward API to detect pitch from raw audio buffers and map frequencies to Hindustani notes.

import { Dhwani } from 'dhwani';

// 1. Initialize
const tuner = new Dhwani({
    sampleRate: 44100, // Audio Context Sample Rate
    threshold: 0.1     // YIN Algorithm sensitivity (lower is stricter)
});

// 2. Detect Pitch (Raw Hz)
// 'buffer' should be a Float32Array from AnalyserNode.getFloatTimeDomainData()
const frequency = tuner.getPitch(buffer); 

if (frequency) {
    console.log(`Detected: ${frequency.toFixed(2)} Hz`);

    // 3. Map to Hindustani Swar
    const note = tuner.getNote(frequency);
    
    if (note) {
        console.log(`Swar: ${note.swar} (Octave ${note.octave})`);
        console.log(`Deviation: ${note.cents.toFixed(0)} cents`);
    }
}

API Reference

new Dhwani(config)

• config.sampleRate (number): The sample rate of your audio source (usually 44100 or 48000).
• config.threshold (number, optional): YIN algorithm threshold (0.05 - 0.2). Defaults to 0.1.

getPitch(buffer)

• Analyzes a Float32Array (time domain data).
• Returns: number (Frequency in Hz) or null (if silence/noise).

getNote(frequency)

• Maps a frequency to the closest Just Intonation Swar.
• Returns an object:

  {
    "swar": "Pa",
    "octave": 0,
    "cents": -4.2,       // Deviation from the perfect harmonic frequency
    "frequency": 360     // The ideal frequency of this Swar
  }

🛠️ Development (Monorepo)

This repository is a monorepo containing both the core logic and the web interface.

Directory Structure

• packages/core: The NPM package source code (Math & Logic).
• packages/web: The Vite-based Web Application (UI).

Local Setup

1. Clone the repository:

   git clone https://github.com/mgks/dhwani.git
   cd dhwani

2. Install dependencies (Root):

   npm install

3. Run the Web App: This starts the Vite development server and links the local core package automatically.

   npm run dev

4. Build for Production:

   npm run build

🧮 Tuning System

Dhwani uses a Just Intonation scale centered around Sa = 240Hz (approx B3, common for male vocals) for relative calculation.

Swar	Ratio relative to Sa	Ideal Freq (Example)
Sa	1/1	240 Hz
re (Komal)	16/15	256 Hz
Re (Shuddh)	9/8	270 Hz
ga (Komal)	6/5	288 Hz
Ga (Shuddh)	5/4	300 Hz
Ma (Shuddh)	4/3	320 Hz
Ma# (Tivra)	45/32	337.5 Hz
Pa	3/2	360 Hz
dha (Komal)	8/5	384 Hz
Dha (Shuddh)	5/3	400 Hz
ni (Komal)	9/5	450 Hz
Ni (Shuddh)	15/8	480 Hz

License

MIT

{ github.com/mgks }