# music-code

Music Code Player is a web app that allows you to type and play music using plain text.

Website: https://stdio2016.github.io/music-code/

Currently, it supports only one format, Music Macro Language.

## Music Macro Language

Music Macro Language (MML) is a text format to describe a music. It is case-insensitive, and ignores all white spaces and newlines.

I have implemented two versions of MML player, the first version is [mus.html](https://stdio2016.github.io/volatile/mus.html), and this is the second version.
Some features are implemented after I finished mus.html, so there are syntax differences between these two versions. I will denote such differences in warning sections.

:::warning
:warning: mus.html does not allow white spaces within a command.
:::

Here is a list of commands:

### `CDEFGAB`
A note. Its format is `pitch accidentals duration dots`.
Pitch is a letter from `A` to `G` and causes the corresponding note to be played.

Accidentals can be zero or more `+`, `#`, `-`, `=` or `@`, where a `+` or `#` denotes a sharp, a `-` denotes a flat, and an `=` or `@` denotes a natural.
:::warning
:warning: mus.html does not support `=`, and allows up to 2 of the same accidental characters.
:::

The note duration is specified by an integer, representing a fraction of a whole note. Valid range is 1 to 64. For example, `C4` is a C quarter note. Duration can have 0 to 2 dots, which correspond to the dots of the note. For example, `C4.` is single dotted C quarter note.
:::warning
:warning: mus.html supports at most one dot. Setting duration to 0 is an error and will crash mus.html.
:::

### `P` or `R`
Rest note. Its format is `P duration dots`. It is similar to a note, but a rest note does not have pitch and accidentals.
:::warning
:warning: mus.html does not support `R` as rest note.
:::

### `O`
Followed by a digit. Sets the octave of the following notes. Octave 4 (`O4`) contains Middle C.

The octave setting will affect current track only. By default, each track is in octave 4 initially.

Octave can be -1 to 9. To reach octave -1 you need to type `O0<`.
:::warning
:warning: mus.html accepts octave higher than 9, and can crash if octave is too large, such as `O2016`.
:::

### `>`
Raise the octave by 1. The highest possible octave is 9. The octave setting will affect current track only.

### `<`
Lower the octave by 1. The lowest possible octave is -1. The octave setting will affect current track only.

### `L`
The format is `L duration dots`. Sets the duration of the following notes to the duration specified by this command.
For each following note:
1. If a note has a duration, then its duration is not affected by this instruction.
2. If a note has dots but no duration, then its duration is the duration specified by this command, but its dots remain unchanged.
3. If a note has neither dots nor duration, the its duration and dots are set to the same as this command.

The L command will affect current track only. By default all notes are quarter notes.
:::warning
:warning: mus.html does not support `L` command with dots.
:::

### `T`
Followed by an integer. Set the tempo in Beats Per Second. Valid range is 32 to 255.
An MML music is assumed to be 4/4 time. By default, a song will play a tempo of 120 (`T120`).

T command will apply to the whole music, so the tempo of each track can by synchronized.
:::warning
:warning: mus.html supports decimal bpm such as `T120.5`, but I do not think it is useful, so I do not add support for non-integer bpm in this program.
:::

### `N`
Play a note in the specified pitch. Its format is `N pitch dots`. The pitch is MIDI note number minus 12, so `N48` plays Middle C. Pitch is an integer between 0 and 115.
N note can have dots, but cannot have a duration. Please use L command to change its duration.
:::warning
:warning: mus.html accepts pitch higher than 115, and can crash if pitch is too high, such as `N2016`.
:::

### `V`
Change the volume of the following notes. Volume is an integer from 0 to 127.
When in MML Compatible Mode, this command will accept an integer between 0 and 15. The program convert this integer to the volume with formula: $volume = input\times 8+7$.
The volume setting will affect current track only. By default, all notes are played in volume 63.
:::warning
:warning: mus.html does not support `V` command.
:::

### `&`
Connect notes of the same pitch together like ties in music.
For example, `C2 & C4.` means to connect a C half note with a C dotted quarter note.

When used with `&`, all the notes in the same chord are tied.
:::warning
:warning: mus.html does not support `&` command.
:::

### `MML@`
Enter MML Compatible Mode. In MML Compatible Mode, you can use `,` to separate tracks. This mode is for playing Mabinogi MML music.
:::warning
:warning: mus.html does not support MML Compatible Mode.
:::

### `;`
Leave MML Compatible Mode. It is also a line comment, so anything after `;` is ignored.
:::warning
:warning: mus.html does not support `;` as line comment.
:::

### Extensions
These commands are extensions created by me.

### `,` (comma)

When in MML Compatible Mode: Switch to next track.
When not in MML Compatible Mode: Lower the octave by 1. This is the same as `<`.

### `'` (apostrophe)
Raise the octave by 1. It is the same as `>`.

### `/`
Chord. Its usage is `note / note / ... / note`. For example, `C/E/G` plays C, E, and G at the same time. Only the first note of the chord needs to specify a duration, since other notes will have the same duration as the first note.

Octave changes after `/` will only apply to the following notes in the same chord, so `C/<G G` plays two G's in different octaves.

### `K keyname`

Set a key signature. Key name is assumed to be major key. For example, `KD` means that this music is played in D major.

After setting a key, the following notes that have no accidentals will add accidentals acording to that key signature.
In D major, for example, C and F are sharp, so `KD C D E F G A B` will play `C+ D E F+ G A B`.

If you want to specify a minor key, please type its relative major key instead.

Key name can have accidentals. For example B flat major can be represented by `KB-`.

### `K accidentals`
Transpose all the following notes. For example `K++` raises notes up 2 semitones. Transposition happens after a note adds accidentals, so `KD K++ F` will play a F sharp note raised by 2 semitones, that is G sharp.

This command affects every tracks, so it can be used to transpose a music.

If there are multiple transposition commands, their effect will sum up. `K++ K-` for example will raise music up 2 semitones, then lower down 1 semitone. The net effect will be raise up 1 semitone.

`K=` has no effect, since this program does not reset transposition by natural symbol.

:::warning
:warning: mus.html does not support transposition command.
:::

### `! tracknumber`

Switch to other track. Valid range of track number is 0 to 999.
For example, `!0 C !1 D` plays C and D at the same time.

You can interleave different tracks as you like. For example, `!0 A B !1 C !0 D !1 E F` is the same as `!0 A B D !1 C E F`.

### `~`

Act as a tie in sheet music. Can only appear immediately after a note.
When used with `/`, only the notes immediately preceding `~` are tied.
For example, only G notes in `C/G~ C/G` are tied, where both C and G in `C/G& C/G` are tied.