VBLOCKS-2030 | API stubs and error checking

lib/twilio.ts

@@ -2,10 +2,11 @@
  * @packageDocumentation
  * @internalapi
  */
+import AudioProcessor from './twilio/audioprocessor';
 import Call from './twilio/call';
 import Device from './twilio/device';
 import * as TwilioError from './twilio/errors';
 import { Logger } from './twilio/log';
 import { PreflightTest } from './twilio/preflight/preflight';
 
-export { Call, Device, PreflightTest, Logger, TwilioError };
+export { AudioProcessor, Call, Device, PreflightTest, Logger, TwilioError };

lib/twilio/audiohelper.ts

@@ -3,6 +3,7 @@
  * @module Voice
  */
 import { EventEmitter } from 'events';
+import AudioProcessor from './audioprocessor';
 import Device from './device';
 import { InvalidArgumentError, NotSupportedError } from './errors';
 import Log from './log';
@@ -147,6 +148,11 @@ class AudioHelper extends EventEmitter {
    */
   private _onActiveInputChanged: (stream: MediaStream | null) => Promise<void>;
 
+  /**
+   * Internal reference to the added AudioProcessor
+   */
+  private _processor: AudioProcessor | null;
+
   /**
    * A record of unknown devices (Devices without labels)
    */
@@ -342,6 +348,35 @@ class AudioHelper extends EventEmitter {
     });
   }
 
+  /**
+   * Adds an {@link AudioProcessor}. If an {@link AudioProcessor} exists in the
+   * {@link AudioHelper}, the {@link AudioHelper} routes the input audio stream
+   * to the {@link AudioProcessor}.
+   *
+   * The {@link AudioHelper} guarantees that this audio stream is always
+   * the active input audio stream and will automatically
+   * update whenever the user's preference changes.
+   *
+   * Only one {@link AudioProcessor} can be added at this time.
+   * @param processor
+   */
+  addProcessor(processor: AudioProcessor): void {
+    if (this._processor) {
+      throw new NotSupportedError('Adding multiple AudioProcessors is not supported at this time.');
+    }
+
+    if (!processor) {
+      throw new InvalidArgumentError('Missing AudioProcessor argument.');
+    }
+
+    if (typeof processor.createProcessedStream !== 'function' ||
+    typeof processor.destroyProcessedStream !== 'function') {
+      throw new InvalidArgumentError('Missing createProcessedStream or destroyProcessedStream.');
+    }
+
+    this._processor = processor;
+  }
+
   /**
    * Enable or disable the disconnect sound.
    * @param doEnable Passing `true` will enable the sound and `false` will disable the sound.
@@ -372,6 +407,18 @@ class AudioHelper extends EventEmitter {
     return this._maybeEnableSound(Device.SoundName.Outgoing, doEnable);
   }
 
+  /**
+   * Removes an AudioProcessor.
+   * @param processor
+   */
+  removeProcessor(processor: AudioProcessor): void {
+    if (this._processor !== processor) {
+      throw new InvalidArgumentError('Cannot remove an AudioProcessor that has not been previously added.');
+    }
+
+    this._processor = null;
+  }
+
   /**
    * Set the MediaTrackConstraints to be applied on every getUserMedia call for new input
    * device audio. Any deviceId specified here will be ignored. Instead, device IDs should

lib/twilio/audioprocessor.ts

@@ -0,0 +1,34 @@
+/**
+ * @packageDocumentation
+ * @module Voice
+ */
+
+/**
+ * Represents an AudioProcessor object that receives an audio stream for processing.
+ * @publicapi
+ */
+interface AudioProcessor {
+  /**
+   * Called whenever the active input audio stream is updated
+   * and is ready for processing such as adding audio filters
+   * or removing background noise.
+   * Use this method to initiate your audio processing pipeline.
+   *
+   * @param stream The input audio stream.
+   * @returns The modified input audio stream after applying filters.
+   */
+  createProcessedStream(stream: MediaStream): Promise<MediaStream>;
+
+  /**
+   * Called after the processed stream has been destroyed.
+   * This happens whenever the current input stream is updated.
+   * Use this method to run any necessary teardown routines
+   * needed by your audio processing pipeline.
+   *
+   * @param stream The torn down processed audio stream.
+   * @returns
+   */
+  destroyProcessedStream(stream: MediaStream): Promise<void>;
+}
+
+export default AudioProcessor;