MAS(R): The Media Application Server(TM) 
        (public release 0.6.2) README

CONTENTS:

 Welcome
 Running MAS: General Considerations
 Examples
 Running Mas: Over The Network
 Tuning
 Working On The Mas Source Base
 Creating A New Mas Device
 List Of Clients
 List Of Devices
 

WELCOME
=======

MAS makes high-quality, network-transparent multimedia possible. This
is the standard release for UNIX-like operating systems. Please see
the file RELNOTES. Installation is discussed in a separate document,
INSTALL.


RUNNING MAS: GENERAL CONSIDERATIONS
===================================

MAS is a client/server system, where network communication is based on
a server to server protocol. When experimenting with MAS, you may find
it convenient to run the server in one shell and clients in
another. Using more than one client will require additional shells.

Run the server before running clients. Running the server as root will
greatly enhance the sound quality because MAS can take advantage of
root's real time scheduling privileges. You can either run the server
directly, or use the provided mas-launch.sh shell script. This script
will also start the MAS watchdog and will divert all errors, warnings,
and debug information to a file /usr/local/mas/mas-1.log. Caution
should be exercised in running as root; authentication will be added
in a future release.

Clients are typically run as a regular user.


EXAMPLES
========

MAS comes with a simple client application (maswavplay) that enables
you to play a .wav file from the command-line.

The developer tools distribution contains two programs (massink and
massource) that play back audio from standard input (massink) or
record audio to standard output (massource). In both cases, the
expected format is 44.1 KHz, 16-bit, stereo, little-endian. You can
use, for example, massink with mpg123 in the following way:

mpg123 -s filename.mp3 | massink
(MAD alternative: madplay -v -oraw:- filename.mp3 | massink)

Where "filename.mp3" is the MP3 file you are choosing.

MAS's precise stream mixing capability also allows you to run multiple
sound-producing applications simultaneously.

You can find other applications in the CVS repository or as separate
tarballs on the mediaapplicationserver.net website. A list of these
applications can be found at the end of this README.


RUNNING MAS: OVER THE NETWORK
=============================

The MAS architecture supports arbitrary distribution of audio
processing tasks across MAS servers on a network.

Networked MAS requires a running MAS server on each participating
networked host computer. The following example describes how to set
up a networked MAS session to use alongside a networked X11 session.

Imagine two computers "beat" and "loge". "beat" is already running an
X11 server; you, the user, are sitting in front of beat. Assume you
want to run programs from the other computer, "loge," as well as
interact with them on "beat" AND have the sound come out of "beat".

   ________     ________ 
  |        |   |        | 
  |  loge  |-->|  beat  |  
  |(remote)|   | (local)|
  |________|   |________| 

If MAS is not already running on these computers, you need up to three
terminals open to start the pair of servers and a client in the
following way:

1. Use ssh or telnet to log into "loge" (the remote computer) and
   start MAS there.

2. Start MAS on "beat" (the local computer).

3. With the remaining terminal, again use ssh or telnet to log into
   "loge" and check the DISPLAY environment variable. If running
   telnet or ssh without X11 forwarding, it should be set to the
   interactive hostname and display "beat:0". If you are using ssh to
   forward X11 protocol, it will be set to the same host with a higher
   display number, say "loge:10". MAS will detect this X11 protocol
   forwarding. If the DISPLAY variable is not set or contains ":0.0",
   you need to manually set the hostname to "beat:0".

4. Start a MAS client on "loge".


TUNING
======

We recommend that certain parts of MAS be tuned to run optimally on
your system. Some of the tunings result in dynamically loadable
parameters; others result in program files that you must compile into
the server and client libraries.

Regarding nanosleep();
----------------------

Procedure:
If you are going to run the server as root with real-time scheduling
privileges, "su root" now. Otherwise, enter:

> mas/masbench

masbench benchmarks the nanosleep() function and produces a C
program file and C header file that contain two arrays and some
#defines used by mas_realsleep() to allow greater sleep accuracy.

After masbench runs for a few minutes, examine the output and the
files /tmp/mas_nanosleep_reality.*. Perform a sanity check on the
numbers that masbench prints to the screen (the first number is
the time the system was asked to sleep, and the third number is the
time it actually slept).

Return to the toplevel directory and enter:

> cp /tmp/mas_nanosleep_reality.* common/.
> cd common; make clean; cd ..
> make debug



