		CRYSTAL SEMICONDUCTOR WAVE PLAYER/RECORDER

Plays or records Microsoft .WAV format audio data files in all standard audio
formats.  Files to be played must have valid headers.  Valid headers will be
created for all recorded files.  A capture only program mode is also
supported for previewing input sources.  Supported Crystal CODEC versions
include the CS4231, CS4231A, and CS4232.  This application runs in the
foreground and operation is terminated by any keystroke except the "hot keys"
used for volume control.

Active volume control is provided by certain keys on extended keyboards.  The
gray pageup, pagedown, home, end, insert, and delete may be used to control
input and output volumes.  The gray insert key is for input volume increase
and the gray delete is for input volume decrease.  The gray home is for
output volume increase and gray end for decrease.  The gray pageup key is for
master volume increase (input and output together) while the gray pagedown is
for master volume decrease.  Other keys will stop operation when pressed.

Command line arguments:
	/P=<filename>[,F] Play from disk w/optional full duplex mode
	/R=<filename>[,<sr>,<bps>,<s/m>,<f>] Record to disk
	/C[=<sr>,<bps>,<s/m>,<f>] Capture without writing to disk
	      sr=sample rate [5510 ... 48000] (Default 44100)
	      bps=bits per sample [4,8,16] (Default=16)
	      m=Mono or s=Stereo (Default=Stereo)
	      f=format [PCM,ALAW,MULAW,ADPCM] (Default=PCM)
	/K=<play filename>,<record filename>,<control port address> Karoke mode
	/A=<I/O address 0x534,etc> Address of CODEC (Default=0x534)
	/I=<IRQ line 5,7,9,11,etc> Interrupt Request Line (Default=5)
	/D=<DMA play>[,<DMA record>][,S] DMA channels and mode (Default=1,0)
	/S=<LINE,AUX,MIC,LOOP>[,<lvol>[,<rvol>]] (Default=LINE)
	/O=<left volume>[,<right volume>] (1-100) (Default=current setting)
	/B=<buffer size in kbytes 1-31> (Default based on average BPS)
	/M[=<display type 1-4>][,S] Monitor audio data, scroll (Default=none)
	/F[=<Number of EQ bars (8,16)>[,<FFT power (4..12)>]] (Default=9,16)
	/X[=<debug display 1-3>] (Default=none)
	/V    Verbose output (Default=no display)
	/L    Digital loopback enable (Default=disable)
	/PIO  Programmed I/O (Default=DMA)
	/TIO  Time interrupt programmed I/O (Default=DMA)

	The beginning slashes are optional.

Program modes:
	P	PLAY the specified file, if found.  If the file name extension
		is not specified, then "wav" will be used. If peak monitoring
		is selected, then the output data is peak scanned. If full
		duplex is specified, then the audio data is re-Captured for
		peak monitoring with CODEC clip detection. The DAC's are
		unmuted and their level set if output volume is specified. In
		the optional full duplex mode, LOOPBACK input is selected
		automatically. Separate DMA channels must be specified for
		full duplex operation.  The files audio data format is always
		displayed.  Playing is stopped by any keystroke.

	R	RECORD the specified file.  A file name must be specified,
		but all other parameters are optional.  If the file name
		extension is not specified, then "wav" will be used.  If the
		file name exists, then the user will be prompted before
		overwriting.  Audio data format will default to 44.1 kHz 16
		bit stereo PCM.  If peak monitoring is selected, then the
		input data is peak scanned.  Clipping detected by the CODEC
		is displayed.  The selected input is unmuted and the volume
		level set, if specified.  The recording audio data format and
		maximum recording time is always displayed.  Maximum
		recording time is calculated by dividing the available disk
		space minus 20 clusters by the average bytes per second of
		the recording format.  Recording is stopped by any keystroke
		or reaching maximum recording time.


	C	CAPTURE the selected input source and discard the audio data.
		All parameters are optional. If peak monitoring is selected,
		then the input data is peak scanned. Clipping detected by the
		CODEC is displayed.  The selected input is unmuted and the
		volume level set, if specified.  The capturing audio data
		format is always displayed.  Capturing is stopped by any
		keystroke.

	K    KAROKE mode allows the wave output to be mixed with the MIC input
		and recorded into a new file.  The new file must have a different
		name, but will record in the same format as the played wave file.
		The Control Port registers are required to implement this feature.
		This number may be found in the CS4232.INI file or by running the
		CS4232C.EXE program with the /V switch.

