Session description refactor

[egreenmachine]

Session Description Refactor

This is a pretty big code refactor in an attempt to simplify SIP.js and the handling of SDP and media. The idea is that SIP.js should be more strictly a signaling library, and not get involved in the handling of the actual media. Handling the media will be the responsibility of the end application. That being said, some of the simplicity of getting up and running with SIP.js has been removed. I am hoping to write a cover library that really makes getting up and running very simple, and then having users who want more control come and use SIP.js directly. With all that being said, let me outline the changes.

hacks.js

hacks.js and all the functions within have been removed. These all seemed to be related to old browser problems and SDP manipulation. The idea was that we could use it as a reference to see which browsers were working as closely to intended behavior as possible. The reality of it was, that once something was added, it was almost never removed. Some hacks never made it into this file. And it was not signaling related, but SDP in almost all cases. There is a new way to do SDP manipulation which will be outlined later.

environment.js

The deprecation of environment.js. The idea with the environment was to essentially act a shim. It had a list of things that any environment running SIP.js had to implement, and then SIP.js would work as expected. The reality is that it caused more trouble than it solved. It required some things that only the browsers implemented and were not actually required for the library to function, like functions required by the media handler. I have started the process of removing everything from here and the hope moving forward is to offer up a different library that acts a better shim in the future.

Session Description Handler

The change of MediaHandler to SessionDescriptionHandler. This is the big one, and it starts with the name. The name MediaHandler does not accurately describe what is actually being handled. SIP.js does not want to handle media directly, that is what WebRTC is for. We want to handle the signaling. The new SessionDescriptionHandler will attempt to do just that, it will set up the PeerConnection and signal that is has done so. The application will then be responsible for doing what it wants with the media, similar to how the application is responsible for implementing it's own user interface.
The mute and unmute options are no longer available on a session.

Example of media handling in application

session.on('accepted', function() {
    var streams = session.sessionDescriptionHandler.peerConnection.getRemoteStreams();
    var remoteElem = document.getElementById('remoteAudio');
    remoteElem.srcObject = streams[0];
    remoteElem.play();
});

SDP Modifiers

The next thing that has changed with the Session Description Handler is the mangling of SDP. We have come up with a scalable way to modify SDP before passing it to the PeerConnection and after receiving it from the PeerConnection. These are SDP modifiers. An SDP modifier function is simply a function that takes SDP and returns a promise which resolves with the modified SDP. The session description handler then runs through this array in order passing the result of the previous manipulation to the next function. Currently getting these modifiers into the session description handler is a bit fickle, but I hope to make this process easier over time.

Hold

Hold is now done by just defining a holdModifier on the session description handler. When the hold function on the session is called, the session simply calls getDescription from the handler and passes it the holdModifier to mangle the sdp appropriately.

Renegotiation

Renegotiation now works correctly. This is tested in Chrome (59+) and Firefox (54+). There is no longer any fake hold being done with the media streams.

Creating your own handler

Just implement the functions in the outline below, wrap it in a factory. That is it. No need to deal with rendering, or muting, etc. That is for the application to worry about.

SessionDescriptionHandler.prototype = Object.create(EventEmitter.prototype, {

  close: {value: function close () {}},

  /**
   * @param {Object} [mediaHint] A custom object describing the media to be used during this session.
   */
  getDescription: {value: function getDescription (constraints, modifier) {
    // keep jshint happy
    constraints = constraints;
    modifier = modifier;
  }},

  /**
   * Check if a SIP message contains a session description.
   * @param {SIP.SIPMessage} message
   * @returns {boolean}
   */
  hasSessionDescription: {value: function hasSessionDescription (contentType) {
    // keep jshint happy
    contentType = contentType;
  }},

  /**
   * Set the session description contained in a SIP message.
   * @param {SIP.SIPMessage} message
   * @returns {Promise}
   */
  setDescription: {value: function setDescription (sessionDescription, constraints, modifier) {
    // keep jshint happy
    sessionDescription = sessionDescription;
    constraints = constraints;
    modifier = modifier;
  }},

  holdModifier: {value: function holdModifier(sdp) {
    return SIP.Utils.Promise.resolve(sdp);
 }}
});

Session Description Handler Options

These options should now all be contained within a single key on the UA configuration. Validation is still done on UA side, but it should change in the future to be done on the SessionDescriptionHandler itself.

Removing WebRTC Dependencies

All WebRTC dependencies should be included in the default session description handler provided by SIP.js. The goal here is to allow SIP.js to run in environments that do not have WebRTC by simply overriding the default sessionDescriptionHandlerFactory. This can be done even with compiled versions of SIP.js by just passing the new factory as a UA parameter. There are no longer any mysteries of isReady() or needing to call WebRTC functions to get SIP.js to run.

