Open Sound System
OSS 4.x Programmer's Guide

Do you have problems with sound/audio application development? Don't panic! Click here for help!

OSS API basics

What is Open Sound System

Open Sound System is the leading audio programming interface for Linux, Unix and many special purpose (embedded and real time) operating systems. It has long history that starts in 1992 as the Sound Blaster driver for Linux. It was soon expanded to support multiple sound card architectures and to work under multiple operating systems (such as FreeBSD and Unixware). Old school programmers may recognize it as the VoxWare sound driver. During the past years the original driver has developed to a full featured audio subsystem and has been renamed to Open Sound System (OSS).

What we call here as the official OSS is the commercial OSS version being developed by 4Front Technologies ( ). In addtion there are numerous independent implementations such as OSS/Free and ALSA for Linux that are based on older versions of OSS.

This manual is the official specification of the OSS 4.0 API. This version is backward compatible with all applications developed for all previous API versions. The number of changes made to the API since the previous versions is relatively small. However the importance of these changes is huge.

OSS 4.0 version fixes all the drawbacks of the earlier API. We have improved the device abstraction so that differences between the devices have been completely hidden from the applications. At the same time we have implemented some API extensions that permit control of every detail of the device if the application wants to do that (the utilities shipped with OSS provide complete control of the device features so there is no need to support them in the application).

The OSS 4.0 approach is completely different from the earlier OSS versions of OSS as well as the competing audio subsystems such as ALSA. The older systems are designed around the devices and their features. The OSS 4.0 device abstraction starts from the application needs. So with OSS 4.0 the application doesn't need to find out what the device can or can not do. Instead it simply tells OSS what it wants to do (or what kind of data stream it has). We take care of all the rest.

The programming model used by OSS is 100% compatible with the standard Posix/Unix file/device API (open/close/read/write/ioctl/select). This makes using OSS in applications extraordinarily easy. The programmer doesn't need to be worried about 200 different audio calls that are not compatible with anything else. This approach has been very successful since it's possible to implement the device related parts of practically every audio application with just 20 to 40 lines of code (including error checkings).

The OSS API has been designed to prevent programmers from using techniques and nasty programming tricks that are known to be dangerous. For example OSS (intentionally) doesn't support interrupt driven programming model (I/O signals) which requires skills of a seasoned rocked scientist. Instead OSS uses the old and reliable select/poll aproach that is significantly easier method for implementing event driven programs.

The OSS API has been designed so that the application programmers can focus on the real business that pays their salary. Everything that can be automated has been automated. This means that the programmers don't need to waste their time on battling with details of secondary importance. There is no need to check what kind of hardware is being used and how it features differ from some others. We have already done all this for you.

We have spent more than 10 years in designing OSS to be practically immune against the random variances in system load (typical problem in multi-purpose and multi-user systems). With OSS it's possible to run typical audio applications without any kind of hiccup in relatively highly loaded systems. There is no need to have dedicated threads or special application level buffers to get the applications to work.

OSS is designed to be used in applications that require very high reliability and high uptime. This makes OSS particularily well suited to applications such as audio streaming, radio broadcasts and acoustic surveilance and monitoring. And with different settings the same API can be used in entertainment applications such as games and DVD players which require tight sync between audio and image. Also very low latency applications are possible (with latencies of few milliseconds).

One unique feature of OSS 4.0 is that it's designed to support dynamically changing environment. For example instead of having recording sources such as input1, input2 and so on it's possible to assign meaningfull names to the sources. For example input1 can be renamed to Sarah and later to Julie when the artist changes. The new OSS 4.0 features make it possible to implement applications that can react to such changes and update their GUI when necessary.

In the future OSS will be more or less virtual environment which permits routing and mixing of signals between devices and applications in dynamic manner. All the features required to support this kind of features are already included in the OSS 4.0 API. All applications that use such features will automatically support any new OSS features in the future. For this reason we think that OSS 4.0 is pretty much the ultimate audio API. It's rather unlikely that the future changes in audio technology will require any major changes to it.

Compatibility between OSS 4.0 and the older versions

As mentioned above OSS 4.o is backward compatible with the earlier OSS versions as well as VoxWare and the independent drivers based on the earlier design. However the same is not true in backwards. While the number of new ioctl calls added to OSS is small the difference is conceptually very big. While the core of the API has not changed at all the new interfaces make it possible to implement more powerfull applications as ever before.

Since OSS is based on the Posix/Unix system call interface. There is no library code that could cause dependency problems with different library versions. This makes it possible to get 10 years old programs to work with the latest OSS version without recompiling (provided that the program doesn't depend on undocumented features). Equally well it's possible to use applications written for the very latest OSS version in a system that runs some 10 years old VoxWare driver version but special care would be required from the programmer. In fact incompatibility problems between different system libraries (libc) will break binary compatibility in typical Linux systems much before this.

It is possible to handle the differences between OSS 4.0 and the older versions. The descriptions of the individual ioctl calls will document the possible approaches for living without the new ioctl calls.

However since we feel the new OSS features very imortant we have decided to promote OSS 4.0 by making the "unregistered" version free for all home users (forever). This smakes it possible to the application developers to start using the new features immediately because all the customers can download the OSS software for free from our web site . We also have a special program for developers who can get a free OSS copy from us (please contact for details).

In general handling the compatibility issues between OSS 4.0 and the older drivers is very simple. All you need to do is compiling your application against the latest soundcard.h version that is always shipped with the OSS software. The new ioctl calls will return errno=EINVAL if they are missing from the target system. It's usually easy (with couple of exceptions) to live with missing calls by assuming some behaviour or by using an alternative method. All this will be documented in the ioctl call descriptions.

Almost all the features that are officially documented in OSS 4.0 have actually been in OSS for several years. So it's possible that they will work with OSS 3.99.1 or even OSS 3.9.2. However older OSS versions will return fixed zero values in some of the fields. For this reason it's recommended that the customers upgrade to OSS 4.0.

There are few major conceptual changes since earlier OSS versions

Don't try this at home

There are certain common programming errors that are causing serious support problems all the time. They can be avoided very easily by following the following guidelines.

Copyright (C) 4Front Technologies, 2007. All rights reserved.
Back to index OSS web site