|    /  /| |    |    |     /| |    |    |\       0000   0000   00000
|   /  / | |    |    |    / | |    |    | \      0  00  0  00 0  
|  /  /__| |    |____|   /__| |    |    |__\     0000   0000  0  000
| /  /   | |    |    |  /   | |    |    |   \    0  00  0     0   00
|/  /    | |___ |    | /    | |___ |___ |    \   0   00 0      0000

   Music Script Maker - MIDI to music script text Converter for RPG Maker 2

=================================================================
 ValhallaRPG                     Alpha Version 0.1.1 (2004/09/28)
=================================================================

Table of Contents                Index

- What is Music Script Maker        TC0001
- Revisions                        TC0002
- System requirements                TC0003
- How to work it                TC0004
- Overview                        TC0005
- Program's GUI                        TC0006
- Menu Options                        TC0007
- Status Bar                        TC0008
- SFX Table Manager (F2)        TC0009
- Drum Kit Manager (F3)                TC0010
- Script Layout (F4)                TC0011
- Music Script Commands                TC0012
- FAQ                                TC0013
- Issues and Bugs                TC0014
- Contact                        TC0015
- Disclaimer                        TC0016

To jump to a scepcific topic, use CRTL+F to find it and write the desired index number
from the table of contents.



----------------------------
 What is Music Script Maker        TC0001
----------------------------

It's a program that converts MIDI files into text documents for music scripts for
RPG Maker 2 on the Playstation2. The program lets you open MIDI files that you convert
in a one or multiple rtf files. (rich text format)

This program is freeware and it is not to be modified or sold.

I put alot of time, heart and effort into this project and I'm hoping to make it even
better. I sacrified alot of my time and even put aside my own RPG Maker 2 project
for this.
Even if this program is this in Alpha development, it is fairly advanced and
operational to
convert with precision the MIDI files in format 1. For those of you who waited for
months
the release of this project, I apologize for the delays, but I had to make sure that
there was no major problems for the MIDI conversions. After all, I don't want you to
spend
countless hours to program music scripts that would be wrong so I had to make sure
there
was no flaw for most possible situations. Well enjoy!


---------------------
     Revisions                        TC0002
---------------------

v0.1.1 (Alpha)

- None.


---------------------
 System requirements                TC0003
---------------------

- A Pentium III or higher running Windows 98, ME, or XP;
- 800 Mhz processor or higher;
- At least 128MB RAM;
- A monitor with minimum resolution of 640 X 480.


---------------------
   How to work it                TC0004
---------------------

Make sure that MSMaker.exe and all its files and folders are in the same programs
folder. Open MSMaker.exe and you're in business!

Here's a brief description of each necessary files and folders:

- MSMaker.exe         The converter program
- Layout.cfg                Configuration file for the script layout
- Comment.cfg                Configuration file for the user's comment at the begining of the
                        Main Script.
- SFX Tables folder        Folder used for the Sound FX Table list
- Drum Kits folder        Folder used for the Drum Kit list

If these files don't exist, the program will create all the default files and folders
necessary when runing MSMaker.exe.


---------------------
      Overview                        TC0005
---------------------

This program lets you convert a MIDI file into text that represent music scripts for
RPG Maker 2. So if you feel more comfortable using MIDI files than composing
directly in
RPGM2 scripts, than this converter can be really useful. In other words, this program
tells you what SFX pitch, tempo, volume, pan, and Wait time to set for each note so
that
you don't have to calculate it.


How does it work?

Basically, you open a valid MIDI file (format 1 only for now) and the text documents
for
the scripts are generated automaticaly. Each document reprensent a track plus you
have the
main script document used to apply all the scripts (tracks) together. You can create
SFX Tables to replace the 128 MIDI programs (sounds) into any of the 200 sound effects
available in RPGM2. In a similar way, you can also create Drum Kits and make your own
drum sets by using RPGM2's sound effects. Then in the script layout window, you can
specify which SFX Table to use and set Drum Kits on the desired MIDI channels.
(Drum Kit is usually set on channel 10)

** Refer the to Help file for a detailed tutorial about this converter. To get the
help,
you can open MSMaker.hlp or press F1 while using the program. Right now there's no
help file available for this release.


---------------------
   Program's GUI                TC0006
---------------------

Once a MIDI file is opened, the program can look like a text editor. (more like a text
viewer in that case) Above, the menu options and the toolbar are displayed. At the
bottom, the status bar is displayed.


---------------------
   Menu Options                        TC0007
---------------------

- FIle Menu -

-> Open Midi File (CRTL + O)
Opens a standard MIDI file.  Right now this programs supports only format 1.

