MGSDRV MML 11

From MSX MUSIC WIKI
Jump to: navigation, search

MGSC1.1[en]

MGSC MML compiler version 1.11 Copyright(c) 1992-93 by Ain

MGSC MML Compiler converts MML (text file) to MGS formatted play data.

Usage

SyntaxMGSC <Source file[.MUS]> [<Object file>] [Option]

<Source file>

Specifies the file name of MML source. If extension is omitted, .MUS is used.


[<Object file>]

Specifies the name of data file after compile. If it is omitted, same name as <Source file> is used.

Path can be included as file name in DOS2 environment.

[Option]

Specifies options. These are available below.

-p

Starts playing music after compilation. Error occurs if MGSDRV does not exist. During playing music, you can do forwarding with SELECT (if you use turboR, fast forwarding is available with SHIFT + SELECT) and exiting with ESC. When MGSDRV resides in memory you can continue to playing music after exiting with SHIFT + ESC. Replaying or volume control is available with ten keys in MGSDRV v3.13 or after.

-q

Reterns to dos immediately. Compare to -p option which returns DOS only when ESC is pressed or playing is finished. If MGSDRV does not reside in memory, returns to DOS after playing music instantly. It is not valid without -p option.

-t

Shows status of usage in every tracks after compile. Numerics in parens mean below (left to right) Allocated bytes (with #alloc etc) Used bytes Available bytes Final line shows sums of these bytes.

-s

Ignores #no_mgs and forces data to be saved.

-n

Does not save data. It is recommended to use with -p option while debugging.

-e

Uses only CP/M functions (see appendix).

Control functions

#opll_mode <0|1>

Specifies OPLL modes. 0 means FM 9 sound mode and 1 means FM 6 sounds + rhythm mode. If this command is not executed, all if other control commands(including MML) are not valid. Execute this first definitely.

#machine_id <0〜7>

Specifies vendor codes which the data made (compiled) for. When programs uses this vendor codes, volume balances are adjusted on every MSX vendors models. Vendor codes are preserved like below.

1:SONY 2:Panasonic 3:SANYO

Numerics other than these are invalid and should not be used. Use 0 (same as omitted) for other vendors.

#lfo_mode <0|1>

LFO mode. 1 makes fast LFO speed little bit. Default is 0.

#title <"string">

Specifies title name of the data. Multiple lines are valid if you use with "{" and "}". Maximum length is 1k byte, including comments or others.

   Example:#title {   "Falcom Ys morning grow"
       "SCC is needed"				}

If you want to use double quotation in strings, repeat twice. If "Object too big" error occurs when exceed 80 characters in the title, usually it can be avoided with allocating track buffer (and reduce it lesser than automatic allocated bytes) with #alloc.

#alloc <track no. = bytes>

Allocates track buffers. Usually, track buffer is automatically allocated (16k/ all tracks(=16 or 18) bytes) when the track is used first time. If you use many tracks to write MML in, allocate bytes with this command.

Example:#alloc	0=100; Allocates 100 bytes to track 0 
    #alloc {	3=100,
       5=256 } 
Allocates multiple track buffers at once

Sums of track buffers are limited upto 16k bytes. Track 0 is not used for MML, but tone settings or others. It is enough to use with default settings.

#psg_tune { notes data for c, c# ... b}

Change data for defining notes for PSG and SCC. Each data define for octave 1( range is from 0 to 4095 and needed for every 12 notes.) Commonly, it is not needed to set up.

#opll_tune { notes data for c, c# ... b}

Change data for defining notes for FM. Each data define for octave 1( range is from 0 to 511 and needed for every 12 notes.) Block information is not included. Commonly, it is not needed to set up. This command destroys parameters of @¥ command of MML(as a specification).

#tempo <57〜2047>

Sets tempo. It us valid in the source codes only once. It is recommended to use this rather than t command in MML when setting tempo at the first time as far as possible. Default is 120.

#macro_offset <definition_character = no>

Sets offset number of macro to a character from alphabet(A-Z). Commonly, definition of macros uses numeric 0-255, and this command makes purpose clearly recognizable by assigning offset number to characters.

Example:#macro_offset a = 32

    *48 = { cdefgab }

It is same as macro number 48, called with *a16.

    #macro_offset { a = 32,
                    c = 16 }
    *20 = { t150 }
    *40 = { v15 }
    *42 = { l16 }
    1 *c4*a8*a10

