API Documentation

Use the Notations library programmatically

The Notations library provides a programmatic API for parsing, modeling, and rendering Carnatic music notation. This guide shows you how to use the library in your JavaScript or TypeScript applications.

Basic Usage

Import the library and use the load function to parse notation:

import * as N from "notations";

const source = `
\cycle("|4|2|2|")
\beatDuration(4)
Sw: S R G M P D N S.
Sh: sa ri ga ma pa dha ni sa
`;

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

if (errors.length === 0) {
  console.log("Notation loaded successfully");
  console.log("Notation:", notation);
  console.log("Beat Layout:", beatLayout);
} else {
  console.error("Errors:", errors);
}

Return Values

The N.load() function returns a tuple with three elements:

notation - The parsed notation object containing all commands, roles, and atoms
beatLayout - Layout information for rendering the notation
errors - Array of parsing errors (empty if successful)

Working with Notation Objects

The notation object contains structured data about your composition:

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

// Access metadata
console.log("Current cycle:", notation.currentCycle);
console.log("Current APB:", notation.currentAPB);

// Access roles
notation.roles.forEach(role => {
  console.log("Role:", role.name);
});

// Access blocks and lines
notation.blocks.forEach(block => {
  block.lines.forEach(line => {
    console.log("Line:", line);
  });
});

Error Handling

Always check for parsing errors before using the notation:

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

if (errors.length > 0) {
  errors.forEach(error => {
    console.error("Error:", error.message);
    console.error("Line:", error.line);
    console.error("Column:", error.column);
  });
  return;
}

// Safe to use notation here
processNotation(notation, beatLayout);

Using the Parser Directly

For more control, use the Parser class:

import { Parser } from "notations";

const parser = new Parser();
const result = parser.parse(source);

console.log("Commands:", parser.commands);
console.log("Metadata:", parser.metadata);
console.log("Errors:", parser.errors);

Rendering

The library provides rendering capabilities through the NotationView:

import * as N from "notations";

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

if (errors.length === 0) {
  const container = document.getElementById("notation-container");
  const view = new N.Carnatic.NotationView(container);
  view.renderNotation(notation, beatLayout);
}

TypeScript Support

The library includes full TypeScript type definitions:

import * as N from "notations";
import { Notation, BeatLayout, ParseError } from "notations";

function loadNotation(source: string): [Notation, BeatLayout, ParseError[]] {
  return N.load(source);
}

Web Components

For easy integration in web applications, use the separate web-components package:

npm install notations-web notations

import { NotationBlock } from "notations-web";
import * as NV from "./NotationViewer";

const container = document.getElementById("notation-container");
const config = {
  createViewer: NV.createViewer,
  cssClasses: {
    sourceContainer: "bg-white",
    outputContainer: "p-4"
  }
};

const block = new NotationBlock(container, config);

See the Web Components Guide for details.

Core Concepts

Notation - Top-level object containing the entire composition
Block - A section of notation with multiple lines
Line - A horizontal line of notation containing multiple roles
Role - A type of content (Sw for swaras, Sh for sahitya)
Atom - Basic unit (Note, Space, Rest, Group)
BeatLayout - Layout information for rendering