croonjs

# CroonJS CroonJS is a toolkit for parsing and playing [numbered musical notation](https://en.wikipedia.org/wiki/Numbered_musical_notation). ## Usage ```typescript 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 ```typescript 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](https://developer.mozilla.org/en-US/docs/Web/API/OscillatorNode/type). If you wish to use instrument sounds, you can use [`@mohayonao/wave-tables`](https://npmjs.com/package/@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`](https://developer.mozilla.org/en-US/docs/Web/API/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](./examples/). ### Notes #### Note notation As with the numbered musical notation, the numbers 1 through 7 are used to represent [quarter notes](https://en.wikipedia.org/wiki/Quarter_note). 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](https://en.wikipedia.org/wiki/Solf%C3%A8ge#Variations), 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`.