FMS-1.0 PROTOCOL
****************


Protocol for communication with fmsbackend, which is a uds controlled backend
for the FMS synthesizer.

fmsbackend, when run, will try to connect to a uds socket (default:
/tmp/fms-uds) as a client.
The following communication contains protocol negotiation and commands for
playing and setting of properties.

In this communication, the program controlling fmsbackend acts as a server and
will be called "server" in the following. You may for instance use the generic
uds server genuds (available from the FROCOR project site fstoehr.de/frocor)
with
	genuds --server -f /tmp/fms-uds
to provide fmsbackend with such a server.
Fms-converter will convert commands received from a frocor-server via
/tmp/frocor2-uds to such fms commands.



A) Protocol negotiation
-----------------------

protocol fms-1.0
	- server sends protocol negotiation



B) Playing commands
-------------------

play 
	- server tells fmsbackend to start playing via /dev/dsp
stop 
	- server tells fmsbackend to pause playing
quit 
	- server tells fmsbackend to quit
stereo
	- server tells fmsbackend to play in stereo mode regardless of balance
	  properties
nobuffer
	- server tells fmsbackend to not buffer sound data, but recompute it
	  regardless repetition properties



C) setting properties
---------------------

Commands that set properties possibly include the following elements, separated
by colons:

a) indicator
Determines what kind of option we are setting.

b) basic operation type

c) object id

d) properties
Properties are set by '=', increased or decreased by '+'/'-'. 
The syntax is PROPERTY_KEY=VALUE (or PROPERTY_KEY+VALUE or PROPERTY_KEY-VALUE).
You can set more than one property at once when seperating the attributions with ':'
The property keys are more or less the same as the command line switches in fmplay.



1. mixer options
~~~~~~~~~~~~~~~~

As there is only one mixer in a fmsbackend-driven fms session, only elements a) and 
d) are supported.

a) indicator
m 
	- server tells fmsbackend that this is a mixer command

d) properties
t
	length of mixer output in seconds
	the value is of type unsigned real
	This typically doesn't make a difference, as fmsbackend sets its output on
	endless loop.
	If using a fms midi mode file, this determines its speed, though.

v
	server sets absolute output volume
	the value is of type unsigned real and must not be larger than 1

V
	server sets sum of relative volumes
	the value is of type unsigned real



2. sound options
~~~~~~~~~~~~~~~~

a) indicator
s 
	- server tells fmsbackend that this is a sound command

b) basic operation type
n 
	- server tells fmsbackend to create a new sound object or override all
	  properties of an existing one
o 
	- server tells fmsbackend to change some properties of an existing object
d 
	- server tells fmsbackend to delete existing object

c) object id
ID
	- ID is the sound object ID, starting with 0; you must specify one, even
	  when creating a sound. 

d) properties

The property keys and their meanings are mostly equivalent to what is documented
in the fmplay man page. This should serve only as an overview.

Property keys:
	s - path of fms sound file [string]
	f - frequency [unsigned real]
	v - relative volume [unsigned real]
	Q - absolute volume [unsigned real]
	e - blur [unsigned real]
	E - blur rate [unsigned real]
	b - balance [unsigned real]
	P - played [bool]
	z - sweep frequency [unsigned real]
	Z - sweep volume [unsigned real]
	m - mode [Sound, Rand, Noise, RandNoise, NoiseRand, Midi]
	d - distribution file for random [string]
	h - holding length for noise [unsigned real]
	a - anti [boolean]
	Y - sweep frequency modulation filename convenience handler [string]
	k - midi repetitions [unsigned real]
	x - midi instrument number for subsequent midi instrument options 
							[unsigned integer]
	I - midi instrument filename [string]
	A - midi instrument attack filename [string]

The following properties lead fmsbackend to create modulators to which all 
applicable subsequent options will be attributed:

	F - frequency modulator filename [string]
	V - volume modulator filename [string]
	G - sweep volume modulator filename [string]
	B - balance modulator filename [string]
	H - holding length modulator filename [string]

You may switch the option attribution back to the parent sound with the command

	c - switch back to parent sound [void]

without operator or argument (e.g. :c:).



D) Examples
-----------
	protocol fms-1.0
	s:n:1:s=/usr/share/fms/sounds/tri:f=1000
	play
# a traingular wave with 1000Hz will be loaded and played
	s:o:1:f-200
# frequency is set down to 800Hz
	quit
# connection is quitted



For further questions please refer to the FROCOR Project Documentation or ask 
the author <daniel_gruen@web.de>
