Giter Site home page Giter Site logo

yogomi / cordova-plugin-iosrtc Goto Github PK

View Code? Open in Web Editor NEW

This project forked from cordova-rtc/cordova-plugin-iosrtc

0.0 2.0 0.0 27.71 MB

Cordova iOS plugin exposing the full WebRTC W3C JavaScript APIs

License: MIT License

JavaScript 33.29% Swift 35.20% Objective-C 30.16% C 1.35%

cordova-plugin-iosrtc's Introduction

cordova-plugin-iosrtc

Cordova iOS plugin exposing the full WebRTC W3C JavaScript APIs.

Yet another WebRTC SDK for iOS?

Absolutely not. This plugin exposes the WebRTC W3C API for Cordova iOS apps (you know there is no WebRTC in iOS, right?), which means no need to learn "yet another WebRTC API" and no need to use a specific service/product/provider.

Why?

Check the release announcement at the eFace2Face site.

Resources:

  • NPM package.
  • Public Google Group for questions and discussions about cordova-plugin-iosrtc.
  • Bug Tracker for reporting issues and requesting new features (please don't use the bug tracker for questions or problems, use the Google Group instead).

Installation

Within your Cordova project:

$ cordova plugin add cordova-plugin-iosrtc

(or add it into a <plugin> entry in the config.xml of your app).

Building

This plugin needs Swift support so some steps are needed to get your project working with it. These steps are explained in the Building documentation, please check it.

IMPORTANT: It seems that the incoming Swift 2.0 (included in the next OS X El Capitan) requires code changes for the plugin to compile. It will be addressed in issue #28.

Usage

The plugin exposes the cordova.plugins.iosrtc JavaScript namespace which contains all the WebRTC classes and functions.

var pc = new cordova.plugins.iosrtc.RTCPeerConnection({
  iceServers: []
});

cordova.plugins.iosrtc.getUserMedia(
  // constraints
  { audio: true, video: true },
  // success callback
  function (stream) {
    console.log('got local MediaStream: ', stream);

    pc.addStream(stream);
  },
  // failure callback
  function (error) {
    console.error('getUserMedia failed: ', error);
  }
);

Q: But... wait! Does it mean that there is no window.RTCPeerConnection nor navigator.getUserMedia?

R: A Cordova plugin is supposed to expose its JavaScript stuff in a specific namespace and, personally, I just hate those libraries that pollute the global namespace. Said that, the plugin provides a registerGlobals() method, so you just need the following extra-code in your existing WebRTC app (assuming that cordova-plugin-device is installed):

// Just for Cordova apps.
document.addEventListener('deviceready', function () {
  // Just for iOS devices.
  if (window.device.platform === 'iOS') {
    cordova.plugins.iosrtc.registerGlobals();
  }
});

And that's all. Now you have window.RTCPeerConnection, navigator.getUserMedia, etc.

Q: What about <video> elements and video.src = URL.createObjectURL(stream)? do I need custom HTML tags or functions to display WebRTC videos?

R: No. Just use an HTML video element as usual, really. The plugin will properly place a native UIView layer on top of it by respecting (most of) its CSS properties.

Q: Can I place HTML elements (buttons and so on) on top of active <video> elements?

R: Not yet, but there is ongoing work to enable this feature (see here).

Q: What about HTML5 video events? Can I rely on video.oncanplay?

R: I see what you mean. As there is no real video attached to the <video> element, media events are artificially emitted by the plugin. The following events are emitted when the MediaStream attached to a video element is ready to render video: onloadedmetadata, onloadeddata, oncanplay, oncanplaythrough. So yes, you can rely on them.

Q: Can I read <video> properties such as readyState, videoWidth, etc?

Again, there is no real video attached to the <video> element so some peroperties are artificially set by the plugin. These are readyState, videoWidth and videoHeight.

Q: Do I need to call special methods to release/free native WebRTC objects? How are they garbage collected?

R: Good question. An RTCPeerConnection is released when close() is called on it, a MediaStream is released when all its tracks end, and other elements are garbage collected when no longer needed. Basically the same behavior as in a WebRTC capable browser.

Q: What about Android? Why just iOS?

R: In modern versions of Android the WebView component is based on the Chromium open source project which already includes WebRTC (more info). For older versions of Android the CrossWalk project provides new WebView versions with WebRTC support as well.

Documentation

Read the full documentation in the docs folder.

Demo application

Check our iOSRTCApp (Google's AppRTC adapted to Cordova iOS with pure HTML5/JavaScript and cordova-plugin-iosrtc).

Who Uses It

People and companies using cordova-plugin-iosrtc.

If you are using the plugin we would love to heard back from you!

Known Issues

iOS Safari and crash on WebSocket events

Don't call plugin methods within WebSocket events (onopen, onmessage, etc). There is an issue in iOS Safari (see issue #12). Instead run a setTimeout() within the WebSocket event if you need to call plugin methods on it.

Or better, just load the provided ios-websocket-hack.js script into your Cordova iOS app and you are done.

HTML5 video API

As explained above, there is no real media source attached to the <video> element so some HTML5 video events and properties are artificially emitted/set by the plugin on behalf of the video element.

Methods such as play(), pause() are not implemented. In order to pause a video just set enabled = false on the associated MediaStreamTrack.

Changelog

(since version 1.2.8)

Version 1.4.4

  • Support CSS border-radius property in HTML video elements.

Version 1.4.3

  • Make private properties more private (issue #34).

Version 1.4.2

  • Use yaeti module as EventTarget shim.

Version 1.4.1

  • Release MediaStreamRenderer and revert <video> properties when the attached MediaStream emits "inactive" (issue #27).

Version 1.4.0

  • Implemented some <video> properties such as readyState, videoWidth and videoHeight (issue #25).
  • Building simplified for both Cordova CLI and Xcode by providing a single "hook" the user must add into his Cordova application (check the Building documentation for further details).

Version 1.3.3

  • CSS object-fit: none properly implemented (don't clip the video).

Version 1.3.2

Version 1.3.1

  • Stop "error" event propagation in <video> element when attaching a MediaStream to it (issue #22).

Version 1.3.0

  • Plugin moved to NPM registry and plugin ID renamed to cordova-plugin-iosrtc.

Version 1.2.8

  • iosrtc.registerGlobals() also generates window.webkitRTCPeerConnection and navigator.webkitGetUserMedia() for backwards compatibility with WebRTC JavaScript wrappers/adapters that assume browser vendor prefixes (webkit, moz) in the underlying WebRTC API.

Author

Iñaki Baz Castillo at eFace2Face, inc.

License

MIT :)

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.