* WARNING *
* *
* This is an unstable development release. *
* The interfaces have not been frozen. *
* The code may not work. *
* You may waste lots of time. (But you'll have fun doing it.) *
MAS(TM): The Media Application Server(TM)
CONTENTS:
0. Warning
1. Building
2. Installing
3. Running
4. Tuning
5. Working on the MAS source code base
6. Requirements
WARNING
-------
MAS makes high-quality, network-transparent multimedia possible on
UNIX-like operating systems. But, the MAS project is still young.
There are NO security features. We've designed it to accept all kinds
of security features, but they're not there yet.
Having said that, MAS wants to run as root to take advantage of
real-time scheduling. If you do this, be sure to run it on a
controlled network. We can't emphasize this enough.
BUILDING
--------
MAS is configured with imake. Our configuration is derived from
X.org's X11R6.5. It does not include imake. We're assuming you have X
installed. MAS is configured to build on the following platforms:
Solaris (SPARC and x86)
Linux with gcc-2.x and glibc2
On any other platform, you'll have to hand edit the Imakefiles, or
make changes in config/. Make sure you send us your patches! If your
platform wasn't one of the above, there's a good chance there isn't a
sound driver plugin for your platform. You'll need this if you want
to make sound with MAS. You can write one yourself, using the
existing ones as a template; you can pay someone to do it; or, you can
beg loudly.
Currently, we have no automatic means to detect the presence of
certain libraries on your system. For now, we assume that you have
the fftw-2.x fourier transform package and gtk+/Gnome 2.x. If you do
not have these, edit the file config/host.def to indicate which ones
you do have.
If everything looks okay, do this (the ">" indicates a command prompt):
> imake -I./config
> make World
INSTALLING
----------
By default, MAS installs to /usr/local/mas. It may use the /tmp and
/var/tmp filesystems to store state information, to log errors, and
for sockets. Here's the breakdown:
/usr/local/mas/bin server and client binaries
/usr/local/mas/lib server and client libraries
/usr/local/mas/lib plugin devices and interfaces
/tmp/.MAS-unix unix domain sockets
/var/tmp/mas state and timing information
If you'd like to change the prefix, edit the file config/site.def,
changing this line:
#define ProjectRoot /usr/local/mas
When you're ready, do:
> make install
RUNNING
-------
To run any MAS application, the server must also be running. To run
the server, execute mas-launch.sh. If you run it as root, MAS will
take advantage of a real-time scheduling privledge.
THINGS TO DO WITH MAS
---------------------
MAS is a client/server system. When experimenting with it, for now,
I find it easiest to use two shells: (in xterms, rxvt's, or just from the
console) one for the server to run in, and one for a client to run
in. If you're going to try out more than one client, you'll want
additional shells open.
Run the server before running any of the clients. From the root of
the source tree, it's "mas/mas". If installed, it'll be
"/usr/local/mas/bin/mas". By default, MAS will log errors, warnings,
and debug information to standard error.
MAS comes with a simple client application, called maswavplay, that
enables you to play a .wav file from the command-line. Other
applications are available in the CVS repository, or as seperate
tarballs on the mediaapplicationserver.net website.
We've got much more in the works. Stay tuned!
RUNNING NETWORKED MAS
---------------------
Networked MAS requires a running MAS server on each participating
networked host computer. Here's how to set up a networked MAS session
to use alongside a networked X11 session:
There are two computers "beat" and "loge". "beat" is already running
an X11 server, and you, the user, are sitting in front of it. You
want to run programs off the other computer, "loge," but interact with
them on "beat" AND, of course, have the sound come out of "beat".
________ ________
| | | |
| loge |-->| beat |
|________| |________|
If MAS isn't running on these computers, you'll need up to three
terminals open to start the pair of servers and a client. Here is the
process:
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're using ssh to
forward X11 protocol, it will be set to the same host with a higher
display number, say "loge:10". This is okay. If neither of these
criteria are satisfied, manually set the hostname to "beat:0".
4. Start a MAS client on "loge".
TUNING
------
Certain parts of MAS can be tuned to run optimally on your system.
This is recommended. Some of the tunings result in dynamically
loadable parameters, others result in program files that you must
compile into the server and client libraries.
Tuning nanosleep()
------------------
Procedure:
If you're going to run the server as root, with real-time scheduling
privledges, "su root" now. Otherwise:
> mas/masbench
It might run for a couple of minutes. Look at the output, then look
at the files /tmp/mas_nanosleep_reality.*. Do a sanity check on the
numbers. On some systems, such as Linux, you need to nanosleep() for
one scheduler tick less than you actually intended to sleep
(e.g. nanosleep(10ms) sleeps 20ms.)
Go back to the toplevel directory.
> cp /tmp/mas_nanosleep_reality.* common/.
> cd common; make clean; cd ..
> make debug
Description:
"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.
WORKING ON THE MAS SOURCE BASE
------------------------------
Since MAS relies so heavily on shared libraries for both programs and
for device plugins, the question you need to ask yourself is "Where am
I getting my libraries from?" When working directly with the code
base, you should be picking them up from the build/lib directory. The
easiest way to make sure this happens is to set your LD_LIBRARY_PATH
environment variable so that the build/lib path comes before the path
to which you installed MAS. If you don't do this, you'll think you
changed something, but you'll get the installed library every time you
run the code.
REQUIREMENTS
------------
- a solaris-like libdl.
dlopen() must allow the dynamically loaded library to resolve symbols
that are global back in the executable, like rtalloc and
new_mas_event...
CREATING A NEW MAS DEVICE
-------------------------
Start with an existing device that is similar to what you're going to
be doing. For instance:
1. 'func' is a generator - it has one source, and a periodic action
that triggers generation of more data out the source.
2. 'datalog' can be configured as a 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. There's a dataflow dependency on
the sink that triggers an action to transform the incoming data in
some way, and post it to the source.
Then, create a new directory in devices/. Copy your chosen template
device to the new directory and rename the files to match your new
device. Most simple devices will have one C file and the profile.h
include file. Assuming your device is called "cruft", the file
mas_cruft_device.c would be the code for the device plugin proper. If
you require a client-side API for the device, the files mas_cruft.c
and mas_cruft.h would be the client-side API for the device.
You'll need to edit the Imakefile. If your Imakefile looks a lot like
the one from datalog, mix, endian, srate, squant, or func, then all
you should have to do is change the SIMPLELIBNAME entry to
"SIMPLELIBNAME = mas_cruft" and add your API header to HEADERS, like
"HEADERS = mas_cruft.h" (this is further down in the file).
... AND ADDING IT TO THE BUILD OF MASLIB
----------------------------------------
Make sure the API header will install:
If you're using the template Imakefile from hexprint, func, or mix (or
most others, actually) be sure that you put the API header file
"mas_yourdev.h" in the "HEADERS = " entry. This will make sure your
header file is installed in include/mas with everything else. NOTE:
Your client will need to explicitly link in your library.