-> Close Text (CRTL + F4)
Close the active text document.

-> Close All
Close all the text documents and the MIDI file.

-> Save As (CRTL + S)
Saves the active text document. The save format is in rtf, which means Rich Text
Format.

-> Save All As (CRTL + L)
Saves the all text documents at once in rtf format. You choose the directory where all
the files will be saved. And then you specify a prefix name for all the files. As for
the rest of the files names, each track is indexed with its track number and original
MIDI channel number. For example, "Battle1 - T02C04.rtf" means that it's the 2nd track
of the music named Battle1 and that it is converted from the channel 4 on the MIDI
file.
The main script would be indexed as follow: "Battle1 - Main Script.rtf".

->Print... (CRTL + P)
Prints the active document. This sofware do not have strong support to customize the
page format for printing. It is recommended that you use a text editor for this.

-> Exit
Ends Music Script Maker's session.


- Edit Menu -

-> SFX Table Manager (F2)
Opens the SFX Table manager. You can view the SFX Table list, delete, rename, and edit
them. When you edit a SFX Table, you specify 3 things for each standard drum sound:
- one of the 200 Sound FX for each standard MIDI sounds;
- the SFX Tempo;
- the Script -> Sound Stop command behavior.

-> Drum Kit Manager (F3)
Opens the Drum Kit manager. You can view the Drum Kit list, delete, rename, and edit
them. When you edit a Drum Kit, you specify 5 things for each standard drum sound:
- one of the 200 Sound FX;
- the SFX Tempo;
- the SFX Pitch;
- the SFX Pan;
- the Exclusive Group number.

-> Script Layout (F4)
Opens the Script Layout dialog box. This is where you format the scripts with your
preferences.


- Tools Menu -
There's nothing for the Tools menu for this program's version. Later, I plan to make
an
utility that could directly convert a MIDI file into a Sharkport or X-Port save of
RPG Maker 2 but I'm far from being at this state in the program.


- Windows Menu -

-> Close
Close the active text document.

-> Close All
Close all the text documents and the MIDI file.

-> Cascade
Sets all documents that are not minimized in a cascade setting.

-> Horizontal
Sets all documents that are not minimized in a horizontal setting.

-> Vertical
Sets all documents that are not minimized in a vertical setting.

-> Arrange Icons
Aligns all the minimized documents at the bottom of the screen.


- Help Menu -

-> Contents (F1)
Displays the help file on Music Script Maker. Right now there's no help file
available for
this release.

-> About ...
Used to view general information about Music Script Maker.


---------------------
    Status Bar                        TC0008
---------------------

At the bottom of the screen, the status bar is displayed. The status bar shows general
information about the MIDI file and scripts as well as specific information about the
active text document (script). The staus bar has 5 sections:

1- Script size
This is the size that the script should have if it is writen exactly the same way in
RPG Maker 2. The number to the left is the size of the actual script document and the
number to the right is total size when you combine all the scripts together.

2- MIDI name
This is the name of the MIDI file currently opened.

3- Script name
This is the name of the active script document. For a track, it uses the first 8
characters
of the MIDI name plus the track number and the MIDI channel number. For the main
script, it
uses the first 8 characters of the MIDI name plus the words "Main Script" at the end.

4- SFX Table used
This is the name of the actual SFX Table used to convert the MIDI file.

5- Drum Kit used
This is the name of the Drum Kit used in the active document to convert the MIDI
channel.



---------------------
SFX Table Manager (F2)                TC0009
---------------------

The SFX Table Manager let's you cerate and manage you SFX Tables. A SFX
Table is used to associate the MIDI programs (sounds) to RPG Maker 2's
sound effects.

Buttons:

- New                Create a new SFX Table. This creates a standard table with
                fairly good sound replacemets.

- Edit                Edit the currently selected SFX Table. See Edit mode for
                explanations.

- Copy                Make a copy of the currently selected SFX Table.

- Rename        Rename the currently selected SFX Table.

- Delete        Delete the currently selected SFX Table. If the SFX Table
                is currently used by the Script Layout, it cannot be
                deleted.

Edit mode:
In edit mode, you can assign some RPG Maker 2 SFX properties to replace
each 128 MIDI sounds. The table is divided into 5 columns:

- #                Standard MIDI database number associated with the MIDI
                sound.

- MIDI Sound        Name of the Standard MIDI sounds. (also known as programs)

- SFX Name        Choose between the 200 Sound effects from RPG Maker 2 to
                replace the MIDI sound.

