Utility Functions
PlatformInit
Call this first to initialize DPS audio processing modules on the platform.
License
DPS always initializes into demo mode. While in demo mode, audio will mute periodically. The license function is used to ingest a license file and application ID string (provided by Bongiovi) to disable demo mode. This is required once for each new process using the DPS library. All instances of DPS (in the current process) will exit demo mode when the license function returns true.
| License Authentication return values | |
| #define AUTH_SUCCESS 0 | |
| #define AUTH_ERR_INVALID_FILE_FORMAT 1 | |
| #define AUTH_ERR_LICENSE_HASH_INVALID 2 | |
| #define AUTH_ERR_JAVA_PACKAGE_INVALID 3 | |
| #define AUTH_ERR_RSA_DATA_INVALID 4 | |
| #define AUTH_ERR_AES_DATA_INVALID 5 | |
| #define AUTH_ERR_FILE_NOT_FOUND 6 | |
| #define AUTH_ERR_INVALID_ARGS 7 | |
| #define AUTH_ERR_INVALID_MODEL 8 | |
| #define AUTH_ERR_INVALID_MANUFACTURER 9 | |
| #define AUTH_ERR_BUNDLE_ID_INVALID 10 | |
| #define AUTH_ERR_APP_ID_INVALID 11 | |
| #define AUTH_ERR_LICENSE_EXPIRED 12 |
setLicenseKey
This method is provided for some embedded systems. Contact your Bongiovi representative for more information.
getLicenseStatus
Returns the license status. This is used to verify the platform is licensed and the audio will not periodically mute (demo mode).
setInstanceId
This assigns a virtual ID number to the current instance so it may be referenced later. Due to the C foundation of the code, a fixed number of instance “slots” are available. Creating a new instance will use one of these slots. Destroying an instance releases the slot. Virtual instance IDs are useful when creating and destroying streams/instances with a known purpose.
For example, a smart speaker (using the GStreamer framework) may require separate instances for Bluetooth audio, FFmpeg audio, and voice synthesis. The audio processing must be different for voice synthesis versus music playback. When a new voice synthesis stream is created, it should be assigned instance ID 0. When a Bluetooth stream is created, it is assigned ID 1, and so on. This allows audio controls and other processes to access the correct DPS instance for the purpose of changing volume, changing the audio profile, or muting the stream.
DpsProcess
Performs audio processing on the given buffer of samples.
- All instances of DPS processing may only be mono or stereo. When choosing the number of channels, only 1 or 2 is valid. If you must process more channels, create more instances.
- Optionally, a subwoofer channel can be generated from the mono or stereo source. Parameters for this function are set up in the Profile Creator tool.
- Click here for more information about software audio processing concepts.
start/stopListener
Starts a socket server on the given port. This allows remote control over audio processing via the DPS Communications API. Full control over sockets is supported in the Profile Creator.
mute/unmute
Mute or unmute the given instance. The audio will fade out when muting and fade in when unmuting.
getVersion
Get the current DPs core code version number.
parseByte
Parses a single byte for the DPS Communication API. This function handles all communication with the SDK from external processes. See Preset Management for more details.
setCommCallback
Set the pointer for the DPS Communication callback.
get/setEnabled
Enable or disable audio processing for the given instance. To prevent pops in the audio, the current stream is faded out, audio is muted while the state of processing is changed, then the audio is faded back in. The entire process takes about 200 milliseconds.
get/setSampleRate
Sets the sample rate of the audio stream. The sample rate parameter is used to calculate filter and non-linear time-related coefficients in the algorithm. Changing the sample rate will trigger a re-calculation of all coefficients. NOTE: This function does not resample the audio to a desired sample rate.
get/setAutomuteEnabled
“Auto Mute” prevents pops in the audio when changing profiles/presets. When Auto Mute is enabled, and a command is received to change presets, the audio stream will fade out, the parameters will change, and the audio will fade back in. This process will take ~200ms, depending on the platform. When Auto Mute is disabled, the parameter change will occur at the start of the next audio process frame.
Preset / Profile Loading
Click here to learn more about how parameter sets are handled
loadEmbeddedProfile
All dynamic DPS libraries or applications using static DPS libraries must include ProDef.c. This file contains 20 profiles (sets of DPS algorithm parameters) that may be loaded into any instance at any time. When a new instance is created, profile 0 is loaded by default. Use the loadEmbeddedProfile function to access profiles within ProDef.c in cases where a BGPS file may not be accessible.
loadProfileFromFile
Loads one of 20 profiles included in a BGPS file. Profiles within a BGPS file are set up in the Profile Creator’s Preset Manager feature.
loadProfileFromBuffer
If a BGPS file is not accessible via the file system, the BGPS binary data may be loaded into memory and accessed with this function.
User Controls
All DPS gain functions take scalar values.
Learn more about converting decibels to scalar values here
get/setUserGain
Controls the user-facing volume control for each instance. This important feature may be configured for pre-AGC (INPUT) operation for speaker protection or post-AGC (OUTPUT) operation for headphones. This volume control is smoothed to prevent noise during real-time operation.
| Gain Range | Decibels | Scalar Float |
| Min | -60dB | 0.001 |
| Max | 0dB | 1.0 |
setMasterVolume
Sets the UserGain for all instances. This is useful for multi-channel applications where all instances must be adjusted simultaneously. This will override the UserGain values set for individual instances.
get/setToneBassGain
This is a special audio tone control feature that works by adjusting the output of band 1 (lowest frequency) of the Multiband AGC. Typically this has the effect of a low shelf filter set to the lowest Multiband AGC crossover frequency.
| Range | Decibels | Scalar Float |
| Min | -10dB | 0.31622776601683794 |
| Neutral | 0dB | 1.0 |
| Max | +10dB | 3.1622776601683795 |
get/setToneTrebleGain
This is a special audio tone control feature that works by adjusting the output of the highest enabled band of the Multiband AGC. Typically this has the effect of a high shelf filter set to the highest Multiband AGC crossover frequency.
| Range | Decibels | Scalar Float |
| Min | -10dB | 0.31622776601683794 |
| Neutral | 0dB | 1.0 |
| Max | +10dB | 3.1622776601683795 |
Notes on Bass and Treble Tone Controls
The Multiband AGC allows for different non-linear algorithms to be selected for each band. To account for this, the Tone controls will set relative output gain values (in decibels) for each of the algorithm options selected for the highest and lowest bands. This assumes the profile was created with a “flat” frequency response. For example, if the highest band was set to Compressor mode and the output gain is set to -3dB, the effective ranges for the Treble control will be as follows:
| Range | Tone API | Band Output Gain (-3dB) |
| Min | -10dB | -13dB |
| Neutral | 0dB | -3dB |
| Max | +10dB | +7dB |
This method allows the Tone controls to work for any 2+ band Multiband AGC configuration.
get/setUserBass/Treble/Gain/Q/Freq
Adjusts 2 user-facing EQ bell filters. Standard parameters:
| Gain Range | Decibels | Scalar Float |
| Min | -10dB | 0.31622776601683794 |
| No Effect | 0dB | 1.0 |
| Max | +10dB | 3.1622776601683795 |
| Bass Frequency Range | Hertz | Note |
| Min | 50 | Lowest usable frequency |
| Normal | 150 | Good default |
| Max | 500 | Highest usable frequency |
| Treble Frequency Range | Hertz | Note |
| Min | 500 | Lowest usable frequency |
| Normal | 5000 | Good default |
| Max | 10000 | Highest usable frequency |
| Q Value Range | Q Value | Note |
| Min | 0.4 | Wide bell |
| Normal | 1.0 | Standard bell |
| Max | 3.0 | Narrow bell |
In most cases, Treble and Bass controls are presented with statically preset Q and Frequency values. The user only has control over the Gain values. Be sure to use setUserBass/TrebleEnabled to hear the effect.
get/setSensitivity
Sensitivity is a user-facing function to adjust the amount of overall dynamic range control applied to the signal. This control works by adjusting the Input and Output gains of the DPS algorithm. It assumes the Bongiovi AGC and Multiband AGC components are set to 2:1 compression ratios. Increasing Sensitivity increases the Input gain of the algorithm while decreasing the Output gain by ½ of the amount (in decibels) the Input gain is increased. The result is quiet sounds become louder while loud sounds remain the same volume.
| Gain Range | Decibels | Scalar Float |
| Min | 0dB | 1.0 |
| Max | +10dB | 3.1622776601683795 |
NOTE: This is a meta-control that simultaneously adjusts Input and Output gain. After setting Sensitivity, getInputGain and getOutputGain may be used to see the new values. Smoothing is applied to Input and Output gain parameters for real-time adjustment.
get/setInputGain
Set the Input gain level of the algorithm. This can be used as a volume control in some circumstances. However, it is normally used for calibration purposes.
| Gain Range | Decibels | Scalar Float |
| Min | -60dB | 0.001 |
| Normal | 0dB | 1.0 |
| Max | +12dB | 3.9810717055349722 |
get/setOutputGain
Set the Output gain level of the algorithm before the final limiter. This can be used as a volume control in some circumstances. However, it is normally used for calibration purposes.
| Gain Range | Decibels | Scalar Float |
| Min | -60dB | 0.001 |
| Normal | 0dB | 1.0 |
| Max | +12dB | 3.9810717055349722 |
get/setVSubEnabled
or
MultiBandVirtualBassSet/GetBypass
Enable or disable the Virtual Subwoofer™ algorithm. This provides a user-facing “bass boost” feature.
get/setNoiseGateEnabled
Enable or disable the Noise Gate.
get/setNoiseGateThreshold
Set the Noise Gate threshold. As a user-facing feature, this may be used to set the level of speech when reducing noise on a microphone signal.
| Gain Range | Decibels | Scalar Float | Note |
| Min | -99dB | 0.00001122018454301963 | Gate will open for all signals |
| Default | -60dB | 0.001 | Gate will open for quiet signals |
| Max | 0dB | 1.0 | Gate will open only for the loudest signals |
10 Band Parametric EQ
get/setEqEnabled
Enable or disable the given EQ band.
get/setEqFreq
Set the center frequency for the given EQ band. As a parametric EQ, all bands may be set to any valid frequency:
| Frequency Range | Hertz | Note |
| Min | 20 | Lowest usable frequency |
| Max | 20000 | Highest usable frequency |
get/setEqQval
Set the “Quality” (width of the bell filter) for the given EQ band. As a parametric EQ, all bands may be set to any valid Q value:
| Q value range | Q | Note |
| Min | 0.1 | Widest possible bell |
| Max | 20 | Narrowest possible bell |
NOTE: Due to the special lattice filter design of the DPS EQ, Q values for higher frequencies may result in wider than expected bell widths. While not normally required, this table describes the discrepancies relative to a standard biquad filter.
get/setEqGain
Set the gain value for the given EQ band. As a parametric EQ, all bands may be set to any valid Gain value:
| Gain Range | Decibels | Scalar Float |
| Min | -15dB | 0.17782794100389226 |
| Normal | 0dB | 1.0 |
| Max | +15dB | 5.623413251903491 |
Karaoke Effects
get/setKaraokeEnabled
Enable or disable the reverb and echo effects.
NOTE: When the global setEnabled function is used, reverb and echo are also affected.
get/setKaraokeDryGain
Set the level of the original signal.
| Range | Decibels | Scalar Float |
| Mute | -infinity | 0.0 |
| Min | -40dB | 0.01 |
| Max | 0dB | 1.0 |
get/setKaraokeReverbGain
Set the level of the reverb mixed with the original signal.
| Range | Decibels | Scalar Float |
| Mute | -infinity | 0.0 |
| Min | -40dB | 0.01 |
| Max | 0dB | 1.0 |
get/setKaraokeEchoGain
Set the level of the repeating echo effect.
NOTE: The echo uses feedback to create the repeating effect. Increasing the gain of the echo will increase the number of times the echo repeats. At maximum gain, the echo will repeat indefinitely.
| Range | Decibels | Scalar Float |
| Mute | -infinity | 0.0 |
| Min | -40dB | 0.01 |
| Max | 0dB | 1.0 |
loadKaraokePreset
Select one of the pre-configured effect presets (takes 0 based index):
- 0 – Smooth Ballad
- 1 – Springs
- 2 – Small Room
- 3 – Echo Plate
- 4 – Mama Robot
- 5 – Epic Cave
- 6 – Baby Robot
- 7 – Daddy Robot
- 8 – Ambient Slap
- 9 – Dark Hallway
- 10 – Small Temple
- 11 – Long Echo
- 12 – Short Echo
- 13 – Medium Echo
Block Commands
Each algorithm stores its parameters in C structs (blocks) as defined in CommDefs.h.
get/setAll (master block)
Used to get and set all algorithm parameters for the given instance. This is useful for saving/loading the state when creating/destroying instances.The master block includes:
- InputBlock
- OutputBlock
- UserBlock
- MetaBlock
- BagcBlock
- EQBlock
- NoiseGateBlock
- StereoWidenBlock
- MultiBandBlock
- OutputCompressorBlock
- KaraokeBlock
- FbxBlock
- PitchShiftBlock
- V3dBlock
get/set Individual Algorithm Blocks
The individual blocks are mainly used by the Profile Creator tool and the Communication API to provide real-time tuning functions during product development.
getMeters
Get an array of real-time meter data (in linear float audio levels) displayed in the Profile Creator tool. The array is defined as follows:
- FpData input[2];
- L/R input level
- FpData output[2];
- L/R output level
- FpData virtualBassGr;
- Level of dynamic bass boost
- FpData bagcOut[2];
- L/R Output level of the Bongiovi AGC algorithm
- FpData bagcGr[2];
- L/R gain reduction level of the Bongiovi AGC
- FpData userOut[2];
- L/R output of the User Controls algorithm block
- FpData specialOut[2];
- L/R utput of the Special Effects blocks (before EQ)
- FpData eqOut[2];
- L/R output level of the EQ
- FpData multiBandOut[2];
- L/R output of the Multiband AGC
- FpData multiBandBandGr[5];
- Gain reduction level for each of the 5 Multiband AGC bands.
- FpData multiBandBandOut[5];
- Mono (summed L/R) output level each of the 5 Multiband AGC bands.
- FpData stereoWideGr;
- Dynamic Stereo Enhancement meter.
- FpData outputLimiterGr;
- Gain reduction of the look-ahead output limiter.