MaxME Node Wrap

Introduction

This project is a wrapper of MaxME for support node based UI framework like Electron.js. For now , it's just tested with Electron V4.0. And we have no plan to support older versions.This module has been test on Windows and Macos, Linux must be fine too but have not test yet.

Quick Statrt

We just provide prebuilt for use, customs can not build this module by self.

Install

Under your Electron project directory, type this command to install this module:

npm i maxme-electron --save or yarn add maxme-electron

Usage

Type var maxme = require('maxme-electron') to import this module, and call maxme.engine({options}) to get the media engine. engine is the only one top level object, and have these child objets:

device
audio
video
desktop

The ditails for these object to see Reference.

Sometimes we want work with popular front-end framwork as react.js/vue.js, There are some advises —— import this module in html template under <script> section, then let it been gloabal so you can accese it in any .vue or .jsx file.

Developer can checkout our react-sample. In this sample, we provide a component named VideoRender. It make easily to integrate 'video preview'/'subscribe remote video' etc.

Reference

Return Values

All methods return an object result like this except constructor:

{
  errno: <Integer>,
  msg: <String>,
  [others]
}

Call a method, then check the errno equal 0 or not. If the errno equal 0 that means action is successed, or not failed.

engine

The constructor is require('maxme-electron').engine({options}), and this object is sigleton. It means bettwon one process, call this constructor more than one time will get the same object. But when you call this constructor in different process, will get deffferent object, and we adviced not to do so.

Options

The options include three field:

server -- The conference server to connect. Default is the cload server provide by MAXHUB.
metrics -- The server that to report metrics.
media -- Special media server that to prevent atomic dispatch.

These options just only used by test or develop, in productions, should keep default.

Properties

version [R] -- The version string.
commit [R] -- The commit id.
device [R] -- The device child object.
audio [R] -- The audio child object.
video [R] -- The video child object.
desktop [R] -- The desktop child object.

Methods

`auth(token, nick)`

Authenticate to conference server.

param	type	details
token	String	The access token.
nick	String	The display name.

The token&nick should get from oauth service with MAXHUB.

Return the singleton root object.

`deauth()`

Deauthenticate from confernece server.

`fastcallin()`

The fast way to create and join a conference.

If the return value's errno equal zero, it also include these fields:

uuid -- the conference's uuid.
no -- the number of confrence that other used to join.

`join(no)`

Join a conference by number of it.

param	type	details
no	String	The number of conference.

`leave()`

Leave if in a conference.

`kickout(uuid)`

Kick out other from current conference.

param	type	details
uuid	String	The uuid of conventioner that want to kicked out.

`dismiss()`

Dismiss current conference.

`cancelJoin()`

When joining, can call this method to cancel.

`transfer(uuid)`

Transfer master privilege to other.

param	type	details
uuid	String	The uuid of conventioner that want to make mster.

`turn(view)`

Turn to video/desktop view.

param	type	details
view	(0, 1, 2)	0 means video, 1 means desktop, 2 means wihte board

Events

Members

Notify all members in current conference.Emited when any member updated except self.

engine.onMembers = (members) => {
  for (member in members) {
    console.log(members[member].uuid)
    console.log(members[member].displayName)
  }
}

The members is an array, each item like:

{
  uuid:String,              // The uuid of member
  userId:String,            // The acount id, maybe empty     
  deviceId:String,          // The device id,maybe empty
  nickname:String,          // The nick
  audiossrc:Unsigned,       // The SSRC of audio
  desktopssrc:Unsigned,     // The SSRC of desktop
  videossrc:[Unsingend],    // The SSRCs of video
  audio:Boolean,            // If audio enabled
  video:Boolean,            // If video enabled
  desktop:Boolean,          // If desktop enabled
  master:Boolean,           // If the master
  self:Boolean              // If self
}

Devoloper should store the memebers, and sync with Joined, Leaved, Kickouted, Recovered events.

RoomStatus

First emited when joining, then emited when view changed.

