| | Open Sound System |
| Do you have problems with sound/audio application development? Don't panic! Click here for help! |
All OSS system calls follow the familiar Posix/Unix semantics. Please look at the standard manual page (man open) for more informtion. This section will only explain some OSS related details. The error codes returned by OSS as well as their meaning will be described in the Possible error codes (errno) returned by OSS calls section.
Before an OSS device can be used it must be opened. This works exactly like opening any other device or file in the system. The only OSS specific thing is which device name should be used. The detailed description this will be given in the Device types supported by OSS section.
The flags parameter of the open call selects the direction for which the device is opened. It's important that the application uses the right right direction depending on it's needs. The direction affects way how some drivers behave. It's possible that the number of supported sampling rates is smaller if the device is ioened with O_RDWR instead of opening it with O_RDONLY or O_WRONLY.
Applications that plan to use the mmap mechanism for playing audio data must use the O_RDWR flag under Linux (may be required under some other operating systems too). Linux doesn't permit mapping of device memory for write only access. This may cause problems when the default audio device (/dev/dsp) is used because the redirection feature may require use of O_WRONLY bit to work. The workaround is to use some of the real devices directly in applications that are going to use mmap.
There is no need to use the O_NONBLOCK (or O_NDELAY) flag when opening OSS devices. The open call will return immediately with errno set to EBUSY if the device cannot be opened immediately. However some freeware OSS implementations violate the OSS specification by waiting until the device gets free. This behaviour is stupid§ and causes nothing but troubles. Applications should not try to get around of this bug by using the O_NONBLOCK flag. This will cause major problems later if the application forgets to turn this flag off after the open (using fcntl).
The O_EXCL flag is new in OSS 4.0 and earlier versions don't support it. It is used with audio devices to prevent virtual mixing (see below). Other types of OSS devices don't use it.
Other open flags don't have any effect with OSS devices at this moment. They must in no case be used since they may cause major problems with future OSS versions. In particular do not use the O_ASYNC since OSS will not support this feature.
OSS 4.0 supports virtual mixing (under most operating systems other than FreeBSD). This feature makes it possible for multiple applications to share the same "real" audio device. In this way they all can play and record audio at the same time.
Output from multiple applications will be mixed together and then sent to the actual device. There are rare cases when this might cause undesirable effects:
1) Mixing may corrupt certain digital audio formats (such as AC3, MP2/3/4, DTS) which makes them unusable. By default mixing will not be enabled on digital audio (S/PDIF) devices so there should not be any problems. However the system administrator may enable virtual mixing manually.
2) System (KDE, GNOME, etc) beeps mixed with audio output from the application may cause annoying problems if the output is being transferred to a tape or to drive an FM transmitter of a radio station. Also in this case it's error of the system administrator if a "critical" audio device is also used as the default audio device.
3) Virtual mixing causes some additional latencies in output (but not in input). These extra latencies are about 10 to 20 msec by default (they can be reduced by increasing the max_intrate parameter in osscore.conf).
4) Virtual mixing may disturb applications that need to play/record audio in perfect sync using multiple devices. This kind of applications typically use SNDCTL_DSP_SYNCGROUP to start the devices at the same time.
As described before virtual mixing doesn't cause any side effects in properly configured systems. In fact it's highly desirable feature that makes it possible to play system sounds or other urgent notifications at the same time when some application such as a game or a media player is using it. Applications should not try to bypass the virtual mixer to access the hardware directly. However this can be done by opening the audio device with O_EXCL.
Using O_EXCL should be avoided because it prevents other applications from running. It may even prevent the application itself from running before all the other applications using the device are exited or killed. For this good reason applications must not use O_EXCL unless requested by the user (command line switch or configuration setting). If such setting is used it must not be turned on by default. This kind of options must be described in the documentation of the application. In particular the user must be warned about the side effects caused by use of exclusive mode.
Some sound cards use hardware mixing. The O_EXCL flag doesn't work with hardware mixing. It doesn't prevent other applications from using the device because each application uses a dedicated hardware level audio engine.
O_EXCL must not be used at all by applications that open the default audio device (/dev/dsp, /dev/dsp_*). It can only be used in applications that force the user to give the audio device name by using the command line or some setup option. Applications that use O_EXCL incorectly may prevent other applications from using /dev/dsp which is not acceptable.
If O_EXCL is used then some configuration setting or command line switch MUST be provided this feature off if it causes problems.
Applications that use O_EXCL must also use SNDCTL_AUDIOINFO_EX instead of SNDCTL_AUDIOINFO (if they need it). SNDCTL_AUDIOINFO returns device capabilities that are valid when the audio device is opened without O_EXCL (virtual mixing is accounted). SNDCTL_AUDIOINFO_EX in turn returns device capabilities without O_EXCL (when the real device itself is being used directly). These ioctl calls are normally used in application setup dialogs and using wrong one may result in incompatible device selection. For example SNDCTL_AUDIOINFO may report input capability (which is provided by the virtual mixer). However if the application uses O_EXCL there may be no recording capability because virtual mixer was bypassed.