The SRS User Manual

The Shark Sound Recording Studio Program


SRS Requirements

The program requires:

	312K RAM
	200K Disk Space
	DOS 3.0+

The play/record features require:

	MediaVision Pro Audio Spectrum Sound 
	or
	any Sound Board supporting .wav files

The display feature requires:

	16 color Graphics System

The dual monitor feature requires:

	16 color Graphics System 
	and monochrome monitor


Qualifications

This program is not for sale and is free from gross defect.  
It is offerred as advertisement for itself and other Shark programs.

In particular, this DOS version of SRS is an advertisement for the 
MultiMedia Windows version of SRS.


SRS Installation

You can set up SRS in your system in three ways:

	keep srs.exe in the srs directory 

		this requires that you change to this directory to
		use the program

	keep srs.exe in the srs directory but put it in your PATH

		this allows you to run srs from any directory, but
		putting a whole directory in your PATH to refer to
		only one program is wasteful, or even impossible on
		systems with lengthy PATH's.

	put srs.exe in a PATH directory, 
	put "set srsopts=-P path" in autoexec.bat

		-P "path" option tells srs where to look for its files.
		this allows you to run srs from any directory but
		doesn't add to your PATH length or the DOS search time, 
		and allows srs to locate its files.  

The last method is suggested.  When you want to "run" a script, if
it is not found in the current directory, then srs looks for it in
its startup directory, or the directory specified with -P.  These
steps are followed by srs when using its "srsplay" and "srsrec" batch
files, too.


SRS Operation

The program starts by performing several initializations, each of the
later overriding any in the former, the first being the setting default 
values, then reading the user's current environment state, executing the 
script "config.srs" in the current directory, and finally parsing the 
command line.  If -noinit is specified, then the environment and the 
"config.srs" file are skipped, but the command line which is always 
processed.

Thereafter, it issues the command prompt, accepts and process a line of 
input, and reissues the prompt, until "exit" is entered or EOF is read.
This allows you to run srs in normal or redirected mode:

	> srs
	Yes? exit
	> srs < commands.srs > commands.out