TODO's

There are a few remaining items left to do.

1. Documentation. Documentation. Documentation. Lots of new documentation needs to be written and old documentation cleaned up.
2. Tests. A lot of unit tests weren't actually testing units, and did not apply once the old media handler stuff was removed.
3. Bug fixes and edge cases. There are definitely some things not working with this, refer is one that jumps to mind that is most likely broken.
4. Finish cleaning up the environment
5. Clean up passing of arguments to the sessionDescriptionHandler and make that consistent.
6. Clean up other issues and PR's that are resolved by this.

Lastly, I would like for this pull request to become SIP.js 0.8.0 release. I expect there are definitely some things that I have missed and some bugs in my code. I encourage the community to try it out and give me your feedback. I am sure a few more commits will make it on to this branch before we merge and release.

[egreenmachine]

This could mess up the underlying WebRTC library if the constraints argument passed to getDescription is an empty object.

[egreenmachine]

I have made the SessionDescriptionHandler a bit more flexible by changing the constraints passed to it via getDescription and setDescription to a property on an options object. The options could be any object you like, so that using your SessionDescriptionHandler can just handle it as it needs to. If you want to use constraints you can, but you are not required to.

On the default WebRTC SessionDescriptionHandler you can redefine the PeerConnection by passing the peerConnectionOptions property to the options of a set/getDescription call. This would be passed down all the way from the application layer functions. This is to not break #260 and #250.

I have also separated the options passed by the UA to the SessionDescriptionHandlerFactory as it's own set of options. This is separate from the options held onto by the session to pass to set/getDescription. Again, this just adds some extra flexibility.

Lastly, the UA will now only check to see that the options for the SessionDescriptionHandlerFactory is an object. It is up to the handler itself to verify these options for itself. As a note here iceServers and turnServers no longer have their own place on the UA options and should instead be defined to the spec of the SessionDescriptionHandler. In the default case this is the WebRTC spec for RTCConfiguration.

[egreenmachine]

Hmmmm... it is not immediately clear to me how removing this return breaks all of our tests.

[egreenmachine]

It is in the test cleanup and how we are cleaning up the UA that is causing the tests to break. We are blindly calling unregister in places, and expecting it to return out of the function if it is not registered.

The issue is, that it is valid to send an unregister even if you are not registered. There are cases where you would want to do this. Either we need to re-write the tests, and confirm that we are not breaking anything. Or we need to keep the current behavior and add some extra behavior to allow this to continue in certain situations.

[egreenmachine]

Just wanted to make note of the following open issues/PRs that would be affected and potentially closed once this PR is complete:
#427 #407 #406 #393 #349 #337 #326 #300 #275 #249 #242 #228 #182 #138 #75 #7 #259

[egreenmachine]

Need to stop using promisify as it breaks Safari

[vadirn]

what about providing already acquired mediastream?

[egreenmachine]

You will need to write your own sessionDescriptionHandler to handle that. It is not something we want to deal with on the default implementation.

[falconsapsan]

i came here with problem sipwise/rtpengine#393
I looked this branch, but i got error..

Google Chrome | 59.0.3071.86  (64 bit)
sip.invitecontext.sessionDescriptionHandler | unable to acquire streams
NavigatorUserMediaError {name: "DevicesNotFoundError", message: "", constraintName: ""}

In Firefox 52.0.2 (32-bit)
TypeError: window.navigator.getUserMedia is not a function

After update Firefox to 52.0.3
sip.invitecontext.sessionDescriptionHandler | unable to acquire streams

If i use master branch - i'm don't got this errors

[egreenmachine]

@falconsapsan,

Your browsers are a bit out of date. Chrome should be 60+, and FF is 55+. This branch definitely will not work on your version of Firefox.

That being said, it appears that Chrome cannot access your media devices. Could you provide a gist of more detailed logging after updating your browsers?

[falconsapsan]

Chorme 61.0.3163.79, (64 bit)
https://gist.github.com/vectorcode/b932ac9ad76c9e7630e849093abf1e07

[egreenmachine]

@falconsapsan

In your UA configuration can you try adding the following

sessionDescriptionHandlerFactoryOptions: {
  constraints: {
    audio: true,
    video: false
  }
}

[egreenmachine]

Simple

So I have added a Simple layer. For now, I am providing documentation here. Eventually it will need to be added to the readme and website.

What is Simple?

Simple is a layer of abstraction on top SIP.js that aims to get new users up and running with SIP.js as quickly and easily as possible. It can make and receive calls, while updating a UI. It is only for use in a browser with WebRTC. Currently it only allows for a single call to happen at any given time.

API

Constructor

var simple = new SIP.WebRTC.Simple(options);