WORKING ON THE MAS SOURCE BASE
==============================

Because MAS uses shared libraries for both programs and devices
(binary plugins), you should know where the libraries originate. When
working directly with the source base, you should pick up the
libraries from the build/lib directory. The easiest way to ensure that
this happens is to set your LD_LIBRARY_PATH environment variable so
that the build/lib path comes before the install path. If the install
path comes before build/lib in your LD_LIBRARY_PATH, you will be using
the old, installed libraries instead of your new modified ones.

Note that MAS depends on a solaris-like libdl; dlopen() must allow the
dynamically loaded library to resolve symbols that are global back in
the executable.


CREATING A NEW MAS DEVICE
=========================

First, start with an existing device that works in a way similar to
the way you want the new device to work. For instance:

    1. func is a generator - it has one source, and a periodic action
       that triggers generation of more data from the source.
   
    2. datalog can be configured as a simple consumer, or as an
       in-line device - it has one sink, one source (which may be left
       unconnected) and a dataflow dependency on the sink that
       triggers a logging action.
   
    3. mix is a more complex device. It has a replicating sink port
       and a single source.
   
    4. endian, srate, and squant are in-line devices. They each have
       one sink and one source. A dataflow dependency on the sink
       triggers an action to transform the incoming data in some way,
       and posts the data to the source.

Second, create a new directory in devices/. Copy your chosen template
device to the new directory and rename the files to match the new
device. Most simple devices will have one C file and the profile.h
include file. If, for example, your device is called "splendid", the
file mas_splendid_device.c would be the code for the device plugin
proper. If you require a client-side API for the device, the files
mas_splendid.c and mas_splendid.h would implement the client-side API
for the device.

If you follow this naming convention all you need do is change the
SIMPLELIBNAME entry in the Imakefile to "SIMPLELIBNAME = mas_splendid"
and add your API header to the HEADERS section (further down), as in
"HEADERS = mas_splendid.h". This will ensure proper installation of
your header files. Note that any client using your API needs to link
in your client side library explicitly.


LIST OF CLIENTS:
================

clients:

clients/maswavplay/maswavplay         command line wav file player
                                   
                                   
utilities:                         
                                   
clients/util/mas-launch.sh            as root, launch MAS and watchdog
clients/util/masmkmf                  Makefile generation                      
clients/util/mas-config               show compile/link flags
clients/util/maswatchdog              MAS watchdog
                                   
                                   
control applications (require GTK+):              
                                   
control-apps/masconf/masconf_gui      2-way audio teleconference
control-apps/masmix/masmix            hardware mixer
control-apps/masmm/masmm              software mixer (works with MAS mix device)
control-apps/masplayer/masplayer      networked mp3 player
control-apps/massignal/massignal      signal generator
                                   
                                   
developer tools:                   
                                   
devtools/masnetstat                   cause net device state dump
devtools/masget                       command line access to mas_get interfaces
devtools/masset                       command line access to mas_set interfaces
devtools/massource_set                command line access to source interface
devtools/masloopback                  loop recorded audio back to the mixer
devtools/massource                    echo recorded audio to standard output
devtools/massink                      takes audio from standard input
devtools/mascodectest                 stdin->codec->stdout for codec testing
devtools/masprobe                     insert a datalog device inline
devtools/mashost                      allow or deny connections from named hosts
mas/masbench                          sleep timer benchmarking
mas/mastestdev                        test a device (dynamic loading etc)



LIST OF DEVICES:
================

anx               audio nexus (interface to the native audio system)
cdrom             control a CDROM drive
datalog           log data and/or RTP header information
flowrate          ? control data flow rate ?
frag              output packets of fixed, settable length
func              function (signal) generator
latpuls           pulses for latency testing
mix               software mixer
net               the network, abstracted into a MAS device
ppm               peak program meter; generates meter data
sbuf              a buffer (on the data packet level)
source            reads wav/mp3 files and paces them out 
split             clone a stream
tag               interpret id3 tags
visual            show real time spectrum (like a graphic eq)


codecs: 

channelconv       mono<->stereo conversion
codec_ulaw        ulaw<->raw pcm
endian            big<->little endian
squant            quantization (bit depth) changes
srate             sample rate conversion

distributed separately:
mp1a_mad          mp3 codec (GPL)
