-----------------------------------------------------------------------------
Highly Experimental v2.07
PSF player plugin for Winamp
Copyright 2003-2004 Neill Corlett
-----------------------------------------------------------------------------

Introduction
------------

Highly Experimental is an input plugin for Winamp that plays PSF and PSF2
files, which contain music from Playstation and Playstation 2 games.  Highly
Experimental emulates the CPU and sound hardware in order to play the music
from these games.  The same concept has been used with similar formats for
other game systems:  NSF, SPC, SID, and GBS.

If you don't have any PSF files to play, you can start by checking my home
page at http://www.neillcorlett.com/, where I've linked to a few archive
sites.

-----------------------------------------------------------------------------

File Format Overview
--------------------

.psf (Playstation Sound Format) - A self-contained file with one song.
  Includes driver code, samples, and sequence data.

.minipsf (Miniature Playstation Sound Format) - An abbreviated file generally
  only containing the sequence data for a song.  Relies on .psflib files,
  residing in the same directory, for driver code and/or samples.

.psflib (Playstation Sound Format Library) - A file providing driver code
  and/or samples for one or more .minipsf files.  Not playable as a separate
  file.

.psf2, .minipsf2, .psf2lib - Similar to the above, but for Playstation 2.

-----------------------------------------------------------------------------

Requirements
------------

* A Pentium or higher PC.  I'd recommend at least a Pentium Pro 200 for PSF,
  and a Pentium II 333 for PSF2.
* A media player which supports either the Winamp 2 or 3 plugin API.
  Note: Winamp 5 will work too.
  Winamp can be downloaded freely from http://www.winamp.com

-----------------------------------------------------------------------------

Setup
-----

For Winamp 2 or 5:

Copy in_psf.dll into the Plugins directory inside your Winamp directory,
i.e. "C:\Program Files\Winamp\Plugins\".  Close and re-start Winamp if
necessary so it will recognize the new plugin.

For Winamp 3:

Rename in_psf.dll to "cnv_psf.wac" and copy it into the Wacs directory inside
your Winamp directory.  Close and re-start Winamp if necessary so it will
recognize the new plugin.

-----------------------------------------------------------------------------

Configuration (WINAMP 2 AND 5 ONLY)
-------------

Highly Experimental saves all its options into the plugin.ini file in the
same directory as the DLL, under the section [HighlyExperimental].  Here's a
rundown of the options you may configure:

General:

* Force all songs to play indefinitely

  Select this if you want all songs to loop for as long as possible.  Winamp
  will still show the standard length and standard seekbar, but when it
  reaches the end of the seekbar, it will keep going.  And going and going!
  Longer than Nixwalk!  Note that songs may still end if there is a prolonged
  period of silence, and you have the "Stop after ___ sec. of silence" option
  enabled.

* Default length / fade

  This is the default length for PSFs that don't have length information in
  their tags.  Format is minutes:seconds.

* Suppress opening silence

  This will cause the plugin to skip silence at the beginning of songs.

* Stop after ___ sec. of silence

  This will cause songs to end prematurely if a prolonged period of silence
  is detected.  This is useful for songs that don't loop, but also don't have
  a length tag.  You can define how prolonged is "prolonged" by entering a
  number of seconds into the edit box.

* Thread Priority

  Selects the priority of the emulation thread.  Higher priorities may help
  if you encounter problems with skipping.

  Note that if you select "Above Normal" or "Highest", the thread will
  temporarily demote itself to "Normal" during initial load and seeking.

Output:

* Global Volume

  This is a multiplier that affects the volume of all PSF files and is
  independant of Winamp's main volume.  Change this if you notice that all
  your PSFs are a different volume than all your MP3s, or something similar.
  1.0 is normal.

* Soft Saturate instead of clipping

  Reduces pops and clicks associated with clipping by using a soft saturation
  algorithm.  No more wincing at those loud crescendos!  You should leave this
  enabled unless you know you have a reason to disable it.

* Resample output to _____ Hz

  Normally, PSF files play at 44100 Hz and PSF2 files play at 48000 Hz (the
  real hardware sample rates).  Enable this option if you'd rather have them
  play at the sample rate of your choice.  This may be helpful if you're
  trying to diskwrite CD tracks from PSF2s, or if your sound card isn't
  capable of 48KHz output.  This option increases CPU usage, so you probably
  shouldn't use it unless you have to.

Errors:

* Perform strict format checking on all files

  Enable this option to perform additional file format checks on every file
  played.  Highly Experimental will refuse to play a file that fails the
  checks.

  Note that CRC checking is now no longer performed unless you have this
  option enabled.  However, zlib's uncompress function should be robust
  enough to handle most corrupt files.

* Show error messages instead of silently advancing

  With this checked, Highly Experimental will verbosely pop up a message box
  on every error, rather than just allowing Winamp to advance to the next
  song.

  This is disabled by default, because I don't think plugins are supposed to
  do this.  Consider:  If you're running Winamp in the background or you're
  away from the PC, and it's shuffling through a large playlist, and a few of
  the files on that playlist no longer exist... you don't want a message box
  and a lot of dead air.  You'd want it to silently advance.  Still, enabling
  this option is useful for troubleshooting.

