[ViewVC] Annotation of: cebix/SIDPlayer/README


  SIDPlayer
  A SID tune replayer

  Copyright (C) 1996-2003 Christian Bauer


License
-------

SIDPlayer is available under the terms of the GNU General Public License.
See the file "COPYING" that is included in the distribution for details.


What is SIDPlayer?
------------------

SIDPlayer is a replayer program for C64 music ("SID tunes"), like PlaySID on
the Amiga or SIDPLAY for Unix. You can think of it as being a stripped-down
C64 emulator that only emulates the CPU and the sound chip of the C64.
SIDPlayer can replay SID tunes in the "PSID" file format, but it cannot run
any C64 programs.


Why would I want to listen to C64 music?
----------------------------------------

The C64 had the most advanced sound capabilities of all home computers in
the early 80's. While other computers of that time were only able to produce
beeps, the C64 had a complete 3-voice analog synthesizer on its MOS 6581
sound chip (called "SID" - "Sound Interface Device"). Even some more modern
computers (as the Atari ST or the first Macs) had worse sound.

The SID chip features three oscillators with selectable waveform, ADSR
envelope generators, programmable resonance filters and special effects like
ring modulation. With the aid of the CPU, it can also replay 4-bit sampled
sounds. SIDPlayer emulates all features of the SID chip, including the
filters.

There were (and are still) many composers programming excellent music for
the C64 and thousands of tunes have been converted for use with SID tune
replayers on nearly every existing computer platform. One big advantage of
SID tunes is that they take very little hard disk space: most are only 4-8K
in size.


System Requirements
-------------------

SIDPlayer runs on all Unix systems supported by SDL (which includes Linux,
FreeBSD, Solaris and Irix) and on BeOS R4.5 or later versions.

Successfully tested systems include:
 - Linux/i386
 - BeOS/x86 R5
 - BeOS/ppc R4.5


Supported file formats
----------------------

The only SID tune file format supported by SIDPlayer is single-file PSID
files (these have the signature "PSID" in the first 4 bytes). Most SID music
available on the Internet is in this format.


Installing SIDPlayer
--------------------

See the file "INSTALL".


Using SIDPlayer under BeOS
--------------------------

SIDPlayer can be started from the Tracker or from the Shell. If you give the
name of a PSID file as an argument from the Shell or drag a PSID file onto
the SIDPlayer icon from the Tracker, that file is loaded and played.

The SIDPlayer window displays some information about the currently loaded
PSID file and has the usual tapedeck-like controls for pausing, restarting
and stopping the replay and for selecting the next or previous song
contained in the PSID file. The number of the song currently playing and the
total number of songs in the loaded PSID file are displayed to the right of
the tapedeck buttons. The slider in the bottom right of the window can be
used to adjust the replay speed.

The SIDPlayer menu has three items:

 - "About SIDPlayer" shows some information about SIDPlayer
 - "Sound Control" opens the sound control window (see below)
 - "Quit" quits SIDPlayer

To load another PSID file, drag it into the SIDPlayer window. To quit
SIDPlayer, close the window or select the "Quit" menu item.

Some functions of SIDPlayer can also be controlled with the keyboard:
  P          : Play/pause
  S          : Stop
  N          : Next song
  Esc/Space  : Stop
  Left arrow : Previous song
  Right arrow: Next song
  Q          : Quit


Using SIDPlayer under Unix
--------------------------

SIDPlayer currently only works as a command line application. It is invoked
as follows:

  sidplayer FILE [song_number]

"FILE" is the name of the PSID file to be loaded. The optional "song_number"
specifies the number of the song to be player (instead of the default song).
SIDPlayer cannot detect when a song has finished, so you have to use Ctrl-C
to quit it.

SIDPlayer accepts a number of command line arguments. Type "sidplayer --help"
to get a list.

If you have a Catweasel MK3 PCI card with a SID chip installed you can
redirect the output of SIDPlayer to the card by specifying the "--cwsid on"
command line argument. Visit www.jschoenfeld.de for more information about
the Catweasel card.


