kurento-utils-universal

Copyright 2018 Kurento. Licensed under Apache 2.0 License.

Kurento Utils for Node.js and Browsers

kurento-utils-js is a browser library that can be used to simplify creation and handling of RTCPeerConnection objects, to control the browser’s WebRTC API. However, the official kurento-utils-js is no longer maintained, and problems might occur when using the official library.

This library is an optimized version of kurento-utils-js, currently it adds supports for screen sharing and mixed media sharing for mainstream browsers (as well as Electron, since v6.18.6) without extra plugins.

Installation Instructions

Be sure to have installed Node.js in your system:

curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
sudo apt-get install -y nodejs

To install the library, it's recommended to do that from the NPM repository:

npm install kurento-utils-universal

Alternatively, you can download the code using git and install manually its dependencies:

git clone https://github.com/LeoHaoVIP/kurento-utils-universal.git
cd kurento-utils-universal
npm install

Developing Instructions

Quickly Shift

If you have read the kurento-docs and already known how to build WebRTC applications with the official kurento-utils-js, you can quickly enjoy the new features by replacing the official dependency item with {"kurento-utils-universal": "latest"} in your package.json file.

Compared to coding with the official library, the only action that you should make is to update the sendSource field when creating WebRtcPeer. Update details about sendSource are provided below.

Updates on Official Library

• Update enumeration values of sendSource

  The official kurento-utils-js supports two kinds of send sources, which are webcam and screen. In this updated library, we have provided four commonly used sharing modes, which are audio|screen|camera|mix.

  When a user is sharing on mix mode, the camera and screen media are mixed into one single media stream via MultiStreamMixer.

  

• Add supports for free-plugin screen sharing

  Most browsers now naturally support getDisplayMedia for screen sharing. In this updated library, we utilized it and implemented getScreenMedia, thus users can share their screen without installing extra browser plugins.

  Besides, considering that some developers are writing WebRTC applications running on Electron framework, since v6.18.6, we also implemented getScreenMediaForElectron and getMixMediaForElectron using desktopCapturer module of Electron.

  It's worth noting that developers don't need to make any extra actions or configuration to start screen sharing, the only thing that you should do is to assign 'screen' or 'mix' to the sendSource field.

Screen Sharing on Electron

Screen sharing works perfectly on mainstream browsers, such as Chrome, Firefox, Microsoft Edge. When the WebRtcPeer is created with sendSource as 'screen' or 'mix', a window will pop up and ask user to select the target window (or the entire screen) to share.

However, Things get different when WebRTC applications are running on Electron, since no popup window will show up.

In this library, we have implemented the basic screen sharing functionality for Electron applications. By default, the target sharing media source is the entire screen.

Sharing A Specific Window on Electron

If you want to share a specific window instead of the entire screen on Electron, some coordination is required. In this tutorial, we will show how to share a certain media source via the Inter-Process Communication (IPC) in Electron.

Step1. Add a Preload Script for you Electron application.

// preload.js | Electron project
let {ipcRenderer} = require('electron');

ipcRenderer.on('media-source-id', (event, value) => {
    // Write the target media source id to the window object
    window.mediaSourceId = value;
})

Step2. Select a target media source via desktopCapturer in the Main Process and send it to the Renderer Process.

// main.js | Electron project
const {app, desktopCapturer} = require('electron');

let mainWindow;

const createWindow = () => {
    mainWindow = new BrowserWindow({
        width: 800,
        height: 600,
        webPreferences: {
            preload: path.join(__dirname, 'preload.js'),
            // Append other webPreferences if necessary
        }
    })
    // Add your window creation logic here
}

// Note: the desktopCapturer module only works when the app is ready
app.whenReady().then(() => {
    createWindow();
    desktopCapturer.getSources({types: ['window', 'screen']}).then(async sources => {
        let targetMediaSourceId;
        for (const source of sources) {
            // Add your media source selection logic here
            targetMediaSourceId = source.id;
        }
        // Send the target media source to the Renderer Process
        mainWindow.webContents.on('did-finish-load', () => {
            mainWindow.webContents.send('media-source-id', targetMediaSourceId);
        })
    })
})

The next following is a sample of media source object.

// A sample of media source object
{
  name: 'app',
  id: 'window:854492:1',
  thumbnail: NativeImage {...},
  display_id: '',
  appIcon: null
}

Explanation

When the kurento-utils-universal library is running on Electron, the mediaSourceId inside the window object will be used as the target media source ID. Thus, developers need to preset the mediaSourceId in the window object, and then the library will start sharing the target media. The relevant codes in our library are as follows:

screenConstrains.video = {
    mandatory: {
        chromeMediaSource: 'desktop',
        // Use the mediaSourceId (if provided) inside the window object.
        chromeMediaSourceId: window.mediaSourceId ? window.mediaSourceId : ''
    }
};

After finishing the above steps, you can share a specific window media on Electron.

---

The next following document is directly copied from official kurento-utils project.

---

About Kurento

Kurento is an open source software project providing a platform suitable for creating modular applications with advanced real-time communication capabilities. For knowing more about Kurento, please visit the Kurento project website: https://www.kurento.org.

Kurento is part of FIWARE. For further information on the relationship of FIWARE and Kurento check the Kurento FIWARE Catalog Entry. Kurento is also part of the NUBOMEDIA research initiative.

Documentation

The Kurento project provides detailed documentation including tutorials, installation and development guides. The Open API specification, also known as Kurento Protocol, is available on apiary.io.

Useful Links

Usage:

• Installation Guide
• Compilation Guide
• Contribution Guide

Issues:

• Bug Tracker
• Support

News:

• Kurento Blog
• Google Groups

Source

All source code belonging to the Kurento project can be found in the Kurento GitHub organization page.

Licensing and distribution

Copyright 2018 Kurento

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.