# HG changeset patch # User Matti Hamalainen # Date 1103655000 0 # Node ID e9ea4ce4c69737a92c50e4124816affdbd2e16ae # Parent 295c1b369d2f81876799d784126b23cf9934d183 Muchly improved documentation and installation instructions. diff -r 295c1b369d2f -r e9ea4ce4c697 INSTALL --- 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: diff -r 295c1b369d2f -r e9ea4ce4c697 README --- 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