This document describes MML commands for Psgino.
| Command Name | Description |
|---|---|
| A-G | Outputs the sound of the specified note. |
| N | Specifies the note number and outputs the sound. |
| R | Inserts a rest. |
| T | Sets the tempo. |
| L | Sets the note length. |
| V | Sets the volume. |
| S | Switches to envelope generator volume control. |
| M | Sets the envelope frequency. |
| O | Specifies the octave for notes A-G. |
| Q | Specifies the gate time of the note. |
| H | Outputs a noise sound. |
| I | Sets the noise frequency. |
| < | Decreases the octave value set by the O command. |
| > | Increases the octave value set by the O command. |
| , | Concatenates MML into a chord. |
| & | Plays notes with slurs and ties. |
| [],| | Specifies a loop section. |
| $E | Toggles software envelope volume control on/off. |
| $A | Sets the attack time of the software envelope. |
| $H | Sets the hold time of the software envelope. |
| $D | Sets the decay time of the software envelope. |
| $S | Sets the sustain time of the software envelope. |
| $F | Sets the fade time of the software envelope. |
| $R | Sets the release time of the software envelope. |
| $M | Sets the software LFO mode. |
| $J | Sets the modulation depth of the software LFO. |
| $L | Sets the modulation frequency of the software LFO. |
| $T | Specifies the delay time before the software LFO starts operating after sound output begins. |
| $B | Biases the frequency of the output sound. |
| $O | Sets the TP offset. |
| $P | Smoothly increases or decreases the frequency of the output sound until it stops. |
| @C | Invokes the user-defined callback function. |
Outputs the sound of the specified note.
| Values | Description |
|---|---|
| <accidental> | Specify accidental symbols using "#", "+", or "-". "#" and "+" raise the note by a semitone, while "-" lowers it by a semitone. |
| <length> | Specify the length of the sound, ranging from 0 to 64. "1" represents a whole note, "4" represents a quarter note. If <length> is omitted, the note length will be set to the value specified by the L command. You can also specify "0" as the note length, in which case no sound is generated. This value is primarily used for the final note in a slur (&) sequence. |
| <dot> | Specify a dot with ".". One dot increases the note length by 1.5 times (= 1 + 0.5). Two dots increase it by 1.75 times (= 1 + 0.5 + 0.25). Up to three dots can be used. |
Example:
C#2.
Specify the note number and output the sound. The note length is determined by the value set with the L command.
| Values | Description |
|---|---|
| <note-number> | Specify the note number within the range of 0 to 95. For example, N36 corresponds to O4C, and N52 corresponds to O5E. Note that N0 is treated as a rest, not O1C. |
| <dot> | Specifies a dot. The dot effect works the same as for A-G notes. |
Example:
L4O4CEG.R8 N36N40N43.R8
Insert a rest.
| Values | Description |
|---|---|
| <length> | Specify the length of the rest, ranging from 1 to 64. "1" represents a whole rest, "4" represents a quarter rest. If this value is omitted, the rest length is determined by the "mode" parameter of the SetMML/SetSeMML() method as follows: - If the 0th bit of mode is 0, the rest length is 4 (quarter rest). - If the 0th bit of mode is 1, the rest length will be the value specified by the L command. |
| <dot> | Specifies a dot. The dot effect works the same as for A-G notes. |
Example:
L4
CR8 C16R16 CR
CR8 C16R16 CR
Sets the tempo. The default tempo is 120 bpm.
| Values | Description |
|---|---|
| <tempo> | Specify a tempo value between 32 and 255. When using multiple tone channels, tempo settings must be included in the MML for each channel. |
Example:
T120CDE2T100CDE2,
T120EGB2T100EGB2
Sets the length of the sound when <length> is omitted in the A-G command. The default value is 4. This setting can also affect the R and H commands, depending on the "mode" parameter of the SetMML/SetSeMML() function.
| Values | Description |
|---|---|
| <length> | Specify the length of the sound from 1 to 128. "1" represents a whole note, and "4" represents a quarter note. |
| <dot> | Specifies a dot. The dot effect is the same as for A-G notes. |
Example:
L4CDE2L16CDECDECDE
Sets the volume for tones and noises. The default volume is 15. Note that the V command and S command are mutually exclusive, and the volume setting will follow the command that is executed last.
| Values | Description |
|---|---|
| <volume> | Specifies the volume level from 0 to 15. |
Example:
V15A V13A V10A
Switches to volume control using an envelope generator. The default setting is OFF. Executing this command enables volume control by the envelope generator. To turn off this volume control, use the V command.
| Values | Description |
|---|---|
| <shape> | Specifies the envelope shape within the range of 0 to 15. Please refer to the PSG datasheet for details on the envelope shape for each value. |
Example:
V15CDER4
L4S0M3000CDER4
V15CDER4
Specifies the envelope frequency. The default envelope frequency is 0.
| Values | Description |
|---|---|
| <frequency> | Specifies the envelope frequency (EP) in the range of 0 to 65535. |
Example:
L4
S0M5000CDER4
S0M1000CDER4
Specifies the octave for notes indicated by A-G. The default octave is 4.
| Values | Description |
|---|---|
| <octave> | Specifies the octave, ranging from 1 to 8. |
Example:
L4
O4 CDE2
O5 CDE2
O3 CDE2
Specifies the note gate time. The default value is 8 (which corresponds to 100%).
| Values | Description |
|---|---|
| <gate-time> | Specifies the gate time, ranging from 1 to 8. For example, if the gate time is set to 3, the note duration will be 3/8, and the remaining 5/8 will be muted. |
Example:
L16CCCCCCCC
R4
Q4CCCCCCCC
Outputs a noise sound with the frequency set by the I command.
| Values | Description |
|---|---|
| <length> | Specifies the length of the noise, ranging from 1 to 64. If this value is omitted, the length of the noise is determined by the "mode" parameter of the SetMML/SetSeMML() method, similar to the R command. |
| <dot> | Specifies a dot. The dot effect is the same as for A-G notes. |
Example:
HR8H16R16HR HR8H16R16HR
Sets the noise frequency (NP) for the noise generated by the H command. The default noise frequency is 16.
| Values | Description |
|---|---|
| <frequency> | Specifies the noise frequency, ranging from 0 to 31. |
Example:
I0H4 I8H4
Lowers the octave set by the O command.
Example:
L4O5C<BA
Raises the octave set by the O command.
Example:
L4AB>C
MML for each part can be concatenated using commas. Since PSG has 3 tone channels, up to 3 MMLs can be concatenated.
Example:
T120L4O4CEG,
T120L4O4EGB,
T120L4O4GB>D
By connecting A-G commands with &, you can create slurs and ties.
| Values | Description |
|---|---|
| <octave-settings> | You can use the O command, along with > and <, to set the octave. The octave value set here will persist even after the performance of slurs and ties. |
Example:
A2R2 A4&A4R2 A2&>A0R2 A2&<A0R2
Loop playback of MML is achieved using []. Loops can be nested up to 3 levels. Loop symbols beyond the 3rd level are ignored. The "|" symbol can also be inserted within the loop section to serve as a break statement. This symbol functions as a break statement only for the last loop.
NOTE: The primary loop of MML registered with the SetMML() method can be reduced to two remaining loop iterations (including the current loop) by calling the FinishPrimaryLoop() method. This method is used to end background music such as end credits.
| Values | Description |
|---|---|
| <loop-number> | Specifies the number of loop iterations, ranging from 0 to 255. If 0 is specified, it creates an infinite loop. If this value is omitted, the loop count defaults to 1. |
Example1:
O3[3 C&>C0]
Example2:
[4 CD|ER4] CR4
In addition to PSG's built-in envelope generator, Psgino supports volume control using software envelopes. This feature is only available when volume is controlled with the V command rather than the S command. The envelope shape is configured using six parameters (the AHDSFR method). Volume control via envelopes can be set independently for each channel.
Sets the ON/OFF state for volume control via software envelope. This value defaults to OFF.
| Values | Description |
|---|---|
| <enabled> | Set in the range from 0 to 1. 0 corresponds to OFF and 1 to ON. |
Example:
V15L4O4
$A0$H100$D100$S90$F2000$R300
$E0
CDER
$E1
CDER
Specifies the rise time of the sound, which is the time it takes for the volume to increase from 0 to the level set by the V command.
| Values | Description |
|---|---|
| <attack> | Specifies the rise time in milliseconds, ranging from 0 to 10000. If 0 is specified, no rise time processing is applied, and the sound is output directly at the volume set by the V command. |
Sets the retention time of the volume level after the attack phase.
| Values | Description |
|---|---|
| <hold> | Specifies the hold time in milliseconds, ranging from 0 to 10000. If 0 is specified, decay processing will start immediately. |
Sets the time it takes for the volume to reach the sustain level after the hold phase.
| Values | Description |
|---|---|
| <decay> | Specifies the decay time in milliseconds, ranging from 0 to 10000. If 0 is specified, the volume is immediately set to the sustain value, and fade processing begins. |
Sets the target volume level for decay processing.
| Values | Description |
|---|---|
| <sustain> | Specifies the sustain volume level as a percentage, ranging from 0 to 1500%. This percentage corresponds to the volume set by the V command. |
Specifies the time it takes for the volume to fade from the sustain level to 0 after the decay process is complete.
| Values | Description |
|---|---|
| <fade> | Specifies the fade time in milliseconds, ranging from 0 to 10000. If 0 is specified, the volume will remain at the sustain level. |
Specifies the time it takes for the volume to decrease from the level at note-off to 0. This effect is only applied when the command following the note-off is a rest.
| Values | Description |
|---|---|
| <release> | Specifies the release time in milliseconds, ranging from 0 to 10000. If 0 is specified, the volume is immediately set to the 0. |
Psgino features a software LFO. By enabling this function, you can add vibrato to the sound output.
Sets the ON/OFF state for the software LFO. The default value is OFF.
| Values | Description |
|---|---|
| <mode> | Sets the software LFO mode, with 0 corresponding to OFF and 1 to ON (modulated by a triangular wave). |
Example:
V15L4O4
$J4$L80$T8
$M0
CDE2
$M1
CDE2
Sets the modulation depth. The default modulation depth is 0.
| Values | Description |
|---|---|
| <depth> | Specifies the modulation depth, ranging from 0 to 255. If the modulation depth is n, the frequency of the sound varies from 2^(-n/360) times to 2^(n/360) times, depending on the modulation function. |
Sets the modulation frequency. The default modulation frequency is 40 (which equals 4.0 Hz).
| Values | Description |
|---|---|
| <low-frequency> | Specifies the modulation frequency, ranging from 0 to 200. The unit is 0.1 Hz. |
Specifies the time from the start of sound output until the LFO starts operating. The default value is 0.
| Values | Description |
|---|---|
| <delay> | Specifies the delay time for the LFO, ranging from 0 to 128. If the delay is non-zero, it uses the same calculations as the L command to determine the delay time. For example, if the delay is set to 4, the LFO will start operating after the time of one quarter note has passed. If the delay is 0, the LFO starts immediately. |
| <dot> | Specifies a dot. The dot effect is the same as for A-G notes. |
Biases the frequency of the output sound. The default value for bias is 0.
| Values | Description |
|---|---|
| <bias> | Specifies the bias, ranging from -500 to 500. If the bias value is n, the frequency of the output sound will be multiplied by 2^(n/360). |
Example1:
V15L4O4
CDE2
$B30 CDE2
$B60 CDE2
$B360 CDE2
Example2:
V15L1O4
AA
,
V15L1O4
A$B1A
Sets the TP offset. The default value for tp-ofs is 0.
| Values | Description |
|---|---|
| <bias> | Specify the tp-ofs in the range (-100) to 100. |
Example:
CDEFGAB>C,
$O1CDEFGAB>C
Smoothly increases or decreases the frequency of the output sound to the value specified by pitchbend-level until the output stops. The default value is 0.
| Values | Description |
|---|---|
| <pitchbend-level> | Specifies the pitch bend level, ranging from -2880 to 2880. If the specified value is n, the frequency of the output sound changes smoothly to a final value multiplied by 2^(n/360). |
Example:
V15L16O4
$P-360 CDEFGAB>C<
$P360 CDEFGAB>C<
Invokes a user-defined callback function. When this command is decoded, it synchronously invokes the registered callback function. The interface for the callback function is as follows:
void (*user_callback)(uint8_t ch, int32_t param);
Here, ch represents the channel number of the MML where this command is written, and param represents the parameter of this command.
The function registered with SetUserCallback() is executed for MML registered with SetMML(), while for MML registered with SetSeMML(), the function registered with SetSeUserCallback() is executed.
| Values | Description |
|---|---|
| <data> | Specifies the value to be stored in the parameter of the callback function as an int32_t type. Enclosing data in parentheses allows for input in C-style octal and hexadecimal formats (e.g., 010, 0xF). |
Example:
T120L4O4CE@C1234G,
T120L4O4EGB@C-999,
T120L4O4@C(0xF)G@C(010)B>D
To add a header at the beginning of the MML, you can do the following:
:V <version-number> [ [header-command] ... ];
The header starts with a colon and ends with a semicolon. If the header section is omitted, the MML is treated as version 1.
NOTE: Currently, there is only one version of MML, which is version 1.
This command sets the mode-flags for the MML. Each field of the flags is as follows:
| Bit | Field | Description |
|---|---|---|
| 15-1 | - | Reserved. |
| 0 | RH_LEN | Switches the default value when the R or H command omits the note length specification. - 0: The default value for note length is 4. - 1: The default note length is the value specified with the L command. |
If this command is not executed, the mode flags will be set to the value specified by the argument mode.
Example:
:V1M1;
L4O4CEG.R8 N36N40N43.R8