"t150v15l16" is written to track 1.

These definitions, such as *a16 etc are available in commands and MML which deals macro number. Be care full sums of offsets and value not to exceed 255 or duplication, because it translate simply these strings to macro number.

#play_start

Starts playing music after compiling. It is same as -p option of command line.

#no_mgs

Does not generate .MGS files. It is same as -n option of command line.

#track_status

Shows usage status of every tracks after compiling. It is same as -t option of command line.

#play_track

Plays only tracks specified when starts playing. It is valid only with MGSC. If it is omitted all tracks are played.

Example:#play_track 367ABR

It plays only track 3,6,7,A,B and R.

Note: this command only specifies tracks and does not play actually.

#end

Specifies the end of the source. MGSC stops to compile when it appears on the line. Actually <EOF> is recognized as the end if the source and this command can be omitted.

#disenable_mgsrc

Sets protection attribute not to be discompiled with mgsrc.com. It is not recommend to use this thoughtlessly ...

Macro definition

MGSC can define macro. Macro can be called with "*" MML command. Contents of macros are not retrieved when macro is defined and error occurs in the line which calls it.

Define macro at the top of the line like below.

  • <macro_number> = {strings}

The range of macro number are 0-255 (offset can be set). Lines can be multiple, if the end of the lines have "}". Redefinition (define same macro number more than twice) can not be allowed. The length of macros should be within 4k bytes.

Definition of program control strings

Define strings which are passed to external programs. This function can be used, for example, synchronizing external programs with playing musics etc. (by passing addresses to work area(MIB)). MGSEL shows strings on the screen with @m MML command.

Define it at the top of the line like below.

@m<define_number> = {"strings"}

Strings should be with quotations. The range of definition number are 0-127. If number is omitted, previous number(default 0) +1 is used. Control codes can be used with escape sign(¥) 40H added to character code you want. (¥C means ^C and ¥Z means ^Z).

Other examples are below.

¥¥ means¥

¥" means"

¥x?? character specified with hexadecimal number(2 digits).

Characters written after escape code are capitalized. ¥@ cannot be used because it is internal code for terminating strings. Strings are written to track 0. If you want define many strings, allocate track buffers previously with #alloc or others. Refer to manuals for control strings.


Tone definition

Tine definition has "@" at the top of the line. All of <number> means tone number. The range are 0-31.

@e<number> = { Mode,Noise,data...data }

Defines envelope data. It is the same format as _ESET in old versions of MGSDRV(which means MGSDRV ver2.xx).

(1) Mode Specifies tone/noise mode for PSG. The range is 0-3 and 1 is used when it is omitted.

0 - no specification (and nothing changed)
1 - only tone
2 - only noise
3 - tone and noise

(2) Noise

Specifies noise frequency for PSG. It is ignored if it is used for tracks other than PSG. It is valid when mide is more than 2. The range is 0-31. 0 is used when it is omitted.

Mode and Noise are set only when @ commands are executed.

(3) Data Specifies envelope data. It is allowed up to about 255 characters (depends on contents)

0〜f(hexadecimal)

Sets hexadecimal number as volume and waits one count. It is written as <volume> below.

<volume>
<counts>

Sets volume and waits counts.

<volume>=<counts>

Changes current volume automatically to specified volume within a time specified by counts.

n<noise frequency>

Changes noise frequency of PSG. It is same as Noise of (2).

/<mode> or *<mode>

Changes Mode of PSG. It is same as Mode of (1).

[

Defines start position of repetition.

]

Defines end position of repetition.

@<tone_number>

Changes tone data. It is valid only for SCC and FM. It changes only tone data, not envelope. It should be defined tone data previously with @v(@s).

y<r>,<d>

Writes data<d> to register<r>, which actually uses envelope. It is ignored for SCC.

¥<n>

Adds <n> to current frequency. The range is -127 to 127. It rises frequency with positive number. Unit is the same as "¥" MML command.

.,

Separator. Place between numerics (example:n4.456789)

The range of the <count> is 2-239.

@r<number> = { Mode,Noise,AL,AR,DR,SL,SR,RR }

Defines envelope data.

   Mode ... same as@e.
   Noise ... same as@e.


These are brief explanations below. The range of these values are 0-255.

