Below are the functions available in the DPS SDK. They are referenced in the DPS.h header file and are as common as possible across all platforms:
int DPSInitialize(environment, context, string license_file);
This “wakes” up the algorithm and initializes all tables, variables, etc. Invoke once at start-up. This will return one of the Licensing values. You must receive AUTH_SUCCESS (integer value 0) for DPS processing to work unrestricted. If any other value is returned DPS will go into demo mode. The other values are defined in the DPS.h file.
int DPSGetDPSEnabled();
Get the status of DPS processing. If 1, then DPS is enabled. If 0, then DPS is bypassed.
void DPSSetDPSEnabled(int enabled);
Enable or bypass DPS processing. Use enabled = 1 to turn on DPS. Use enabled = 0 to turn DPS processing off. DPS HEAR and User Volume Control (see below) is maintained with DPS off.
int DPSLoadPreset(char *fname);
The “Preset” refers to a DPS Profile. This contains the settings that conform the DPS algorithm to a specific playback device. For example, this could be Bose Headphones, Klipsch Speakers or a “City” profile that is universal to many devices.
The DPS library now uses the .bgvx format for all parameters. .bgva and .bswt formats have been depricated.
This function returns 0 = success, 1 = file doesn’t exist, 2 = invalid preset
int DPSLoadPresetBuf(char *c, int length);
This function is used to load profiles from memory.
Returns 0 = success, 1 = file doesn’t exist, 2 = invalid preset
Note that presets/profiles are typically around 4kB in size.
void DPSFlattenAll(void);
This sets all DPS parameters to flat state. The DPS algorithm is still running but there is no effect on the audio. This maintains the audio latency (total delay caused by the algorithm).
void DPSProcessBuffer(short *buffer, int numOfFrames, numberOfChannels);
This is how we pass audio to the DPS algorithm for processing. This function returns the buffer with DPS processing applied.
numOfFrames = number of stereo samples. Maximum value allowed is 2048.
Currently the DPS algorithm supports stereo audio only. Multi-channel support is coming soon.
The DPS Equalizer is a mastering quality parametric equalizer that occurs after DPS processing. This EQ can be simplified to be a basic Treble/Bass tone control or provide the user with advanced controls.
i = 0 for low band, i = 1 for high band.
The latest version of the Core API can now take parameters for the User EQ:
int DPSGetUserEqEnabled(int band); // 1 enabled, 0 bypass void DPSSetUserEqEnabled(int band, int enabled); // enabled = 1 enable user eq, enabled = 0 bypass user eq int DPSGetUserEqFreq(int band); float DPSGetUserEqQfactor(int band); float DPSGetUserEqGain(int band); float DPSGetUserEqGain_dB(int band); void DPSSetUserEqFreq(int band, int frequency); void DPSSetUserEqQfactor(int band, float Q); void DPSSetUserEqGain(int band, float magnitude); void DPSSetUserEqGain_dB(int band, float dB);
We recommend a Frequency value of 160Hz and a Q value of 0.7 for bass tone control.
We recommend a Frequency value of 5000Hz and a Q value of 0.7 for treble tone control.
The old format uses indices to set/get EQ values:
void FcKnobMoved(int i, int Fc); //i = 0 for low band, 1 for high band void QKnobMoved(int i, int Q); //i = 0 for low band, 1 for high band void GKnobMoved(int i, int gain); //i = 0 for low band, 1 for high band int GetFcKnob(int i); //i = 0 for low band, 1 for high band int GetQKnob(int i); //i = 0 for low band, 1 for high band int GetGKnob(int i); //i = 0 for low band, 1 for high band
Click Here for a plain table of Index and Ranges
The integer values below represent recommended ranges for the equalizer sliders:
Low-band:
Gain from 4 to 32. 24 = 0dB = No change in gain.
Frequency Center (FC) from 0 to 29
Q (width value): from 0 to 15
We recommend a Frequency value of 15 (160Hz) and a Q value of 3 (0.7) for bass tone control.
High-band:
Gain: from 4 to 32. 24 = 0dB = No change in gain.
FC: from 30 to 57
Q: from 0 to 15
We recommend a Frequency value of 45 (5000Hz) and a Q value of 3 (0.7) for treble tone control.
The integer values above represent indexs in the following arrays:
//public final static double[] GainArray = {0.251189, 0.266073, 0.281838, 0.298538, 0.316228, 0.334965, 0.354813, 0.375837, 0.398107, 0.421697, 0.446684, 0.473151, 0.501187, 0.530884, 0.562341, 0.595662, 0.630957, 0.668344, 0.707946, 0.749894, 0.794328, 0.841395, 0.891251, 0.944061, 1.000000, 1.059254, 1.122018, 1.188502, 1.258925, 1.333521, 1.412538, 1.496236, 1.584893, 1.678804, 1.778279, 1.883649, 1.995262, 2.113489, 2.238721, 2.371374, 2.511886, 2.660725, 2.818383, 2.985383, 3.162278, 3.349654, 3.548134, 3.758374, 3.981072, 4.216965, 4.466836, 4.731513, 5.011872, 5.308845, 5.623413, 5.956622, 6.309574, 6.683439, 7.079458, 7.498942, 7.943282};
Calculate the Decibel value using (10*Math.log10(Math.pow(value,2))) .
//public final static double[] FcArray = {28.0, 31.0, 35.0, 40.0, 45.0, 50.0, 56.0, 63.0, 70.0, 80.0, 90.0, 100.0, 112.0, 125.0, 141.0, 160.0, 180.0, 200.0, 225.0, 250.0, 280.0, 315.0, 350.0, 400.0, 450.0, 500.0, 560.0, 630.0, 700.0, 800.0, 900.0, 1000.0, 1120.0, 1250.0, 1400.0, 1600.0, 1800.0, 2000.0, 2250.0, 2500.0, 2800.0, 3150.0, 3500.0, 4000.0, 4500.0, 5000.0, 5600.0, 6300.0, 7000.0, 8000.0, 9000.0, 10000.0, 11200.0, 12500.0, 14100.0, 16000.0, 18000.0, 20000.0}; //value in HZ
//public final static double[] QArray = {0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0, 1.2, 1.4, 2.0, 2.5, 3.0, 4.0, 5.0, 6.5, 8.0}; //Q value
Click Here for a plain table of Index and Ranges
(Stereo Widener) – This unique algorithm delivers a wider, more immersive stereo field without sacrificing the original sound of a recording. This is for speaker systems only (not headphones).
int DPSGetStereoWidenEnabled()
– Get the status of Stereo Widener processing 0 = off. 1 = on.
void DPSSetStereoWidenEnabled(int enabled)
– Turn Stereo Widener on or off. 0 = off. 1 = on.
int DPSLoadStereoWidenProfile(char *fname)
– Load a bswt stereo widener profile. 0 = success, 1 = file doesn’t exist, 2 = invalid preset
int DPSLoadStereoWidenProfileBuf(char *c, int length)
– Load a bswt profile from memory. 0 = success, 1 = file doesn’t exist, 2 = invalid preset, //note that profiles are typically around .5kB in size
int DPSGetStereoWidenGain()
– Get the position of the stereo widening control. Use same gain array as set/get GKnob
void DPSSetStereoWidenGain(int gain)
– This is the user’s control over the stereo widening effect. Use GainArray from userEQs with an index range of 24 to 48.
This feature provides a virtual surround sound experience for headphones. Stereo content is mapped to pre-selected HRTF parameters for various popular use cases. As of DPS Core version 2.2.0, these presets are loaded via the bgvx profile (recommended).
void DPSGet/SetHeadphonesEnabled()
– Turn the Headphones effect on or off.
int DPSGet/SetHeadphonesMode(int mode)
– Choose from one of seven presets:
int int DPSGet/SetHeadphonesDelaySamples(int delay)
– This affects the stereo effect of the Headphones algorithm. The default of 4 samples is best for most applications. The allowed range is 3 to 13 samples. As of DPS Core 2.2.0, this function is deprecated.
NOTE: The effects of this algorithm are applied before the main DPS functions.
void DPS_PitchShifter_SetBypass(int bypass); int DPS_PitchShifter_GetBypass();
– Enable or bypass the pitch shifter
void DPS_PitchShifter_SetShift(float percent); //allowable range [.25,2.0]
– This sets pitch in percentage format
void DPS_PitchShifter_SetShift_Semitones(float semitones); //allowable range [-24,+12]
-This sets pitch in semitone format
float DPS_PitchShifter_GetShift(); float DPS_PitchShifter_GetShift_Semitones();
-This gets current pitch in percentage or semitone format
void DPS_PitchShifter_SetQuality(int quality); //0, 1, or 2 allowed int DPS_PitchShifter_GetQuality();
-Set or get the quality of the pitch shifter. 0 = low quality though it is quite good. 1 and 2 are higher quality for different types of source audio.
void DPSSetUserGain(float gain)
This functions scales the output volume of the audio by the single precision floating point argument. Calculate the decibel value using (10*Math.log10(Math.pow(value,2))). By passing a float to scale the audio, you have the ability to create your own volume curve to suit your application.
For example, the GainArray used in the User Bass/Treble function creates a series of decibel values in 0.5dB increments. However, a proper User Volume Control should replace the master volume control of a device. This means the range of your volume control should be -infinity(mute) to 0dB. While you may scale the volume above 0dB this is not recommended as most profiles will incur distortion.
float DPSGetUserGain()
Returns the current User Volume setting.
DPS HEAR (formerly called KidSafe) is a slight modification to the Bongiovi DPS processing that delivers clear, crisp audio for headphones while maintaining a healthy listening volume. Click Here to learn more.
int DPSGetKidSafe();
Get the status of DPS HEAR. 1 = on, 0 = off.
void DPSSetKidSafe(int enabled);
Use enabled = 1 to turn DPS HEAR on. Use enabled = 0 to turn off DPS HEAR.