Program options:
	A	I/O port address of the Crystal CODEC.  If possible, the Crystal
		CODEC will be detected and automatically identified.  Supported
		boards include CDB4231, CRD4231, and CRD4232.  Also, Windows Sound
		System standard addresses are automatically searched.  When used
		with a CRD4231, the board must already be configured with the
		CSxxMOD1 utility, as minimum support is provided for the MAD16
		ASIC.  Default locations are 0x530, 0x604, 0xE80, or 0xF40.

	I	Interrupt request line for the Crystal CODEC.  If possible,
		this parameter will be determined automatically.  The BLASTER
		environment variable is used to determine IRQ setting for the
		CRD4232.  When used with a CRD4231, the board should first be
		configured with the CSxxMOD1 utility.  Default is 7.  Any IRQ
		on the first or second PIC may be used.

	D	DMA channel(s) and mode for the Crystal CODEC.  If possible,
		these parameters will be determined automatically.  The
		BLASTER environment variable is used to determine DMA play
		channel setting for the CRD4232.  When used with a CRD4231,
		the board should first be configured with the CSxxMOD1
		utility.  Defaults are play channel 1, capture channel 0, and
		demand mode.  Only the eight bit DMA channels 0, 1, and 3 are
		supported.  Single mode DMA may be specified for compatibility
		with certain bus controller chip sets.

	S	Select the input source and volume for ADC's capture or
		record.  The range is 1 to 100 and is scaled to each control.
		If volume is not specified, then the input is just unmuted.
		The volume setting controls the ADC's gain.  The default input
		source is AUX for the CODEC's AUX1.  The default input volume
		is to use the ADC's current settings unmuted.  The microphone
		gains are enabled when the source is MIC.  The input volume
		may be specified as a single number used for both left and
		right, or as separate left and right values.

	O	Output volume setting for the DAC's, in the range 1 to 100.
		The default is to use the DAC's current settings unmuted.
		The CS4232 master volumes are also set.  The output volume
		may be specified as a single number used for both left and
		right, or as separate left and right values.

	B	Buffer size in KBytes (1024) for DMA transfer buffers.  Two
		buffers are used for half duplex operation and four are used
		for full duplex.  The default for this is calculated by
		dividing the average bytes per second for the audio data by 20
		and rounding to the nearest 1024 (K) in the range 1K to 16K.

	M	Monitor the audio data by displaying a continuous bar of the
		peak values (VU meter).  Specifying just M is the same as M=1.
		In half duplex play mode the peaks are computed from the
		playing data buffers, without CODEC ADC clip detection.  The
		bar display is 80 characters wide and is split in half for
		stereo mode.  The display characters are '' for left or ''
		for right.  When the peak value is minimum, a special half
		character '' for left or '' for right is displayed in the
		least signal position.  When the peak value is maximum, a
		special full box character '' is displayed in the greatest
		signal position. When clipping is detected by the ADC's, the
		character in the greatest signal position is replaced by a ''
		or '' indicating the over range condition.  The characters
		are reversed when the middle out bar type is selected.  Left
		channel stereo data or mono data is displayed in blue.  Right
		channel stereo data is displayed in red.

		Four different bar displays are available for stereo data.
		One is a bar at the top of the screen that grows from screen
		edge to middle.  Two is a bar at the top of the screen that
		grows outward from the middle.  Three is a two bar display.
		One and two can be scrolled using the S option.  In record or
		capture mode, the time from the start is displayed.  In play
		mode the time remaining is displayed.

		Note:  If the peak bar is not displayed or the time updated
		then is means that interrupts from the CODEC are not
		occurring.

	F	Calculate an FFT and display the result as equalizer bars.
		The equalizer bar display must either be 8 or 16.  The FFT
		size is controlled by specifying the FFT power.  FFT size is
		always a power of two.  The available FFT powers (sizes) are
		4 to 12 (16 to 4096).  The defaults are a 16 bar display of a
		512 point FFT (2 to the 9th).  A debug option is avilable
		during FFT processing and that is enabled by pressing the
		gray slash above the numeric keypad.  This causes the program
		to dump the audio data used in the FFT calculation to a file
		name "FFTDATA".  A message is also displayed with the sample
		size, number of channels, and the left/right buffer increment
		flag.

	X	Debugging mode where the program dumps the CODEC registers
		just prior to starting the play or capture operation.  When
		X=1, the operation is the same.  If X=2, then the raw peak
		values are displayed.  A -2 will cause the CODEC's I11
		register and DMA status register to be displayed every 10
		milliseconds for diagnosing stuck DMA operations.  If X=-1,
		the program will display the CODEC registers and then exit
		without further operation.  Debugging code is changed as
		needed.

	V	The option will display most of the technical configuration
		data.

	L	This option enables the digital loopback register (I13).  If
		an input volume is specified, then I13 will also be set
		accordingly.

	PIO	This causes the program to operate in Programmed I/O mode
		where the audio data is transferred to or from the CODEC by
		polling the status register.  In this mode, sample rates above
		11kHz will cause skips in the wave form.  Peak monitors are
		not available in the mode.

	TIO	This is a combination of timer interrupt and programmed I/O
		modes.  Samples are transferred, using programmed I/O, to or
		from the CODEC during timer interrupts, while buffers are
		serviced in the foreground.  Performance is similiar to DMA
		mode.

