﻿================================================================================
              VGM PLAYER by BEN RYVES version 1.1 [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/.
There is a copy of the loading tune from the BBC Micro game Fire Track included.

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

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.
[x] (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. The mode is
shown after the control strip and before the time. The modes correspond to 
the following systems:
- SMS: Sega Master System or Game Gear mode.
- SC3: SC-3000H mode.
- BBC: Acorn BBC Micro mode.
You can click the mode text to cycle noise modes if you find that easier.


There is a row of asterisks [****] which are there to allow you to switch on/off
individual channels. You can click them to toggle them, or use the keys 1-4.

Note that if you have QuickEdit mode enabled (right-click titlebar, Preferences,
Options) - which is the default in Windows 2000 - mouse clicks will not be sent
to the application.

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

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. I use the ZLIB 
library to decode the GZ compressed VGM files (.VGZ).

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

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.

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

Tested VGM packs
----------------

BIOS, Marble_Madness, Ninja_Gaiden, Prince_of_Persia, Ristar_(GG), Road_Rash,
Sonic_the_Hedgehog, Space_Harrier, The_Flash.
I have not found any problems trying to play VGMs from the above packs.

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

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

[VERSION 1.1]
- Fixed reading of files. I'd used 'char' instead of 'unsigned char'. Files
  that played back as plain silence now play back fully, also play at correct
  speed. What a stupid mistake - it's amazing it worked at all!
  I ended up rewriting the entire PSG emulation thinking it was that that was
  to blame... evidently not!
- Halved frequency of noise channel by only switching output once on 2 clocks.
  It was an octave too high before!
- Fixed odd jumping/incorrect (after loop) seek bar.
- Changed [x] exit button to use 'x' character rather than the cross symbol -
  the cross appeared as a "Pt" sign under Windows 2000.
- Removed display of Japanese tags.
- VGM files that loop back to the exact start of the file are now looped rather
  than ignored.
- Added display of system name for noise mode and very stupid autodetection.
- Sound output is now averaged inside each 44100Hz sample to "antialias" the
  output. Sound output that relies on channels at 0 outputting fully now work.
  Sampled audio still sounds a bit noisy/weird. Sound is now output at 16-bit.
- Option to enable/disable sound channels individually.
- Accelerated seeking considerably.

[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