API Version: 6.4

Reference

/

Classes

/

IPCortex.Types.Av

   
  • IPCortex.Types.Av
  • Description
  • Prerequisites
  • AV chat model
  • Getting hold of the remote audio and video
  • Properties
  • Methods
  • av.accept
  • av.reject
  • av.merge
  • av.addStream
  • av.removeStreamByID
  • av.removeStream
  • av.mute
  • av.addListener
  • av.removeListener
  • av.close
  • Events

    • IPCortex.Types.Av

    The AV Class, used by chat add-on features

    Description

    Prerequisites

    • Load the api.js and adapter.js (or use api/wrapper_av.whtm helper)
    • Log in as a user with sufficient access
    • Start chat with enableChat()
    • Enable the AV feature with enableFeature()

    AV chat model

    • An AV (Audio and/or Video) call takes place within a chat room. The room and the AV conversation are independent, so while you need to be in the room to join the AV chat, not being in the AV chat will not eject you from the room.
    • In theory, it is possible to have multiple AV sessions (Av objects) running simultaneously. In practice, it is more usual to merge the 2nd or subsequent AV chat into a running one.
    • The first person to request a chat calls Room.videoChat(media) where media is the browser streams for their camera and/or microphone (see navigator.mediaDevices.getUserMedia() ). This returns an Av class object for the AV session.
    • All other chat room members will receive a callback (provided when calling enableFeature()) whith an Av class object for the AV session. They may then call av.accept(media), av.reject() or av.merge(oldAv), in order to accept, reject or cause the merge of the av into an existing conversation.
    • Upon joining a chat room, if an existing chat is in progress, and if this feature has been enabled, the new member will immediately be sent a new-session callback, which can be accepted or rejected as required.
    • An Av object becomes invalid and is destroyed when the last peson leaves
    • An Av object becomes invalid and is destroyed if you leave it or reject it.
    • If in a room with an existing AV session that has not been joined, calling Room.videoChat(media) and having an existing member respond with av.merge(oldAv) will allow a member to join later.

    Getting hold of the remote audio and video

    • Upon receiving an Av session object, it is necessary to add a listener for the 'update' event, and optionally the 'media' event
    • If needed, use the av.signalling property to get a reference to the roomn the AV session is running in.
    • On each 'update' event, av.remoteMedia can be read which will represent the current state of all remote media (see below)
    • On each 'media' event, av.remoteMedia can be read which will represent only the media that has changed. (see below)
    • When reading av.remoteMedia, a negative numbered id indicates that there is no incoming media for an endpoint that jas joined the AV session. Any other entries may be treated as browser MediaStream objects.
    • Browsers do not reliably/consistently implement the MediaStream interface, so a status attribute is provided by the AV layer. It will typically progress through connecting, connected and then to closed, timeout or error.
    TODO: Need a picture here.

    Properties

    Name Type Description
    name String The initiators name.
    id String Unique identifer.
    signalling Class Usually a Room - This contains a reference to the signalling layer used to set up the Av
    localMedia Object Object of local mediaStream keyed by stream id.
    remoteMedia Object Object containing remoteStream(s) keyed by stream id. IMPORTANT:
    • The key (stream id) will be one of two types of value
    • A string that appears to be a negative number eg. "-123" - This indicates that the media connection exists, but the remote end it providing no AV media streams - It is just a placeholder, and not a real media object.
    • A long random string which is the browser internal media id. This occurs when media is being provided by the remote end.
    • Additionally if a remoteMedia entry switches between a with-media and without-media state because streams are added or removed by the originator, then the stream id will change
    • Depending on whether a browser supports adding and removing streams to a connection, there may ba multiple remoteMedia objects per remote party; There will only ever be a single negative-number entry for each endpoint, and it will by definition always be stand-alone as if media starts to arrive it is replaced.

      • Object remoteMedia

      Name Type Description
      cN String Friendly name of the media owner.
      cid Number Contact ID of the media owner.
      status String Connected state of the media.
      active Boolean false if this stream is dead.
      NOTE: Other fields will be available, but vary based on browser type and media stream implementation.
    party String Av party.
    • callee
    • caller
    state String Av state.
    • unknown - Newly created. Should be transient.
    • offered - Initiated here.
    • acknowledged - Initiated elsewhere but not accpted here.
    • accepted - Accepted here.
    • rejected - Rejected here.
    • connecting - Connections progressing (do not rely on seeing this).
    • connected - Connection is "up".
    • timeout - Timeout with no responses, or protocol timeout.
    • error - Protocol error.
    • closed - Closed, or all parties left.
      • If the state is one of timeout error rejected or closed then the Av object will be destroyed after this callback and should not be used again.
    type String Av type.
    • audio
    • video
    • screen

    Methods

    av.accept([stream])

    Kind: class method of IPCortex.Types.Av
    Accept the request to exchange media. Optionally include a mediaSteam to add to conversation.
    Parameter Type Description
    stream mediaStream (Optional) mediaStream from getUserMedia()

    av.reject()

    Kind: class method of IPCortex.Types.Av
    Reject the request to exchange media.

    av.merge(av)

    Kind: class method of IPCortex.Types.Av
    Generally a Room will support only one Av session at a time. If a participant in a room sends a new Av request, it may be desirable to 'merge' their request with the existing Av session. This is done by calling merge() instead of accept() or reject(). The single parameter is the Av session object that is to be merged with.
    Parameter Type Description
    av Av Av to merge request into

    av.addStream(stream)

    Kind: class method of IPCortex.Types.Av
    Add a media stream to the av.
    Parameter Type Description
    stream mediaStream mediaStream from getUserMedia()

    av.removeStreamByID()

    Kind: class method of IPCortex.Types.Av
    NOTE: Not yet implemented. This is a placeholder.

    av.removeStream(stream)

    Kind: class method of IPCortex.Types.Av
    Remove a media stream from the av.
    Parameter Type Description
    stream mediaStream mediaStream from getUserMedia()

    av.mute(tracks, [id])

    Kind: class method of IPCortex.Types.Av
    Mute or un-mute a local media stream.
    Parameter Type Description
    tracks Object {audio: Boolean, video: Boolean}
    id String Unique track id, or null for all tracks.
    NOTE: If required, the track id for the optional 2nd parameter can be retireved from the MediaStream by using MediaStrem.getTracks(), MediaStrem.getAudioTracks() or MediaStrem.getVideoTracks().

    av.addListener(event, callback)

    Kind: class method of IPCortex.Types.Av
    Add listener method, inherited from Api base class and common to all classes.
    Parameter Type Description
    event String Name of event, e.g. 'update'
    callback Function Callback which is passed a reference to the updated Class object

    av.removeListener(event, callback)

    Kind: class method of IPCortex.Types.Av
    Remove listener method, inherited from Api base class and common to all classes. event and callback must be identical to those used in addListener() in order for the remove to succeed.
    Parameter Type Description
    event String Name of event, e.g. 'update'
    callback Function Callback which is passed a reference to the updated Class object

    av.close()

    Kind: class method of IPCortex.Types.Av
    Close the connection(s) and destroy the object.

    Events

    • new - A new av is created.
    • update - The av state changes.
    • media - The remoteMedia object has changed, ie. a new offer, connected or closed id exists. IMPORTANT reading Av.remoteMedia (see above) during a media callback event results in a changes-only view of the media. Reading Av.remoteMedia outside of a meida callback, will return all id entries regardless of state.