- Tempo                This is the SFX Tempo to apply. To give a fixed SFX tempo
                for the entire script, enter a value from 1 to 999. To use a
                variable tempo (the MIDI note length), enter the value 0.
                For instrumental SFX like piano or flute, you should use the
                value 0 to keep the the MIDI note length. For fixed length
                SFX like "Gun", you may prefer to give a fixed SFX tempo.
                100 is the default SFX in RPG Maker 2 when creating a new
                Sound effect.

- Script -> Sound Stop        Choose how to apply the Script Sound Stop Command.
                        If you choose "Always", a Stop command is placed
                        after each note that stops playing. If you choose
                        "When SFX tempo is over 999", a Stop command is
                        placed only when the SFX tempo is over 999. This is
                        good to prevent long-time SFX (like flute) to stop
                        playing after their playing time-length is over,
                        thus preventing to overlap on the next sound in the
                        same track. If you choose "Never", there's no Stop
                        command placed after the note that stops playing.

Note:
Using a Script -> Sound Stop command will also stop any other sound
effects that are currently playing, so use that command wisely. The "Always"
option should not be used unless your music uses only one voice. Even then,
the "When SFX tempo is over 999" is probably your best option if you need to
make a sound stop when it finishes playing.


---------------------
Drum Kit Manager (F3)                TC0010
---------------------

The Drum Kit Manager let's you cerate and manage you Drum Kits. A Drum Kit
is used to associate the MIDI Drum sounds to RPG Maker 2's sound effects.

Buttons:

- New                Create a new Drum Kit. Right now I haven't got the time to
                arrange a decent Drum Kit but expect to a Standard
                Drum Kit soon.

- Edit                Edit the currently selected Drum Kit. See Edit mode for
                explanations.

- Copy                Make a copy of the currently selected Drum Kit.

- Rename        Rename the currently selected Drum Kit.

- Delete        Delete the currently selected Drum Kit. If the Drum Kit
                is currently used by the Script Layout, it cannot be
                deleted.

Edit mode:
In edit mode, you can assign some RPG Maker 2 SFX properties to replace
each drum sounds. A Midi drum kit can have 128 sounds, but usually about
half of the sounds are used in a standard kit. The table is divided into 7
columns:

- #                Standard MIDI database number associated with the drum
                sound.

- MIDI Drum        Name of the Standard MIDI drum sounds. Right now, the names
  Sound                are for a Standard kit. Later I will add the names for an
                Orchestral kit as well. With a MIDI sequencer, you can play
                each note from a drum program to help you figure out the
                properties of you own RPG Maker 2 Drum Kit.

- SFX Name        Choose between the 200 Sound effects from RPG Maker 2 to
                replace the MIDI drum sound.

- Pitch                Choose the SFX Pitch. The value can range from -12 to +12.
                It's useful to use multiple pitches to create different
                drum and cymbal sounds

- Tempo                This is the SFX Tempo to apply. To give a fixed SFX tempo
                for the entire script, enter a value from 1 to 999. To use a
                variable tempo (the MIDI note length), enter the value 0.
                Since most drum sounds usually play for a fixed time length,
                it's better to set a fixed SFX tempo value, like 100.

- Pan                Choose the SFX Pan. The value can range from -100 to +100 or
                you can set it to "MIDI". To give a fixed SFX pan for the
                entire script, enter a value from -100 to 100. To use the
                MIDI Pan, use the value "MIDI". Using fixed pan values for
                different drum sounds is a good way to create a good stereo
                atmosphere.

- Exclusive        An exclusive group is a group of drum sounds where only one
  Group                sounds can play at the same time. This means that if a sound
                of an exclusive group is currently playing, it will be cut
                if another sound of the same group starts to play. This is
                useful to simulate a hi-hat cymbal that opens and then
                closes. If the open hi-hat is suddently closed, than the
                sound of the open hi-hat must be muted to hear only the
                hi-hat closing. In real life, that's how it would sound.
                In RPG Maker 2, this means that a Script -> Sound Stop
                command will be used to simulate that effect. You can use
                up to 128 different exclusive groups or set this option to
                "Off". For this program's version, the exclusive group
                feature IS NOT WORKING.


Note:
Using a Script -> Sound Stop command will also stop any other sound
effects that are currently playing, so use as less Exclusive Groups as
possible. Except for Exclusive Groups, no other Stop command will be genrated
for Drum Kits. For this program's version, the exclusive group feature
IS NOT WORKING.
                        

---------------------
  Script Layout (F4)                TC0011
---------------------

The Script Layout is used to format the RPG Maker 2 scripts with your preferences. The
layout is divided into 6 sections: General, Channels On/Off, Drum Kits, Transposition,
Stop Command, Texts and Comments. You can reset the script layout to its default
values
with the "Default" button. Here's the explanation of each sections:

- General -

Music Title:
Here you can change the prefix title that identifies each of your scripts. A midi
file must
be opened to change this setting. The title can have up to 8 characters max.

Sound FX:
MIDI to RPG Maker 2 SFX Table: This is where you assign the SFX Table that will be
used.

Display Line Number:
Choose whether or not to display the script line number at the begining of a
command. It's
highly recommended to keep this option checked because it can be a good reference if
you
want to trace some specific command lines in your script in RPG Maker 2.

Muisc Tempo:
Here you can see the current MIDI tempo. (starting tempo) You can also view the
starting
tempo of your music scripts. Of course to view these informations you must have a
MIDI file
opened. You can change the music script tempo by changing the tempo ratio. So this
means
that the given tempo will change the "SFX Tempo" values and the "Wait" values.


- Channels On/Off -

Here you select the channels that will be converted into music scripts. So if there
are
some channels you don't need, just uncheck them.


- Drum Kits -

Here you select the channels that will use a Drum Kit instead of the SFX Table. In
MIDI
files, the drum kit is usually set on channel 10.


- Transposition -

Here you can transpose the MIDI pitch (not SFX Pitch) for each channels. The values
can
range from -60 to +60.

As you know, the SFX Pitch is limited from -12 to +12, where a
zero value is the central C key. So everything under -12 or over +12 is automatically
transposed in that range for RPG Maker 2's compatibility.

Transposing the MIDI Pitch can be useful if you want to make the notes fit as close as
possible to the RPG Maker 2 SFX range, or if you simply want to transpose the whole
music
in another pitch.


- Stop Command -

Here you select the channels where a Script -> Sound Stop command could be applied. If
you uncheck a specific channel, no Stop command will be applied to the tracks using
that
channel. Know that a Stop command mutes every SFX currently playing in RPG Maker 2, so
unchecking some channels from the Stop command can be a good thing. It depends of how
the tracks notes play together.


- Texts and Commands -

Here you can add some text message comments in your scripts. Comments are displayed in
pale gray in an RPG Maker 2 script and it does not have any effect on the script
coding
itself.

Copyrights and User's Comment (Main Script):
If desired, you can write a short introduction paragraph to add informations about
your
music. If you check the "Display in Main Script" option, this text will appear at the
begining of the Main Script.

MIDI Comments Displayed:
Here you can choose to display "On" or "Off" some comments that gives various
information
about the music and the MIDI file. This can be useful to verify some informations
about
the scripts and the MIDI file.

- Pitch Bend        When the Pitch Bend controler is used, the value is displayed. For this
                program's version, this comment is not active. Music Script Maker does not
                support converting Pitch Bend controler data either.

- Track Tile        Display the name of the MIDI track.

- Tempo                Displays the MIDI tempo changes. For now it does not display the tempo
                ratio if it was changed in the "General" section.

- Time                Displays the MIDI time signature.
  Signature

- MIDI Save        Displays the MIDI format. Right now, this program's version only supports
  Format        format 1.

- Total number        Displys the total number of tracks that exist in the MIDI file,
including
  of tracks        the ones not converted.

- Music Time        Displays the time that the music should play in RPG Maker 2 if the
scripts
  Length        are writen completely.

- Program        Displays the MIDI program (sound) database number that has been changed.
  Change        This can be useful to track down why the SFX's sound name would change in
                the middle of a script. For example, if you have a comment like this:
                ** Midi Program Change: 61, this would mean that the track has switched
                to the "Brass Section" sound.

- Bank Change        Displays the MIDI bank database number that has been changed. A bank        
                contains 128 programs. So a MIDI track can change banks when it needs a
                sound from another bank or a drum kit.

- Volume Change        Displays the MIDI volume change. The volume change is for the overall
                volume of the track, not for the volume of a single note.

- Pan Change        Displays the MIDI pan change. This can be useful to track down why the
pan
                suddently changes in a SFX.

- Damper Change        Displays the Damper switch's current status: "On" or "Off". Damper
events
                are usually used to keep a sound playing even if the note was released,
                like the right pedal on a piano. For now, this program does not support
                Damper events so if you have a piano music which uses alot of these, the
                music SFX may sound kinda broken.

- Total Wait        Displays the total amount of "Wait" values that where used in the track.
  Value                Wait value is 1/30 of a second.

Note:
MIDI comments use alot of memory and command lines in a script. You should use MIDI
comments only to analyse your MIDI file and text scripts. And once you're satisfied
with
the result, you should set most of them to "Off" to lighten your scripts.


---------------------
Music Script Commands                        TC0012
---------------------