engine.onRoomStatus = (status) => {
  console.log(status.view) // current view(0:video, 1:desktop, 2:whiteboard)
  console.log(status.viewOnwer) // who turn view to current
  console.log(status.duration) // time since current conference begin
}

Joined

Notify that other user joined current conference.Emited when other joined.

engine.onJoined(nick) {
  message.info(nick + 'has joined');
}

Kickouted

Emited when other kickouted by master.

engine.onKickouted = (nick) => {
  message.info(nick + 'hase kickouted by master');
}

Leaved

Emited when other leaved current conference.

engine.onLeaved = (nick) => {
  message.info(nick + 'has leaved');
}

Connected

Emited when network session connected.

engine.onConnected = (ev) {
  console.log(ev.type)  // type of session(1:media, 2:signal, 3:white board)
  console.log(ev.addr) // service address
}

Disconnected

Emited when network session disconnected.

engine.onDisconnected = (ev) {
  console.log(ev.type) // type of session(1:media, 2:signal, 3:white board)
  console.log(ev.addr) // service address
}

Reconnecting

Emited when reconnecting to service.

engine.onReconneting = (ev) {
  console.log(ev.type) // type of session(1:media, 2:signal, 3:white board)
  console.log(ev.addr) // service address
}

Dismissed

Emited when current conference dismissed

engine.onDeismissed = () =>{
  console.log('the conference is dismissed')
}

Error

Emited when sevice error.

engine.onError = (err) => {
  console.log(err.code)
  console.log(err.msg)
}

Transfered

Emited when master transfereed.

engine.onTransfered = (uuid) {
  console.log('current master is' + uuid)
}

device

This object used to list all available audio/video device, and select one to used.

Properties

microphones (Dict), all available microphones.
speakers (Dict), all available speakers.
cameras (Dict), all avaliable video cameras.
usedMicrophone (Unsigned), the index of used mircorphone
usedSpeaker (Unsigned), the index of used speaker
usedCamera (Unsigned), thie index of used camera

Methods

selectMicrophone(index)

Select used microphone.

param	type	details
index	Int	the index of microphones.

selectSpeaker(index)

Select used microphone.

param	type	details
index	Int	the index of speakers.

selectCamera(index)

Select used microphone.

param	type	details
index	Int	the index of cameras.

Events

DevicesChanged

Emited when devices changed cause by plugged.

device.onDevicesChanged = (type) =>{
  console.log(type) // type(1:camera, 2:microphone, 3:speaker)
}

DeviceError

Emited when hardware error.

device.onDevicesError = (type, name)=> {
  console.log(type)   // 1:camera, 2:microphone, 3:speaker
  console.log(name)  // device name.
}

audio

This object used to control audio record/playout/send/recieve.

Properties

recvStat (JSON String), the statistics of audio recieve streams.
sendStat (JSON String), the statistics of audio send stream.
localMuted (Boolean), if local speaker muted

Methods

mute(uuid)

To make other user muted.

param	type	details
uuid	String	the uuid of other user.

demute(uuid)

To make other user demuted.

param	type	details
uuid	String	the uuid of other user.

muteLocal()

Muted self.

demuteLocal()

Demuted self.

muteAll()

Muted all members in current conference except self.

demuteAll()

Demuted all members in current conference except self.

playout()

Enable speaker to playout.

stopPlayout()

Disable speaker to playout.

Events

Muted

Emited when other muted.

audio.onMuted = (nick) =>{
  console.log(uuid + 'has muted')
}

Demuted

Emited when other demuted.

audio.onDemuted = (uuid) => {
  console.log(uuid + 'has demuted')
}

LocalVolume

Emited interval when not muted.

audio.onLocalVolume = (vol) =>{
  console.log('The voluem is ' + vol )
}

RemoteVolume

Emited interval with each speaking user.

audio.onRemoteVolume = (ev) => {
  console.log(ev.uuid) // the uuid of user
  console.log(ev.vol) // the volume 
}

video

This object used to control send video, subscribe actived-video, subscribe other's video etc.

