Add mediaStreamSet event

Author: tylerlong

README.md

@@ -584,12 +584,12 @@ callSession.on("disposed", () => {
 
 ### CallSession Events
 
-### `answered` event
+#### `answered` event
 
 - Triggered when the call is answered.
 - Note: There is a [known issue](#known-issue) affecting outbound calls.
 
-### `disposed` event
+#### `disposed` event
 
 - For answered calls, this event is triggered when either you or the remote peer
   hangs up.
@@ -598,7 +598,7 @@ callSession.on("disposed", () => {
 - For outbound calls, if call failed (for example, invalid callee number), it
   will be disposed automatically. So, this event will be triggered.
 
-### `failed` event
+#### `failed` event
 
 - This is for outbound call only. It means the outbound call was not successful
 - It may be caused by invalid target number
@@ -643,6 +643,22 @@ if (callSession.state === "failed" || callSession.state === "disposed") {
 Failed call sessions will be disposed automatically, so the state will become
 "disposed". "failed" is just a temporary state.
 
+#### `mediaStreamSet` event
+
+This is triggered when `callSession.mediaStream` is set. An interesting use case
+is to apply noise reduction to this object.
+
+```ts
+callSession.on("mediaStreamSet", (mediaStream) => {
+  console.log("a new mediaStream object is set");
+});
+```
+
+When you make an outbound call: `const callSession = await webPhone.call(...)`,
+at the time that you get the `callSession` object, `callSession.mediaStream` is
+already set. It would be too late to subscribe for `mediaStreamSet` event. In
+such case you can access `callSession.mediaStream` directly.
+
 #### Where is the `ringing` event?
 
 `ringing` event is implicit.

src/call-session/index.ts

@@ -33,7 +33,7 @@ class CallSession extends EventEmitter {
   public localPeer: string;
   public remotePeer: string;
   public rtcPeerConnection: RTCPeerConnection;
-  public mediaStream?: MediaStream;
+  public _mediaStream?: MediaStream;
   public audioElement: HTMLAudioElement;
   public state: "init" | "ringing" | "answered" | "disposed" | "failed" =
     "init";
@@ -49,6 +49,14 @@ class CallSession extends EventEmitter {
     this.webPhone = webPhone;
   }
 
+  public get mediaStream(): MediaStream | undefined {
+    return this._mediaStream;
+  }
+  public set mediaStream(stream: MediaStream) {
+    this._mediaStream = stream;
+    this.emit("mediaStreamSet", stream);
+  }
+
   // for inbound call, this.sipMessage?.headers["Call-Id"] will be the call id
   // for outbound call, this._callId will be the call id. Once the call session is out of "init" state, this.sipMessage will be set
   private _callId = uuid();
@@ -228,6 +236,7 @@ class CallSession extends EventEmitter {
     // note: we can't dispose the call session here
     // otherwise the caller will not be able to talk to the flip target
     // after the flip target answers the call, manually dispose the call session
+    // todo: review this part
     return flipResult;
   }