----------------------------------------------------------------------------- Highly Quixotic v1.01 QSF player plugin for Winamp Copyright 2003-2004 Neill Corlett ----------------------------------------------------------------------------- Introduction ------------ Highly Quixotic is an input plugin for Winamp that plays QSF files, which contain music from Capcom CPS1 and CPS2 arcade games using QSound hardware. Highly Quixotic emulates the Z80 CPU and sound hardware in order to play the music from these games. This is similar in concept to Icer Addis' original QSound Player, except that QSF allows the QSound ROM data to be individually queued in a playlist or tagged. If you don't have any QSF 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 -------------------- .qsf (QSound Format) - A self-contained file with one song. Includes full Z80 and sample ROM data. .miniqsf (Miniature QSound Format) - An abbreviated file containing only data specific to one song, usually just a command number. Relies on .qsflib files, residing in the same directory, for the remainder of the Z80 code and/or samples. .qsflib (QSound Format Library) - A file containing common Z80 and sample data for one or more .miniqsf files. Not guaranteed to be playable as a separate file. ----------------------------------------------------------------------------- Requirements ------------ * A Pentium or higher PC. I'd recommend at least a Pentium Pro 200. * A media player which supports either the Winamp 2 or 3 plugin API. Note: Winamp 5 will work too, since it uses the Winamp 2 API. Winamp can be downloaded freely from http://www.winamp.com ----------------------------------------------------------------------------- Setup ----- For Winamp 2 or 5: Copy in_qsf.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_qsf.dll to "cnv_qsf.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 Quixotic saves all its options into the plugin.ini file in the same directory as the DLL, under the section [HighlyQuixotic]. 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. 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 QSFs 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 QSF files and is independant of Winamp's main volume. Change this if you notice that all your QSFs 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, QSF files play at 44100 Hz. Enable this option if you'd rather have them play at the sample rate of your choice. 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 Quixotic 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 Quixotic 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 QSF 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. ----------------------------------------------------------------------------- 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 QSF file's creator ("QSF by"). 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 QSF 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 ---------------------------------- * QSound emulation is based on information from MAME and isn't very accurate (by my perfectionist standards). Specifically, there seems to be some sort of ADSR envelope action going on that isn't documented anywhere. I also think there's some extra signal processing that's supposed to happen to get the wide-stereo effect, but that's not emulated either. And without actual hardware to bang on, I'm kind of stuck. So there you go. * HQ uses 4-point Gaussian interpolation for now, since I think it sounds nice and smoothes out some of the 8-bit sample noise. In the future, this may be optional. * Speed. There's plenty of room left to optimize, but it's not even breaking 1% CPU time on my P4 2.4GHz anyway, so I didn't optimize it yet. Sorry. * 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 QSF to the beginning. This is an unfortunate tradeoff of the format. ----------------------------------------------------------------------------- Terms of Use ------------ Highly Quixotic 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 Quixotic or any media or software package containing it. Anyone using Highly Quixotic 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 Quixotic 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 & László Molnár http://upx.sourceforge.net/ ----------------------------------------------------------------------------- Thanks to --------- * Paul Leaman, Miguel Angel Horna, and anyone else involved in MAME's QSound implementation. * All the Capcom musicians who made QSound worthy of its own format. * P-P-P-ProtoCat. ----------------------------------------------------------------------------- Where to find me ---------------- web: http://www.neillcorlett.com/ -----------------------------------------------------------------------------