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

Programming with OSS

The principal design goal of the OSS API has been agressive simplicity. Our goal has been to develop a programming interface that is easy to use, robust and pushes the programmer's productivity to the limits. The default values used by the OSS drivers have been perfected during the 10+ years history of OSS. So if you are a professional software developer then OSS is the right tool for you.

The default behaviour and all the default values uses by OSS have been perfected during the 12+ years of we have spent developing OSS. In most cases the defaults will be automatically selected to match the particular device. It would be very difficult to make anything better. For this reason the golden rule of OSS development is that you should not try to do anything more than what is absolutely necessary. Only if the simpliest approach doesn't work you should start thinking about the details.

If you like to write a perfect OSS program you should avoid using ioctl calls that are not absolutely necessary. In this way you don't prevent OSS from using most optimal strategies.

However we agree that this highly disciplined programming style may be extremely boring to the razor sharp young programming geniuses who love ultimate challenges like multithreading, non-blocking I/O and controlling every possible detail of every possible device. To keep everybody happy we have created a big enough sandbox to keep the kids busy until they retire. So beware. The OSS interface is consists of just few system calls and few more ioctl calls. However this is just the tip of the iceberg. Some of the new interfaces provided by OSS 4.0 are like "wormholes" to the cyberspace.

If you are a "just for fun" programmer then you should probably start OSS programming from the OSS Mixer Programming section and take a look at the device discovery stuff (Getting information about devices). The Digital audio interface status and setup section may be entertaining too. Using The mmap() system call is also going to be challenging in particular if you like to try to get it working with every device in the world. Computer music enthusiasts may be interested about OSS MIDI Programming. I think this should be enough to keep you busy for the time being. We will try to develop some more cool APIs in the OSS 5.0 version.

However as you may have noticed between abobe lines we don't recommend using many OSS features in professionally made programs. Our main goal is keeping everything as simple as possible. It's a known fact that every extra OSS feature used in programs make them less portable and increases the risk of making them incompatible with some devices (or in worst case dependent on one specific device model). It also increases the propability that the programmer uses some feature he/she doesn't fully understand. Our technical support sees this kind of completely unnecessary problems every day.

After carefully analyzing dozens of audio applications written for OSS we have found out that practically all of them do lot's of unnecessary things. This doesn't make them any better. Instead there are many kind of problems in certain special cases. In all such cases about 40-60% of the OSS related code can be simply removed. The result is a program that works significantly better than the original.

Developer support services

We have created a free program for OSS developers. Members of this program can get free OSS license(s). We also have a newsletter that is e-mailed to the registered developers more or less frequently. To join this program you should send e-mail to sales@opensound.com. Include a short description of the application. Note that it's possible to join this program after at least a beta version has been released so please include a pointer to the web site of the project when you apply for the membership. Both open source and proprietary software developers can join this program. In particular we recommend that novice developers join this program.

4Front Technologies also offers full developer support services for professional software developers. We do contract application development as well as give step by step help to the developers. We can also find out the best sound devices for your purposes (we have practically all of them in our lab). Please contact sales@opensound.com for more info about our consulting services.

If you have any questions about this manual or OSS programming in general, please don't hesitate to contact our developer support department (devsupport@opensound.com). We would like to keep improving this document and every kind of input is highly welcome.

Writing an OSS compatible program

The OSS API is defined in the soundcard.h header file. So the first thing to be done when writing an OSS program is including the right version of this header. You need to add the #include <soundcard.h> line to the beginning of your program. Then modify the Makefile or the configuration script to look at the right place.

We do not recommend using soundcard.h as a source of information. In addition to the official interfaces it also contains features that have never been working or that have been abandoned years ago. There may also be features that are not yet included in the production version of OSS. This manual is the only good source of OSS programming information.

Many Linux and Unix systems already ship an old version of this file. However in most cases it's an old version and not suitable to be used with OSS 4.0. In addition they may contain definitions that conflict with the official soundcard.h version. For this reason it's recommended to include just <soundcard.h> instead of <sys/soundcard.h>. In this way the risk of using wrong version is smaller.

The right version of soundcard.h will be shipped with OSS so the latest OSS version must be installed in the system. The best way to find out the right file is to use the OSSLIBDIR variable defined in /etc/oss.conf after OSS is installed. If this file is missing it simply means that OSS is not installed yet. With GNU make (and compatibles) it's very easy to handle this in the Makefile. For example:

• include /etc/oss.conf
• CFLAGS := $(CFLAGS) -I$(OSSLIBDIR)/include/sys

After including the right header you may want to check that it's version is 0x040000 or later by checking the SOUND_VERSION preprocessor variable that is set by soundcard.h. It's possible to compile the program with older soundcard.h version too but that will require heavy use of #ifdef directives in the program. So it's recommended to compile the program against the latest soundcard.h version even if it's going to be used also with older versions.

Most ioctl calls will fail with errno=EINVAL if the driver doesn't support this call (EINVAL will also be reported if a major error was made when the application calls the ioctl). The compatibilility issues subsection for each ioctl call describes the backup strategy in detail.

A typical OSS program uses the following OSS services. The exact details depend on the device type and this will be described in detail in the Audio Programming, OSS Mixer Programming and OSS MIDI Programming chapters.

• The very early decision to be made is what device to use. The Device types supported by OSS section will help you in this. After you know the device you are going to use the next step is opening it with The open() system call.
• The next step is doing some device setup using The ioctl() system call. This is not absolutely necessary since OSS audio and MIDI devices will work without any setup. However with audio devices the application should set up the sample format (number of bits), number of channels and sampling rate since otherwise the device may decide to use different parameters than the application expects it to use.
• With mixer devices the application performs all operations by using some ioctl calls. However audio and MIDI devices are accessed using the The read() system call and the The write() system call system calls. After the device is correctly set up this is actually all that is required. OSS will take care of the syncronization by waiting inside the read or write call if the device is busy with the earlier data. Some applications will require more demanding timing but with majority of applications this is not necessary.
• Acter the application doesn't need the device any more it should release it by calling The close() system call. In all but very few cases this is all that is needed. If the application is going to terminate there is actually no need to close the device manually. The device will be closed automatically when the application exist. However closing the device explicitly is highly recommended because that might be cause serious problems later if the application structure gets changed.

This is how a typical OSS application works. There are some more details and they will be described in the sections for different OSS device types.

The Some OSS sample programs section contains some usefull sample programs that explain how to use OSS from programs.