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** (Sega PSG) and T6W28** (NeoGeo Pocket 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 (MSX PSG)
- GameBoy DMG
- NES APU (incl. FDS)
- MultiPCM
- UPD7759
- OKI6258 (Sharp X68000 ADPCM)
- OKI6295
- K051649
- K054539
- HuC6280 (PC Engine)
- Namco C140
- K053260
- Pokey (Atari)
- QSound
- SCSP (Saturn Custom Sound Processor, YMF292-F)
- WonderSwan
- Virtual Boy VSU
- SAA1099
- ESS5503
- ESS5505/6
- Seta X1-010
- Namco C352
- Irem GA20


* 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.
! You need a sample ROM, called yrw801.rom, to make playback work. Place it in the directory where VGMPlay.exe lies.

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:
Space - Pause
Cursor Left/Right - Seek 5 seconds backward/forward
Ctrl + Cursor Left/Right - Seek 1 minute backward/forward
ESC/Q - 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:

166 MHz should be enough for SN76496 + YM2612.
For chips with 12+ FM channels you need probably need at least 700 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 unless FM Hardware is used.

Under Linux you have to double-tap ESC to quit the program (or just press Q). 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.)
Using Wine with the Windows-version of VGMPlay should work.

It runs fine on openSUSE. (I compile and test it regularly with 12.3 64-bit. Older version were successfully tested with 11.1 32-bit and 11.4 64-bit)
It also ran fine on the Debian system at university.


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
- one YM2413 OPL Mapper was ported from MEKA.
- 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
- The default HuC6280 core is from Ootake.
- EMU2149, the alternative NES APU core and the NES FDS core were ported from rainwarrior's NSFPlay.
- the WonderSwan core was ported from in_wsr
- Virtual Boy VSU core was ported from vbjin and originates from mednafen
