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_SETPLAYVOL

Changes the current audio playback volume

Usage

int level=(left)|(right<<8);
ioctl(fd, SNDCTL_DSP_SETPLAYVOL, &level);

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 changes the current audio playback volume for this particular device. The level argument is encoded in the following way: level=(left)|(right << 8). The permitted ranges for the left and right volumes are 0 (muted) to 100 (max). After the call the active playback level will be returned in the variable pointed by the argument.

Some devices or OSS implementations may use only mono volumes. For this reason it's highly recommended that applications implement only mono control and use only the level returned for the left channel.

It's possible that the level refuses to change. This happens when the device doesn't have any volume control. This is not an error and the application must not cpomplain about the situation. Instead it should just silently update possible GUI controls to the returned value. It's also possible that the level changes "itself" because some mixer application has touched it. It might be a good practice to check the level occasionally and update the GUI when necessary.

This ioctl call replaces the SOUND_MIXER_PCM method used with earlier OSS versions.

Related ioctl calls

Compatibility issues

This ioctl call is new in OSS 4.0 and not supported by the freeware implementations based on older OSS versions. If this call returns errno=EINVAL then the best approach is to assume that the playback volume is fixed. In this situation it's better to ask the user to change the recording source manually rather than trying to use desperate hacks to change the volume.

Traditionally many audio applications have used the mixer ioctl calls to change the playbac volume. This must be avoided because in practice no program does this correctly. In addition the only correct way doesn't work with the freeware OSS clones anyway.

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

No sample programs available

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