gym2mid Version 0.75 by Paul Jensen
------------------------------------


Contents
--------

	1) What is gym2mid?

	2) How do I Create a .GYM File?

	3) What's New in this Version?

	4) Features

	5) Future Features (NEW!  Updated 5/12/99)

	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' YM2612 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 .GYM FILES!!! :)


Features
--------

	Spiffier, Simpler GUI
	Note On/Note Off events
	Frequency Changes
	Realistic Pitch Bending
	Pseudo-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.  This mode is used for synth drums and
	sound effects. 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.

	(New!) User-defined patch changes (Coming very soon...)

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


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

(2/20/99):

	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.75 (5/12/99):

	This is a major/minor update.  I completely re-tooled the GUI
	(modeled after Winamp, only without the cool visuals and
	custom skins), added in a toggle switch for pitch bending
	(which eliminates the trilling effects caused by musics that
	use vibrato effects), and a toggle switch for DAC support.  Now
	before you freak out because of a stupid misunderstanding,
	gym2mid does not support digital sound, for several reasons:

		1) I don't know a damn thing about digital sound
		   programming.  I'm a MIDI author/VB coder, not
		   Sardu or Hiroshi.

		2) Even if I was either of those people, MIDI doesn't
		   support digital sound anyway.

		3) (The Big One) Even if I _were_ Sardu or Hiroshi,
		   and even if MIDI _did_ support digital sound,
		   DAC emulation would be impossible because .GYM
		   files do not contain any DAC information, as doing
		   so would result in a lot of redundant data (or so
		   I imagine).

	And just in case you're wondering what in the kuso user-defined
	patch changes are (most of you probably aren't, but...) here's
	the short of it:

	The MD/Genesis' sound processor (Yamaha YM2612) has eight
	feedback algorithms for producing different types of sounds.
	The programmer's guide lists suggestions for which types of
	sounds/instruments each	algorithm is best suited for (since the
	waveforms can be modified on the fly, one algorithm can be used
	for several different sounds).

	Determining which exact instrument the YM2612 is trying	to
	synthesize is basically impossible, which is why gym2mid
	inserts only a marker for where a patch	(instrument) change
	occurs, so it can be edited later.  Unfortunately, those of
	you without MIDI editing software can't change the patches to
	suit your liking.  But once I add user-defined patch changes,
	you'll be able to select an instrument for each of the eight
	algorithms.

	NOTE:  This feature is NOT present in gym2mid 0.75.  It will be
	included with any future release(s).		

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
----------------

(5/12/99):

	Well, the big changes are that the GUI is different, the file
selection process has been modified (and simplified), and the MIDI code
and gym2mid engine have been separated (in anticipation of a new
utility...).

(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
----------------

(5/12/99):

	I read a few eMails/Usenet posts concerning certain disliked
features in gym2mid.  Since I try to keep people happy, I added in
options for toggling certain features (mainly because some just plain
don't work right, but also so that people can tweak the output files
to their liking).  The next big thing is user-defined patch changes,
so stay tuneder, whatever. 

(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.  Good luck with your new
job, Jim.

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(s) available.


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

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

Please *DO* visit the gym2mid homepage periodically to learn about
updates, and new utilities.

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.