AUSS User Manual

Abstract:

Introduction:

Intended Readership:

• Pipes consist of understanding what "ls | sort" would do.
• Client Server concepts consist of understanding that servers sit on a computer waiting for connections on ports while clients connect to the host's port to communicate.
• Understanding audio data would be knowing if you are using a stereo or mono audio stream, if it's 44100hz, if it's 16bit or float or double or byte.

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.

• Channel – one monaural stream of audio.
• Float – floating point number usually 32-bit in size
• Interleave – mix 1 or more channels of audio together by having each following sample belong to a different channels. E.g. LEFT – RIGHT – LEFT – RIGHT - ..
• Mono / Monaural – Single channel audio.
• Multichannel – Two or more streams of audio like stereo or 5.1. Generally interleaved on output.
• Patch – To connect two units together, much like patch audio cables. Patches provide a transport for audio between units.
• Realtime – A system in which the audio is immediately played to a sound output device at the rate in which it is heard.
• Short – 16 bit Integer number.
• Stereo – Dual channel audio, usually interleaved.
• Frame– 1 fully interleaved sample. In a 5 channel interleaved integer based sound stream a frame consists of 1 sample from all the channels thus 5 integers would make a frame.
• Input Connection– A connection which provides input to a service. E.g. If a white noise generator was connected to connector, it would be an input port.
• Ouput Connection– A connection which provides output from a service. E.g. If connector connected to a soundcard out object, that the sound card out object would be an output port connection.
• Filter Connection– A bi directional connection over sockets which is both an input and output port. E.g. a low pass filter could provide both an input and output interface.

To compile and make AUSS type:

		% make

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

• ./Connector
• ./Configurator
• ./examples
• ./AUSSLib

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

The AUSS Project Consists of:

Connector

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.

Configurator

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.

Muxer

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

DeMuxer

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

PipeSplitter

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

AUSSLib is a library for developers to help integrate applications with AUSS. AUSSLib is currently supported in C, Java, and Perl.

Running:

% Connector % Connector 6666

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

Explaination:

• The 1st port (6780) is the input connection port for streams which only provide sound.
• The 2nd port (6781) is the output connection port for streams which only recieve sound streams and output them.
• The 3rd port (6782) is the filter connection port for streams which take incoming streams and produce outgoing streams. Essentially filter connections can filter other audio streams.
• The 4th port (6783) is the config connection port for the Configurator and configurator like programs to connect to communicate to the connector with.

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

Running:

% RunConfigurator % RunConfigurator localhost 6783

Commands:

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.

Exit

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.

• The system without patches.
  
• Two patches are dragged and made.
  
• One patches is removed by right clicking.
  
• Unpatch by right clicking then add two new patches by dragging
  

Running:

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

Commands:

Muxing

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:

Running:

		%  DeMuxer 
		%  DeMuxer 6780 | soundoutput
		

Commands:

DeMuxing

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:

Running:

		%  Sink  
		%  Sink 6780 | soundoutput
		

Commands:

Outputing

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:

Running:

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

Commands:

Splitting

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:

Netcat:

Ecasound:

Csound:

Doxygen:

Examples:

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