gym2mid Version 0.7  by Paul Jensen
------------------------------------


Contents
--------

	1) What is gym2mid?

	2) How do I Create a .GYM File? (New! 2/20/99)

	3) What's New in this Version?

	4) Features

	5) Future Features

	6) Known Bugs (Updated 2/20/99)

	7) Revision Notes

	8) Port Author Info

	9) MIDI Author Info

	10) Special Thanks

	11) Contact Info


What is gym2mid?
------------------

	gym2mid is a utility for Windows 9x that converts Genecyst version
	'x.xx' YM-2612 log files (.GYM) to MIDI format 0 files (.MID).


How do I Create a .GYM File?
----------------------------

	I'll make this short, and sweet:

	1) Make sure you have Genecyst version 'x.xx'

	2) Go to 'LOG YM2612 -> START' on the 'SOUND' menu.

	3) Start up the song you want to sample (a sound test is a
	   good place for this).

	4) Go to 'LOG YM2612 -> STOP' on the 'SOUND' menu when you've
	   sampled what you've wanted to sample.

	5) There is no step 5.  You're done.  Now STOP ASKING ME HOW TO
	   CREATE A .GYM FILE!!! :)


Features
--------

	Spiffy GUI
	Note On/Note Off events
	Frequency Changes
	Realistic Pitch Bending
	Patch Change Markers (see MIDI Author Info)
	Stereo Sound
	DAC Event Capturing (see MIDI Author Info)
	PSG support (Master System-type noises)
	Volume Levels


Future Features
---------------

	Evidently, YM Channel 3 can have 4 individual frequencies when
	set to a special mode.  I might look into this, but I don't
	know if it's really worth the effort.

	Native support for playing MIDI files via Win32	API calls.

	More faithful algorithm (instrument) changes.

	Sound envelope alterations using MIDI RPNs.

	I'm open to suggestions... (See Contact Info)


Known Bugs
----------

(2/20/98):

	The frequency -> MIDI note code is better now, but still a
little dodgy.  Hopefully it works for you.


(11/22/98):

	While the new frequency->MIDI note code is more accurate than
before, a few games don't like it.  I've noticed that music from
Telenet and Wolfteam games come out sounding pretty bad.  If there are
others, please let me know.


<SQUASHED>
	Many (if not most) of the .mid files produced by gym2mid will
not be recognized by Windows Media Player (and a few other MIDI apps, I
believe).  I'm not sure what is causing this.  I might modify the
program to output MIDI format 1 files instead of format 0.  I don't
know if that will do anything, but it's worth a shot.
</SQUASHED>


Revision Notes
--------------

Version 0.7  (2/20/99):

	Another minor update, I added a few options that let you
	enable/disable stereo sound, patch change markers, volume
	levels, and re-implemented support for pseudo-pitch bending.
	The conversion progress indicator has been slightly modified,
	and an about box has been added. Version 0.7  also allows you
	to minimize the window.

Version 0.51  (11/24/98):

	This is a rather minor update.  I updated and re-implemented
	volume levels for the FM chip.  It doesn't quite match the
	dynamics of the original Genesis, but the channels blend
	together a little better now.

	I also changed the default midi program (instrument) from
	'Acoustic Grand Piano' to 'Bass + Lead'.  I found that this
	is a more mellow patch with a greater range.  It also puts
	greater emphasis on the pitch bending.

Version 0.5  (11/22/98):

	Added PSG support(!!!), made the frequency->MIDI note code more
	accurate, and did the usual code cleaning.

Version 0.4  (11/17/98):

	Added more realistic pitch bending, added partial support for
	the PSG, ditched the Common Dialog ActiveX Control in favor of
	Win32 API calls, and fixed up the code a little bit.

Version 0.3.50 (11/9/98):

	Fixed a MAJOR bug... That is, the one that prevented a Windows
	Media Player and several other MIDI players/editors from
	reading gym2mid output files.  Smiles and rainbows all around.

Version 0.3 (11/9/98):

	Fixed some bugs, and increased conversion speed... a lot.
	Conversions are running about 100X+ faster now.  No, really...
	I'm not kidding.  Thanks go out to Renato Cherullo de Oliveira
	for figuring out how to change gym2mid from a Pinto to a
	Porsche.