AL

Volume at the moment of the key on. Bigger number, bigger volume.

AR

Speed of reaching to maximum volume(255) from key on. AR is added to AL every moment and DR processing starts when sum exceeds 255 in real processing.

DR

Speed of reaching to next SL from maximum point. DR is reduced from maximum point at every moment and SR processing starts when sum is less than or equal to SL real processing.

SL

Moving point from DR to SR.

SR

Speed of reducing volume. This value is reduced from SL at every moment. This processing continues until if volume become zero or key off.

Up to about 10 is appropriate because if you set huge number to this parameter, sound ends in a moment (if you wish it on some purpose).

RR

Speed of reducing volume from key off. RE is reduced from envelope volume which currently holded.

@r and @e

@r and @e shares working are to define, so both of them cannot be defined simultaneously. Latter one is valid, in such case.

@s<number> = { data1 .... data32 }

Defines tone data fir SCC. Data are hexadecimal(00-ff). Data should be 32 units and cannot be omitted.

Example:@s02 = { 7f7f7f7f 7f7f7f7f 7f7f7f7f 7f7f7f7f	;PSG
       80808080 80808080 80808080 80808080 }
@v<number> = { data ... }

Defines original tone of FM.

Example:@v15 = {						;BRASS
  ;       TL FB
          25, 7,
  ;       AR DR SL RR KL MT AM VB EG KR DT
           8, 8, 1, 2, 0, 0, 0, 1, 0, 0, 0,
           8, 2, 1, 1, 1, 1, 0, 1, 0, 0, 0 }

Parameter format is same as _VSETC of the old versions of MGSDRV.

@#<number> = <n>

Changes assigned ROM tone number of the tone. MGSC assigns 1-15 of ROM tone to @0-14. Tones after @15 is assigned 0(original tone) and definition of tone is valid when <number> is more than 15. @# changes ROM tone number assigned to each tones. The range of <n> is 0-15 and 0 means original tone(refer about other numbers).

Comments

If ";"(semicolon) are found in the lunes(including MML), it is recognized as comment from the semicolon to the end of the line(CRLF) and ignored.

MML

When 1-H exists at the top of the line, MML data is written to the specified track. Tracks are assigned according to #opll_value as such below.

Mode 0 (FM 9 sounds mode)

 1-3 ... PSG  4-8 ... SCC  9-h ... (continues a,b,c,d...)

Mode1(FM 6 sounds + rhythm mode)

 1-3 ... PSG  4-8 ... SCC  9-e ... FM  f ... rhythm (r is available as well)

One or more spaces (or tabs) should be between track specification and MML data.

Example: 123a v15cdef ;"v15cdef" is written to track 1,2,3a

Length of the sound can be specified by steps with "%". Quarter note equals to 48 steps (example:a4=a%48). Steps within one note can be set up to 256.

Available MML are below. These are listed with small letter but, both of capital or small letters are equivalent, both are OK actually. <n> means number. Almost of all numbers cannot be omitted and it is different from that of old versions of MGSDRV. Spaces and tabs among MML are ignored.

t<n>

Specifies tempo. The range is 57-2047. Effects all of tracks.

l<n>

Specifies default sound length. The range is 1-192(but limited according to tempo). It can be specified with . , % or number of steps. Default is 4.

^<n>

It means tie, to lengthen note by adding commands of note length. If <n> is omitted, length will be

&

It means slur and is valid only when put immediately after notes. It is distinguished from tie.

q<n>

It means ratio of length. The range is from 0-8. Key on continues when it is 0(only for FM). Default is 8. It is not available in rhythm track.

v<n>

Controls volume. Volumes for all instruments are set in rhythm track. The range is 0-5. Hardware envelope is disabled for PSG. Default is 0.

v+|-<n>

Changes volume relatively. The range is 0-15. Volumes for all instruments are set in rhythm track.

)<n>

Increases volume. It is same effect as v+. The range of <n> is 1-15. 1 is used when it is omitted.

