sakuramml

# sakuramml-rust `sakruamml` is a MML/ABC to MIDI compier. This compiler that converts the MML/ABC into MIDI files. MML is a notation system that represents sheet music using text such as `cde`. It is a tool that allows you to easily create music. It is made with Rust and works on multiple platforms (macOS/Windows/Linux/WebAssembly). `sakuramml` is a historic music production tool developed around the year 2000. It was recognized as an award-winning entry in the "Online Software Grand Prize 2001" in Japan, and was even featured in high school IT textbooks. - [README(日本語)](https://github.com/kujirahand/sakuramml-rust/blob/main/README_ja.md) ## Samples Many users have composed music using `sakuramml`, and over 2,000 songs have been posted on this forum. Additionally, more than 100 songs are compatible with `sakuramml-rust`. - [mmlbbs6](https://sakuramml.com/mmlbbs6/index.php?action=pico) ## Tutorial An online tutorial is available. You can learn the commands while listening to the music. - [Tutorial](https://sakuramml.com/index.php?Tutorial) ## Install ### Binary - command line tool - [Command line binary(win/mac)](https://github.com/kujirahand/sakuramml-rust/releases/) ### Web Assembly - Web Player - [PicoSakura](https://sakuramml.com/picosakura/) - [sakuramml.com(Web)](https://sakuramml.com) ### Compile with Rust Please install [Rust compier](https://www.rust-lang.org/tools/install). ```sh git clone https://github.com/kujirahand/sakuramml-rust.git cd sakuramml-rust cargo build --release ``` When compiled, the executable file will be saved in `target/release/sakuramml`. ## CLI Usage Please make text file `test.mml`. And execute the following command to generate a MIDI file `test.mid`. ```sh # Compile MML file to MIDI file ./sakuramml test.mml test.mid # Compile MML file to MIDI file, can omit output file ./sakuramml test.mml ``` You can test MML command easily with `--eval` option. ```sh ./sakuramml --eval "o4l4 cege c1" ``` You can check MIDI file with `--dump` option. ```sh ./sakuramml --dump test.mid ``` ## MML Basic You can play the following text as a music. ``` o4 cdefgab>c<bagfedc ``` You can specify tracks(`TR`) and channels(`CH`), Voice(`@`). ``` TR(1) CH(1) @1 l1 ceg^ TR(2) CH(2) @1 l1 egb^ ``` ## Harmony You can play chords. ``` l4 `ceg` `dfa`8 `egb`8 `ceg` ``` ## Time Pointer You can specify the writing position using a time pointer(`TIME`). ``` // top TIME(1:1:0) cdef TIME(1:1:0) efga // 2mes TIME(2:1:0) cdef ``` `SUB{...}` command let time pointer back. ``` SUB{ cdef c } SUB{ efga e } rrrr g ``` ## Rhythm macro In the rhythm macro, one character is treated as one instruction regardless of uppercase or lowercase letters. Rhythm macro definitions are described as "$(char){definition}". ``` // define macro $b{n36,} $h{n42,} $o{n46,} // new macro $S{n37,} CH(10) // sample Rhythm{ 　[4　l8 　　　brSr bbsr r-1 　　　hoho hoho 　] } ``` ### How to specify tuplets The tuplets are written as "DIV{...}", but "DIV" can be omitted and written as "{ceg}". ``` l4 DIV{cde} f DIV{gab} >c< l4 {cde} f {gab} >c< ``` ``` l4 {cde}c {gfe}d {c^d} e {d^e} f ``` The tuplets can nest. ``` l1 { c d {efe} d } c ``` ### Velocity Using the `v` command, you can specify the velocity. It can be set within the range of 0 to 127. ``` l8 v127 cdef v64 cdef v127 c^^^ ``` "(" decreases the velocity by 8, and ")" increases the velocity by 8. ``` v127 c ( c ( c (( c )) c ) c ) c ``` ### Reservation notation - v.onTime(low, high, len, ...)　OR v.T(low,high,len,...) - The value that should be specified for `len` is the tick. When specifying the note length, it should be written as `!4`, for example. - v.onNote(v1, v2, v3, ...)　OR v.N(v1,v2,v3,...) - t.onNote(v1, v2, v3, ...)　OR t.N(v1,v2,v3,...) - (ControllChange or PB or p).onTime(low, high, len, ...) ``` v.onTime(0,127,!1) l8cccccccc BR(2) PB.onTime(-8192,0,!4) l4c PB(0) efg^ ``` ### Macro It can define Macro. ``` // define Macro STR P1 = {cdefg} #P1 = {cdefg} // expand Macro P1 #P1 ``` The macro can replace with arguments. It replaces `#?1` `#?2` `#?3` ... ``` // define macro #Unison = { Key=#?2 Sub{ #?1 } Key=0 #?1 } // expand macro with arguments #Unison{cde},7 ``` ### Script It can use IF/FOR/WHILE/FUNCTION script. ``` // IF INT A = 3 INT B = 5 IF (A == B) { PRINT({A == B}) } ELSE { PRINT({A != B}) } // FOR FOR (INT N=1; N < 5; N++) { PRINT(N) } ``` ### Variables It can define variables of INT, STR, and ARRAY types. ``` // define variables INT I1=30 STR S1={abcd} ARRAY A1=(1,2,3) // use variables PRINT(I1) // 30 PRINT(S1) // abcd PRINT(A1) // (1,2,3) PRINT(A1(2)) // 3 ``` Replace `{i}` with `{c}` in the value of the string variable `S1` and `S2`. ``` // define variables STR S1={iiri iiri} // replace {i} to {c} S1.s({i}, {c}) PRINT(S1) // ccrc ccrc // REPLACE function STR S2 = REPLACE({iiri iiri}, {i}, {c}) PRINT(S2) // ccrc ccrc ``` ## reference - Command List --- [command.md](command.md) - Voice List - [voice.md](voice.md) ### Related Repository - [GitHub/sakuramml-rust](https://github.com/kujirahand/sakuramml-rust) - [crate.io/sakuramml](https://crates.io/crates/sakuramml) - [npm/sakuramml](https://www.npmjs.com/package/sakuramml) - Player - [GitHub/picosakura](https://github.com/kujirahand/picosakura) ... web player - [GitHub/picosakura-rust](https://github.com/kujirahand/picosakura-rust) ... local player - Sakura v2 - [GitHub/sakura2](https://github.com/kujirahand/sakuramml) - [Command List](https://sakuramml.com/doc/command/index2.htm) / [Sorted](https://sakuramml.com/doc/command/index.htm)