The Sound Control window (BeOS only)
------------------------------------

Sound post-processing is controlled with the "Effect" pop-up menu and the
"Delay" and "Feedback" sliders. The available effects are "None" (no post-
processing), "Reverb" (simple reverb) and "Spatial" (reverb with phase
shift, intended for headphone users).

The checkbox labeled "Filters" is used to turn the emulation of the SID
filters on or off.

The "New SID Chip" checkbox selects the type of SID chip to be emulated.
Currently this only affects some combined waveforms.

The eight slider gadgets in the right part of the window control the stereo
panning and volume of each of the four voices (3 synthesized voices, 1
sampled voice).


Where do I get PSID files
-------------------------

The two largest collections of SID tunes are the "High Voltage" SID
Collection (http://hvsc.c64.org) and the "NemeSIDs" archive
(ftp://frodo.hiof.no/pub/c64/sidmusic). These have been used for testing
during the development of SIDPlayer and they should all work.

Twenty demonstration SID tunes are included with SIDPlayer in the "PSID
Demo" directory.


Support
-------

Updates of SIDPlayer are available on the official SIDPlayer home page:

  http://www.uni-mainz.de/~bauec002/SPMain.html


History
-------

V1.0 - First release
V2.0 - SID filter emulation, better envelope generation
V2.1 - Implemented notch filter, 60Hz replay now works, added faster/
       slower buttons, compiled for BeOS DR8
V2.2 - Improved the 6510, triangle waveform is now 12 bits, output
       clipping, stereo output, corrected SID sustain behaviour,
       reading from a write-only SID register returns the last byte
       written to the SID, combined waveforms sampled from a 6581R4
V2.3 - Corrected BRK, DCP, ARR and LAS instructions, volume levels up
       to 200% possible, compiled for BeOS DR9
V2.4 - Shows name/author/copyright in ISO-Latin1
V2.5 - Converted panning/volume sliders to BSlider class
V3.0 - Unified PPC/x86 release
V4.0 - Now based on Frodo V5 CPU/SID code (more efficient CPU emulation,
       post-processing effects (reverb, spatial), prefs manager), replaced
       faster/slower buttons by slider, added popup menu and sound control
       window, ported to BeOS R5 with new Media Kit, implemented CIA timer
       speed control, and SIDPlayer can now also be used as a CL-Amp plugin
V4.1 - Runs as a command line application under Unix (requiring SDL),
       preferences items can be passed on the command line, and SIDPlayer
       can now also be used as a SoundPlay plugin
V4.2 - Fixed writes to mirrored SID registers, output to WAV file is possible
       in SDL version
V4.3 - Added support for Catweasel SID hardware in SDL version (use option
       "--cwsid on"), CIA timer speed control now actually works


Acknowledgements
----------------

Special thanks go to Claes L�fqvist and Marco Nelissen for their help with
adding CL-Amp and SoundPlay plugin support.


Christian Bauer
<Christian.Bauer@uni-mainz.de>
Revision:	1.17
Committed:	2003-04-11T20:23:01Z (21 years, 7 months ago) by cebix
Branch:	MAIN
Changes since 1.16:	+11 -4 lines
Log Message:	- added support for Catweasel SID - replay timing is now based on CIA timer value, removed replayfreq
#	User	Rev	Content
1	cebix	1.1
2	cebix	1.15	SIDPlayer
3	cebix	1.5	A SID tune replayer
4	cebix	1.1
5	cebix	1.17	Copyright (C) 1996-2003 Christian Bauer
6	cebix	1.1
7
8			License
9			-------
10
11			SIDPlayer is available under the terms of the GNU General Public License.
12	cebix	1.10	See the file "COPYING" that is included in the distribution for details.
13	cebix	1.1
14
15			What is SIDPlayer?
16			------------------
17
18	cebix	1.3	SIDPlayer is a replayer program for C64 music ("SID tunes"), like PlaySID on
19	cebix	1.4	the Amiga or SIDPLAY for Unix. You can think of it as being a stripped-down
20	cebix	1.3	C64 emulator that only emulates the CPU and the sound chip of the C64.
21			SIDPlayer can replay SID tunes in the "PSID" file format, but it cannot run
22			any C64 programs.
23	cebix	1.1
24
25			Why would I want to listen to C64 music?
26			----------------------------------------
27
28			The C64 had the most advanced sound capabilities of all home computers in
29			the early 80's. While other computers of that time were only able to produce
30			beeps, the C64 had a complete 3-voice analog synthesizer on its MOS 6581
31			sound chip (called "SID" - "Sound Interface Device"). Even some more modern
32			computers (as the Atari ST or the first Macs) had worse sound.
33
34			The SID chip features three oscillators with selectable waveform, ADSR
35	cebix	1.3	envelope generators, programmable resonance filters and special effects like
36			ring modulation. With the aid of the CPU, it can also replay 4-bit sampled
37			sounds. SIDPlayer emulates all features of the SID chip, including the
38			filters.
39	cebix	1.1
40			There were (and are still) many composers programming excellent music for
41			the C64 and thousands of tunes have been converted for use with SID tune
42			replayers on nearly every existing computer platform. One big advantage of
43			SID tunes is that they take very little hard disk space: most are only 4-8K
44			in size.
45
46
47	cebix	1.5	System Requirements
48			-------------------
49
50			SIDPlayer runs on all Unix systems supported by SDL (which includes Linux,
51			FreeBSD, Solaris and Irix) and on BeOS R4.5 or later versions.
52
53			Successfully tested systems include:
54			- Linux/i386
55			- BeOS/x86 R5
56			- BeOS/ppc R4.5
57
58
59	cebix	1.1	Supported file formats
60			----------------------
61
62			The only SID tune file format supported by SIDPlayer is single-file PSID
63			files (these have the signature "PSID" in the first 4 bytes). Most SID music
64			available on the Internet is in this format.
65
66
67	cebix	1.5	Installing SIDPlayer
68			--------------------
69
70			See the file "INSTALL".
71
72
73			Using SIDPlayer under BeOS
74			--------------------------
75	cebix	1.1
76	cebix	1.3	SIDPlayer can be started from the Tracker or from the Shell. If you give the
77			name of a PSID file as an argument from the Shell or drag a PSID file onto
78			the SIDPlayer icon from the Tracker, that file is loaded and played.
79
80			The SIDPlayer window displays some information about the currently loaded
81			PSID file and has the usual tapedeck-like controls for pausing, restarting
82			and stopping the replay and for selecting the next or previous song
83			contained in the PSID file. The number of the song currently playing and the
84			total number of songs in the loaded PSID file are displayed to the right of
85			the tapedeck buttons. The slider in the bottom right of the window can be
86			used to adjust the replay speed.
87	cebix	1.1
88	cebix	1.3	The SIDPlayer menu has three items:
89	cebix	1.1
90			- "About SIDPlayer" shows some information about SIDPlayer
91	cebix	1.5	- "Sound Control" opens the sound control window (see below)
92	cebix	1.1	- "Quit" quits SIDPlayer
93
94			To load another PSID file, drag it into the SIDPlayer window. To quit
95			SIDPlayer, close the window or select the "Quit" menu item.
96
97			Some functions of SIDPlayer can also be controlled with the keyboard:
98			P : Play/pause
99			S : Stop
100			N : Next song
101			Esc/Space : Stop
102			Left arrow : Previous song
103			Right arrow: Next song
104			Q : Quit
105
106	cebix	1.5
107			Using SIDPlayer under Unix
108			--------------------------
109
110	cebix	1.17	SIDPlayer currently only works as a command line application. It is invoked
111	cebix	1.5	as follows:
112
113			sidplayer FILE [song_number]
114
115			"FILE" is the name of the PSID file to be loaded. The optional "song_number"
116			specifies the number of the song to be player (instead of the default song).
117			SIDPlayer cannot detect when a song has finished, so you have to use Ctrl-C
118			to quit it.
119	cebix	1.1
120	cebix	1.17	SIDPlayer accepts a number of command line arguments. Type "sidplayer --help"
121	cebix	1.16	to get a list.
122
123	cebix	1.17	If you have a Catweasel MK3 PCI card with a SID chip installed you can
124			redirect the output of SIDPlayer to the card by specifying the "--cwsid on"
125			command line argument. Visit www.jschoenfeld.de for more information about
126			the Catweasel card.
127
128	cebix	1.1
129	cebix	1.5	The Sound Control window (BeOS only)
130			------------------------------------
131	cebix	1.1
132	cebix	1.3	Sound post-processing is controlled with the "Effect" pop-up menu and the
133			"Delay" and "Feedback" sliders. The available effects are "None" (no post-
134			processing), "Reverb" (simple reverb) and "Spatial" (reverb with phase
135			shift, intended for headphone users).
136
137	cebix	1.1	The checkbox labeled "Filters" is used to turn the emulation of the SID
138			filters on or off.
139
140	cebix	1.3	The "New SID Chip" checkbox selects the type of SID chip to be emulated.
141			Currently this only affects some combined waveforms.
142
143			The eight slider gadgets in the right part of the window control the stereo
144			panning and volume of each of the four voices (3 synthesized voices, 1
145			sampled voice).
146	cebix	1.1
147
148			Where do I get PSID files
149			-------------------------
150
151			The two largest collections of SID tunes are the "High Voltage" SID
152	cebix	1.3	Collection (http://hvsc.c64.org) and the "NemeSIDs" archive
153			(ftp://frodo.hiof.no/pub/c64/sidmusic). These have been used for testing
154			during the development of SIDPlayer and they should all work.
155
156			Twenty demonstration SID tunes are included with SIDPlayer in the "PSID
157			Demo" directory.
158
159
160			Support
161			-------
162
163			Updates of SIDPlayer are available on the official SIDPlayer home page:
164	cebix	1.1
165	cebix	1.3	http://www.uni-mainz.de/~bauec002/SPMain.html
166	cebix	1.1
167
168			History
169			-------
170
171			V1.0 - First release
172			V2.0 - SID filter emulation, better envelope generation
173			V2.1 - Implemented notch filter, 60Hz replay now works, added faster/
174			slower buttons, compiled for BeOS DR8
175			V2.2 - Improved the 6510, triangle waveform is now 12 bits, output
176			clipping, stereo output, corrected SID sustain behaviour,
177			reading from a write-only SID register returns the last byte
178			written to the SID, combined waveforms sampled from a 6581R4
179			V2.3 - Corrected BRK, DCP, ARR and LAS instructions, volume levels up
180			to 200% possible, compiled for BeOS DR9
181			V2.4 - Shows name/author/copyright in ISO-Latin1
182			V2.5 - Converted panning/volume sliders to BSlider class
183			V3.0 - Unified PPC/x86 release
184			V4.0 - Now based on Frodo V5 CPU/SID code (more efficient CPU emulation,
185			post-processing effects (reverb, spatial), prefs manager), replaced
186			faster/slower buttons by slider, added popup menu and sound control
187			window, ported to BeOS R5 with new Media Kit, implemented CIA timer
188			speed control, and SIDPlayer can now also be used as a CL-Amp plugin
189	cebix	1.17	V4.1 - Runs as a command line application under Unix (requiring SDL),
190	cebix	1.12	preferences items can be passed on the command line, and SIDPlayer
191			can now also be used as a SoundPlay plugin
192	cebix	1.16	V4.2 - Fixed writes to mirrored SID registers, output to WAV file is possible
193			in SDL version
194	cebix	1.17	V4.3 - Added support for Catweasel SID hardware in SDL version (use option
195			"--cwsid on"), CIA timer speed control now actually works
196	cebix	1.1
197
198	cebix	1.13	Acknowledgements
199			----------------
200
201			Special thanks go to Claes L�fqvist and Marco Nelissen for their help with
202			adding CL-Amp and SoundPlay plugin support.
203
204
205	cebix	1.1	Christian Bauer
206			<Christian.Bauer@uni-mainz.de>