Enter your search terms Submit search form   Web www.opensound.com manuals.opensound.com developer.opensound.com

Open Sound System OSS 4.x Programmer's Guide

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 (http://www.opensound.com ). 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 sales@opensound.com 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

• The device abstraction is stronger than earlier. In fact conceptually the application doesn't talk to the device at all. Instead what we call "device" in this document is actually something that can better be called as an endpoint. In many cases the application doesn't access the hardware directly. Instead it may be using some kind of virtual device. In some cases there may be no audio hardware involved at all but the application just talks with another application. It's possible to find out what kind of device is being used by checking it's capabilities.
• Many recent consumer sound devices are limited to one fixed sampling rate, sample format and/or only to stereo operation. Also professional audio devices are often configured in this way. OSS can do on fly format conversions between the format preferred by the application and the format required by the device. This will be done practically transparently but it has certain side effects to the values returned by few ioctl calls. This in turn may break poorly designed applications that use OSS features in a wrong way. For this reason it's very important that programmers don't use certain optional OSS features unless they are fully qualified to use them. The core feature set of OSS has been designed so that it cannot be used incorrectly.
• As mentioned above the OSS API services are divided to few core services that are easy to use and very safe. In addition there are several optional features that are required for some special purposes. They are not intended to be used in normal applications. Please read the ioctl description before using it.
• Certain mixer operations that have earlier been done using the mixer API have been moved to the audio API. Things like recording source and playback routing selections as well as recording and playback level adjustments belong to the audio API more naturally than to the mixer API. It's still possible to use any mixer application to do the same changes but audio programs must in no case try to access the mixer directly. This has been the major reason for device incompatibility problems during past 10 years so we would like to see this pervert practice to fade away as soon as possible.
• The old "legacy" mixer API (the SOUND_MIXER_* thing) is no longer included in this document because it's completely incapable to handle modern devices. It's still supported by most OSS drivers but new applications should not use it. Instead applications should use the new recording and playback control ioctl calls or the new mixer API.
• The old /dev/sequencer and /dev/music API is no longer being developed and using it is not recommended in new applications. While it will stay supported in the future no new devices will support it. In the future OSS versions the /dev/midi API will be used for the same purpose than this interface.

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.

• Do not implement any applications based on some older program. It's almost certain that they use OSS incorrectly. Use only the sample programs developed or recommended by 4Front Technologies.
• Do not read older OSS programming manuals or any audio programming HOWTOs you have found from the net. Use only the documentation available from 4Front Technologies .
• Don't try to access mixer in audio applications. This simply will not work. Some devices don't have mixer at all. The others have a mixer that is incompatible with the device you used when developing the application. Handling all the special cases is impossible. You will have to spend the rest of your life in trying to solve all kind of support problems if you make this mistake.
• Don't use the old "legacy" mixer API (SOUND_MIXER_*). It's obsolete. Period.
• Don't try to use more OSS features than you need. This is how OSS is designed to be used. The default behaviour provided by OSS is probably much more optimal for your purposes than some random changes made without adequate knowledge. It's quite common that this kind of extra ioctl calls makes the application to fail with different hardware or different OSS version/implementation than the one you used for testing.
• Do not use OSS features that are not documented or which you don't fully understand. While checking for some real-time capabilities may look cool but in reality it will prevent the application to fail with large number of devices. 90% of all OSS features have been designed to be used only in some very special cases. Please read the documentation.
• Don't make the ioctl calls in a wong order or wrong moment. Please read what this document tells about the call order.
• Do not non-blocking I/O. There is no reason to use it. Many applications turn on non-blocking I/O and then use applied black magic to find out how long time they should sleep before calling read or write again. This is idiotic approach because normal "blocking" write/read does all this automatically without any effort from the programmer. If you really need to use non-blocking I/O then you should use select/poll which is the only sane way to do this.
• Don't use hardcocded device names. This works properly only when there is only one device in the system. In most cases the end user needs some way to select a different device. Please look at the section for The open() system call for more info.
• Don't set the device buffer size too small because this makes the application to fail if there is any other activity in the system. Small buffers are required only when you need to be able to react very rapidly to external (asyncronous) input or events. In all the other situations there are several much better ways to handle lag problems between audio and the screen events.
• Do not use mmap(). This approach bypasses most functionality of OSS. This means you will have to be prepared to support any kind of devices yourselves. OSS cannot do sample rate or sample format conversions for you. In the mmap method the application writes or reads the device directly and this is not possible with all devices.