An AI Framework for Learning and Generating Carnatic Ragas
DeepRaaga is an open-source platform dedicated to modeling the intricate structural beauty of Carnatic music using Artificial Intelligence. By harmonizing traditional heritage with modern machine learning paradigms, we strive to build a computational bridge to India's rich musical legacy.
Inspired by the visionary dialogue between PM Narendra Modi and veteran composer Ramesh Vinayakam on creating a "National Knowledge Repository" for Indian music, DeepRaaga stands as a foundational step toward that goal.
Carnatic music cannot be reduced to simple discrete notes; it is defined by the continuous, microtonal inflections (Gamakas), characteristic melodic pathways (Sancharas), and the strict grammatical constraints of ascending (Arohana) and descending (Avarohana) scales. Our mission is to encode this profound acoustic heritage into robust AI models, moving beyond Western-centric MIR (Music Information Retrieval) to create an open platform that respects, preserves, and innovates upon the grammar of Indian Classical Music.
The project is decoupled into two primary subsystems to ensure scalability and rapid inference:
- Environment Requirement: Python 3.10+
- Data Ingestion: Conversion of Carnatic compositions (MIDI, MusicXML) into
NoteSequenceandTFRecordformats holding deep arrays of pitch bends and timing. - Deep Learning Core: Training of sequence models (RNN/LSTM or Transformer-style) heavily conditioned on specific Raga constraints.
- Microservices: A FastAPI/Flask REST layer to expose the
.generate()methods via endpoints.
- Technology Stack: React 18, Vite 5, Material UI 3
- Usage: A modern, glassmorphic Single Page Application (SPA) offering visual generation tools, Raga playback via WebMIDI/Tone.js, and an integrated technical blog.
git clone https://github.com/sgmoorthy/DeepRaaga.git
cd DeepRaaga
# Initialize virtual environment
python -m venv .venv
# Activate environment
source .venv/bin/activate # Unix/macOS
.\.venv\Scripts\activate # Windows
# Install ML Dependencies
pip install -r requirements.txt(Dependencies include TensorFlow, Magenta, librosa, pretty-midi, and FastAPI)
# Install exact dependencies
npm install
# Spin up high-speed local dev server
npm run dev
# Compile for production
npm run buildDeepRaaga utilizes robust GitHub Actions pipelines to automate testing and deployments natively.
The Workflow (.github/workflows/deploy.yml):
- Trigger: Activated automatically upon merging code into the
masterbranch. - Environment: Spins up an
ubuntu-latestcontainer running Node.js. - Build: Installs dependencies cleanly utilizing
npm ciand compiles the React application utilizingnpx vite build --base=/DeepRaaga/. - Deploy: Artifacts are packaged and pushed directly to the
gh-pagesbranch, instantly updating the lived production URL.
(Note: Contributors do not need to manually push a build. Simply open a PR against master and the CI/CD pipeline handles it!)
DeepRaaga ships with a fully integrated, beautifully stylized publishing platform structurally inspired by Google's "The Keyword" blog.
The frontend incorporates a dynamically mapped Client-Side Router that leverages raw .md (Markdown) data without requiring a dedicated backend database.
- Create your Markdown file: Add your technical writing to
docs/blog/your-new-post.md. - Handle Media Natively: Use standard Markdown image syntax (
). For YouTube videos, standard hyperlink anchor tags ([Video](https://www.youtube.com/watch?v=VIDEO_ID)) are dynamically intercepted by our custom React Markdown engine and converted into secure, auto-responsive<iframe>embeds. - Register your Post: Open
src/components/BlogViewer.jsxand add your metadata to theblogsmanifest array:
import newPost from '../../docs/blog/your-new-post.md?raw';
{
slug: 'your-new-post',
title: 'Your Premium Title Here',
category: 'Engineering',
date: 'April 15, 2026',
image: '/DeepRaaga/blog-images/feature.png',
description: 'A brief description that appears on the feed card.',
content: newPost
}Vite will automatically hot-reload your new post into the responsive grid feed!
DeepRaaga pioneeringly treats Indian Classical Music as Code. In this paradigm:
- Ragas are Functional Constraints: They are not just melodies but logical schemas (Arohana/Avarohana) that act as validator functions for generative outputs.
- Compositions are Verisonable Artifacts: Every Kriti or Sanchara is treated as a structured data artifact (MIDI/MusicXML) that can be linted for grammar, version-controlled, and audited.
- Pedagogy as CI/CD: Learning is viewed as an iterative refinement process, where model weights are updated based on structured feedback from musicians, much like code reviews.
To solve the data bottleneck in Carnatic AI and allow for reproducible benchmarking, we have standardized the DeepRaaga-Dataset structure. This repository includes a high-fidelity folder hierarchy for all 72 Melakarta Ragas, treating each musical scale as a unique "Namespace."
We provide a utility script to instantly generate the standardized directory tree:
python data/melakarta_init.pyThis creates the following structure under data/DeepRaaga-Dataset/:
Melakarta/01_Kanakangi/,02_Ratnangi/, ...72_Rasikapriya/midi/: Standardized MIDI performance data (Melodic Artifacts).musicxml/: Structured sheet music (Symbolic Code).annotations/: Phrase-level metadata and Gamaka labels (Documentation).
Researchers and musicians can contribute high-quality musical code by placing it in the correct Raga namespace and submitting a Pull Request. This allows for a collective, open-source benchmark for Carnatic MIR.
Data must be grouped by raga under data/raw/ in MIDI format. To quantize and prepare the data for TensorFlow:
python data/convert_data.pyGeneration is performed by autoregressively sampling from the trained sequence model while conditioning on a specific Raga Latent Vector:
python generate.py --raga="Bhairavi" --duration=300 --temperature=0.8Building the ultimate AI framework for Carnatic music is an ongoing journey:
- Phase 1: Melakarta Integration: Map all 72 parent scales explicitly.
- Phase 2: Rhythmic Tala-Awareness: Introduce chronological constraints so models respect the 8-beat structure of cycles like Adi Tala.
- Phase 3: Transformer Infrastructure: Upgrade baseline
RagaLSTMnodes to causal Transformers (e.g., MusicLM variants) for improved Alapana continuity. - Phase 4: Open API Sandbox: Offer a real-time web REST API for digital musicians.
We rely on Musicologists, ML Engineers, and React Developers to build this repository. See our detailed breakdown of roles in How to Contribute to DeepRaaga.
- Fork the repo!
- Create your feature branch:
git checkout -b feature/carnatic-magic - Push to the branch:
git push origin feature/carnatic-magic - Submit a Pull Request.
If you use DeepRaaga in academic work, please cite the associated paper:
@inproceedings{swaminathan2025deepraaga,
author = {Gurumurthy Swaminathan},
title = {DeepRaaga: Learning and Generating Carnatic Ragas with Deep Neural Sequence Models},
year = {2026},
booktitle = {Proceedings of the Audio Engineering Society}
}Released under the MIT License.