Google
 

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!

SNDCTL_DSP_SYNCGROUP

Creates a synchronization group.

Usage

oss_syncgroup group;
ioctl(fd, SNDCTL_DSP_SYNCGROUP, &group);

The above code fragment lacks all error checks for clarity. Real world applications must always check for the errors and handle them as described below. Also most OSS ioctl calls will return information in the argument variable and it's usually necessary to check it too.

Description

This ioctl call can be used to create a new synchronization group and to add more devices to it. After establishing a group it's possible to start all devices belonging to the group exactly at the same time by calling SNDCTL_DSP_SYNCSTART.

The oss_syncgroup structure has the following fields:

The application can create new synchronization group by setting the id field to zero. The first SNDCTL_DSP_SYNCGROUP call will return the newly created group handle in this field. When the SNDCTL_DSP_SYNCGROUP is made with the remaining devices the id field must be initialized with this group id (instead of zero).

The sync group identifier is a global number. It can be given to any other task in the (same) system. In this way it's possible to synchronize several applications together.

If the PCM_ENABLE_OUTPUT bit was set in the mode field then it's necessary to write some audio data (one or few fragments) to the device between the SNDCTL_DSP_SYNCGROUP and the SNDCTL_DSP_SYNCSTART calls. Otherwise playback may fail to start. Do not overfill the DMA buffer. Writing too few or too many samples to the output devices(s) will destroy sync between the devices.

Sample acurrate start will not be possible between device files that belong to different sound cards. Also the virtual mixer (vmix) subsystem will make sample acurrate operation impossible. You can bypass vmix by opening the device with the O_EXCL flag.

Related ioctl calls

Compatibility issues

This call is supported only by OSS 4.0 compatible drivers. Other versions will return errno=EINVAL. There is no exact replacement call but SNDCTL_DSP_SETTRIGGER can be used (not reliable with multiple devices).

For many "consumer" audio devices this call is emulated based on the SNDCTL_DSP_SETTRIGGER mechanism. This doesn't guarantee sample acurrate start with such devices but gives better results than calling SNDCTL_DSP_SETTRIGGER separately for each device.

The sync group mechanism has been developed for starting multiple devices as precisely as possible. In some cases this means sample acurrate start. However the "error" between devices depends on the hardware and may be multiple samples.

Please look at the When OSS audio ioctl calls can be made section for information about DSP ioctl call ordering.

OSS ioctl return values

The return value from the OSS ioctl calls will be -1 if a fatal error occurred. Other values mean that the ioctl call was more or less successful. However in most cases the application must check the value returned in the argument to see what was the accepted value.

Please see the Possible error codes (errno) returned by OSS calls section for more info about the error codes returned by OSS.

Sample programs

synctest.cA program that demonstrates use of syncronization groups.


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