Tutorial: Getting Started

Getting Started

tutorial

Setup

MDPS requires the WebRTC adapter, AES for licensing support and the two MDPS JS files, as follows:

<script src="https://webrtc.github.io/adapter/adapter-latest.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.2/rollups/aes.js"></script>
<script src="mdps/mdpsasm.js"></script>
<script src="mdps/mdpslib.js"></script>

File Structure

The following describes the directory structure that will reside on the server and provides the MDPS support.

mdps
│   mdpsasm.js       // the mdps core library
│   mdpslib.js       // the mdps API library
|   license.key      // the license file    
│
└───config           // the configuration directory
|       configfiles  // list of all config files
|       presetfiles  // list of all preset files
│       abc.cfg      // config files
|       def.cfg
│       123.bgvx     // preset files
|       456.bgvx
│   
└───docs             // the documentation directory

Licensing

A license file is required to use the MDPS API and is tied to the domain(s) of the server(s). This file resides in the mdps sub-folder on the server. Contact Bongiovi Medical for more details.

Configuration

Configuration is specified via a .cfg file, along with an API for loading the .cfg files. The configuration is specified as a JavaScript dictionary, ala:

config = {
  presetFile: 'desktop_speakers.bgvx',
  userGain: 0,                  // -10.0 - 4.0 db
  noiseGateEnabled: 1,          // 0 or 1
  noiseGateThreshold: 0.5,      // 0.0 to 0.9
  noiseGateRelease: 0.999,      // 0.99097 - 0.99981
  noiseGateHold: 80,            // 0 - 99
  noiseGateFloor: 0.1,          // 0.09999 - 0.89125
  noiseGateHyst: 1,             // 1.0 - 2.0
  commFrequency: 0.08,          // 0.020 - 0.2 sec
  unmuteDelay: 0.5,             // 0.0 - 3.0 sec
  micAtten: 0.0,                // 0.0 - 1.0
  muteRampDuration: 0.2         // 0.003 - 0.3 sec (3 to 300 ms) 
}

Notice that it also specifies a bgvx file. Both the config and bgvx reside on the server in the mdps/config sub-folder. The API also provides a way to get a list of available config and bgvx files - this list is maintained in two files within that same folder and list the corresponding files. The two files are named configfiles and presetfiles.

API Usage

Core

At the most basic level, you can make full use of MDPS through 4 API calls:

MDPSInitialize();
MDPSSetMicStream(stream);
MDPSSetSpeakerStream(event.stream);
MDPSSetupDataChannel(peerConnection, isCaller);

MDPSSetMicStream should be called with the result of a MediaDevices.getUserMedia() call. MDPSSetSpeakerStream is called from the result of RTCPeerConnection's onaddstream callback. MDPSSetupDataChannel is used to setup the WebRTC data channels needed to communicate state information between peers, for features like smart microphone attenuation.

This set of calls, along with proper configuration of the RTCPeerConnection, will provide basic peer-to-peer, WebRTC-based audio communications with MDPS processing and smart microphone attenuation. See the MDPS Demo sample code for a full implementation.

Beyond these basic calls, there is API to modify the MDPS settings for the noise gate (microphone signal) and general audio processing (speaker signal), a logging facility, a callback API for receiving relevant notifications, API for managing config and settings files, an API for managing the push-to-talk feature, and a low-level processing API.

Settings

The settings API is broken up into 3 sections:

  • State - API for changing the current state or performance settings of the system.
  • Processing - API for changing the processing parameters.
  • NoiseGate - API for changing the noise gate parameters.

Logging

The logging API allows for the specification of the logging level and a log function. There are different levels defined for logging, such that messages will only get logged if they are of at least the current log level.

Callbacks

The system provides for the specification of callback functions in order to be notified of relevant events and information, such as mic attenuation/mute states, push-to-talk state changes, diagnostic information and parameter changes.

Configuration files

As noted above, configuration files are maintained on the server. There are several API functions for managing and loading these files.

Push-to-talk

Push-to-talk is a feature that allows for half-duplex communication mode, meaning one side has exclusive one-way communication rights. API functions are provided in order to explicitly enter and exit this mode.

Processing

The core API is provided for handling mic and speaker audio processing at a high level. There are also a number of routines for handling lower level processing. This allows for processing audio at the sample level, independent of WebRTC support.