XMMS-SID - SIDPlay input plugin for X MultiMedia System (XMMS)
==============================================================
Programmed and designed by Matti 'ccr' Hamalainen
  (C) Copyright 1999-2008 Tecnic Software productions (TNSP)

"Kummatti City", theme of XMMS-SID 0.8
  by Ari 'Agemixer' Yliaho
  (C) Copyright 1998 Scallop

NOTICE! "Kummatti City" song is freely distributable as part
of XMMS-SID, but it is not distributed under GNU General Public
License like the rest of XMMS-SID package is, but "copyrighted
freeware". Contact mr. Ari Yliaho if you wish to use this
song in any other way.

---------------------------------------------------------------------
                     This release is dedicated
                         to the memory of

                          Richard  Joseph
                       (RIP, March 4th 2007)

              He was one of the old C64 music legends,
                now gone, but forever in our hearts.
---------------------------------------------------------------------
                           Also dedicated
                          to the memory of

                       Lauri 'Enochian' Sipila
                      (3.5.1979   -  26.7.2007)

                 A friend, who will be sorely missed.
---------------------------------------------------------------------

Short introduction
==================
XMMS-SID is a plugin for XMMS (X MultiMedia System) which provides
support for playing "SID tunes", which are music from old Commodore
64/128 computer series software, including games, demos, etc.


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 it consumes very much
  CPU power!


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 file "INSTALL" for discussion about
  emulator libraries and their aspects.

- 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".


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 "Only when song-length is unknown" option makes
playtime limit effective only when song length information
is not found from song-length database.

- Use XSIDPLAY-compatible database: If enabled, you can specify
  song-length database file and it is used. If disabled, the
  database is not used.

- DB-file: Specify path and filename, usually Songlengths.txt,
  that contains lengths for most songs in High Voltage SID
  Collection (HVSC) in XSIDPLAY compatible format, for example:
  /media/Songlengths.txt

  Click the "Browse" button to get a file selector dialog.

I highly recommend that you download the database and configure
XMMS-SID to use it. The SLDB is included with latest versions of
HVSC.


Title-tab
---------
SID Tune Information List (STIL) database:

- Use STIL database: If enabled, the settings below take effect
  and XMMS-SID can utilize additional information from High
  Voltage SID Collection (HVSC) STIL-database. STIL contains
  general information about the tune, plus trivia, history and
  comments from the composers.

- STIL file: Path and filename of STIL database (STIL.txt).
  Usually the STIL database file is under DOCUMENTS/ sub-
  directory of HVSC, for example:
  /media/C64Music/DOCUMENTS/STIL.txt

- HVSC path: Path to your High Voltage SID Collection directory,
  for example: /media/C64Music

  Click the "Browse" button to get a file selector dialog.

Song name/title format:

- Override generic XMMS titles: Enable to override generic XMMS
  titlestring setting and use XMMS-SID specific titlestring
  format.


Misc-tab
--------
Sub-tune control:

- Disabled: No separate sub-tune control. The sub-tune selector
  in XMMS-SID's fileinfo dialog will still be enabled.

- Seek back/forward changes sub-song: This method is similar to
  the one used in "XMMS-SidPlay"

- Pop-up via seekbar (UADE-style): Similar to selector used in
  Unix Amiga Delitracker Emulator (UADE). Any interaction with
  XMMS's seeking capabilities pops up a sub-tune control window.
  Mouse and arrow keys can be used to select a tune. Escape key
  (ESC) or moving mouse out of the window closes it.

- Song-position patch: If you have a patched version of XMMS
  (patched with song-position patch, which comes with XMMS-SID),
  you can select this method. Then you can use XMMS's seekbar
  to select the sub-tune. (Back in XMMS-SID v0.7 this was the
  only option.)

Automatic sub-tune changes:

- Go through all sub-tunes in file: When enabled, all sub-tunes
  in files will be played. The default tune is played first, then
  others that have not been played.

- Only tunes with specified minimum length: Only sub-tunes with
  this given minimum length will be played by automatic sub-tune
  changer.

  NOTICE: You can always manually change to wished sub-tune.

Miscellaneous options:

- Detect file by contents: Determine if file is a SID-tune
  by checking the file contents. If disabled, only filename
  extension (.sid, .dat, ...) is checked.

  If XMMS-SID doesn't recognize your SID-tunes, try enabling
  this option. It is EXTREMELY slow if you have a 10000-tune
  playlist, though.


Miscellaneous tips
==================
* The emulator engine backends will adjust the preferred configuration
  settings if they do not support them as they are. To see the
  adjusted settings, play a tune after configuring and then go back
  to plugin configuration after that.

* SIDPlay2-emulation is heavier, but more accurate. So you need to
  have more CPU-power for it.

* Oversampling is available with SIDPlay2-emulation, it can further
  enchange the audio quality, but you need some really powerful
  hardware to run it smoothly.

* Filter-settings can be usually left as they are, unless you know
  what you're doing.

* For those who don't know it: Autopanning and stereo are not native
  to the original SID chip, but are extra options implemented in
  libSIDPlay. So if you think that the tune does not sound as it
  sounds on real C64, use the Mono setting.

* The "kb/s rate" box is actually the play rate in Hz, so you can
  see if it's an NTSC or PAL song (if you haven't set the Force Speed
  option).

Also see FAQ for more tips, gotchas and such.


License
=======
XMMS-SID is distributed under GNU General Public License version 2,
see COPYING for more information.

If you like XMMS-SID, you can thank me by distributing message
about it's existence and voting it on freshmeat.net.


Contact, support and new versions
=================================
New releases of this plugin should be available at TNSP's WWW-
homepages, see below for address. Bug-reports, suggestions,
patches, etc. should be sent to ccr at least for now, please see
the homepage for latest information.


IRC      : ccr @ freenode.net
           (see http://www.freenode.net/ for more information)

           or #audacious @ irc.atheme.org

E-mail   : ccr@tnsp.org

Homepage : http://www.tnsp.org/xmms-sid.php