Properties

muted (Boolean), if video sending

Methods

mute()

Stop video sending.

demute()

Enable video sending.

clearPreviews()

Stop all local video preview.

clearSubscribe()

Unsubscribe all other user's video, and destroy recieve streams/renderers.

clearActive()

Unsubscribe all active-video streams.

clearViews()

Clear all of video recieve streams, and destory all renderers.

subscribe(uuid, quality)

Subscribe video of other user.

param	type	details
uuid	String	the uuid of user.
quality	<180, 360, 720>	the quality expected.

If successed, the return value include a field named 'sink'.It's a instance of MaxMEVideoSink.Devoloper should register callbacks to this object to render video frames and so on.Checkout VideoRender componet under react-sample to see example.

unsubscribe(uuid)

Unsubscribe video of other user.

param	type	details
uuid	String	the uuid of user.

subActive(tag)

Subscribe active-video.

param	type	details
tag	Inter	the unique tag to identify this stream.

unsubActive(tag)

Unsubscribe active-video

param	type	details
tag	Inter	the unique tag to identify this stream.

addPreview(tag)

Add a preview of local video.

param	type	details
tag	Inter	the unique tag to identify this stream.

rmPreview(tag)

Remove a local video preview.

param	type	details
tag	Inter	the unique tag to identify this stream.

Events

Muted

Emited when other user's video muted.