Title:

* Title Format

  This affects the titles shown in Winamp's main player window and the
  playlist.  Variables enclosed in % signs, such as %title% or %game%, are
  replaced with the corresponding values from the PSF file's tag.

* Fallback if no variables are defined

  If a particular file contains none of the variables listed in the title
  format, then the plugin will use this alternate format instead.

Emulation:

* Enable Main

  Lets you enable or disable the main (non-reverb) output.  Useful if you
  want to "solo" the reverb effects alone.  I added this for debugging and
  decided to leave it in as a permanent option.

* Enable Reverb

  Lets you enable or disable reverb effects.  For authentic sound, you
  should leave this on.  I left it optional in case someone wants to
  diskwrite and add their own effects, for instance.

* Simulate frequency response of real PSX/PS2

  This adds some subtle filters to the sound in an attempt to make it closer
  to the real Playstation analog output.

* Compatibility mode

  This is an advanced option used mainly for debugging.  It should be kept at
  "Friendly", as "Harsh" can cause a delay at the beginning of certain songs,
  or cause them not to work at all.

* Show R3000 CPU usage (percent) under "kbps"

  Check this option to make Winamp's kbps display (which is otherwise unused)
  show the current R3000 CPU usage.  This is based on the number of idle
  cycles detected during emulation, and is not related to host CPU usage.

-----------------------------------------------------------------------------

File Information (WINAMP 2 AND 5 ONLY)
----------------

The layout of the File Information (Alt+3) box should be familiar to anyone
who's used Winamp to play MP3s before.  Here you may edit the title, artist,
game, year, genre, comment, and copyright associated with the song, and the
name of the PSF file's creator ("PSF by").

(Note: Changing the "PSF by" name does not actually make it so that person
created the PSF.  I have no plans to resolve this issue in future versions.)

You can also set the relative volume, song length, and fade length of each
file.  The volume you set here is relative to the global volume set under
Configuration.  Lengths set here will override the defaults.

Finally, the Raw Mode button will allow you to edit the raw ASCII tag
associated with the PSF file.  This can be useful if you wish to add your
own custom variables to the tag.  Simply add extra lines of the format
variable=value to the end of the tag.  You can then make these show up in
Winamp's player window and playlist, by adding %variable% to the title
format under Configuration.

-----------------------------------------------------------------------------

Known Bugs, Issues, Unhappy Things
----------------------------------

* Winamp 3 support is incomplete, and now that Winamp 3 itself is deprecated,
  I don't see much reason to finish it.  Upgrade to 5 if you haven't already.

* Seeking.  Seeking forwards is slow, and seeking backwards requires the
  plugin to rewind the PSF to the beginning.  This is an unfortunate tradeoff
  of the format.

* Speed.  There's still a lot of optimization left to go, especially on the
  PS2 side of things, where there's double the SPU and a more complicated
  runtime environment.

* Emulation.  I've filled in a few gaps since v1.0, but it's still far from
  complete.  There's a fine line which must be walked between "what can be
  emulated" and "what can be nopped out"...

* Reverb.  It sounds great and I don't plan on revisiting it anytime soon,
  but it's still not 100% accurate.

-----------------------------------------------------------------------------

Terms of Use
------------

Highly Experimental is freeware and may be distributed freely as long as it
is not modified, and this documentation is included and not modified either.
"Distributed freely" means no money, goods, or services may be charged or
solicited for Highly Experimental or any media or software package
containing it.

Anyone using Highly Experimental does so at their own risk.  I will not be
held liable for any loss or damage arising from its use.  No warranty is
expressed or implied.

-----------------------------------------------------------------------------

Highly Experimental includes code from the following projects:

* zlib Copyright 1995-2002 Jean-loup Gailly and Mark Adler
  http://www.gzip.org/zlib/
* UPX Copyright 1996, 1997, 1998, 1999, 2000, 2001, 2002 Markus F.X.J.
  Oberhumer & Lszl Molnr
  http://upx.sourceforge.net/

-----------------------------------------------------------------------------

Thanks to
---------

* Necrosaro/radimvice.  This was all his crazy idea; blame him.
* _Demo_, because ePSXe is handy for debugging.
* Pete Bernert, for contributing to my Neill Corlett Appears In Every Readme
   Ever Project.  The least I can do is return the favor.
* All the people who followed my progress on this without getting fed up.
* ProtoCat, for everything.  For bug testing, but most importantly, for
  awarding me the Nixwalk Seal of Approval.
* Peter Pawlowski for assistance with Winamp 3 support.
* Yaz0r for some PS2 info.

-----------------------------------------------------------------------------

Where to find me
----------------

email: neill@neillcorlett.com
web:   http://www.neillcorlett.com/

-----------------------------------------------------------------------------
