> ## Documentation Index
> Fetch the complete documentation index at: https://chart-spec.enchor.us/llms.txt
> Use this file to discover all available pages before exploring further.

# Note pairing

> How note-on and note-off events pair into notes in a .mid file, and how long each note is.

A `.mid` file writes each note as two events: a note-on where it starts, and a note-off where it ends. A scanner pairs them into one note, whose length is the number of ticks between them:

```text theme={null}
PART GUITAR
  0      Track name  PART GUITAR
  1920   Note on     96   Expert green
  2400   Note off    96
  2400   Note on     96   Expert green
  2880   Note off    96
  2880   Note on     97   Expert red
  2880   Note off    97
```

Here a green note is held from tick 1920 to tick 2400, and a second green note starts where it ends and is held to tick 2880. A red note at tick 2880 has no sustain.

A `.chart` file writes each note's length in the note itself. See [Notes](/chart/instrument-sections#notes).

## Pairing

These rules apply to every note of an instrument track: notes, modifiers and phrases. Vocal tracks pair the same way, and trim overlapping notes of one pitch as sustains are trimmed: see [Vocals and harmonies](/mid/vocals#invalid-forms).

* A note-off ends a note of its own number and channel.
* A note-on with velocity 0 is a note-off. A note-off's velocity has no effect.
* **Required:** a note-off later in its track for every note-on.
* **Required:** each note ends at or before the tick where the next note of its number and channel starts.
* **Recommended:** every note of a track on one channel.

### Events at one tick

**A note that ends where the next starts.** **Required:** the note-off before the next note-on of its number, when the two share a tick. Then every scanner reads two notes, as in the example above.

**Edge case: a note of length 0.** A note-on, then its note-off, at one tick. A note of length 0 has no sustain, and a modifier of length 0 covers the notes on its tick. For a phrase, see [Phrases](/mid/phrases#rules-for-every-phrase).

## Length

A note's length is its note-off's tick minus its note-on's tick. What it means depends on the note:

| Note | Its length |
| - | - |
| A 5-fret or 6-fret note | Its sustain |
| A drum note | No sustain, but it counts where a note's end does. See [Notes](/chart/drums#notes) |
| A modifier | Which notes it covers. See [Note modifiers](/mid/modifiers#which-notes-a-modifier-covers) |
| A phrase | Where the phrase ends. See [Phrases](/mid/phrases) |
| A vocal note | How long it's sung. See [Vocals and harmonies](/mid/vocals#notes) |

### The sustain cutoff

A note whose sustain is no longer than the cutoff is read with no sustain. In a `.mid` file, the cutoff is the resolution divided by 3, rounded down, plus 1:

| Resolution | Cutoff | Sustains cut |
| - | - | - |
| 192 | 65 | 1 to 65 ticks |
| 480 | 161 | 1 to 161 ticks |
| 960 | 321 | 1 to 321 ticks |

* `sustain_cutoff_threshold` in `song.ini`, in ticks, replaces it. See [Settings](/ini/settings#sustains-and-chords).
* The cutoff applies to notes, not to phrases or vocal notes.

A `.chart` file has no cutoff by default. See [Cut off short sustains](/chart/note-resolution#cut-off-short-sustains).

After pairing and the cutoff, a scanner resolves the notes as in a `.chart` file. See [How notes resolve](/chart/note-resolution). It decides strums and HOPOs with the `.mid` rules on [Note modifiers](/mid/modifiers#natural-hopos).

## Invalid forms

<Accordion title="Overlapping notes of one number">
  A scanner ends the latest open note of the number first, then trims overlapping sustains, as [How notes resolve](/chart/note-resolution#trim-overlapping-sustains) says. So two overlapping notes read as they would in a `.chart` file. Clone Hero, YARG and scan-chart read them this way. scan-chart reports `overlappingMidiNotes`. Saving with scan-chart keeps them as written.
</Accordion>

<Accordion title="Two note-ons of one number at one tick">
  Clone Hero, YARG and scan-chart keep the longer note, as in a `.chart` file. scan-chart's export writes the longer one.
</Accordion>

<Accordion title="A note-on before the note-off at a shared tick">
  For notes that should end and start at one tick, the file has the next note-on before the note-off. Clone Hero, YARG and scan-chart pair that note-on with the note-off at its tick, and trimming overlapping sustains then gives the two notes the charter meant. scan-chart reports `overlappingMidiNotes`, and its export writes the note-off first.
</Accordion>

<Accordion title="A note-on with no note-off">
  Every scanner ignores it, and also a note whose note-off comes after the end of track. scan-chart's export leaves it out. YARG's lyrics read a vocal phrase without its note-off differently: see [Vocals and harmonies](/mid/vocals#invalid-forms).
</Accordion>

<Accordion title="A note-off with no note-on">
  Every scanner ignores it, except YARG's lyrics for a vocal phrase: see [Vocals and harmonies](/mid/vocals#invalid-forms).
</Accordion>

<Accordion title="A note-off on another channel than its note-on">
  The note-off doesn't end the note, so every scanner ignores the note.
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.