CroonJS

CroonJS is a toolkit for parsing and playing numbered musical notation.

Usage

import { parse, play } from 'croonjs'

/** Parse notation */
const notation = `!120 | 1 1 5 5 | 6 6 5 - | 4 4 3 3 | 2 2 1 - |`
const parsedNotation = parse(notation)

/** Digitize notation */
const digitizedNotation = digitize(parsedNotation)
// Or
// const digitizedNotation = digitize(notation)

/** Play notation */
const playingPromise = play(digitizedNotation)
// Or
// const playingPromise = play(parsedNotation)
// const playingPromise = play(notation)

Options

function play(notation: string | ParsedNotation | DigitizedNotation, options?: PlayOptions): Promise<unknown>

options could have the following properties:

• waveform?: "sawtooth" | "sine" | "square" | "triangle" | PeriodicWaveOptions

  Specify what shape of waveform the oscillator will output. See also here.

  If you wish to use instrument sounds, you can use @mohayonao/wave-tables.

• gain?: number

  Specify the global volume of the audio. Defaults to 1.

• simulation?: 'idiophone' | 'aerophone'

  Simulate the effect of an instrument. Currently supports 'idiophone' or 'aerophone'.

• context?: AudioContext

  By default, play will create an AudioContext instance automatically. However, it is also possible to make multiple scores play in the same context by specifying context. This is useful for playing multiple tracks at the same time.

• signal?: AbortSignal

  This allows you to abort it if desired via an AbortController.

Syntax

A CroonJS score consists of a number of notations, which can be separated by any blank character. The syntax supported by CroonJS is generally the same as that of the numbered musical notation, but with some improvements for ease of input.

Full examples can be found in Examples.

Notes

Note notation

As with the numbered musical notation, the numbers 1 through 7 are used to represent quarter notes. By default 1 means C4 and 7 means B4.

In particular, the number 0 is used to indicate a musical rest, representing a quarter note stop.

1 1 5 5 6 6 5 0

You can also use do, re, mi, fa, sol, la, ti instead of 1 to 7 respectively. so and si are also supported as dialects of sol and ti.

Octaves and accidentals

Add + or - to raise or lower a note to other octaves. If you need to raise or lower multiple octaves, you can use it as 1++ or 1--.

1- 1 3 1 4 1 3 1

Add # or b before the note to raise or lower the pitch. This allows you to declare a scale similar to the black keys of a piano.

6+ 5+ #4+ 5+

Note length

Add an underscore _ after a note to halve its length. For example, 1_ means an eighth note and 1__ means a sixteenth note.

Add a dot . to increase its length by half, two dots by three-quarters, and so on.

The underscore should always be noted before the dot sign.

4 4 3 3 2 2_. 3__ 1 1

Inter-note relations

Use - to indicate that the previous note is extended by one quarter note. More than one can also be used in succession, but they need to be notated as multiple notes.

1 1 5 5 6 6 5 - 4 4 3 3 2 2 1 - - -

^ could be added at the start of the note to indicate that it does not need to be preceded by the previous note, and is usually used to indicate a single note across the beat.

& could be added at the end of the note to indicate the preceding leaning note, which takes up a quarter of a beat of the following note.

7_ 1+_ #5_ 6_ ^6 2+& 3+

Bar lines

Use | as a bar separator. Use || as a terminator for the score.

Bar separators and terminators are semantically meaningful only.

1 1 | 5 5 | 6 6 | 5 - | 4 4 | 3 3 | 2 2 | 1 - ||

The use of ||: indicates the start of a repeated section of the score, and :|| indicates a return to the previous repetition point. If there are certain bars in the repeated section that you only want to play on the nth repetition, you can use the [n. notation, which will continue until the next :|| notation.

You can also leave out the ||: notation, which defaults back to the beginning of the score.

1 1 | 5 5 | 6 6 | 5 - | 4 4 | 3 3 | 2 2 | 1 - | [1. 5 5 5 | 4 4 | 3 3 | 2 - | 5 5 | 4 4 | 3 3 | 2 - :||

Key signature, time signature and tempo

The key signature, time signature and tempo notations will take effect for everything after them.

Key signature

CroonJS supports Movable Do, which means you can define a tune using the form 1=C. 1=C means that 1 in the score is equivalent to C4, which is the key of C major. You can also use a notation like 2=D, which is obviously equivalent to 1=C.

If you want to use a minor, you can add the # or b character before the letter after the equal sign, similar to accidentals.

1=bB

The default key signature is 1=C.

Time signature

The time signature is written as a fraction, e.g. 2/4, which means one beat in quarters and two beats per measure.

2/4

The default time signature is 4/4.

Tempo

You can define the tempo of the score with the ! command, followed by a number indicating how many beats per minute.

!120

The default tempo is !60.