Typical operations:
	Recording from the microphone to a file in CD quality stereo data
	format using the defaults:

		WAVE R=TEST S=MIC,40

	Checking the level of the default input source connected to AUX1:

		WAVE C M

	Playing a file with scrolling VU meter display in full duplex mode:

		WAVE P=filename,F M=2,S

	Play a file using programmed I/O mode with verbose display:

		WAVE /P=filename.wav /PIO /V

GENERAL NOTES:

File buffering - the input or output file is provided with a 16K byte buffer.

Audio data formats - valid audio data formats include PCM, ALAW, MULAW, and
	ADPCM.  PCM may be 8 or 16 bits.  ALAW and MULAW are always 8 bits.
	ADPCM is always 4 bits.  Any format or sample rate may be mono or
	stereo.  Mono is always sampled from the left channel on a stereo
	connector.

Sample rates - valid sample rates are 5512, 6615, 8000, 9600, 11025, 16000,
	18900, 22050, 27428, 32000, 33075, 37800, 44100, and 48000.  If any
	other rate is specified, then the nearest actual less than or equal
	to 48000 rate is used.

CDB4231 configuration - when capturing on the CDB4231 in half duplex mode,
	the jumpers on the DMA capture channel should be removed.  The DMA
	play channel will be used, but will not work if the capture channel
	is jumpered.

ADPCM peaks - the decoding for determining the peak values when playing or
	recording ADPCM format is very simplistic and therefore does not
	directly represent the signals amplitude level.  It is provided only
	for the purpose of determining signal presence.

FFT sampling - the samples used for FFT calculations come from the beginning
	of the data buffers, which are always greater than or equal in size.
	Alternate left and then right samples are processed on each call.

WAV Format Headers -
	4  bytes  'RIFF'
	4  bytes  <length>   ; total file length
	4  bytes  'WAVE'
	4  bytes  'fmt '
	4  bytes   <length>  ; 10h - length of 'data' header block
	2  bytes   xx        ; format tag
	           01  =  PCM
	           06  =  ALAW
	           07  =  MULAW
	           17  =  ADPCM
	2  bytes   01/02     ; channels (1=mono, 2=stereo)
	4  bytes   xxxx      ; samples per second
	4  bytes   xxxx      ; average bytes per second
	2  bytes   01/02/04  ; block alignment
	2  bytes   04/08/16  ; bits per sample
	4  bytes  'data'
	4  bytes  <length n>
	n  bytes  <sample data>

Program logic -
	WAVE Player
	- Check hardware configuration
	- Set defaults
	- Process command line
	- Validate operations
	- Save CODEC registers
	- Install keyboard and error handling ISR's
	- Allocate buffers
	- Install WAVE ISR
	- Pre-fill buffers w/wave data
	- Setup CODEC
	- Enable CODEC
	- Start DMA controller
	- Adjust mixers
	- Service buffers, while checking for keystrokes and errors
		- If playing, read wave data from disk
		- If recording, write wave data to disk
	- Wait until DMA buffers empty (played)
	- Reset CODEC
	- Reset DMA controller
	- Reset PIC
	- Restore CODEC registers
	- Free buffers
	- Un-install ISR's
	- Exit

	WAVE ISR
	- Save CODEC index
	- Reset IEN (CODEC Interrupt Enable)
	- Enable interrupts
	- While CODEC interrupt status true
		- If Playback interrupt
			- Mark buffer for service and switch buffers
			- Reset Playback interrupt
			- Clear PIC
		- If Capture interrupt
			- Mark buffer for service and switch buffers
			- Reset Capture interrupt
			- Clear PIC
	- Disable interrupts
	- Set IEN (CODEC Interrupt Enable)
	- Restore CODEC index
	- Chain to previous interrupt handler


