--- a/INSTALL	Tue Dec 21 18:49:02 2004 +0000
+++ b/INSTALL	Tue Dec 21 18:50:00 2004 +0000
@@ -1,6 +1,6 @@
 This document describes overall requirements and procedure
 for installation of XMMS-SID package, please read it carefully!
-For more tips, please also read README and FAQ.
+For more information and tips, please refer to README and FAQ.
 
 Requirements
 ============
@@ -12,19 +12,55 @@
   GNU toolchain. I have no idea whether this compiles with
   any other compiler ... sorry.
 
-- You need AT LEAST one emulation library:
+- You need AT LEAST one of the following emulation libraries:
 
    * libSIDPlay1
    * libSIDPlay2
 
-Only one is required, but all are supported. You may also need
-some supplementary libraries, that  are required by the emulator
-library. See below for more information.
+  Only one emulator backend library is required, but all are
+  supported with run-time configuration. You may also need
+  some supplementary libraries for each emulator library.
+  See below for more information.
 
 
-NOTICE!  Refer to file README for recommendations about which
-emulator libraries you should install!
+Emulator library selection recommendations
+==========================================
+Some words on which emulation library you should choose to install
+and use - it depends somewhat on your system and personal preferences.
+
+- libSIDPlay v1: This is the old SIDPlay v1 emulation library. Its
+  emulation is "frame-based" and not very accurate. The waveforms
+  produced are harsher and emulation of SID filter is far from
+  accurate.
+
+  libSIDPlay v1 requires very little CPU power, it is faster and
+  may have fewer bugs due to being more mature software. Many
+  OS distributions have pre-built packages of it, not something that
+  can be said of libSIDPlay v2. Some people may even like the
+  harsher sound produced by libSIDPlay v1.
 
+  Drawbacks are: worse emulation, eventually weakening compability
+  as new SID-tunes/files are ripped into "RSID"-format which
+  libSIDPlay v1 does NOT support.
+
+
+- libSIDPlay v2: New, next generation modular SID-emulation framework.
+  Along with reSID-library it produces probably most accurate emulated
+  representation of SID-chip available. This, however, comes at high
+  cost: libSIDPlay2 tends to eat CPU like popcorn, depending on the
+  selected emulation options. It is also less spread, not as many
+  distributions/operating systems come with pre-packaged libSIDPlay2,
+  so you may have to roll your own.
+
+  Also the API-stability of libSIDPlay2 is not yet 100%, there may
+  be changes. Bugs are evident, though many of them will be fixed
+  eventually.
+
+  
+Conclusion thus is as follows: If you are using an old system with not
+much spare CPU-power, choose libSIDPlay v1. On a relatively recent
+system (more powerful than Pentium III 500MHz) you may wish to choose
+libSIDPlay v2, although your mileage may vary.
 
 
 Where to get XMMS?
@@ -108,7 +144,7 @@
 
 Post-installation configuration
 ===============================
-To gain full advantages of using XMMS-SID, you need to configure it.
+To gain full advantage of using XMMS-SID, you need to configure it.
 XMMS-SID can be configured just like any other XMMS plugin, in XMMS
 do as follows:
 

--- a/README	Tue Dec 21 18:49:02 2004 +0000
+++ b/README	Tue Dec 21 18:50:00 2004 +0000
@@ -15,62 +15,85 @@
 from old Commodore computer software including games, demos, etc.
 
 
-
-Installation requirements and recommendations
-=============================================
-Refer to file "INSTALL" for information about what XMMS-SID requires,
-where to get those required packages and how to install.
-
-Some words on which emulation library you should choose to install
-and use - it depends somewhat on your system and personal preferences.
-
-
-- libSIDPlay v1: This is the old SIDPlay v1 emulation library. Its
-  emulation is "frame-based" and not very accurate. The waveforms
-  produced are harsher and emulation of SID filter is far from
-  accurate.
-
-  libSIDPlay v1 requires very little CPU power, it is faster and
-  may have fewer bugs due to being more mature software. Many
-  OS distributions have pre-built packages of it, not something that
-  can be said of libSIDPlay v2. Some people may even like the
-  harsher sound produced by libSIDPlay v1.
-
-  Drawbacks are: worse emulation, eventually weakening compability
-  as new SID-tunes/files are ripped into "RSID"-format which
-  libSIDPlay v1 does NOT support.
-
-
-- libSIDPlay v2: New, next generation modular SID-emulation framework.
-  Along with reSID-library it produces probably most accurate emulated
-  representation of SID-chip available. This, however, comes at high
-  cost: libSIDPlay2 tends to eat CPU like popcorn, depending on the
-  selected emulation options. It is also less spread, not as many
-  distributions/operating systems come with pre-packaged libSIDPlay2,
-  so you may have to roll your own.
-
-  Also the API-stability of libSIDPlay2 is not yet 100%, there may
-  be changes. Bugs are evident, though many of them will be fixed
-  eventually.
-
-  
-Conclusion thus is as follows: If you are using an old system with not
-much spare CPU-power, choose libSIDPlay v1. On a relatively recent
-system (more powerful than Pentium III 500MHz) you may wish to choose
-libSIDPlay v2, although your mileage may vary.
-
-
-
 Configuration
 =============
 