(<n>

Decreases volume. It is same effect as v-. It is same as ")<n>" other than that.

v<instrument><n>

It is valid for only rhythm track. Specifies volumes of the instruments. Select one from bsmhc as <instruments>. The range of <n> is 0-15.

v<instruments>+|-<n>

Changes relative volume of rhythm instruments. The range is 0-15.

k<n>

It is valid for only PSG and SCC. Specifies speed of vanishing sound after key off. The range is 0-255. The fastest is 0. It is ignored(set but not effected) when using envelope set by @r or hardware envelope. Default is 0.

@<n>

Changes sound tone. The range is0-31. It is not available for rhythm track.

@e<n>

Copies envelope data set by @e or @r to current tone. It is valid for SCC or FM. It is same as <n> for PSG.

@r<n>

It is same as @e<n>

m<n>

It is valid only for PSG. Sets envelope cycle. The range is 1-65535.

s<n>

It is valid only for PSG. Sets hardware envelope shape. Software envelope is reset(but still has tone number and can be reversed with V command etc.) The range is 0-15.

n<n>

Sets noise frequency. It is valid only for PSG. The range is 0-31.

o<n>

Sets octave. The range is 1-8. Default is 4.

>

Moves to higher octave.

<

Moves to lower octave.

a〜g[+,-][n]

Makes tones. + sharps a note and - flats. Number after note means length of note(number of l command is adopted if it is omitted).

_scale

(Example:a_o4c4, a_>>g, a_b%100)

Changes notes smoothly from previous one to specified note. (example:a_o4c4 a_>>g a_b%100)

r

Rest. It adopts value if l command if it is omitted and that is different from BASIC.

name_of_instrument[
]

Makes specified rhythm sound. Default length of sound adopted if ":" is specified (example:bh4 bh:). It is not valid in other than rhythm track.

¥<n>

Sets detune quantity. The range is -127-127. Default is 0.

@¥<n>

Sets detune quantity in detail. The range of PSG and SCC is -32768-32767. 128 equals to half note. The range of FM is 0-255.

p<n>

It is valid for only PSG and SCC. Sets quantity of automatically redundancy of notes. The range is 0-255. It is not available with LFO at a time. If you want effects like p command of older versions of MGSDRV, add 128(it is differently executed between 0-127 and 128-255).

h<n1>,<n2>,<n3>,<n4>

Sets and starts tine LFO. It is only triangle wave.

n1:Delay(0-255) n2:Depth(0-127) n3:Speed(0-255) n4:Roughness(-127-127)

@p<n>

Sets roughness of LFO. It is valid only for PSG and SCC. The range is -32768-32767. It is used immediately after set of tone LFO.

ho

Starts tone LFO.

hf

Stops tone LFO.

hi

Initialize tone LFO and return to execution if decay(LFO parameter itself is not initialized)

[<number_of_loops>-]

Repeats playing MML from inside of braces specified times. The range of loops is 0-255. 0 means eternal loop. It is available up to 16 times nest.


[-]<numberofloop>

Same as upper one. Number of repetition is written outside of braces.

|

It is used with repeating command. When it appears in playing final loop, exits loop here.

so

It is valid for only FM. Set on sustain.

sf

It is valid for only FM. Set off sustain(default).

ko

It is valid for only rhythm track. Not to turn off the sounds when rhythm sound is generated(default).

kf

It is valid for only rhythm track. It turns off the sounds when rhythm sound is generated.

/<n>

It forcibly key off for FM(it is valid with q0). It changes tone or noise mode for PSG. The range is 0-3. It is same as Mode in @e other than that 0 means "mute sound". It is not available in other tracks. Parameters are not available for FM.

y<n1>,<n2>

Write data n2 to register n1. Sound source is automatically selected according current playing tracks. The ranges of n1 are, 0-56 for FM(rhythm) and 0-15 to PSG. The range of data is 0-255. It is not available for SCC.

@l<n>

Changes total level of original tone(of FM). It is same as y2,<n>. It is not available for SCC.

  • <n>

Calls macro according to specified number. It is available 8 times nest. The range is 0-255(offset available).

!

Ignores all of MML after this command in the track.

@m<n>

Calls control strings. The range is 0-127. Previous number(default 0) +1 is used when it is omitted. Note that precessing of omission executed in compile time.

@o<n>

Sets offset of control strings. For example, "@o2@m12" sets "@m14" for 2(@o2)+12(@m12). It is used for lyrics etc. which has same MML but different data during loops.

@f

Increments [fadefg] of MIB. MGSEL starts fading out but actual behavior is different among programs(sometimes nothing occurs).

$

It means debug command. It does fast forward automatically up to the position of "$" command when played with -p.

About Errors

MGSC stops compiling when detects even one error in the source.

   <error_reason> in <line_number>
   >> <(all_of)contents_in_the_line>

Error reason is printed in Kanji character when Kanji driver resides and printed in alphabets in other case.

Line numbers are counted from 0 (and matches with KID.COM,AKID.COM editors' one). Note that there are not always exists the reason of errors in displayed line inside (especially in the case of macros and omission of close brace).

Appendix

(1)Tempo

MGSC never occurs tempo gaps between tracks with any tempo, but pay attention to tempo changing.

'#tempo' should be used with for the first time. You should change tempo in the first track and if you change it again in the songs, synchronize timings with other tracks.

Example:
  1 t86l4ct190def
  2  l8ccddeeff
  3    l16cdecdecd

Example above does not occur tempo gaps but example below occur it, because changing tempo while playing musics on the tracks 2 and 3.

Example:
         1 t86l8ct190def
          2    l4cdef
          3    l4gggg

Tempo are not independent on every tracks. Track 2 and 3 does not have tempo settings but that on the track 1 (to be exact, at the note next to changing tempo) effects other tracks in 2 examples above. Tempo setting on such manner only consumes track buffers.

Example:
          1 t86cdet90cdet100cdef
          2 t86efgt90efgt100efga
          3 t86ccct90ccct100cccc

(2)Length settings

Meanings of length setting with "%" of MGSC are different from old versions. MGSC is not effected by tempo, old versions has different value for each tempo though.

For example, fourth note is always %48. MGSDRV does not need length setting with %, as far as notes has the length which can be divided by 192.

Quintuple note (5 notes) cannot be divided from 192 by integer, set appropriate length of note with %.

Valid minimum length of note is effected by tempo(MGSDRV cannot make sound shorter than 1/60 seconds). Formula of minimum length of note with tempo is as follows.

14400/tempo = minimum length (truncated after the decimal point)

Minimum length of note is hundred-ninety-second(192) note when result of this formula is greater than 192.

(3)Searching to MGSDRV

MGSDRV is required for playing musics with -p option. Resided MGSDRV is used but if it is not on the memory, the file defined as environmental valuable mgsdrv is loaded. DOS1 searches MGSDRV.COM in the current directory.

    • Compiled data with this version of MGSC can be played on MGSDRV v3.13 or higher.

(4)Assigning ROM tone number

The name of tones are different from that of MSX-MUSIC

Tone number ROM tone number Tine name
0 1 Violin
1 2 Guitar
2 3 Piano
3 4 Flute
4 5 Clarinet
5 6 Oboe
6 7 Trumpet
7 8 Organ
8 9 Horn
9 10 Synthesizer
10 11 Harpsichord
11 12 Vibraphone
12 13 Synthesizer bass
13 14 Wooden bass
14 15 Electric bass
15 0
: Original tones
31 0

(5)-e option on command line

-e option limits to only CP/M functions. MGSC works on CP/M emulators etc. if Z80 commands are supported. Playing musics are not supported (-p option and others are not valid).

History

version1.06(private ver)

  • Added @f command
  • Added $ command
  • Inserted waits to fast forwarding(SELECT) while playing with -p option on fast mode of turbo R
  • Added fast forwarding with SHIFT+SELECT keys (on only fast mode if turbo R)
  • Added control command
  • Added automatic return to DOS after end of playing music


version 1.07

  • Added #macro_offset,#machine_id
  • Discontinued function to enclose MML with "{" and "}" which had had bugs from ver1.04
  • Added hi (LFO initialization) command


version 1.08

  • Corrected kanji text garbling in control strings
  • Added #disenable_mgsrc command
  • Added -s option to force saving data


version 1.09

  • Added Y and \ command to @e envelope
  • Corrected end of file error of DOS


version 1.10

  • Corrected disorder bug of "/" command in @e envelope.
  • Added #opll_tune
  • Added @l command


version 1.11

  • Added -q option
  • Enables standard input as source(type a.mus | mgsc)
  • Added CP/M support


    • Citation and redistribution are not restricted


Special thanks

TARO
Saibara
BLASTER
TAKAWO
CHABIN

Refference: MXC Document

MARIO NET  :AIN
FALCON NET :FALC0180
NATSUME NET:NAT25667

�Ain