API Reference

Complete API reference for the Notations library

Complete API reference for the Notations library classes, interfaces, and functions.

Core Functions

N.load(source: string)

Main function to parse and load notation from a source string.

Parameters

  • source (string) - The notation DSL source code

Returns

Tuple of [Notation, BeatLayout, ParseError[]]

  • Notation - Parsed notation object
  • BeatLayout - Layout information for rendering
  • ParseError[] - Array of parsing errors (empty if successful)

Example

const [notation, beatLayout, errors] = N.load(source);
if (errors.length === 0) {
  // Use notation and beatLayout
}

Parser Class

new Parser()

Creates a new parser instance for more control over parsing.

Methods

  • parse(source: string) - Parse the source and return the result

Properties

  • commands - Array of parsed commands
  • metadata - Parsed frontmatter metadata
  • errors - Array of parse errors

Example

const parser = new Parser();
const result = parser.parse(source);
console.log("Commands:", parser.commands);
console.log("Errors:", parser.errors);

Notation Class

Properties

  • blocks - Array of Block objects
  • roles - Array of role definitions
  • currentCycle - Current cycle pattern
  • currentAPB - Current atoms per beat (beat duration)
  • currentBreaks - Current line break pattern
  • metadata - Metadata from frontmatter

Methods

  • newRoleDef(name, notesOnly) - Create a new role definition
  • setCurrRole(name) - Set the current active role
  • newLine() - Create a new line
  • ensureNamedLayoutParams(name) - Get or create named layout parameters

Block Class

Represents a block of notation with multiple lines.

Properties

  • lines - Array of Line objects
  • index - Block index in the notation

Line Class

Represents a single line of notation containing multiple roles.

Properties

  • roles - Map of role name to RoleView
  • offset - Line offset (Fraction)
  • marginText - Text to display in margin
  • layoutParams - Layout parameters for this line

Methods

  • addAtoms(roleName, notesOnly, ...atoms) - Add atoms to a role

Atom Classes

Note

Represents a musical note or syllable.

Properties

  • value - The note text (e.g., "S", "ri")
  • octave - Octave offset (0 = middle)
  • duration - Duration in units (Fraction)
  • embellishments - Array of gamaka objects

Group

Represents a group of atoms sharing a beat.

Properties

  • atoms - Array of Atom objects
  • duration - Total duration (Fraction)

Space

Represents an empty duration (karvai).

Properties

  • isSilent - Whether this is a silent space
  • duration - Duration in units (Fraction)

Rest

Represents an explicit rest (no note continuation).

Properties

  • duration - Duration in units (Fraction)

BeatLayout Class

Contains layout information for rendering.

Properties

  • beats - Array of Beat objects
  • totalDuration - Total duration of the layout

Carnatic Module

N.Carnatic.NotationView

Class for rendering Carnatic notation to the DOM.

Constructor

new N.Carnatic.NotationView(container, config?)

Parameters

  • container (HTMLElement) - DOM element to render into
  • config (optional) - Configuration object

Methods

  • renderNotation(notation, beatLayout) - Render notation to the view

Properties

  • notation - Current notation object
  • beatLayout - Current beat layout
  • rootElement - Root HTML element

Example

const container = document.getElementById("notation");
const view = new N.Carnatic.NotationView(container);
view.renderNotation(notation, beatLayout);

ParseError Interface

Properties

  • message - Error message
  • line - Line number where error occurred
  • column - Column number where error occurred

TypeScript Types

The library includes full TypeScript type definitions:

import {
  Notation,
  BeatLayout,
  ParseError,
  Parser,
  Note,
  Group,
  Space,
  Rest,
  Atom
} from 'notations';

See Also