CSC 499 Project
Abram's Unix Sound System (AUSS) Program
API Document

Revision Table

1.0 Abram Hindle Started Wed Sep 18 19:44:24 EDT 2002


0. Preamble

1. AUSS Philosophy

2. AUSS Sound Format Explained

3. Connector


0. Preamble

Most items that are covered in an API Specification are already located in the SDD. For the sake of "Document Reuse" Information communicated in the SDD will not be repeated here.

1. AUSS Philosophy

AUSS is meant to be designed with the end developer in mind. The target market is people using opensource audio software who want to link various opensource components together. I am not restricted AUSS to only opensource but it is the "market" which is the most relevant.

1.1 Why is AUSS Easy to Develop For?

AUSS is easy to develop for because at the very least all one needs to do is using pipes to stream audio between applications, you don't even "need" a header. As long as the user is aware of the types of audio streams they are using the system will work easily. Potentially one could just print audio bytes to stdout which could be piped into a sound stream player. Your audio printing program would then be playing audio is realtime!

AUSS is multi-language. You can use any language which gives any of these features; writing to stdout; reading from stdin; pipes; sockets; tcp connections,... You can use languages which the library hasn't been ported to just because you can print!

Sockets are used in many cases instead of pipes because:

2. Sound Format Explained

Each Frame consists of 1 sample per channel of audio. 1 Sample is the size of the number representing the amplitude of the audio at one point in time. A frame of CD AUDIO quality sound consists of 2 16bit samples, for Left and Right channel. What AUSS enables users to do is to pass raw frames between processes easily, because you can do this your program doesn't need to interface.

Optionally headers can be included in front of an audio stream (or in the opposite direction of a stream accepting audio). These headers are in XML but MUST be padded to be a the size of a multiple of frames. This is so that systems which don't support AUSS headers can still play the sound stream, this means the headers will be played as if they were normal audio. At most this will be a little pop. By being the same size as a multiple it makes sure all frames are properly aligned and interleaved data does not lose sync. If the header wasn't a multiple potentially you could have even the samples not being aligned so would hear noise rather than the sample itself.

Headers are useful for AUSS programs which would like named connections, programs like the Connector, otherwise most AUSS programs will just want anonymous connections.

Most of the header is optional. The main point of a header is pass an audio stream's name along.

A good explanation of the protocol used by AUSS is located in the SDD in Section 5.2.1 .

3. Connector

There are 3 ways to talk to the connector:

Each of these connection types connect to a specific port on the connector. This allows there to be no dependency on the header to determine what kind of connection there is.

In the case of the Output connection a header maybe provided if underlying link is by directional (a socket). The Connector will check for a header, once the header is read in the connector will ignore any further bytes.

Once a program is connected to the Connector, a program can read and write audio depending on the connection type. If there are no bytes to read the program should block until there are bytes since the system maybe outputting to the soundcard and only so much data can be passed to the soundcard at once.

The connector configuration protocol is detailed in SDD Section 5.2.2 .


The interface for AUSS Lib is detailed in SDD Section 5.1.3 .

The interface for AUSS Lib Languages is detailed in AUSSLib Language Specification.

A program using AUSS Lib would generally either connect to another program or connector using the "connect" method. Headers are sent when requested or when necessary.

A program could then use "read" or "write" to read or write data to and from the connection. Read and write will be blocking calls. This is an attempt at taking advantage of blocking to provide flow control. Programs using AUSS can buffer and block all they want.

Once a connection is finished with you can disconnect it using "disconnect".

For demultiplexing a mixDown routine is provided to mix the connections into one audio stream.

You do not need to use AUSS Lib to use the AUSS system. AUSS Lib is useful for more complex applications.