VGM Player - Readme
==========

General
=======
Usage: Drop a file on the executable or open the program and type the filename.

Supported files types are:
- Video Game Music Files (*.vgm, *.vgz)
- Creative Music Files (*.cmf)
- DosBox RAW OPL Log Files (*.dro)
- Playlist files (*.m3u)

Supported chips
---------------
- SN76496** (PSG) and T6W28** (NGP custom)
- YM2413* (OPLL)
- YM2612 (OPN2)
- YM2151 (OPM)
- SegaPCM
- RF5C68
- YM2203 (OPN)
- YM2608 (OPNA)
- YM2610/B (OPNB)
- YM3812* (OPL2)
- YM3526* (OPL)
- Y8950* (MSX AUDIO)
- YMF262* (OP3)
- YMF278B (OPL4)
- YMF271 (OPLX)
- YMZ280B
- RF5C164 (Sega MegaCD PCM)
- PWM (from Sega 32x)
- AY8910 (another PSG)
- GameBoy DMG
- NES APU
- MultiPCM
- UPD7759
- OKI6258
- OKI6295
- K051649
- K054539
- HuC6280
- C140
- K053260
- Pokey
- QSound


* This chip can be emulated via OPL Hardware (like Soundblaster sound cards).
** OPL hardware emulation is available, but software emulation is prefered. Hardware emulation is used if another chip activates HW emulation or FMForce is True.

OPL hardware emulation can be enabled by setting the "FMPort"-entry in the ini-file.
If you want to use FM Hardware under Windows NT/2000/XP/... you have to install PortTalk.
PortTalk Website: http://www.beyondlogic.org/porttalk/porttalk.htm
Under Linux the program must have root rights to use Hardware FM.

It's possible to write Wave-Files by editing the "LogSound"-line in the ini-file.
Batch conversions are possible by opening a playlist.
FM Hardware can't be logged to Wave files.

Keys
----
You can use the following keys during playback:
Cursor Left/Right - Seek 5 seconds backward/forward
Ctrl + Cursor Left/Right - Seek 1 minute backward/forward
ESC - Quit the program
F - Fade out
R - Restart current Track
PageUp/B - Previous Track
PageDown/N - Next Track

Note: All keys also work during silent sound logging.


System Reqiurements
===================
It depends on the files you want to play.

Minimum Reqiurements
--------------------
Software Emulation:

Pentium II with at least 233 MHz
16 MB RAM (plus a size of the VGM you want to play, so for a 100 MB vgm, you need ~110 MB RAM)

That allows you to play VGMs with up to 2x FM, 2x PSG or FM + PSG + PCM.
It's NOT enough for YMF271 emulation.
The YMF262 is equal to 2x FM. The YMF278B is Wavetable + YMF262 (with the latter one disabled if unused).

Hardware FM Playback:

486 with 33 MHz? - I dunno
On my PII 233 MHz FM Playback takes 3.5% CPU at a maximum.


Bugs
====
PauseEmulation is disabled under Linux if no FM Hardware is used.

Under Linux you have to double-tap ESC to quit the program. I haven't yet found a way around it.

Sometimes MAME's sound cores tend to sound strange. I already fixed some, but it's not my fault.

Ubuntu refuses to run (or maybe compile) VGMPlay correctly. It either crashes upon opening a vgm file or doesn't open the sound device. (and the ini-file, too. VGMs are opened for some reason.)
It runs fine on openSUSE. (tested with 11.1 32-bit and 11.4 64-bit)
Note: Using Wine with the Windows-version of VGMPlay should work.


Comments
========
If you want to set some options, open the ini-file. It's well commented.

The T6W28 doesn't use MAME's T6W28 core. Instead I modified the SN76496 core to emulate the T6W28 with 2 SN76496 chips.

The SN76496 OPL emulation is okay, but it's impossible to get the noise sound right.

EMU2413 Emulator was added, because sometimes the one of MAME sounds strange.
I added the Gens YM2612 core for the same reason (before I fixed MAME's YM2612 core).

I haven't yet found a player that supports all three version of dro files. 
P.S.: AdPlug now seems to support them.

Some may be wondering, how someone can have the idea to implement OPL Hardware support. Here a more or less small story:
I like CMF MIDI files, but I was unable to listen to them while doing other things on my computer in Windows 95. It was impossible to listen to them unter Windows 2000. When I found AdPlug, the CMF support was bad and I started to make my VGM Player play CMF files. Debugging wasn't nice - a Pentium2 233MHz isn't stong enough for a Software OPL Emulator in Debug Mode. The OPL2-Port option in AdPlug was interesting (I have a Soundblaster 16) and showed me the power of PortTalk.
My MIDI-FM Player that got OPL-Hardware-Support earlier than my VGM Player, because playing usual MIDI files requires a lot more debugging than playing simple VGM files. When it was working in my MIDI player, I implemented OPL-Hardware-Support into VGMPlay. Of course the first working chips were OPL/OPL2/OPL3. I remembered that Meka had OPL-Support, too and wrote my OPLL->OPL-Mapper. It sounded quite good, but I was unable to get the PSG and the YM2413 of Space Harrier Theme in sync. So a PSG->OPL-Mapper followed. Later I ported Meka's OPL Mapper, because I liked the bass of some Phantasy Star tunes.


Credits
=======
This program was written by Valley Bell.

- almost all software emulators are from MAME (http://mamedev.org)
- EMU2413 and Gens YM2612 were ported from Maxim's in_vgm
- the YMF278B core was ported from openMSX
- zlib compression by Jean-loup Gailly and Mark Adler is used
- all custom OPL Mappers were written using MAME software emulators and the OPL2/3 programming guides by Jeffrey S. Lee and Vladimir Arnost
- the RF5C164 and PWM cores were ported from Gens/GS
- the MAME YM2612 core was fixed with the help of Blargg's MAME YM2612 fix and Genesis Plus GX' YM2612 core
- AdLibEmu (OPL2 and OPL3 core) was ported from DOSBox
