﻿================================================================================
              VGM PLAYER by BEN RYVES version 1.0 [SEPTEMBER 2005]
================================================================================

Brief
-----
This is a simple, small, stand-alone VGM player. There are existing players
available, but they either require external software (such as Maxim's WinAmp
plugin), run as part of an emulator (Martin Konrad's Emukon) or are in Japanese.
As a little weekend project I decided to knock together a player, and this is
the result!
If looking for VGM packs, head over to http://www.smspower.org/.

================================================================================

Features
--------
- Plays VGM files for the SN76496 PSG (Master System, Game Gear, BBC Micro, ...)
- Game Gear stereo mode.
- Simple interface: Seek bar, play/pause/stop.
- Change white noise generator sound between 3 different effects.
- Supports loading of VGZ files.
- No need to install extra apps (which is why I wrote it!)
- Display of GD3 tags.
- Loop point support.

================================================================================

Running
-------
Drag and drop a VGM/VGZ file on top of the vgmplay.exe program. It should start
playing. You can also run the application from the command line, but when you
run it from the command line no mouse events will be triggered so you have to
control the player using the keyboard.
Note: GD3 tag dates are displayed in the form YYYY/MM/DD.

================================================================================

Control
-------

[►] (Space)     : Play         - Start playback of loaded VGM.
[▼] (Space)     : Pause        - Pauses playback of loaded VGM.
[■] (Full-Stop) : Stop         - Stops playing.
[♫] (N)         : Change Noise - Cycles white noise effect.
[→] (L)         : Looping off  - Disables looping at loop point.
[↔] (L)         : Looping on   - Enables looping at loop point.
[×] (Escape)    : Quit         - Quits the application.
You can click on the seek bar to jump around your music file.
The different noise effects relate to different hardware. The default mode is
Sega Master System/Sega Game Gear, but will cycle through SC-3000H and Acorn
BBC Micro modes. All 3 have slightly different quality of sound.

================================================================================

Thanks (in no particular order)
------

- Richard Talbot-Watkins for his SMS documentation which provided the main
  reference for the PSG emulation.
- Maxim for his in-depth SN76496 PSG documentation that cleared up a few
  timing issues and provided the source for accurate noise-channel emulation.
- Dave for his documentation on the VGM format and the source inside Maxim's PSG
  documentation.
- SMS Power! for their great collection of VGM packs, assorted documents
  and VGM tools.

================================================================================

Technical
---------
Just in case you're wondering - the PSG emulation was coded from scratch and was
surprisingly simple. To get the basic features up and running took all of about
15 minutes! The only thing that took a bit of extra time to implement was the
accurate noise channel from Maxim's extensive notes - hopefully it sounds good
enough! I'm using SDL to create a sound device and manually mixing the audio (it
seemed to be the easiest way). I ignore the FM chip writes (sorry!) as most of
the music I was interested in was purely for the PSG anyway.

================================================================================

Source
------
I have included the source code for anyone who wants to nose around in it. It's
not very neat (just a single source file!) I developed it in VS.NET (so there 
are project files included). It will need to have access to the SDL and ZLIB 
libraries/headers.

================================================================================

Known issues
------------
Files that specify exact delays (0x61 NN NN) are not played at the correct
speed - I have no idea why. The speed problem is also the reason why these files
go a bit bonkers if you start seeking inside them. Most files seem to be fine,
though.
Also, the Japanese GD3 tags display as empty on my PC. Not sure why this is,
(I use wprintf() to display the data..?) but maybe it's because I'm using a UK
English copy of Windows.

================================================================================

Change log
----------

[VERSION 1.0]
- Removed visualisation. Emphasis is now on a simple player.
- Completely rewrote noise channel code to emulate more accurately. (Used to be a
  case of "rand()&1").
- Seek code now goes by sample rather than position in file - slower seeking, but
  more accurate and scales by time rather than complexity of song.
- Added support for VGZ (.GZ compressed VGM files) through the ZLIB library.
- Fixed sample timing so rather than my guessed frequency scaling the frequency
  is calculated correctly.
- Enable/Disable loop options.
- Time display.
- Stopped crash on Ctrl+C, Ctrl+Break or click of Close button.
- Updated frequency scaling between clock rate of 

[VERSION 0.2]
- Fixed loader so that song was loaded correctly at right address.
- Fixed loop offset so songs now loop cleanly.

[VERSION 0.1]
Preliminary version, test release.


================================================================================
           Ben Ryves 2005 - http://benryves.com, benryves@benryves.com