PSG2YM 0.40: PSG to YM Converter
Copyright (C) 1998 PenSoft. Written by Niclas Pennskog.
URL: http://www.rtg.se/~niclas/  E-mail: niclas@rtg.se
Based on code written by Marcel de Kogel.

*** NOTE! This is version 0.40 and has not been tested very much.
*** This text document is just a quick info about the program.


Description
-----------

This program converts PSG files to uncompressed YM files in YM3 or YM5 format.
YM-files can be played with the ST-Sound Player.

The PSG format is simply a recording of the sound chip registers synchronized
to vertical blank interrupts.

The YM3 format is more or less also just the sound chip register values stored
in a file. The YM5 format adds more entries in the header, like Title, Author,
Loop Point etc. If you're interested in the specification of the format, download
the ST-Sound Player.

All YM files can and should be compressed with LHA to save space.


Usage
-----
Usage: PSG2YM [options] <PSG file> <YM file>
 Available options are:
  -ym3            - Write in YM3-format (default)
  -ym5            - Write in YM5-format
  -c              - Compress using LHA
  -as             - Analyze start of tune
  -o <value>      - Start at offset (interrupt freq.)
  -ifreq <value>  - Set the interrupt frequency in Hz (default=50 Hz)
  -cfreq <value>  - Set the chip frequency in Hz (default=1,832,727 Hz)

Notes:
The -ifreq and -cfreq switches are only used with the -ym5 switch.


Steps
-----

Steps to record a song in the fMSX Emulator and convert
it to a YM-tune playable in the ST-Sound Player. I've used fMSX-DOS
by Marcel de Kogel (http://www.komkon.org/~dekogel/fmsx.html).

1. Start fMSX with the option "-logsnd dump.psg" where
   dump.psg is the file the PSG is logged to.
2. Use PSG2YM to convert the PSG dump to a YM-tune:
   "PSG2YM dump.psg dump.ym -as"
3. The new file "dump.ym" will now be an uncompressed
   YM-file playable in the ST-Sound Player.

Steps to get the right start position:
1. Play the YM-file in ST-Sound and write down
   the aprox. time (in seconds) for the starting point.
2. Lower this time with a second or so and multiply this
   with 50 (ifreq).
3. Use the PSG2YM switch "-as" to make the conversion
   search for the first position where one of the sound
   channels volume is higher than 0.
   Set the "-o <value>" switch with the calculated value
   to set the offset where the search should start.
   Example: "PSG2YM dump.psg dump.ym -as -o 450"
   It is possible the search could fail. Then you have
   to try guessing the offset value by increasing it
   until it sounds good.

Steps to find the loop point:
1. Record the song as in the steps above.
2. Convert to YM3-format using PSG2YM.
3. Use YMTOOL (from author of ST-Sound) to analyze for
   the loop point.

How to compress the YM tune. There are two ways:
1. Put LHA.EXE in the same directory as PSG2YM.
   Use the -c switch when converting.
2. Use YMTOOL with the switch -C. You will also need LHARC.EXE.
   Future versions of PSG2YM will also have this function (with
   the help of LHARC).

Distribute:
 Please do not distribute songs that don't sound correct,
 or songs that are incomplete. Always use the YM5 format,
 otherwise the song will not be tuned correctly.
 Compress all songs.


Limitations
-----------
1. The defauly chip frequency is probably not correct. I'm using the
   frequency stated in the fMSX source code. But Marcel De Kogel (author
   of fMSX-DOS) tells me that the frequency should be 1,789,773 Hz. I'll
   change the default value when I can tell the frequency for sure...

1. PSG2YM does not convert SCC sound chip data since the YM format is
   strictly for the YM. This is not really a limitation!
   The SCC sound chip was used by Konami in several games and is not
   a standard MSX component.

2. The main theme for Auf Wiedersehen Month does not convert very well.
   The "blips" and "blops" disappear and sometimes strange "blips" can be
   heard. I don't know if this is because of the PSG log file or PSG2YM.


History
-------

Version  Date       Comment
0.40     98-01-29   It is now possible to compress the YM file (-c).
                    Added an option to set the cip freq. (-cfreq) since
                    the default value probably is wrong.
0.31     98-01-19   Fixed a bug in the YM5 format (Number of VBLs).
0.30     98-01-17   Analyzing of start point (-as) and an option to set
                    the start offset (-o).
0.20     98-01-07   Added a few options (-ym5 and -ifreq)
0.10     98-01-07   First working version (YM3).


Contacts and locations
----------------------

PSG2YM
Description: Converts PSG files to YM files
Author: Niclas Pennskog [niclas@rtg.se]
URL: http://www.rtg.se/~niclas/

ST-Sound Player
Description: Plays YM files (and more)
Author: Arnaud Carr (Leonard / OXYGENE) [leonard@mygale.org]
URL: http://www.mygale.org/09/leonard/stsnd.htm

fMSX Emulator
Description: Portable MSX Emulator
Author: Marat Fayzullin [fms@cs.umd.edu]
URL: http://www.komkon.org/fms/

fMSX-DOS Emluator
Description: MS-DOS port of the fMSX Emulator
Author: Marcel de Kogel [m.dekogel@student.utwente.nl]
URL: http://www.komkon.org/~dekogel/fmsx.html

PaCifiST
Description: Atari ST Emulator
Author: Frederic Gidouin [frederic.gidouin@hol.fr]
URL: http://www.pacifist.fatal-design.com/
