FMS-0.9 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.

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 http://ccteam-be.de/projekte/frocor_html) with 
	genuds --server -f /tmp/fms-uds
to provide fmsbackend with such a server.


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

protocol fms-0.90 
	- server sends protocol negotiation


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

play 
	- server tells fmsbackend to start playing via /dev/dsp
stop 
	- server tells fmsbackend to pause playing
quit 
	- server tells fmsbackend to quit


C) setting sound options
------------------------

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

There is only one mixer in a fmsbackend-driven fms session. 

m:t=LENGTH
	server sets length of mixer output in seconds
	LENGTH 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.

m:v=VOLUME
	server sets absolute output volume
	VOLUME is of type unsigned real and must not be larger than 1


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

Each sound option setting command is a line with a minimum of 4 sections, seperated with ':'

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

c) object id
ID
	- ID is the sound object ID, starting with 1

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 ':'

Property keys:
	p - path of fms sound file [string]
	f - frequency [unsigned real]
	v - relative volume [unsigned real]
	mi - midi instrument file path [string]
	mh - midi attack curve file path [string]


D) Examples
-----------
	protocol fms-0.9
	s:n:1:p=/usr/share/fms/sound/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>