+Audio-tab
+---------
+- Resolution: 8 or 16-bit. Usually you should select 16-bit, unless
+  your audio hardware/drivers do not support it for some reason.
+  Speed benefit from using 8-bit audio is minimal, audio quality
+  is much worse than 16-bit.
 
+- Channels: Mono is the way to go. Original SID (single chip) output
+  is mono, the "stereo" and "autopanning" settings are just
+  artificial additions.
+
+- Samplerate: High samplerate means better quality sound. Usually
+  you'll set this to 44.1kHz (44100 Hz), but latest audio hardware
+  may support rates up to 48kHz (48000 Hz) and sometimes 96kHz.
+
+  Bigger samplerate means also more work for the emulator and
+  thus requires more CPU power.
+
+- Oversampling: Some emulator backends (currently only SIDPlay 2)
+  support technique called "oversampling", which further enhances
+  audio quality. Oversampling is done by computing audio data to
+  higher rate (factor * samplerate) and then downsampling with
+  rate-conversion filter.
+
+  This results in smoother waveforms, BUT consumes very much CPU!
+
+Emu#1-tab
+---------
+- Emulator library selection: Here you can choose a emulator
+  backend from those which for support has been compiled in
+  XMMS-SID. Refer to discussion about emulator libraries in file
+  "INSTALL" for more information.
+
+- Memory mode: libSIDPlay supports several different memory modes
+  for SID emulation, most of those are for compatibility, though.
+  For SIDPlay 2 emulation, select "Real C64" unless you know better.
+  For SIDPlay 1 emulation, select "Bank switching".
 
-Usage
-=====
-Using the plugin is quite simple: if you are familiar with XMMS and
-SIDPlay, then you already know how to use XMMS-SID. Configuration
-should be self-explanatory for most part, here are few tips:
+Emu#2-tab
+---------
+- Clock Speed: Sets default clockspeed and can also "force" the
+  emulator backend to use it. Usually the tune's clockspeed is
+  automatically detected, so do not set "Force speed" unless you
+  know what you're doing.
+
+- SID Type: Sets default SID-chip type. Most fileformats contain
+  information about the preferred SID-chip type to emulate, but
+  here you can select a default for those situations when it is
+  not known.
+
+- SIDPlay 2 options:
+  - Optimization mode: If enabled and SIDPlay 2 emulator library
+    has been selected, the emulator is run in "optimization" mode
+    which is partial frame-emulation. Results in faster, but
+    inaccurate emulation.
+
+  - reSID-emulation / HardSID: Select SIDPlay 2 backend. reSID
+    is a software SID-chip simulation and currently the only
+    option available. HardSID is backend for HardSID card,
+    but it is not supported yet by XMMS-SID.
+
+Filters-tab
+-----------
+- Emulate filters: Enable filter emulation. Usually you will want
+  to enable this option, unless you are running on very slow CPU.
+  SID filters affect outcome of most tunes very much.
+
+- Filter settings: Unless you are advanced user (and thus know what
+  these are), the defaults will work very well and there is no need
+  to touch filter settings.
+
+Songlength-tab
+--------------
+Most of song length settings should be self-explanatory. The
+respective "Only when song-length is unknown" options make
+maximum/minimum playtime limits work only when song length
 
 * XSIDPLAY-compatible song-length database is a file that contains
   lengths for most songs in High Voltage SID Collection (HVSC). I
@@ -78,6 +101,10 @@
   XMMS-SID to use it. The SLDB is available at
   http://www.geocities.com/SiliconValley/Lakes/5147/sidplay/sldb.html
 
+
+
+Miscellaneous tips
+==================
 * SIDPlay2-emulation is heavier, but more accurate. So you need to
   have more CPU-power for it.
 
@@ -90,7 +117,7 @@
 
 * If the plugin doesn't recognize your SID-tunes, try checking the
   'Determine filetype by contents' option in the XMMS-SID config
-  window. This is horrendously slow if you're reading a 10000-tune
+  window. This is EXTREMELY slow if you're reading a 10000-tune
   playlist, though.
 
 * For those who don't know it: Autopanning and stereo are not native
@@ -102,7 +129,7 @@
   see if it's an NTSC or PAL song (if you haven't set the Force Speed
   option).
 
-Also see FAQ for more tips, notes and such.
+Also see FAQ for more tips, gotchas and such.
 
 
 License