maxme-electron
Version:
The electron wrap of MaxME.
798 lines (616 loc) • 21.9 kB
Markdown
# 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](#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.|
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.
##### 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.|
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.
##### 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.|
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 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.|
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.
##### 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.
}
````