options

At least one remote media element is required.

{
  media: {
    remote: {
      audio: <DOM element>,
      video: <DOM element>
    },
    local: {
      video: <DOM element>
    }
  },
  ua: {
    wsServers: <WebSocket Server>,
    uri: <SIP URI>,
    authorizationUser: <SIP Auth User>,
    password: <SIP Password>
  }
}

Methods

call

Start a new call to the uri provided.

simple.call('hello@onsip.com');

answer

Answer an incoming call that is ringing.

simple.answer();

hangup

Hangup a call.

simple.hangup();

mute

Mute the local media of a call.

simple.mute();

unmute

Unmute the local mdia of a call.

simple.unmute();

hold

Place a call on hold and mute the local media.

simple.hold();

unhold

Take a call off hold and unmute the local media.

simple.unhold();

sendDTMF

Send a DTMF event via SIP Message

simple.sendDTMF('1');

Events

Events are emitted the same in both incoming and outgoing calls.

registered

Emitted when the UA registers.

unregistered

Emitted when the UA unregisters.

new

Emitted when there is a new call. Before a progress message is sent or received.

connecting

Emitted once a progress message is sent or received.

connected

Emitted when the call is connected.

ended

Emitted when the call is completed, either from a hangup or an error.

hold

Emitted when a call is placed on hold or you place a call on hold.

unhold

Emitted when a call is taken off hold.

mute

Emitted when the mute function is called.

unmute

Emitted when the unmute function is called.

dtmf

Emitted when a SIP DTMF message is received

States

Simple has 5 states that it can be in at any given time. The states will always flow in a single direction from STATUS_NEW to STATUS_COMPLETED. For example you cannot go from STATUS_CONNECTED to STATUS_CONNECTING, but you could go directly from STATUS_CONNECTING to STATEUS_COMPLETED. Once you are in STATUS_COMPLETED you can transition back to STATUS_NEW.

STATUS_NULL

A blank state for when Simple is instantiated.

STATUS_NEW

A new call has been initialized.

STATUS_CONNECTING

The call is setting up, but is not yet finalized.

STATUS_CONNECTED

The call is now connected and media is flowing.

STATUS_COMPLETED

The call is completed.

[falconsapsan]

        let options =  {
            media: {
                remote: {
                    audio: document.getElementById('audio'),
                    video: ''
                },
                local: {
                    video: ''
                }
            },
            ua: {
                traceSip: false,
                displayName: 'Meee',
                uri: '103@1.sips.me',
                wsServers: ['wss://1.sips.me:7443'],
                authorizationUser: '',
                password: 'хххххххх',
                sessionDescriptionHandlerFactoryOptions: {
                    constraints: {
                        audio: true,
                        video: false
                    },
                    rtcConfiguration: {
                        rtcpMuxPolicy: 'negotiate'
                    },
                }
            }
        }
        this.userAgent = new SIP.WebRTC.Simple(options);

make call..
this.userAgent.call('1003@1.sips.me');

try Hold
this.userAgent.hold();
try unHold
this.userAgent.unhold();
103 don't hear 1003
103 - Google Chrome | 61.0.3163.91
1003 - PhonerLite user

Browser console - https://gist.github.com/falconsapsan/b230856a34c500da6d3111c25a39add7

[egreenmachine]

@falconsapsan I cannot reproduce. Can you check that your media server is behaving as expected?

[egreenmachine]

Some notes on Safari (as of Tech Preview Release 39)

The media devices are chosen as the system defaults. The user has no option when allowing media to choose a different set of devices, like in Chrome or Firefox.

Safari does not allow the auto-playing of a media element from an async javascript function. The play function must be called from a synchronous user action. This is a bit annoying, but to get around it you can set the autoplay attribute on the media element that you are trying to do. This is pretty well documented as a Safari 'quirk' and documentation around the internet on this is pretty good.

On my Late 2016 MacBook Pro, when Safari requests the microphone it puts the internal microphone in 4-channel 24-bit audio mode. Why does it need this many channels? I could not say. However Firefox cannot handle the internal Macbook Pro microphone being in this mode. The error message that it spits out is extremely vague at best.

MediaStreamError { name: "NotReadableError", message: "Failed to allocate audiosource", constraint: "", stack: "" }

The way to fix this is to go into Applications > Utilities > Audio Midi Setup and choose the Built-in Microphone from the left panel. Then under format change it to 2 ch. Firefox will then work again, but if you use Safari again it will switch it back on it's own. I imagine that this will frustrate a lot of Macbook owners, but I have not tested other Mac models.

[egreenmachine]

Assuming that there are no glaring issues, I am starting on documentation with the expectation to merge this and do a version bump first thing tomorrow.