API Overview

Utility Functions

License

All new instances of DPS are created in 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.

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.

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 be faded out when muting and faded 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.

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 RangeDecibelsScalar Float
Min-60dB0.001
Max0dB1.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. 

RangeDecibelsScalar Float
Min-10dB0.31622776601683794
Neutral0dB1.0
Max+10dB3.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.

RangeDecibelsScalar Float
Min-10dB0.31622776601683794
Neutral0dB1.0
Max+10dB3.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:

RangeTone APIBand Output Gain (-3dB)
Min-10dB-13dB
Neutral0dB-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 RangeDecibelsScalar Float
Min-10dB0.31622776601683794
No Effect0dB1.0
Max+10dB3.1622776601683795
Bass Frequency RangeHertzNote
Min50Lowest usable frequency
Normal150Good default
Max500Highest usable frequency
Treble Frequency RangeHertzNote
Min500Lowest usable frequency
Normal5000Good default
Max10000Highest usable frequency
Q Value RangeQ ValueNote
Min0.4Wide bell
Normal1.0Standard bell
Max3.0Narrow 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 RangeDecibelsScalar Float
Min0dB1.0
Max+10dB3.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 RangeDecibelsScalar Float
Min-60dB0.001
Normal0dB1.0
Max+12dB3.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 RangeDecibelsScalar Float
Min-60dB0.001
Normal0dB1.0
Max+12dB3.9810717055349722

get/setVSubEnabled

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 RangeDecibelsScalar FloatNote
Min-99dB0.00001122018454301963Gate will open for all signals
Default-60dB0.001Gate will open for quiet signals
Max0dB1.0Gate 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 RangeHertzNote
Min20Lowest usable frequency
Max20000Highest 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 rangeQNote
Min0.1Widest possible bell
Max20Narrowest 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 RangeDecibelsScalar Float
Min-15dB0.17782794100389226
Normal0dB1.0
Max+15dB5.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.

RangeDecibelsScalar Float
Mute-infinity0.0
Min-40dB0.01
Max0dB1.0

get/setKaraokeReverbGain

Set the level of the reverb mixed with the original signal.

RangeDecibelsScalar Float
Mute-infinity0.0
Min-40dB0.01
Max0dB1.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.

RangeDecibelsScalar Float
Mute-infinity0.0
Min-40dB0.01
Max0dB1.0

loadKaraokePreset

Select one of the pre-configured effect presets (takes 0 based index):

  1. 0 – Smooth Ballad
  2. 1 – Springs
  3. 2 – Small Room
  4. 3 – Echo Plate
  5. 4 – Mama Robot
  6. 5 – Epic Cave
  7. 6 – Baby Robot
  8. 7 – Daddy Robot
  9. 8 – Ambient Slap
  10. 9 – Dark Hallway
  11. 10 – Small Temple
  12. 11 – Long Echo
  13. 12 – Short Echo
  14. 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.
Was this page helpful?