video.onMuted = (nick) =>{
  console.log(nick +''s video muted.')
}

This event also emited through MaxMEVideoSink if the user's video is subscribed.

Demuted

Emited when other user's video demuted.

video.onDemuted = (nick) => {
  console.log(nick + ''s video demuted')
}

This event also emited through MaxMEVideoSink if the user's video is subscribed.

desktop

This object used to handle desktop sharing and remote desktop control etc.

Properties

recvStat (JSON String), the statistics of desktop sharing recieve streams.
sendStat (JSON String), the statistics of desktop sharing send stream.

Methods

sources()

If no error, the return value include a array named sources which contain all can be captured screens and windows. Each item in the array like:

{
  type:<'screen', 'window>,   // source type
  id:Number,                  // the id of this source
  title:String,               // the title of window
  app:String                  // the app name of window
}

snapshot(type, id)

Get snapshot of one source.

param	type	details
type	0:screen, 1:window	the type of source
id	Number	the source's id

If sucessed, the snapshot(An argb data block) would callbacked by Snapshot event.

stopSnapshot

Stop snapshot.

That means stop capture thumbnail of windows/screens.

selectSource(id)

Select captured source.

param	type	details
id	Number	the source's id

excludeWin(win)

To notify not capture special window.

param	type	details
win	Number	the native window handle(HWND/CGWindowID).

removeExcludeWin(win)

To remove window from excluded.

param	type	details
win	Number	the native window handle(HWND/CGWindowID).

excludeEventWin(win)

To nitify not hook i/o event with special window.

param	type	details
win	Number	the native window object(HWND/NSWindow).

removeExcludeEventWin(win)

To remove window from event excluded.

param	type	details
win	Number	the native window object(HWND/NSWindow).

subscribe(uuid)

Subscribe other user's desktop.

param	type	details
uuid	String	the user's uuid.

unsubscribe(uuid)

Unsubscribe other user's dektop.

param	type	details
uuid	String	the user's uuid.

subscribeShared(tag)

Subscribe sharing desktop stream in current conference.

param	type	details
tag	Int	the unique identify this stream.

unsubscribeShared(tag)

Unsubscribe sharing desktop stream in current conference.

param	type	details
tag	Int	the unique identify this stream.

requestAssist(uuid, type)

Request other user to control self's desktop, or to control other user's desktop.

param	type	details
uuid	String	user's UUID.
type	String	'help' or 'control'

responseAssit(uuid, rsp)

Response assit request.

param	type	details
uuid	String	the UUID of requester.
rsp	String	'OK' or 'reject'

cancelAssist(uuid)

Cancel assist request.

param	type	details
uuid	String	user's UUID.

updatePPT(action)

To notify remote Powerpoint to open or close.

param	type	details
action	String	'open' or 'close'.

pptAction(action)

To notify remote Powerpoint to forward or backward.

param	type	details
action	String	'forward' or 'backward'.

dropAssist()

To stop assist.

clearExcludeWin()

Clear all excluded windows

clearExcludeEventWin()

Clear all excluded event windows.

startShare()

To start sharing local screen/window.

stopShare()

To stop desktop sharing.

Events

Started

Emited when other start desktop sharing.

desktop.onStated = (uuid) => {
  console.log(uuid + ' start sharing desktop.')
}

Stoped

Emited when other stop desktop sharing.

desktop.onStoped = (uuid) => {
  console.log(uuid + ' stop sharing desktop.')
}

AssistRequest

Emited when other request to assist.

desktop.onAssistRequest = (uuid) => {
  this.confirm(uuid ' request assist?');
}

AssistCancel

Emited when other cancel assist request.

desktop.onAssistCancel = (uuid) => {
  alert(uuid + ' has canceled assist.')
}

AssistResponse

Emited when other responsed assist request.

desktop.onAssistResponse = (uuid, rlt) => {
  console.log(uuid)   // who response
  console.log(rlt)    // 'ok' or 'reject'
}

AssistDrop

Emited when other drop assist session.

desktop.onAssistDrop = (uuid, type) => {
  console.log(uuid)   // who droped.
  console.log(type)   // 'close' or 'switch'
}

AssistRequestTimeout

Emited when asssit request timeout.

desktop.onAssistRequestTimeout = (uuid) => {
  console.log('timeout when request to ' + uuid)
}

AssistTimeout

Emited when one action timeout bettwen assist session.

desktop.onAssistTimeout = () => {
  console.log('timeout on assist session.');
}

PowerPointUpdate

Emited when remote notify open or close PPT.

desktop.onPowerPointUpdate = (state) => {
  console.log('PPT is' + state) // 'close' or 'open'
}

PowerPointAction

Emited when remote notify forward or backward PPT.

desktop.onPowerPointAction = (action) => {
  console.log(action) // 'forward' or 'backward'
}

Suspend

Emited when remote suspend desktop sharing(only cause by the captured window is minimized).

desktop.onSuspend= () => {
  console.log('The desktop sharing is suspended.') 
}

MaxMEVideoSink

When subscribe any video/desktop-sharing source, methods return a sink which type is MaxMEVideoSink.This object adapt for webgl-video-renderer to render video stream, and emit all audio/video events of bound endpoint.

Events

FrameReady

Emited when every video frame been decoded or captured.

sink.onFrameReady(frame) => {
    glcontent.render(frame, frame.width, frame.height, frame.uOffset, frame.vOffset);
}

FirstFrame

Emited when first frame since last inactived.

sink.onFirstFrame = () =>{
    // To hide loading shape etc.
}

Muted

Emited when mute video stream.

sink.onMuted = ()=> {
    // To show muted shape.
}

Demuted

Emited when demute video stream.

sink.onDemute = () =>{
    // To hide muted shape.
}

SourceChanged

Emited when sink bound to active-video, and the source has changed.

sink.onSourceChanged = (nick) => {
    message.info(nick + 'was actived.');
}

Actived

Emited when sink bound member been video-actived.

sink.onActived = () => {
    // Do something like append borderd canvas.
}

AudioMuted

Emited when sink bound member's audio muted.

sink.onAudioMuted = ()=> {
    // Do something like change icon.
}

AudioDemuted

Emited when sink bound member's audio demuted.

sink.onAudioDemuted = ()=>{
    // Do something like change icon.
}

QualityChanged

Emited when sink bound video source's quality changed.

sink.onQualityChanged = (ev)=>{
    message.info(ev.position + 'quality change to' + ev.quality);
    // position means up or down, qulity may one of 'excellent' 'good' 'poor' 'bad' 'worst'
    // Do something notice user.
}