donmai-me / maiconverter

A Simai, Ma2, and SDT (and predecessors) chart format Python library.

MaiConverter

A Python program for parsing and converting Maimai charts. Made up of two parts:

• An importable package for parsing, creating, exporting, and converting SDT, Ma2, and 3Simai charts. And
• a commandline script for parsing and converting the 3 formats.

If you're not familiar with these file formats, then you can read about sdt files here and simai files here. You can read about my blog post about this here

If you're interested in anything MaiMai modding related, then go join MaiMai TEA in Discord.

Dependencies

• Pycryptodome
• Lark

Commandline

The command-line script, installed as part of the package, can parse, convert, encrypt, or decrypt MaiMai chart formats. The general form is:

maiconverter COMMAND /path/to/file/or/directory

COMMAND can be the following, with descriptions later:

• encrypt
• decrypt
• ma2tosdt
• ma2tosimai
• sdttoma2
• sdttosimai
• simaifiletoma2
• simaifiletosdt
• simaitoma2
• simaitosdt

The second positional argument is the path to a chart file or directory. If given a directory, it will convert all relevant files found in the directory.

The program will save all converted file in the "output" folder in the input file's parent directory or the input directory. It will make an "output" folder if there is no existing folder.

encrypt, decrypt

These commands will either encrypt an S*T chart file to their equivalent S*B file or vice versa. Requires: -k or --key parameter followed by a hexadecimal AES key. The program can encrypt or decrypt a table by adding a -db or --database toggle parameter.

Example

Convert an SDT to SDB:

maiconverter encrypt --key 0xFEDCBA9876543210 100_songname_02.sdt

Convert an SCB to SCT:

maiconverter decrypt --key 0xFEDCBA9876543210 252_donmaime_05.scb

Decrypts an encrypted table:

maiconverter decrypt --key 0xFEDCBA9876543210 mmtablename.bin

sdttoma2, sdttosimai

These commands will either convert an S*T file to ma2 or Simai, respectively. Requires -b or --bpm parameter followed by the song's BPM as either an int or float. Note: For sdttosimai, it does not produce a complete Simai file. sdttosimai only generates a Simai chart.

Example

Convert a 200 bpm SRT file to Simai:

maiconverter sdttosimai --bpm 200 300_segapls.srt

Convert a 130 bpm SDT file to Ma2:

maiconverter sdttoma2 --bpm 130 301_dontsue.sdt

ma2tosdt, ma2tosimai

These commands will either convert a Ma2 file to SDT or Simai, respectively. Note: For ma2tosimai, it does not produce a complete Simai file. ma2tosimai only generates a Simai chart.

Example

Convert a Ma2 file to SDT:

maiconverter ma2tosdt 000404_02.ma2

Convert a Ma2 file to Simai:

maiconverter ma2tosimai 001401_04.ma2

simaitoma2, simaitosdt

These commands convert a text file containing only a Simai chart file to either a Ma2 or SDT, respectively.

simaifiletoma2, simaifiletosdt

These commands differ from the previous by parsing an entire maidata.txt. All charts are individually converted to a Ma2 or SDT, respectively.

Misc commandline arguments

-o, --output

Specify an output directory, or it defaults to the input directory.

-d, --delay

If you want to apply an offset to every converted chart's notes, you can do so using this argument. It accepts both negative and positive offsets in terms of measures.

-ct, --convert_touch

If converting from Ma2 or Simai to SDT, you can add this toggle to (naively) convert touch notes to regular tap and hold notes. Useful when you want to manually convert touch notes to tap and hold notes. You just need to modify the note's button, no need to figure out the timing.

-md, --max-divisor

Sets the max Simai divisor ("{}") that is allowed when exporting a Simai chart. Set it to a low number like 128, should you want a more readable output. Defaults to 1000.

Python package

If you installed the wheel file, you could import the program like a standard Python package. If you want to make a chart maker or GUI frontend for this converter, please use it. See how_to_make_charts.md for an introductory guide on using MaiConverter for chart making. There is also (incomplete) documentation for classes and functions in the package. See licensing below.

TODOS

• Documentation
• Do all the TODOs scattered in the package
• Reduce jank

Contact

If you have questions or bug reports and for some reason you don't want to make an issue at GitHub, send me a DM or ping me at MaiTea Discord server.

• Discord: donmai#1493
• Twitter: @donmai_me
• GitHub: donmai-me
• Listed.to: @donmai

License

This is an open-sourced application licensed under the MIT License

maiconverter's Issues

SDT to SDB - Binascii Error

Hi! I tried to use the encrypt function with the Finale AES Key that I have but the program keeps returning binascii error, non hexadecimal digit found. Can I check how do I resolve this issue? Thank you!

How to convert sdt to sdb

ValueError: Invalid Literal for int() with base 0

Hi! Thanks for updating. The error does not happen anymore. However, now I am getting a ValueError: invalid literal for int() with base 0. This happens both when I input the key in hex and input the key in ASCII. Is it that my key is wrong?

Originally posted by @brian-vb in #7 (comment)

Parse Ma2 by parts

There are four parts (more for other games) for ma2: header, events, notes, and statistics. Each part is separated by an empty line. It would be nice if instead of parsing a chart line by line and ignoring certain parts, the parser would parse a chart part-by-part.

The header contains metadata about the chart and the resolutions used for timing. Events are a list of bpm and time signature changes in chronological order. Notes are self-explanatory. And, statistics contains information about all of the notes present in the chart.

Simai absolute time support

According to my checklist, defining duration in terms of seconds seems to be the only missing feature for 3Simai. I've already added functions that can help convert seconds to measures with ease.

Key not supplied

I'm sorry to distube u so much,but when I execute the encrypt(sdt to sdb),it's said that "key not supplied".

Simai Compatibility Modes

Since the official Simai format documentation is a bit unclear on certain things. The current popular Simai editor, Majdata, has different behaviour compared to the original Simai Flash player. There's also AstroDX with their own parsing library which may have different behaviour to Majdata and original Simai Flash player.

It would be nice if a Simai class has a hint (possibly an attribute) that the export method and converter functions can use to address these differences in behaviours.

how to use the command line

Festival support

Hi, i tried to convert a ma2 file to simai and have a version error??

Add Sdt slide verification

It would be nice if there are checks for MaiMai classic slides. Failed checks will raise a ValueError, and an optional switch to disable checks should be added to the parsing method.

For a guide on which slides are valid, I made a blog post that contains information on valid slides.

Python < 3.8 support?

I would like to know why the Python Version requirement is 3.8.
I tested it locally (by changing the things to 3.7 or perhaps lower) and it works.

Unless a local runner test for this already done. Thanks!

Allow MaiSxt to be exported to older formats

Currently, we can only export a MaiSxt object to an SDT chart. A MaiSxt can be constructed from an SRT, SZT, SCT, and SDT file (based only on its file extension.) It'll be nice if, during export, you can specify the chart format via a passed enum. If there are no passed enum to the export method, SDT should be the default export.

Add ma2 slide verification

There's a difference between valid slides in ma2 and in Sdt (and predecessors). There should be verification in added ma2 slides via MaiMa2's add_slide method. With an optional toggle to disable the check.

Failed checks will raise a ValueError.

ma2tosimai - A problem about 360° slides.

When using ma2tosimai, 360° Slides will be converted to A^A (A is the same number), and it will be recognized as a clockwise rotation by default when playing, which may cause the problem of reverse direction.

使用 ma2tosimai 时，遇到 360° 的 Slide 将被转换为 A^A （A 是同一个数字），在游玩时会默认被识别为顺时针旋转，可能会导致方向转反的问题。