Getting Started

Install the Notations library and write your first notation

The Notations library provides tools for parsing, modeling, and rendering Carnatic music notation. This guide will help you install the library and create your first notation.

Installation

Install via npm:

npm install notations

Or with yarn:

yarn add notations

Basic Usage

Import the library and load a notation string:

import * as N from "notations";

// Parse and render notation
const source = `
S R G M P D N S.
sa ri ga ma pa dha ni sa
`;

const [notation, beatLayout, errors] = N.load(source);

if (errors.length === 0) {
  console.log("Notation loaded successfully");
  // notation contains the parsed data
  // beatLayout contains the layout information
}

Your First Notation

Try this simple example:

S R G M P D N S. sa ri ga ma pa dha ni sa

The notation above shows a basic Carnatic scale with swaras (notes) on the first line and sahitya (lyrics) on the second line. The dot after the final S indicates it's one octave higher.

Understanding the DSL

The Notations library uses a domain-specific language (DSL) for writing music. Here are the key concepts:

  • Lines: Each line represents a role (swara, sahitya, percussion, etc.)
  • Notes: Capital letters represent swaras (S R G M P D N)
  • Spaces: Commas (,) add timing gaps between notes
  • Groups: Square brackets group notes that share a beat
  • Octaves: Dots before a note (.S) for lower octaves, dots after (S.) for higher octaves. Use multiple dots for multiple octaves (S.. or ..S)

Example with Grouping

S R [G M] P , D N S.

In this example, G and M are grouped together and share one beat.

Example with Octaves

.N .D S R G M P D N S. R.

This example shows notes spanning three octaves. .N and .D are in the lower octave, S through N are in the middle octave, and S. and R. are in the upper octave.

Next Steps

Now that you have the basics, explore these topics: