AUSS User Manual


User manual for Abram's Unix Sound System (AUSS). Describes the components of AUSS and how to use the components of AUSS.

Document Status:

This is the inital version of the AUSS User Manual.

Document Change Record:

Abram HindleUpdating the User Manual Tue Dec 17 21:44:54 PST 2002
Abram HindleWorking on the User ManualMon Dec 2 15:10:52 PST 2002
Abram HindleStarted the User ManualTuesday Nov 26 10:01:07 PST 2002

  1. Abstract:
  2. Document Status:
    1. Document Change Record:
  3. Introduction:
    1. Intended Readership:
    2. Purpose:
    3. Terminology:
  4. Installation:
  5. Overview Section:
    1. The AUSS Project Consists of:
    2. Connector:
      1. Running:
      2. Explaination:
    3. Configurator:
      1. Running:
      2. Commands:
    4. Muxer:
      1. Running:
      2. Commands:
    5. DeMuxer:
      1. Running:
      2. Commands:
    6. Sink:
      1. Running:
      2. Commands:
    7. PipeSplitter:
      1. Running:
      2. Commands:
  6. Useful Tools That The Author Uses:
    1. Netcat:
    2. Ecasound:
    3. Csound:
    4. Doxygen:
  7. Examples:
    1. Mp3 Stream To Connector:
    2. Using Netscat And Ecasound To Play Output From A Sound Connector:
    3. Perl and Muxer piping to the connector:
    4. Demuxer and Csound:


Intended Readership:

Intended readers are the users of AUSS. AUSS users are expected to understand general networking concepts of servers and clients; how to use UNIX pipes; understand the structure of the audio data they are working with. Most computer musicians and enthusiasts should be up to this level.


The purpose of this manual to introduce and inform the user on how to use AUSS effectively. It is also meant to answer user questions and provide some context to the user. This manual is also meant to provide end-user documentationt to further the acceptance of AUSS.

AUSS is a stream based sound routing system. AUSS will provides an easy to use API, who's purpose is to hasten the development of audio applications. AUSS enables the use of pipes and sockets to move digital audio between processes and computers. AUSS is meant to enable interprocess, intercomputer patching of audio. AUSS enables computers and processes to be connected.

The philosophy behind AUSS is keep it easy, keep is simple. Audio is transmitted raw and often headerless. It is expected that you know what your system is using. There are headers but they are XML (so they are easily extendable and readable).

AUSS is also meant to be open, extendable and free. AUSS is GPL'd while the libs are LGPL. You are welcome to make AUSS software with any license or any language. AUSS is meant to be so simple that it will be trivial to communicate to with in most languages.



Currently how you want to install AUSS is up to you.

To compile and make AUSS type:

		% make

Once AUSS is compiled then you can run the various programs found in:

If you plan to compile AUSS programs in C and don't want to statically link files I suggest you install into /usr/local/lib or an appropriate library directory.

For the connector and the configurator you can also "make docs" to regenerate the documentation if you have both javadoc and doxygen installed.

Overview Section:

The AUSS Project Consists of:

The Connector is a daemon which accepts audio connections to it for input output and filtering of streams. Audio streams between connections can be dynamically routed by the Configurator. The Connector is probably the heart of AUSS although it is not nessecary to use the connector.
The Configurator is a GUI frontend to control the Connector. The Configurator provides graphical representations of the input output and filter connections to the connector. These connections can then be combined by dragging the mouse to connect the components.
The Muxer is a commandline program you can use to distribute your sound stream from STDIN (STDOUT of another program) to a connector or other networked AUSS hosts.
% soundProgram | Muxer host1 port1 host2 port2 ...
The DeMuxer is a commandline program which accepts connections on a port and then downmixes the audio streams from those connections into one output stream sent out on STDOUT. DeMuxer is usually not used with a connector as provides the static functionality of the Connector.
% Demuxer port1 | soundCardPlayer
The pipesplitter takes an interleaved stereo audio stream and streams the two channels out on STDERR (left) and STDOUT (right)
% stereoSoundProgram | PipeSplitter 2>e; /dev/null | soundCardPlayer
AUSSLib is a library for developers to help integrate applications with AUSS. AUSSLib is currently supported in C, Java, and Perl.



% Connector % Connector 6666
The default port is 6780, the port you provide is the first of 4 ports e.g.

Waiting for connection on port 6780
Waiting for connection on port 6781
Waiting for connection on port 6782
Waiting for connection on port 6783


The connector now may be connected to by other program on the previously defined ports.

It is up to the Configurator to connect the connections of the Connector before any audio will be moved.

The Connector can be shutdown by commands from the Configurator



% RunConfigurator % RunConfigurator localhost 6783


Connect and Update
This is a two in one command, it connects to the server (as specified on the commandline) and updates the view. If there were new connections between the last update they will be added to the main panel.
Shutdown Server
This shutsdown the server (the Connector). Disconnects all the connection including the config connection and closes the server. The server also stops listening on the four ports.
This closes the configurator and disconnects from the server. This does not shutdown the server.
Patch Connector
By dragging on the "node" ends of a connector you can create a patch between two compatible node ends. Output nodes (right nodes) can be only connected to Input nodes (left nodes) (and vice versa). This patch enables the transmission of sound between the two connectors. Filter connections have two nodes, Input Connections only have an output node while Output Connections have an input node.
UnPatch Connector
To unpatch a Connector simply middle or right click on the connection between the two connectors. The line/path between the connectors will disappear and audio will be cut off.
Disconnect a Connector
Simply right click on a connector and it will be permanently disconnected. All patches will be removed and the connection closed.



		% soundSource | Muxer     ...  
		% soundSource | Muxer localhost 6780 


The muxer reads from STDIN and outputs the sound stream to each of the host port combinations. Each host port pair recieves the same sound stream. If one host is no longer recieving the stream it does not disturb the other hosts. Muxer can also be used to forward sound streams to a connector very easily.



		%  DeMuxer 
		%  DeMuxer 6780 | soundoutput


The DeMuxer sits and accepts connections on the specified then it mixes and pipes audio from these connections out to stdout. Mixing is linear mixing so the number of connections affects the amplitude of each connections when mixed.



		%  Sink  
		%  Sink 6780 | soundoutput


The sink connects to a connector or output connection and writes data sent to the sink out to stdout. The Sink is a one way pipe out from a connector or another AUSS program. The name sink comes from convential pipe and filter terminology as it syphons and drains data from a AUSS system.



		%  PipeSplitter 
		%  soundin | PipeSplitter > /dev/null 2| soundout 


PipeSplitter splits interleaved audio consisting of shorts. Each channel is output to either STDOUT or STDERR. Left Channel goes to STDOUT and right Channel goes to STDERR. Usually this is used to access one channel rather than both.

Useful Tools That The Author Uses:


Like cat but over TCP, exactly compatible with AUSS. Netcat can listen on a port and output to stdout. It can connect to remote host and communicate through bother stdin and stdout. Unfortunately the tool comes a shady source :).


Great unix commandline utility. Very powerful software. I use it to play auss audio streams to the sound card.


Excellent Unix/Windows sound synthesizer. It's much like macro assembler for sound synthesis. You write instrument and then use an orchestra or real time events to call it.


Doxygen is an excellent source reverse engineering and program understanding tool. It's currently being used to generate up to date architectural diagrams and design documention for C/C++.


Mp3 Stream To Connector:

% mpg123 -s ~/we_didnt_start_the_fire.mp3 | ./Muxer localhost 6780

Using Netscat And Ecasound To Play Output From A Sound Connector:

% nc localhost 6781 | ecasound -i stdin

Perl And Muxer Piping To The Connector:

% perl -e 'for(;;){print pack("s",rand(65000));}' | Muxer localhost 6780

Demuxer And Csound:

% Demuxer 6787 | csound -i -o devaudio file.orc file.sco