Version 0.2 (11/5/98):

	Spiffed-up the GUI, cleaned up the code, fixed some bugs, made
 	the frequency->MIDI note conversion more accurate, added
 	support for DAC events (see MIDI author info), and changed the
	name from GYM-2-MID to gym2mid (what a difference, huh?).

Version 0.1 (10/4/98):

	Initial Release, a few bugs/unhandled errors.


Port Author Info
----------------

(2/20/99):

	Nothing big this time, either.  Sorry, guys (and girls(?))

(11/22/98):

	No real changes this time around, either, except for the
new PSG code.

(11/17/98):

	The only real differences in this version are the new
pitch-bend code, some commented-out code for PSG support, and the
addition of 'CommDlg.bas' (Win32 API support).

(11/9/98):

	The .gym input data and .mid output data are now stored
differently in memory now.  Instead of being stored as strings, they
now stored as dynamic byte arrays.

	I also added a new function called WriteMidiEvent.  I added
this to centralize the code that handles all of the .mid data, and
eliminate redundant code.

(11/5/98):

	You'll notice that I have added some 'CONST's to the code.  I
hope this makes the code appear less confusing.  I've also added a
couple of comments, but nothing very verbose.

(10/4/98):

	The source for gym2mid is written in VB5, but I imagine it
could be easily ported to another language.  If you have any specific
questions, please feel free to contact me (see Contact Info).

	I haven't added any comments yet, but I will do so if the need
arises.


MIDI Author Info
----------------

(2/20/99):

	Nothing new this time.  Sorry.

(11/22/98):

	PSG tone generator 1, 2, 3, and the noise channel are on MIDI
channels 11, 12, 13, and 14 respectively.  The default program for the
three tone generators is 80 (square wave).  The noise channel uses
the Applause and Helicopter patches to simulate the proper PSG noises.

(11/17/98):

	The new pitch bending utilizes Registered Parameter Numbers
(RPNs) to alter pitch wheel sensitivity.  Howver, this may or may not
work correctly on your particular soundcard.  It should work just fine
if you have an AWE32/AWE64, or any soudcard that supports RPNs.

(11/5/98):

	DAC events are handled as follows: when the DAC is enabled on
the YM2612, FM Channel 6 is disabled.  However, certain Genesis games
use Channel 6 to control DAC stereo output.  If the DAC is enabled, and
a speaker position change occurs on Channel 6, the gym2mid creates a
MIDI note 42 (closed high hat) on MIDI channel 10, marking the moment
which the sound is supposed to be played.  These notes can then be
edited to match the original composition.
	
(10/4/98):

	When you first open a .MID file created with gym2mid, you'll
probably notice a lot of junk mixed in with all of the notes.  This is
caused by two simultaneous 'Note-Off' events (I think).  To clean up
the notation, all you have to do is select every note (ideally with a
'Select All' command), filter out the ones with a length/duration of 0,
and delete them.

	gym2mid creates patch change markers at the points where the
YM2612 changes its algorithm (don't worry about what that means).
Simply put, if the YM2612 changes instruments, then a Patch Change event
will occur, set to 0 (Acoustic Grand Piano).  You can then modify the
patch to whatever instrument you think would sound best.


Special Thanks
--------------

Thanks to Jim at EMU News for all his help.

Thanks to Dave (author of DTMNT) for his help and moral support. 

Thanks to Marat Fayzullin for his document on emulator authoring.

Thanks to Renato Cherullo de Oliveira for finding a more efficient way
to store the .GYM and .MID data in memory.

Thanks to Genter Nagler for his utilities MidiFix, Midi2Txt, and
Midi2Hex.  These tools were essential in figuring out just what the
hell was wrong with the output files.

Thanks to the folks at Emulation Zone for the web space.
http://www.emulationzone.org

And, of course...

Thanks to Sardu for creating Genecyst (and Callus, and NESticle), the
best (IMO) Genesis (and CPS1, and NES) emulator available.


Contact Info
------------

Please feel free to send any questions, comments, or bug reports to me,
Paul Jensen ( pj@emulationzone.org ).

Please *DO* read the documentation.  It should answer most of your
questions.

Please *DO NOT* ask me questions about Genecyst (unless it pertains to
gym2mid), where to find .GYM files, Genesis ROMs, etc.  Any such
requests will be ignored.