This is the list of script commands that can be used to create the music scripts:

- Sound: SFX -
Used to play a SFX. In the SFX, you can set a sound, the volume, the pitch, the tempo
and the pan. Here's an example of how a SFX command is displayed in a text document:

Sound: SFX [170 Snare]  Volume: 74  Pitch: 0  Tempo: 100  Pan: 0

If there's a (T) sign next to the pitch value, this means that the note was transposed
to make it fit in the RPG Maker 2 pitch range between -12 and +12. If that's the
case, any
extra SFX with the same pitch value playing at the same time will be eliminated.


- Others: Wait -
Used to insert a time delay before the next command is executed. The wait unit is in
1/30 of seconds. This is used to insert a time delay between the notes (SFX) that are
played. Here's an example of how a Wait command is displayed in a text document:

Wait: 2


- Script: Sound Stop -
Used to stop all the SFX currently playing. If you have multiple tracks playing at
the same
time, use this command wisely because it could "break" some sounds that you would
want to
hear at the same time. Here's an example of how a Stop command is displayed in a text
document:

Sound: Stop (160 Organ, 7)

In parenthesis, you have the name of the sound and the pitch value it is meant to
stop.
What's in parenthesis is just a reference to understand why a Stop command was
generated.
The program eliminates any extra Stop commands that could appear at the same time if
multiple notes (in a same track) are released together.


- Script: Apply Together -
Executes multiple called scripts at the same time. This is used to play all the tracks
(scripts) at the same time.


- Script: Apply in Order -
Executes one called script at a time.


- Script: Call Script -
Used to call a script and execute it. THis is used to play the tracks. Here's an
example
of how a Call Script command is displayed in a text document:

Call Script <BATTLE1A T01C04>


- Comments -
Comments are used to add some information to the script. Comments do not interfer
with the
script's execution. For music scripts, comments are message commands displayed in
pale gray.
Here's an example of how a comment is displayed in a text document:

** Music Time: 1 min  31,57 sec

In the text document, a comment always starts with two * . In RPG Maker 2, it is
displayed
in pale gray.


---------------------
        FAQ                        TC0013
---------------------

Q. I try to open a MIDI file, but it says that format 0 is not supported?

A- For now only format 1 is supported.


---------------------
   Issues and Bugs                TC0014
---------------------

- You cannot save different Script Layout settings (like files) for now. However the
current Layout setting you use is retained even if you close the program so that you
can continue to work on the same scripts later.

Tips: 
The current Layout setting is saved as Layout.cfg in the program's folder. If you
work on
multiple music projects at the same time and really want to keep all of your Script
Layouts,
you could save each of your settings by making a backup file of Layout.cfg. All you
have to
do to use a specific Layout setting again is to rename it Layout.cfg and put it in the
program's folder. This is a good temporary solution until I complete the option of
saving
and loading Layout settings.

- You cannot directly export the music scripts into a sps or xps file. Yeah I know
this
sucks but I'm working on how to figure that out.

- If you try to Edit, Rename, Copy or Delete a SFX Table or Drum Kit while the list is
empty, an error occur and the program ends. This will be taken care of for the next
release.

- Damper events are usually used to keep a sound playing even if the note was
released,
like the right pedal on a piano. For now, this program does not support Damper
events so
if you have a piano music which uses alot of these, the music SFX may sound kinda
broken.

- This program does not support converting Pitch Bend controler data.


---------------------
     Contact                        TC0015
---------------------

My email is jf.aquin@pyroair.com if you need to report a bug or problem. You can also
report at:

RPG Magazine's forum
Pavillon's forum
Agetec's forum in the RPG Maker 2 section.
RPG Maker Club.

A good reason why you should report bugs in forums is that everyone
can be aware of what the hell is going on with that program :D


---------------------
     Disclaimer                        TC0016
---------------------

- Music Script Maker - MIDI to music script text Converter for RPG Maker 2
  Copyright 2004 ValhallaRPG.
- RPG Maker 2 for the Playstation2 is a registered trademark of Agetec / Enterbrain.
- Playstation2 is a trademark of Sony.

ValhallaRPG is not affiliated with Sony or Agetec / Enterbrain in any way.
Music Script Maker is Freeware and can be distributed freely as long as it is not
modified
or sold. You have the right to upload this software for your RPG Maker 2 webpage as
long as
you give credits to the author (ValhallaRPG). When you use this software you do so
at your
own risks. The author is not responsible for any loss or damage resulting from the
use or
misuse of this software.

If you do not agree with these terms then do not use Music Script Maker.

Now for those who agree with these terms, ... Enjoy and have fun !!

