* 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.