maidata-parser

A fast, strict simai chart parser that converts maidata notation to .ma2 format.

Download the latest binary from Releases.

---

Overview

maidata-parser converts either a full maidata.txt (every difficulty at once) or a plain-text simai chart (the body of a single inote field) into ready-to-use .ma2 files, and prints a short summary for each chart.

The parser implements the simai specification including BPM change compensation for holds and slides, pseudo-each (`) timing offsets, equivalent-BPM durations, preview marker (###) extraction, and playability validation. All timing is computed with exact rational arithmetic; the output resolution is chosen per chart so that every note lands exactly on the tick grid whenever possible.

When a chart contains errors, the parser reports every error it can find in a single run, each with the fragment index, the measure position and the raw simai fragment for tracing.

---

Usage

maidata_parser [--skip-validation] INPUT [INPUT ...]

Each INPUT can be:

Input	Output
a maidata.txt, or a song folder containing one	a <name>_ma2 folder next to the input, holding one 000000_0<diff>.ma2 per difficulty
a text file holding the body of a single chart (no &key=value fields)	<name>.ma2 next to the input

Files and folders can also be dragged and dropped onto the executable. Running it without arguments prints the usage.

Examples

# Convert every difficulty of a song: writes maidata_ma2/000000_00.ma2 ... 000000_05.ma2
./maidata_parser maidata.txt

# The same, given the song folder
./maidata_parser "songs/My Song"

# Convert a single chart body: writes chart.ma2
./maidata_parser chart.txt

# Several inputs at once, without chart validation
./maidata_parser songA songB chart.txt --skip-validation

Options

Flag	Description
--skip-validation	Skip the playability validation (see below). Utage charts always skip it.

Difficulties and file names

&inote_2= to &inote_7= becomes 000000_00.ma2 to 000000_05.ma2. Other inote IDs (such as &inote_1=) have no diff and are skipped with a notice.

---

Console Output

maidata parser by lcebot

maidata.txt
  inote_4 -> maidata_ma2/000000_02.ma2  (resolution 384, 512 notes)
  inote_5 -> maidata_ma2/000000_03.ma2  (resolution 1920, 1024 notes, DX)
  preview window: 11451 ms - 41919 ms; parsed in 8.10 ms

done

• resolution: the tick resolution chosen for the chart. It is the smallest multiple of the chart's timing grid not below 384, so that every BPM change, note position and duration is exact. If that would exceed 1920, the parser picks the resolution between 384 and 1920 with the smallest total timing error, and marks the chart with (some timings rounded).
• DX: shown when the chart uses DX-exclusive note types or connected slides.
• preview window: taken from the two ### markers of the highest difficulty that has a valid pair; without one, the 20 seconds starting from the first note of the highest difficulty.

Problems are printed to stderr under the chart they belong to. Warnings never prevent output. An error prevents the affected chart from being written; the other charts of the same input are still written. Errors that concern the whole song, namely invalid maidata fields (see below) and ### markers that do not form a valid preview window, prevent every chart of that input from being written. The exit code is 1 if any chart was not written, 0 otherwise.

---

maidata Format

• Fields start with & at the beginning of a line: &key=value. A value runs until the next field and may span lines. If a field appears more than once, the first one is used.
• Charts are written as &inote_<id>=. A chart body ends at the next field or at a standalone E. Completely blank charts are ignored with a warning.
• Answer count (&answer=, alias &clock_count=) and designer (&des=) follow the same rules: write either one global value (&answer=4) or one value per chart (&answer_5=4), never both; per-chart values must cover every chart. The answer count must be a positive integer and defaults to 4; a designer name must not be empty. Values for non-existent charts are ignored with a warning.
• A title of the form [X]Name (one character in brackets followed by a name) marks an utage chart. A lone [X] is an ordinary title.

---

Validation and Warnings

The validation enforces playability constraints:

• Sensor conflicts: two notes occupying the same judgment region while one is still active (for example a tap landing inside an ongoing hold on the same button).
• Sensor overcommit: more than two simultaneous inputs required (touch, touch hold and slide together count as one hand).

The following checks always run, even with --skip-validation:

• Slide geometry: invalid start and end combinations for straight, curve, V-shape and opposite-side patterns.
• Slide length: every slide segment must last at least one output tick; shorter slides are removed and reported.
• Opening lead-in: the first note must leave at least one bar of lead-in, or two bars when the BPM is 240 or higher (a bar is answer count quarter notes).

Warnings point out writing that does not affect the output, such as a duration whose BPM declarations do not match the chart's actual BPM changes (with an equivalent rewrite suggested).

---

Notes

• This repository currently distributes compiled binaries only.
• The binary is self-contained and has no runtime dependencies.