Examples : Volume Control

There are several levels of volume control, such as system level, exlcusive level and application level.  In a nutshell, CIOS Audio Core do only application level volume control.  Please do not use CIOS Audio Core as a system wide volume controller.

Not all Host APIs support output volume control and input volume control, some of them support only output volume control.

Determine if there is a volume controller

As a matter of face, some Host APIs do not support volume control.  Therefore, you will have to find out which one can do volume control :

Stream

virtual bool hasVolume (void) = 0 ;

Stream is the actual implementation of volume control in Host API, all Host API must inherit this function and implement it even if volume control can not actually function.  However, we do not suggest you use this function directly.

Core

virtual bool hasVolume (Stream * stream) ;

We suggest you use this function to determine if there exists a volume control function.

Volume control functions

There are four volume control functions:

virtual CaVolume MinVolume (Stream * stream) ;
virtual CaVolume MaxVolume (Stream * stream) ;
virtual CaVolume Volume (Stream * stream,int atChannel = -1) ;
virtual CaVolume setVolume (Stream * stream,CaVolume volume,int atChannel = -1) ;

All volume control in CIOS Audio Core are linear.  Some Host APIs control volume based on dB, for example, Apple Core Audio.  Within CIOS Audio Core, all units are converted into linear volume unit.  In general, volume ranges between 0.0~10000.0, double precision.  However, you should not always assume they are fixed values.  The author will try his best to control the range of volume, keep it always between 0.0~10000.0.  However, there is no hard rules to completely define the values and ensure all the other implementation will follow this suggestion.

Example

Volume control takes effect only after the stream is started.  Any changes before stream is started is invalid.

Core * core ;
Stream * stream ;
...
Initialize core
Inialize stream
Start stream
....
if ( core->hasVolume ( stream ) ) {
  double minv = core->MinVolume(stream) ;
  double maxv = core->MaxVolume(stream) ;
  double volume = core->Volume(stream) ; // average volume
  double v1 = core->Volume(stream,0) ; // left channel volume
  double v2 = core->Volume(stream,1) ; // right channel volume
  ...
  convert into your own volume measurement
  ...
  core->setVolume(stream,volume) ; // average volume
  core->setVolume(stream,v1,0) ; // left channel volume
  core->setVolume(stream,v2,1) ; // right channel volume
  ...
}
....
Stop stream
Close stream
Terminate core