The program will not overwrite or delete an existing file, unless 
the file was created during the current srs session, and only if the 
file is marked for writing.  The "record" action is different in this
respect, though, as it will overwrite "readonly" buffers;  it will not
overwrite existing files that are not in the buffer list.

	It is possible to have srs overwrite an existing file
	by referring to the file using the $N, $I, or $O 
	variables (see "Sound Buffer Names").

	Should a "holdover" file prevent an operation, use 
	the Shark "rm" program (or the DOS "erase" command") to 
	remove the offending file, and then repeat the action.

	A quick method of overcoming this obstacle is illustrated:

	> srs
	Yes? reverse sound.wav into x
		dointo() error: name not in buffers but exists!
	Yes? rm x; !!
	rm x; reverse carcass.wav into x
	Yes?

	In this example, the attempt to reverse the sound.wav buffer
	into the buffer x failed because the file x existed on the
	disk and was not in the buffer list.  So, the "rm" program
	(or the DOS "erase" program) was used to remove the file "x",
	and the "!!" command (which executes the last command) was
	used to repeat the action (see "History of Commands" below).


Command Lines

A command line consists of a set of phrases.  Specifically, phrases 
specifying a "source" buffer, a "target" buffer, and an "action".

The ";" character is considered a "newline" when no "whitespace" 
preceeds it.

	This is treated as three commands: load, play and stat:

		? load from destruct.wav; play; stat

	Allowing "whitespace" before the semicolon inhibits this
	substitution, allowing the ";" to be passed along to DOS,
	as it has meaning to other SHARK programs.

	The beginning of the line is considered to be non-whitespace.

The "#" character causes the rest of the line to be ignored as comment.

	This allows scripts to be commented:

	? type echo10cs.scr
	# echo1s.scr - adds 10cs echo of loaded file into "$N.echo"
	cut from $N at 00 csecs into $N.echo	# first sound into 
	add from $N at 10 csecs into $O		# first echo, .1 second in
	add from $N at 20 csecs into $O		# second echo, .2 seconds in
	add from $N at 30 csecs into $O		# second echo, .3 seconds in

	This implies that the "#" character can not be used in a 
	buffer name.


Command Phrasing

There are three phrases for most actions: from, into, and action.

The phrases can be specified in any order.  Input is processed up to 
the end of line after an action has been specified, at which time the 
action function is called.  

The "from" phrase is sufficient to create a buffer (the "input" buffer), 
from a file, and so, this phrase is enough to load the specific .wav 
file, "sound.wav":

	? sound.wav

	The file is now loaded and ready for use.

The "from" phrase will accept "wildcards", much like DOS but with 
additional pattern-matching styles:

	? *.wav

	This pattern matches any buffer or file with ".wav" in its name
	and srs will then load each one.

You can also specify a "buffer number" (reported by "stat", the number
in the far left column) for the "from" buffer.

	Be aware, though, that SRS searches for the actual name
	first, and if a buffer with the name of the number you 
	specify exists, it will be found first:

		? load *.wav
		? stat
		   0  sound.wav    ....		r  c:\tools\srs\sound.wav
		   1  screech.wav  ....		r  c:\tools\srs\screech.wav
		   2  imtired.wav  ....		r  c:\tools\srs\imtired.wav
		? play 1
		? load 1 into 2
		? stat
		   0  sound.wav    ....		r  c:\tools\srs\sound.wav
		   1  screech.wav  ....		r  c:\tools\srs\screech.wav
		   2  imtired.wav  ....		r  c:\tools\srs\imtired.wav
		   3  2            ....		r  c:\tools\srs\7

		Specifying a number that is not a valid entry in the
		buffer table causes the number to be treated like any
		other unrecognized word.

		The "into" phrase does not accept numbers as entries
		in the list of buffers, nor does it process wildcards
		(it does process $variables, though).  It treats its
		argument as the actual name you desire.  Thus "into 7"
		creates a buffer named "7".
		
	Important to remember is that SRS searches the disk for files 
	ONLY when it can not find an already-loaded buffer with the 
	pattern or number you specified.

	So, if you first load "sound.wav" from disk, and then try to
	load "*.wav", SRS will not load any additional files from disk
	because "*.wav" matched "sound.wav":

		? load sound.wav
		? stat
		   0  sound.wav    ....		r  c:\tools\srs\sound.wav
		? load *.wav
		? stat
		   0  sound.wav    ....		r  c:\tools\srs\sound.wav

	However, you can tell SRS to search the directory by prefixing
	the pattern with ".\";  that is, ".\*.wav" will tell SRS, in
	essence, to get the *.wav files from the current directory.  We
	say "in essence" because SRS does not treat this specially;  it
	simply does not find that pattern in its "known-buffer" list,
	and so searches the disk.

		Users familiar with DOS directory stuff will 
		recognize that the dot, ".", refers to the 
		"current" directory, and so dot-slash-pattern 
		refers to files in the current directory with 
		the specified pattern.

	So, to load one .wav file, then decide to load them all:

		? load sound.wav
		? stat
		   0  sound.wav    ....		r  c:\tools\srs\sound.wav
		? load .\*.wav
		? stat
		   0  sound.wav    ....		r  c:\tools\srs\sound.wav
		   1  screech.wav  ....		r  c:\tools\srs\screech.wav
		   2  imtired.wav  ....		r  c:\tools\srs\imtired.wav

	The pattern matching facility with the "from" phrase can be 
	used to reference a number of buffer-names to set up a list
	of names, and yet another "from" name, using this syntax:

		? stat
		   0  src          ....		r  c:\tools\srs\src
		   1  src.1        ....		r  c:\tools\srs\src.1
		   2  src.2        ....		r  c:\tools\srs\src.2
		   3  src.3        ....		r  c:\tools\srs\src.3
		? from src.* into sub.$I:e sub from src
		? stat
		   0  src          ....		r  c:\tools\srs\src
		   1  src.1        ....		r  c:\tools\srs\src.1
		   2  src.2        ....		r  c:\tools\srs\src.2
		   3  src.3        ....		r  c:\tools\srs\src.3
		   4  sub.1        ....		r  c:\tools\srs\sub.1
		   5  sub.2        ....		r  c:\tools\srs\sub.2
		   6  sub.3        ....		r  c:\tools\srs\sub.3
	
		This syntax used "from src.*" to build a series of
		repetitions (src.1, src.2, src.3) and "into sub.$I:e"
		to generate output names (sub.1, sub.2, sub.3), then
		the action "sub" followed by the buffer to use as the
		"subtraction" source (src), and expanded to this:

		from src.1 into sub.1 sub from destruct.wav
		from src.1 into sub.1 sub from destruct.wav
		from src.1 into sub.1 sub from destruct.wav

		The second "from" simply overwrote the first "from"
		since "from" does little except reference a buffer.

			As an aside, this feature was "discovered"
			by a shark when trying to accomplish a series
			of subtracts using a single "source" buffer;
			because the "into" phrase does not accept
			patterns, this odd syntax is required.

		So, you can do even more than that:

		? from src.* into add.$I:e add from sub.*

		You run out of files, though, with some of these
		actions, so append "save" to the command line to
		prevent the temporary files from being removed.

	This last example is rather confusing, but shows the 
	flexibility of the command interpreter and the power of the 
	pattern-matching facility.  It is with this in mind that we 
	state with confidence that there is no substitute for the 
	command-line, except for the simplest of actions, especially 
	when this feature was not known to the designers!

The "into" phrase allows you to rename the sound buffer as it is loaded,
usually to simplify typing:

		? load sound.wav into s
		? stat
		   0  s		   ....		r  c:\tools\srs\sound.wav

	From now on, the buffer "s" refers to the file "sound.wav".
	Using this, you can load the same file a number of times into
	different names:

		? load sound.wav into s1
		? load sound.wav into s2
		? load sound.wav into s3
		? stat
		   0  s1	   ....		r  c:\tools\srs\sound.wav
		   1  s2	   ....		r  c:\tools\srs\sound.wav
		   2  s3	   ....		r  c:\tools\srs\sound.wav

Alternatively, you do not need to specify the name, in which case SRS 
supplies a default name, either the filename or the name found in the 
file for "load", or "t###" for other operations:

		? load sound.wav 
		? stat
		   0  sound.wav    ....		r  c:\tools\srs\sound.wav
		? cut sound.wav
		? stat
		   0  sound.wav    ....		r  c:\tools\srs\sound.wav
		   1  t001         ....		r  c:\tools\srs\sound.wav

The arranging of default names allows you to specify a series of actions
without indicating the buffer names, and so the t### name suffices for
many operations:

		? load sound.wav		# $N= sound.wav
		? cut				# $I= sound.wav $O= t001
		? reverse			# $I= t001 $O= t002
		? play				# $I= t002 $O= t003
		? display			# $I= t003 $O= t004
		? load into output.wav		# $I= t004 $O= output.wav
		? del t0*			# remove intermediates

	There is a problem with this, though, and that is "what if you
	want to load a number of files (using a pattern) into different
	names?".  There is no simple way of doing this in one command,
	unless the desired output name can be somehow "made" from the 
	"input" anme, and the program does give you reference to current 
	"action, the last "load-name" and current "input-name" and 
	"output-name", as well as some internal variables:

		$N	= name of last buffer "loaded"
		$I	= name of current input buffer
		$O	= name of current output buffer
		$C	= current CHANNELS
		$T	= current THRESHOLD
		$R	= current SAMPLERATE
		$A	= current "action"

	You can modify these variables using any number of these strings 
	appended to the variable string:

		:e	= extension
		:r	= name without extension

		:l	= name to lower-case
		:u	= name to upper-case

		:0	= zero characters of name
		:1	= one character of name
		:2	= two characters of name
		...
		:9	= nine characters of name

	An example:

		? cut destruct.wav

		$I 		= destruct.wav

		$I:1		= d		# 1 char
		$I:2		= de		# 2 char
		$I:e		= wav		# extension
		$I:1.$I:e	= d.wav		# 1 char, "." and extension 
		$I:e:1		= w		# extension, 1 char of
		$I:e:2		= wa		# extension, 2 chars of
		$I:r		= destruct	# name, no extension
		$I:r.$A		= destruct.cut	# name, no ext, "." action

	This allows you to process multiple files in one fell swoop,
	yet still give them reasonable names:

		? set channels to 2
		? cut *.wav into $I:r.2	both	# convert *.wav into *.2
						# .2 files are now stereo
		? pan *.2 into $I:r.l2r		# .l2r are left-to-right pans
		? swap *.l2r into $I:r.r2l	# .r2l are right-to-left pans

		? stat
		   0  sound.wav    ....		r  c:\tools\srs\sound.wav
		   1  screech.wav  ....		r  c:\tools\srs\screech.wav
		   2  imtired.wav  ....		r  c:\tools\srs\imtired.wav
		   3  sound.2      ....		r  c:\tools\srs\sound.2  
		   4  screech.2    ....		r  c:\tools\srs\screech.2  
		   5  imtired.2    ....		r  c:\tools\srs\imtired.2  
		   6  sound.l2r    ....		r  c:\tools\srs\sound.l2r
		   7  screech.l2r  ....		r  c:\tools\srs\screech.l2r
		   8  imtired.l2r  ....		r  c:\tools\srs\imtired.l2r
		   9  sound.r2l    ....		r  c:\tools\srs\sound.r2l
		  10  screech.r2l  ....		r  c:\tools\srs\screech.r2l
		  11  imtired.r2l  ....		r  c:\tools\srs\imtired.r2l
		
	The "into" phrase does not process patterns or buffer numbers.
	The designers felt that it was too dangerous to use patterns 
	with "into", as a failure to match a name in the buffer table 
	might not fail to match a DOS file, which could be terrible:

		? stat
		   0  sound.wav    ....		r  c:\tools\srs\sound.wav
		   1  screech.wav  ....		r  c:\tools\srs\screech.wav
		   2  imtired.wav  ....		r  c:\tools\srs\imtired.wav
		? insert from sound.wav into c*.*

			OOPS!  No buffers named c*.*! If you happened 
			to be in the root directory and "command.com"
			was present, well, inserting sound.wav into 
			that file would have troublesome side-effects.

		So, no pattern matching processing is done with the
		"into" buffer, however, there is a way to specify
		a pattern of "into" names:

		? from s*.wav into $I from sound.wav action

		This translates into "into s*.wav from sound.wav action".

		NOTE: this bypasses the safety checks that SRS uses to
		prevent overwriting existing DOS files, and defeats the
		reason why pattern-matching is not done on the "into"
		phrase!  But, if you get to the point that you are 
		using this feature, then you probably don't need to be
		told to be careful using patterns and to work in 
		directories that hold sound files only!


Command Syntax

The syntax for the command line mode is:

	from  	"buffer" {at ###} {for ###} {left OR right}
	into 	"buffer" {at ###} {for ###} {left OR right}
	action	

	Because these can be entered in any order, all of the 
	following are valid:

		? load destruct.wav into x
		? into x load destruct.wav
		? from destruct.wav into x load
		? into x from destruct.wav load

	Commands need not be completely specified per line:

		? from destruct.wav
		? into x
		? load

		? into x
		? destruct.wav
		? load

	The key is:

		before the action requested can be executed properly,
		the "from" and "into" clauses must have been specified
		(if required).

Additional or different syntaxes exist for other commands:

	set 	"variable" {to ###} 
	amp	by ###
	ren	"buffer" to "newname"
	run	"script"

Known Words

Buffer Related Words

These words specify or qualify the relevant sound buffers:

	from	source buffer

		this name must be known either in the buffer table
		or in the current directory.

		? from destruct.wav
		? from *.wav

		This phrase can be used in a command line more than
		once:

		? from src.* into $I sub from src

		This syntax allows you to use the $I to reference
		src.*, but the second "from" allows the "sub" action
		to use a different source.

		In effect, the "from src.* into $I" is treated as
		though you used "into src.*", which is not 
		understood by the program.

		This allows you to use patterns for the "into" phrase
		since it does not do so itself.

	into	target buffer

		? into x.x.x.x.x

		this name need not be known and will be created if
		it doesn't.  If it does exist in the buffer table,
		it must not be marked "read-only";  if it does not
		exist in the buffer table, then it must not exist
		in the current directory, as srs will not overwrite
		existing files that it did not create in the current
		session.

		Both of these words will recognize the $N, $I and $O
		variables (see "Sound Buffer Names") to simplify and
		regulate the naming of buffers.

		? from $N into $N:r.1	# from last "loaded" buffer
					# into "name.1"
		? from $O into $I:r.2	# from last "output" buffer
					# into "name.2"

	at	start position in buffer

		this word is followed by either a number
		specifying the start position, or the word
		"mark" followed by a number specifying which
		mark to use from the mark list (marks are
		added during "play" (the 'm' key) and are
		displayed during "stat" under the buffer
		with which they are associated.

		> from x at 1000
		> from x at mark 0

		The syntax "action mark N" is a shorthand method
		for "action from mark.file at mark.offset";  that
		is, "mark" is a synonym for "from XXX at NNN",
		where XXX is the buffer specified by the particular
		mark and NNN is it's associated offset.

	for	length of buffer

		this word is followed by a number specifying
		the length of the buffer in question.

		> into x for 10000 

	upto	end of buffer

		this word indicates that the value specified is
		to be used as the address of the end of the buffer,
		and so the size, or "for" value, is then calculated 
		by subtracting from this the offset, or "at", value.

		This word can be used with "mark", similar to "for".

		After playing and marking a buffer, the command:

		"cut mark 0 upto mark 1" will grab the section so
		marked into a temporary buffer.  

	secs	multiply value by samplerate
	csecs	multiply value by samplerate/ 100
	left	left channel of stereo buffer
	right	right channel of stereo buffer

		> from x at 10 csecs		# 10 1/100 seconds
		> into y for 5 secs		# 5 seconds
		> into y left			# left channel of y

An example of fully qualifying the buffers:

	? from x at mark 0 for 10 secs into y left at 10000 for rest 


Action Words

The "help" actions simply lists the available actions:

	help	list available actions and other words



These actions operate on the internal sound buffers:

	play	play from buffer
	record	record into buffer

		? play from destruct.wav
		? play *.wav
		? record into memo337.wav

		during record, the program calculates
		a pause time based on the requested 
		buffer size, and watches for any 
		keypress, which terminates recording.

		during play, the program pauses for
		a time calculated by the size of the
		buffer and the samplerate and channels,
		and monitors the keyboard.  The following 
		keys cause certain actions to occur:

		Affect Play

			ESC	stop
			space	restart 
			p	pause/unpause
			l	loop back "threshold" eighth-seconds
			L	loop to start upon completion
		
		Affect Samplerate

			s	-1
			S	-10
			CTRL-S	-100
			f	+1
			F	+10
			CTRL-F	+100
			R	enter new samplerate

		Affect Channels

			c	+1
			C	-1

		Add Marks

			m	add mark to list

		Miscellaneous

			!	system("command")

		The sound programs offered by vendors of sound-boards
		will probably not support playing from a specified
		offset into or for a specified length of the sound
		file.  So, when attempting to play a "shadowed"
		buffer, or from a buffer in a "library", you must
		"play into" another buffer.  Alas and alack, 'tis true.

	load	load buffer into new buffer using input channels

		This command simply replaces existing buffer entries
		or creates new entries with the specified "from" name.

		The "load" command is so basic that it can occur by
		simply specifying the "from" name.  The following are
		are equivalent:

		? destruct.wav
		? from destruct.wav
		? load destruct.wav
		? load from destruct.wav
		? load from destruct.wav into destruct.wav

	cut	load buffer into new buffer using current channels

		Similar to the load command, "cut" is different in
		the following ways:

		it performs "channel adjusting"

			if the channel numbers differ, the output
			buffer is "multiplied" or "divided" as required

		it performs "buffer-size adjusting"

			if replacing an existing buffer, the size of 
			the buffer remains the same, unless the input
			size is smaller, in which case the smaller
			size results.  

	blend	using stereo buffers, load left channel into left channel 

		This command will load the left channel of one stereo
		buffer into the left channel of the stereo output buffer.

		This command will operate on non-stereo buffers, as
		it simply takes every other byte from the input buffer
		and copies it into every other byte of the output buffer.

	insert	insert buffer into buffer

		This command enlarges (or creates) the output buffer
		and places the insert buffer at the specified point:

		? from src.wav at 1 secs for 5 secs 
		? into dest.wav at 10 secs
		? insert

	shadow	point buffer to another buffer's file

		This action is interesting.  Using it, you can refer
		to an existing buffer (and its file) with completely
		different parameters: offset, size, channels, and 
		samplerate.  Actions using this buffer use those
		parameters, and not the parameters of the buffer
		being shadowed:

		? load destruct.wav		# 1 channel, 11025 rate
		? set channels to 2
		? set samplerate to 5512	
		? shadow destruct.wav into d.1	# 2 channels, 5512 rate

		Operations will then treat the file "destruct.wav" as
		though it had the parameters associated with "d.1"
		when using "d.1" as the input buffer.

		This action also allows you to set up different "views"
		into the shadowed buffer, as specified by the "at" and
		"for" phrases:

		? shadow from destruct.wav at 1 secs for 5 secs into d.2

		This is most useful for buffers being shadowed that are
		writable, allowing you to modify that buffer "underneath
		the nose of the buffer shadowing it":

		? load destruct.wav into src
		? load src			# set up $N= src
		? run shadow.001		# script to set up shadows:
			shadow from $N at 0 into $N.0
			shadow from $N at 1 into $N.1
			...			
		? from src.* into p.$I:e cut 	# cut src.1 into ph.1 ...
		? from p.* into $I sub from src # from each p.* into each one,
						# sub "src".  
						# guitar "phase" effect
						# in effect, subtract the src
						# buffer into the ph.? buffer
						# where ph.? is a different
						# offset into the src buffer
		? play p.*
		? save from p.7 into destruct.p7# save the one you like
		? del p.*

		? load kaboom.wav into src	# src.* now refer to "kaboom"
		? from src.* into p.$I:e cut	# cut kaboom at offsets
		? from p.* into $I sub from src	# same as above
		? play p.*			


		? load *.wav
		? blend s into t
		? insert a into b ; insert a into b 
		? shadow from main.wav at 5 secs for 5 secs into t2

		? load d.wav 		# channels = 1, samplerate = 11025
		? set channels to 4	# channels * 4
		? set samplerate to 44100	# samplerate * 4
		? cut d.wav into d.4	# quadruple samples
		? avg d.4 into avg.d.4	# smooth out curves
		

	stat	display buffer and file status

		this will display all buffers, unless there is a 
		current input buffer:

		? stat			# status of all buffers
		? stat buffer		# status of "buffer"
		? stat *.0		# status of buffers matching pattern

		The output pauses after a screenful, and stops if no
		key is pressed (or ESC is pressed) after 2 seconds.

	save	mark buffer to not modify or delete file

		Saves the current input buffer, to the current output
		buffer if specified.  This command follows the same rules
		regarding overwriting exising files not created during
		the current SRS session, or those created and already
		saved.

		? save sound.0 into sound.wav
		? save src.*
		? from src.* into destruct.$I:e save

	del	remove buffer, and file if not read-only

		this command will accept wildcards:

		? del *			# same as "clear"
		? del *.1.*		# remove buffers with ".1." in name

	clear	delete all buffers and non-read-only files

		? stat .\*.wav
		? save from stereo into newwave.wav
		? delete des*.wav
		? clear

		You can perform an action and save the result like so:

		? cut x into y save

		This is useful when processing multiple buffers by
		using the pattern matching facilities and the internal
		"naming" variables:

		? cut *.wav into $I:r.2 save

			This syntax will, for each *.wav:

			cut file1.wav into file1.2
			save file1.2

	add	add one buffer to existing buffer
	sub	subtract buffer from existing buffer

		These function add each of the samples together
		of the from and into buffers and store the result
		into the into buffer.  The data is interpreted as 
		being valued according to the PCM logic:

			silence  : 0x80
			positive : 0x81 to 0xFF
			negative : 0x7F to 0x00

		? load destruct.wav into d+c
		? add carcass.wav into d+c
		? sub carcass.wav into d+c-c

		? fc /b carcass.wav d+c-c
		fc: no differences encountered

			at this point, d+c-c should contain the
			same sound data as destruct.wav, but
			note that if these arithmetic operations 
			overflow the 8-bit data size the value is
			set to the maximum (0 or -1), and so d+c-c
			will not equal destruct.wav if the original
			addition exceeded the allowable range.

	fadeup	linear fade sound up   
	fadedn	linear fade sound down 
	amp	increase volume by factor
	damp	decrease volume by factor

		? fadeup src.l into src.l.u
		? fadedn src.l into src.l.d
		? amp src.l.u into src.l.u.5 by 50
		? damp src.l.d into src.l.d.5 by 50

	display	graphic of sound buffer, "threshold" (max 8) rows

		The output will pause for 1 second upon completion 
		of one screen of display if a key was pressed 
		during the draw, unless the key was ESC, in which 
		case the display routine exits.

		When the display routine exits, the program 
		pauses for 1 second, unless ESC was pressed.

	avg	average hi/lo buffer values over "threshold" units
	chop	make buffer silent below "threshold"
	pan	linear pan left to right stereo channels
	swap	swap left and right stereo channels
	reverse	reverse sound buffer

		? display 
		? avg from m into m.avg
		? chop from m into m.chop
		? pan from s into s.pan
		? swap from s into s.swap
		? reverse from m into m.reverse


	dadd	decimal add 
	dsub	decimal subtract 

		these actions treat each buffer	as a binary number.  
		Normal actions convert the data byte to an internal 
		format for processing.

		Instead, the data from each buffer is simply added 
		(or subtracted) and generated-carry's are propogated 
		down the line.

		The functions are reciprocal:

		? load into org

		? load into added
		? dadd org into added

		? load into subed
		? dsub org into subed

		? fc /b org subed
		fc: no differences encountered

		The operation is performed in reverse-buffer order
		so as to treat each buffer as a single number.  If 
		a carry occurs in the first byte of data (from the
		operations performed from the last byte forward),
		this information is lost!.

		It was decided to include these functions since 
		the results are virtually impossible to obtain using 
		any other program, although the practicality of 
		adding binary numbers that are thousands, even 
		millions of digits long, seems to escape us.

			However, the fact that no practical
			purpose has yet been determined does
			not translate into a reason to not 
			include such a feature.  As sharks,
			we'll eat rubber tires if the fancy
			strikes us.

The "set" command modifies internal variables:

	Variable Name	Short	Meaning

	samplerate	sa	set samplerate 
	channels	ch	set number of channels
	filter		fi	set PAS filter
	threshold	th	set value used by certain actions
	filemode	fm	set read/write on buffer
	debug			debugging messages
	bequiet			no prompting or status messages
	usemono			use monochrome monitor after display
	dohistory		save command lines in history.srs
	interactive		menu system
	prompt			SRS command prompt

	The syntax for this command is similar to the DOS "set"
	command:

		set variable=value

	It has an additional syntax that ignores whitespace:

		set variable to value

	? set

		This will display the values of all variables

	? set debug

		This will set if debug is not set, unset otherwise

	? set debug to 0
	? set debug to 1

		This will unset (0), or set (1), the variable

	? stat
	   0  destruct.wav	..... 		r c:\tools\srs\destruct.wav

	An additional syntax is available to the set command, wherein
	the specified variable is applied to a buffer (and not the system):

	? from destruct.wav set filemode to w 
	? stat
	   0  destruct.wav	..... 		w c:\tools\srs\destruct.wav
	? into destruct.wav set fm
	? stat
	   0  destruct.wav	..... 		r c:\tools\srs\destruct.wav


	The prompt can include the DOS prompt metacharacters and 
	SRS internal variables using the '$' strings:

		$#	current command number
		$q	double-quote character
		$$	dollar-sign character
		$l	greater-than character
		$l	less-than character
		$b	pipe character
		$t	time string
		$d	date string
		$p	current directory
		$n	current drive letter
		$v	SRS copyright
		$I	last input name
		$O	last output name
		$N	last "load" name
		$_	newline
		$e	escape character
		$h	backspace character

	This implentation includes the ability to set and access 
	"user" variables, however, it is not fully functional.

	When setting an unknown variable, the variable and the value
	are stored in the variable list, which can be accessed in 
	the command line or scripts using the following format:

		? set if=source.wav		# ${if} and ${of} are
		? set of=target.wav		# referred to in the
		? run process.scr 		# script

	There is 1024 bytes of user variable space, and when this
	overwraps, previous values will be overwritten.  This feature
	was added late and is unfortunately incomplete.

The "ren" command will change the name associated with a buffer, but
not the DOS filename:

	ren "buffer" to "newname"

	? load destruct.wav
	? stat
	   0  destruct.wav	..... 		r c:\tools\srs\destruct.wav

	? ren destruct.wav to d
	? stat
	   0  d 		..... 		r c:\tools\srs\destruct.wav

	? L destruct.wav
	? S
	   0  d 		..... 		r c:\tools\srs\destruct.wav
	   1  destruct.wav	..... 		r c:\tools\srs\destruct.wav

	? ren to e
	? S
	   0  d 		..... 		r c:\tools\srs\destruct.wav
	   1  e 		..... 		r c:\tools\srs\destruct.wav

These words affect internal variables for specific actions:

	by	"value"
	to	"word" or "value"

		? amp by 100 
		? rename to t0
		? set debug to 0

The "history" action lists the history of commands

	history	list commands entered during session

		This command can be referred to by a single "!"

		? history
		? !

		The output is a list of the most recently used 
		commands.  This list is available to the user to
		retrieve, modify, and execute (see "History of 
		Commands" below).

The "exit" command causes the program to shutdown.  The program removes
all temporary files that were not "saved".


The "mixer" allows access to the onboard mixer on the PAS.  (Not available 
in the advertisement version).  Note that because SRS passes unknown 
commands to DOS, you have access to the "pas" program and its commands:

	> srs
	Yes? pas set volume to 75
	
The "run" command executes a file containing commands.  This allows you
to build new commands using the existing set of commands to provide
additional functionality not previously envisioned by the designers or
not included due to time or space considerations.

		? run panr2l		# read commands from panl2r

	To read a script prior to exection:

		? type panr2l
		pan 			# pan does left to right
		swap			# this makes right to left
		del			# delete output from pan

	Run a script from the command line

		> srs L destruct.wav; run panl2r; save into destruct.l2r

	Scripts can refer to the variable $N which stores the name of
	the last buffer "loaded":

		? type panr2l.2
		pan			# pan does left to right
		swap into $N:r.l2r	# swap into "load-file-name"".l2r"
		del			# delete output from pan
		? load destruct.wav	# $N= destruct.wav
		? run panr2l.2		# the script generates a file
		? stat destruct.r2l	# $N.r2l= destruct.r2l

	Scripts can be used for building a "master" from a series of
	"cuts", although you will probably need paper and pencil to
	make notes on buffer offsets and lengths, unless you are using
	Windows or something like Sidekick.

	The best purpose for scripts is to provide actions that are
	not included internal to SRS.  We hope that the basics are
	covered, although the point has been made that "pan" could
	accept an argument as to the direction;  however, it is hoped
	that shortcomings in this area can be made up for using the
	script feature.
	

Sound Buffer Names

Buffers are named using up to 15 characters.  Case is not significant.  
This name is used as the sound file name, unless this name is invalid, 
in which case the name F#### is used, #### being a number that is 
consecutively incremented if the directory entry exists.

Buffers can be referred to using variables so as to automate the
processing of large numbers of files:

	$N	= last name used during "load"
	$I	= current or last input name
	$O	= current or last output name
	$C	= current CHANNELS value
	$R	= current SAMPLERATE value
	$T	= current THRESHOLD value

	These variables can be modified using the "fe" syntax:

		:r	- remove extension
		:e	- retrieve extension
		:d	- retrieve drive letter

		:l	- string to lowercase
		:u	- string to uppercase

		(see "fe" under "Support Progams" in "srs.doc" 
		for a complete list of modifiers, however, 
		these other modifiers have no effect since 
		buffers do not include path elements)

	These variables can be embedded in strings.  The text
	is copied, the variable substituted and modified, and
	remaining text copied:


		Examples

		$I 		= destruct.wav

		$I:r		= destruct
		$I:r.2		= destruct.2
		X_$I:r		= X_destruct
		new$I:e		= new.wav

	? load destruct.wav into $I:r	# output buffer name= destruct

	? load mono.slb			# load library of mono sounds
	? set channels to 2		# prepare to make stereo library

	? cut * into $I:r.2 both save	# cut (both channels) and save

	? cat -b *.2 > stereo.slb	# put all sounds into library
	? clear				# clear the buffer list
	? load stereo.slb		# load new library of stereo sounds
	
	When a buffer is requested, this substitution is performed,
	which occurs late in the execution procedure.

		Because of this, it is possible to overwrite 
		existing files (normally, srs will overwrite 
		only files it created during the current session 
		and only those not yet saved).

		? stat
		   0  destruct.wav    30720	r  c:\tools\srs\destruct.wav
		   1  destruct.1      10000	w  c:\tools\srs\destruct.1
		? cut destruct.1 into destruct.wav 	# fails
		? cut destruct.1 into $I:r.wav		# succeeds
		? stat
		   0  destruct.wav    10000	r  c:\tools\srs\destruct.wav
		   1  destruct.1      10000	w  c:\tools\srs\destruct.1


History of Commands

	The history list can be manipulated on the command line
	in a manner that will be familiar to C-shell users.

	History is accessed in the command line with the "!"
	character.  

		As an input line is read, characters are
		copied to the command line until a "!" is found.

		The following character patterns refer to:

			!!	the last command
			!n	the command number "n"
			!-n	the "n"th to last command (!-1 == !!)
			!frag	the command starting with "frag"
			!$	the last argument from the last command
			!#	the current command line up to before !#
			!:	nothing 

		History references can be followed by qualifiers 
		that specify a word or words:

			:n	refer to word number n 
			:$	refer to the last word
			:*	refer to words from 1 to last

			:n-m	refer to words from n to m
			:n-*	refer to words from n to one before last
			:n-$	refer to words from n to last (!!:0-$ == !!)

		Appending a history reference with ":p" causes the
		display of the translated command and causes execution 
		of the command to be skipped:

			:p	only print the new command line

		Appending a history reference with any of the following
		specifies a certain modification to the retrieved command:

			:r	remove last ".ext" 
			:h	remove last "file.ext" 
			:t	leave last "file.ext" 
			:d	leave "drive:" at beginning
			:l	translate to lower case
			:u	translate to upper case
			:s/x/y/	substitute y for first x
			:g/x/y/	substitute y for all x


		? !!	# the last command
		? !7	# the 7th command
		? !-3	# the 3rd to last command
		? !add	# the last command that started with the word "add"

	An example of the way that this simplifies command line 
	interaction:

		? add from source.wav into target.wav at 00
		? !!:0-* 10
		? !!:s/10/20
		? !!:s/2/3/
		
Examples:

? load destruct.wav into !@$.%^&*
? stat
BUF Buf Name	Offset Length  Ch  Rate   Mode	File Name	
  0 destruct.wav     0  30720  1   11025  r	c:\tools\srs\destruct.wav	
  1 !@$.%^&*	     0  30720  1   11025  w	c:\tools\srs\F002		

Sound Buffers can also be referred to using a set of special characters:

	load *.wav
	del d*.wav
	stat *.?.?.*
	play *.1 

The program searches its internal buffer list first when attempting 
to locate a sound, before searching the current directory.  If you
wish to use the pattern-matching facility, be aware of this.  An
example will illustrate:

load *.wav
stat
	
  0 destruc0.wav     0  30720  1   11025  r c:\tools\srs\destruc0.wav
  1 destruct.wav     0  30720  1   11025  r c:\tools\srs\destruct.wav

cd wav
load *.wav
stat

  0 destruc0.wav     0  30720  1   11025  r c:\tools\srs\destruc0.wav
  1 destruct.wav     0  30720  1   11025  r c:\tools\srs\destruct.wav

--- the "load *.wav" failed to load additional files because the ---
--- pattern *.wav matched entries in the internal buffer list ------

load .\*.wav
stat
  0 destruc0.wav     0  30720  1   11025  r c:\tools\srs\destruc0.wav
  1 destruct.wav     0  30720  1   11025  r c:\tools\srs\destruct.wav
  2 fakinit.wav      0 459264  1   11025  r c:\tools\srs\wav\fakinit.wav
  3 satbo.wav        0 311808  1   11025  r c:\tools\srs\wav\satbo.wav

--- the "load .\*.wav" loaded additional files because of the ".\" ---
--- prefix (current directory) which indicates to search the disk ---- 

--- The following set of four examples show different methods of ---
--- achieving the same result  ---

	load destruct.wav into x
	play 
	reverse x into y
	play
	reverse y into z
	fc /b x z
	fc: no differences encountered

	L destruct.wav into x
	P
	V into y
	P
	V into z
	fc /b x z
	fc: no differences encountered

	L destruct.wav
	P
	V
	P
	V
	fc /b $N $O
	fc: no differences encountered


> srs -qN "L destruct.wav; P; V; P; V; fc /b $N $O"
fc: no differences encountered

--- 
There is a limit to the number of files that can be referenced 
internal to the program, and srs will remove the "oldest" file if 
it runs out of table space.  Because of this, batch processing 
could fail to produce the desired result.  

	Assuming there are more .wav files than there are 
	file-table entries:

		srs -c2 "cut *.wav into $I:r.2; save *.2"

	the command above will not save all of the "cut" files
	because we specified to srs to first perform the "cut" 
	action on all .wav files and then save all the generated
	.2 files, which means that those files first "cut" will be
	removed as the program continues processing the remaining
	files, after the number of files processed exceeds the
	number of file table entries.

	Fortunately, you can "save" directly after an action.
	Compare the command below to that above:

		srs -c2 "cut *.wav into $I:r.$C save"

	This syntax will cause the "cut" to be performed followed
	immediately by "save", for each of the .wav files.
	

srs D *.wav
srs play *.wav
srs P *.wav

===================================================================
Disclaimer

This program and the accompanying SHARK utilites are provided as
"advertisement" for these and other programs available from SHARK.
No permission is granted for modifications to any of the programs
or their documentation, except for the srs.txt file which is to
have any and all comments desired added to its contents.  

Distribution of this package of files is encouraged.  SHARK hopes 
to bring "superuser" status to all those exposed to these programs.

These programs represent the latest "hot-off-the-press" versions,
and can not be guaranteed to be completely free of defects;  as
such, you should be reminded that they serve as advertisement for
themselves and other programs available from SHARK.  In no way can
SHARK or its employees be held liable for any use or misuse of
these programs.

===================================================================
Other SHARK Programs

This is a list of other programs available.

	Program	Function

	SRS	sound file processing, and more

	dump	dump contents of file using templates
	fe	foreach processing of list using substitution

	grep	better "find", more than Unix grep
	sort	better "sort", multiple keys, types
	sed	edit stream

	cat	text/binary file concatenation
	math	input stream arithmetic processing

	ls	better "dir", attributes, sorted
	mv	better "ren", renames or moves directories and files
	rm	better "del", directories, hidden/system files
	more	better "more", multiple files, search, instant editor
	strings	display text in binary files

	form	Informix-like forms with text data-files

	fractal	guess (right!)
	sine	generate sine-wave binary files

	IP	graphic image processor

	MISC	miscellaneous utilities (s2m, head, tail, pipe, 
		cmp, dt, wc, vga, lotus)


It should be noted that these programs are in daily use by sharks and 
are guaranteed to work as specified or immediate corrections are made.

All programs are available as "advertisement" (read: free).  This 
should not discourage you from purchasing them, as each of these gets 
better as someone requests additional functionality.
	
SHARK Addresses

	Mail

		SHARK
		922 San Leandro Suite C
		Mountain View, CA 94043

	Telephone

		(415) 969-3015

	Fax

		(415) 969-6600

	Internet

		shark@parallax.com


	


Preface

We at SHARK would like to thank all those persons responsible for 
allowing us access to their computers over the past decade, and for 
posing to us problems to solve using them.  We hope to return the 
favor by writing programs that allow all users the ability to process 
information in ways previously impossible for them.  An example is 
this program, which, although written for use with sound files, was 
designed to use any kind of file, or sound file formats from any 
sound-board vendor, and in conjunction with other SHARK programs 
like dump and math, and in ways not-necessarily related to sound.

Although many users will find the command-line interface unacceptable
except for the simplest actions, we at SHARK believe there is no
substitute (we have been typing at terminals and consoles for years), 
and until computers can communicate via the spoken word, the only 
user-interface that is acceptable is either the command-line, or a 
menu system that generates the command-line and allows you to accept 
or modify its output.  In the meantime, the flexible method of 
specifying i/o, the automatic default buffer-naming, the shorthand 
action words, the scripting capability, the history mechanism, and
the command-line execution feature should eliminate much of the 
repetitive typing as well as provide functionality otherwise 
unattainable with the current spate of GUI stuff.

We hope that this program in its current stage of development proves 
satisfactory enough to continue using it.  However, we are lazy, and 
this version requires TOO MUCH typing!  Thus, we hope you register 
your copy of SRS so we can notify you when the menued version is ready.  
We would hate for SRS to leave a bad taste in your mouth simply because 
you must type in order to use it.  And we know that the display 
function is substandard; work on this was postponed until the ability 
to interact with the display is incorporated (this was not a majority 
decision;  some sharks felt that to be a severe shortcoming, but the 
others convinced them to wait until the UI was defined).

We would like to hear from all of you, especially those that have
found a real use for this program.  Because we are an independent
group of computer users, programmers and analysts, we can also offer
immediate response time for any additional features you might desire.
The program was designed to be easily enhanced, with new processing
modules simply included in the lists of words and functions.  This 
version has a minimal set of operations, but if you want or write a 
routine you would like incorporated into the program, we can do so.
In fact, using the SHARK system, we can develop a special version 
just for YOU!

Of course, the source code to SRS and all other SHARK utilities is
available to interested parties.

Regardless, have fun with the program.  

Introduction to SRS 

Who Could Use This Program

There are many "types" of users, and this program was designed to
work for a number of you.


Business Users 

As an example, you can now have a Multi-Media display station on
any computer that has both a graphics- and a sound-board.  It is
because this program was written to interface with the Operating 
System that you can easily combine graphics (from your favorite 
program) with sound (from srs, or any other sound-program).  With
commands as easy as:

	show slide1
	play slide1.sound
	pauseforkey 5 secs

	You can build presentations that will Knock Their Socks Off.

	You can build interactive training programs:

	:prob1			# Problem 1 Script
	play prob1.sound	# Play sound 
	show prob1.slide	# Display sound during Play
	getkey abcd		# get a key, a, b, c, d, or escape
	ifesc exit		# escape pressed, quit
	goto prob1$KEY		# go to label ":prob1$KEY", $KEY= key pressed

	:prob1a			# pressed a
	show prob1.nota.slide	# wrong answer!
	play prob1.nota.sound
	getkey			# wait for any key
	goto prob1		# do it again

	...

	:prob1c			# pressed c
	show prob1.isc.slide	# correct!
	play prob1.isc.sound
	getkey			# wait for any key
	goto prob2		# next Problem

	...

	In essence, you do not need to buy "Presentation Programs" for 
	100's (or 1000's) of $'s when you can use the "paint" program 
	you like best and the SHARK utilities, and do it your way (the 
	"advertisement" version of the program does not include the 
	full set of SHARK utilities nor interactive scripting).


Technical Users

For programmers and scientists, this program provides binary data
processing facilities, and when used in conjuction with the SHARK 
utilities, allows you to process data from virtually any other program
you use in ways previously unanticipated or impossible.

	It can translate ascii input into sound data elements allowing 
	srs to read the output from any other number-crunching program 
	such as gnuplot or spreadsheets.  As the program allows you to 
	add, subtract, and xor two buffers, considerable effort was 
	expended to provide precise operation, illustrated below by 
	performing operations that should have no net-effect and 
	verifying this using the fc program:

	set noname			# no "name" chunks otherwise, 
					# fc will detect a difference

	load sound.wav into org    	# "org" is source sound

	load org
	amp by 100 into amped		# double amplitude
	damp by 50 into damped		# halve doubled-amplitude

	fc /b org damped		# should be the same
	fc: no differences encountered

		
	load org
	load into added			# add echo to sound
	add org into added at 1 secs	
	add org into added at 2 secs	

	load added into subed		# remove echo from sound
	sub org into subed at 1 secs
	sub org into subed at 2 secs

	fc /b org subed			# should be the same
	fc: no differences encountered


	load org
	amp by 100 into amped		# double wave

	load org into added		# get wave
	add org into added		# add wave to itself

	fc /b amped added		# should be the same
	fc: no differences encountered

	Scientists and programmers can appreciate the ability to 
	provide graphic and arithmetic operations on raw data;  there 
	is little more frustrating than having a great program but 
	being unable to use your existing data-sets;  you may have 
	files containing analog data or programs capable of generating 
	samples of data but no means of gross manipulation or of even 
	display.  1-2-3 can generate dozens of columns of solutions to 
	trigonometric equations, but can display only 8192 samples per 
	data-set: so, generate a .prn file and process the text into 
	binary as discrete 8-bit data samples:

	> dectopcm data.prn data.buf

		"dectopcm.bat" consists of this command:

		math 255 & 128 - f"%c" x < %1 > %2

	This assumes that the values in data.prn mean:

		 0 		for no deflection, 
		 1 to  127 	for positive deflection
		-1 to -128 	for negative deflection

	The math program does this:
		READ number,		# read from data.prn
		AND with 0xFF, 		# 255 &
		SUBTRACT 0x80, 		# 128 -
		DISPLAY as byte, 	# f"%c" x

	and, in so doing, converts the decimal values to PCM format.  

		Of course, this calculation could be done 
		in the spreadsheet, but having this .bat 
		file allows you to convert any list of 
		numbers in merely seconds.

	The output file can then be read into srs:

	> srs save data.buf into data.wav

PC Users

For users who just want to fool around with their new hardware, this 
program is for you.  If you are using batch files, you can do things 
like make a "While You Were Out" system, or, if you have a network 
and other users with sound boards, use srs to record messages and then 
place into a public directory: jokes are funnier when heard (sometimes).  
If you use email, you can attach sound files to documents!  Record 
explanations to spreadsheets!  Use srs for dictation!  Record your voice
and have the computer answer your phone!  Have it say things to people
when you aren't there!  Record what goes on when you are away!  Really, 
the possibilities for (im)practical application of SRS and sound in
general are endless (actually, disk space can be a limiting factor)!


DOS Version

We no longer have DOS 2.x, so we are unable to test that.  If anything,
the .bat files will need to have "@echo" changed to "echo".