Add cordova.plugins.iosrtc.observeVideo(video) (related to #49).

cordova-rtc · Aug 25, 2015 · 5e68121 · 5e68121
1 parent b7fc452
commit 5e68121
Show file tree

Hide file tree

Showing 7 changed files with 127 additions and 77 deletions.
diff --git a/dist/cordova-plugin-iosrtc.js b/dist/cordova-plugin-iosrtc.js
@@ -1,5 +1,5 @@
 /*
- * cordova-plugin-iosrtc v1.4.4
+ * cordova-plugin-iosrtc v1.4.5-pre
  * Cordova iOS plugin exposing the full WebRTC W3C JavaScript APIs
  * Copyright 2015 Iñaki Baz Castillo at eFace2Face, inc. (https://eface2face.com)
  * License MIT
@@ -522,7 +522,7 @@ MediaStreamRenderer.prototype.render = function (stream) {
 
 	exec(null, null, 'iosrtcPlugin', 'MediaStreamRenderer_render', [this.id, stream.id]);
 
-	// Subscribe to 'update' event so we call native mediaStreamChangedrefresh() on it.
+	// Subscribe to 'update' event so we call native mediaStreamChanged() on it.
 	stream.addEventListener('update', function () {
 		if (self.stream !== stream) {
 			return;
@@ -2120,35 +2120,48 @@ var
 /**
  * Dependencies.
  */
-	debug = require('debug')('iosrtc'),
-	exec = require('cordova/exec'),
-	domready = require('domready');
+	debug                  = require('debug')('iosrtc'),
+	exec                   = require('cordova/exec'),
+	domready               = require('domready'),
+
+	getUserMedia           = require('./getUserMedia'),
+	getMediaDevices        = require('./getMediaDevices'),
+	RTCPeerConnection      = require('./RTCPeerConnection'),
+	RTCSessionDescription  = require('./RTCSessionDescription'),
+	RTCIceCandidate        = require('./RTCIceCandidate'),
+	MediaStream            = require('./MediaStream'),
+	MediaStreamTrack       = require('./MediaStreamTrack'),
+	videoElementsHandler   = require('./videoElementsHandler'),
+	rtcninjaPlugin         = require('./rtcninjaPlugin');
 
 
 /**
  * Expose the iosrtc object.
  */
 module.exports = {
 	// Expose WebRTC classes and functions.
-	getUserMedia:          require('./getUserMedia'),
-	getMediaDevices:       require('./getMediaDevices'),
-	RTCPeerConnection:     require('./RTCPeerConnection'),
-	RTCSessionDescription: require('./RTCSessionDescription'),
-	RTCIceCandidate:       require('./RTCIceCandidate'),
-	MediaStream:           require('./MediaStream'),
-	MediaStreamTrack:      require('./MediaStreamTrack'),
+	getUserMedia:          getUserMedia,
+	getMediaDevices:       getMediaDevices,
+	RTCPeerConnection:     RTCPeerConnection,
+	RTCSessionDescription: RTCSessionDescription,
+	RTCIceCandidate:       RTCIceCandidate,
+	MediaStream:           MediaStream,
+	MediaStreamTrack:      MediaStreamTrack,
 
 	// Expose a function to refresh current videos rendering a MediaStream.
 	refreshVideos:         refreshVideos,
 
+	// Expose a function to handle a video not yet inserted in the DOM.
+	observeVideo:          videoElementsHandler.observeVideo,
+
 	// Select audio output (earpiece or speaker).
 	selectAudioOutput:     selectAudioOutput,
 
 	// Expose a function to pollute window and naigator namespaces.
 	registerGlobals:       registerGlobals,
 
 	// Expose the rtcninjaPlugin module.
-	rtcninjaPlugin:        require('./rtcninjaPlugin'),
+	rtcninjaPlugin:        rtcninjaPlugin,
 
 	// Expose the debug module.
 	debug:                 require('debug'),
@@ -2159,15 +2172,10 @@ module.exports = {
 
 
 domready(function () {
-	observeVideos();
-});
-
-
-function observeVideos() {
 	// Let the MediaStream class and the videoElementsHandler share same MediaStreams container.
-	require('./MediaStream').setMediaStreams(mediaStreams);
-	require('./videoElementsHandler')(mediaStreams, mediaStreamRenderers);
-}
+	MediaStream.setMediaStreams(mediaStreams);
+	videoElementsHandler(mediaStreams, mediaStreamRenderers);
+});
 
 
 function refreshVideos() {
@@ -2208,17 +2216,17 @@ function registerGlobals() {
 		navigator.mediaDevices = {};
 	}
 
-	navigator.getUserMedia                  = require('./getUserMedia');
-	navigator.webkitGetUserMedia            = require('./getUserMedia');
-	navigator.mediaDevices.getUserMedia     = require('./getUserMedia');
-	navigator.mediaDevices.enumerateDevices = require('./getMediaDevices');
-	window.RTCPeerConnection                = require('./RTCPeerConnection');
-	window.webkitRTCPeerConnection          = require('./RTCPeerConnection');
-	window.RTCSessionDescription            = require('./RTCSessionDescription');
-	window.RTCIceCandidate                  = require('./RTCIceCandidate');
-	window.MediaStream                      = require('./MediaStream');
-	window.webkitMediaStream                = require('./MediaStream');
-	window.MediaStreamTrack                 = require('./MediaStreamTrack');
+	navigator.getUserMedia                  = getUserMedia;
+	navigator.webkitGetUserMedia            = getUserMedia;
+	navigator.mediaDevices.getUserMedia     = getUserMedia;
+	navigator.mediaDevices.enumerateDevices = getMediaDevices;
+	window.RTCPeerConnection                = RTCPeerConnection;
+	window.webkitRTCPeerConnection          = RTCPeerConnection;
+	window.RTCSessionDescription            = RTCSessionDescription;
+	window.RTCIceCandidate                  = RTCIceCandidate;
+	window.MediaStream                      = MediaStream;
+	window.webkitMediaStream                = MediaStream;
+	window.MediaStreamTrack                 = MediaStreamTrack;
 }
 
 
@@ -2262,8 +2270,10 @@ function attachMediaStream(element, stream) {
 (function (global){
 /**
  * Expose a function that must be called when the library is loaded.
+ * And also a helper function.
  */
 module.exports = videoElementsHandler;
+module.exports.observeVideo = observeVideo;
 
 
 /**
@@ -2425,14 +2435,12 @@ function videoElementsHandler(_mediaStreams, _mediaStreamRenderers) {
 }
 
 
-/**
- * Private API.
- */
-
 function observeVideo(video) {
-	debug('observeVideo() | [class:"%s", src:%s]', video.className, video.src);
+	debug('observeVideo()');
 
-	if (video.src) {
+	// If the video already has a src property but is not yet handled by the plugin
+	// then handle it now.
+	if (video.src && !video._iosrtcMediaStreamRendererId) {
 		handleVideo(video);
 	}
 
@@ -2470,6 +2478,10 @@ function observeVideo(video) {
 }
 
 
+/**
+ * Private API.
+ */
+
 function handleVideo(video) {
 	var xhr = new XMLHttpRequest();
 

diff --git a/docs/iosrtc.md b/docs/iosrtc.md
@@ -132,6 +132,32 @@ When calling this method, the height/width, opacity, visibility and z-index of a
 Call this method when the position or size of a video element changes.
 
 
+### `iosrtc.observeVideo(video)`
+
+Tell the plugin that it must monitor the given HTML5 video element.
+
+*NOTE:* This method should just be used for those `<video>` elements not yet inserted into the DOM in which the app want to attach a `MediaStream`. If the video element is already placed into the DOM at the time a `MediaStream` is attached to it then calling this method is not needed at all.
+
+```javascript
+peerconnection.addEventListener('addstream', function (event) {
+  // Create a video element in memory (not yet in the DOM).
+  var video = document.createElement('video');
+
+  // Tell the plugin to monitor it.
+  cordova.plugins.iosrtc.observeVideo(video);
+
+  // Attach the MediaStream to it.
+  video.src = URL.createObjectURL(event.stream);
+
+  // When the stream is ready to be rendered then append the video
+  // element to the DOM.
+  video.addEventListener('canplay', function () {
+    document.getElementById('videoContainer').appendChild(video);
+  });
+});
+```
+
+
 ### `iosrtc.selectAudioOutput(output)`
 
 Select the audio output device. Given `output` argument must be "earpiece" or "speaker".

diff --git a/js/MediaStreamRenderer.js b/js/MediaStreamRenderer.js
@@ -59,7 +59,7 @@ MediaStreamRenderer.prototype.render = function (stream) {
 
 	exec(null, null, 'iosrtcPlugin', 'MediaStreamRenderer_render', [this.id, stream.id]);
 
-	// Subscribe to 'update' event so we call native mediaStreamChangedrefresh() on it.
+	// Subscribe to 'update' event so we call native mediaStreamChanged() on it.
 	stream.addEventListener('update', function () {
 		if (self.stream !== stream) {
 			return;

diff --git a/js/iosrtc.js b/js/iosrtc.js
@@ -17,35 +17,48 @@ var
 /**
  * Dependencies.
  */
-	debug = require('debug')('iosrtc'),
-	exec = require('cordova/exec'),
-	domready = require('domready');
+	debug                  = require('debug')('iosrtc'),
+	exec                   = require('cordova/exec'),
+	domready               = require('domready'),
+
+	getUserMedia           = require('./getUserMedia'),
+	getMediaDevices        = require('./getMediaDevices'),
+	RTCPeerConnection      = require('./RTCPeerConnection'),
+	RTCSessionDescription  = require('./RTCSessionDescription'),
+	RTCIceCandidate        = require('./RTCIceCandidate'),
+	MediaStream            = require('./MediaStream'),
+	MediaStreamTrack       = require('./MediaStreamTrack'),
+	videoElementsHandler   = require('./videoElementsHandler'),
+	rtcninjaPlugin         = require('./rtcninjaPlugin');
 
 
 /**
  * Expose the iosrtc object.
  */
 module.exports = {
 	// Expose WebRTC classes and functions.
-	getUserMedia:          require('./getUserMedia'),
-	getMediaDevices:       require('./getMediaDevices'),
-	RTCPeerConnection:     require('./RTCPeerConnection'),
-	RTCSessionDescription: require('./RTCSessionDescription'),
-	RTCIceCandidate:       require('./RTCIceCandidate'),
-	MediaStream:           require('./MediaStream'),
-	MediaStreamTrack:      require('./MediaStreamTrack'),
+	getUserMedia:          getUserMedia,
+	getMediaDevices:       getMediaDevices,
+	RTCPeerConnection:     RTCPeerConnection,
+	RTCSessionDescription: RTCSessionDescription,
+	RTCIceCandidate:       RTCIceCandidate,
+	MediaStream:           MediaStream,
+	MediaStreamTrack:      MediaStreamTrack,
 
 	// Expose a function to refresh current videos rendering a MediaStream.
 	refreshVideos:         refreshVideos,
 
+	// Expose a function to handle a video not yet inserted in the DOM.
+	observeVideo:          videoElementsHandler.observeVideo,
+
 	// Select audio output (earpiece or speaker).
 	selectAudioOutput:     selectAudioOutput,
 
 	// Expose a function to pollute window and naigator namespaces.
 	registerGlobals:       registerGlobals,
 
 	// Expose the rtcninjaPlugin module.
-	rtcninjaPlugin:        require('./rtcninjaPlugin'),
+	rtcninjaPlugin:        rtcninjaPlugin,
 
 	// Expose the debug module.
 	debug:                 require('debug'),
@@ -56,15 +69,10 @@ module.exports = {
 
 
 domready(function () {
-	observeVideos();
-});
-
-
-function observeVideos() {
 	// Let the MediaStream class and the videoElementsHandler share same MediaStreams container.
-	require('./MediaStream').setMediaStreams(mediaStreams);
-	require('./videoElementsHandler')(mediaStreams, mediaStreamRenderers);
-}
+	MediaStream.setMediaStreams(mediaStreams);
+	videoElementsHandler(mediaStreams, mediaStreamRenderers);
+});
 
 
 function refreshVideos() {
@@ -105,17 +113,17 @@ function registerGlobals() {
 		navigator.mediaDevices = {};
 	}
 
-	navigator.getUserMedia                  = require('./getUserMedia');
-	navigator.webkitGetUserMedia            = require('./getUserMedia');
-	navigator.mediaDevices.getUserMedia     = require('./getUserMedia');
-	navigator.mediaDevices.enumerateDevices = require('./getMediaDevices');
-	window.RTCPeerConnection                = require('./RTCPeerConnection');
-	window.webkitRTCPeerConnection          = require('./RTCPeerConnection');
-	window.RTCSessionDescription            = require('./RTCSessionDescription');
-	window.RTCIceCandidate                  = require('./RTCIceCandidate');
-	window.MediaStream                      = require('./MediaStream');
-	window.webkitMediaStream                = require('./MediaStream');
-	window.MediaStreamTrack                 = require('./MediaStreamTrack');
+	navigator.getUserMedia                  = getUserMedia;
+	navigator.webkitGetUserMedia            = getUserMedia;
+	navigator.mediaDevices.getUserMedia     = getUserMedia;
+	navigator.mediaDevices.enumerateDevices = getMediaDevices;
+	window.RTCPeerConnection                = RTCPeerConnection;
+	window.webkitRTCPeerConnection          = RTCPeerConnection;
+	window.RTCSessionDescription            = RTCSessionDescription;
+	window.RTCIceCandidate                  = RTCIceCandidate;
+	window.MediaStream                      = MediaStream;
+	window.webkitMediaStream                = MediaStream;
+	window.MediaStreamTrack                 = MediaStreamTrack;
 }
 
 

diff --git a/js/videoElementsHandler.js b/js/videoElementsHandler.js
@@ -1,7 +1,9 @@
 /**
  * Expose a function that must be called when the library is loaded.
+ * And also a helper function.
  */
 module.exports = videoElementsHandler;
+module.exports.observeVideo = observeVideo;
 
 
 /**
@@ -163,14 +165,12 @@ function videoElementsHandler(_mediaStreams, _mediaStreamRenderers) {
 }
 
 
-/**
- * Private API.
- */
-
 function observeVideo(video) {
-	debug('observeVideo() | [class:"%s", src:%s]', video.className, video.src);
+	debug('observeVideo()');
 
-	if (video.src) {
+	// If the video already has a src property but is not yet handled by the plugin
+	// then handle it now.
+	if (video.src && !video._iosrtcMediaStreamRendererId) {
 		handleVideo(video);
 	}
 
@@ -208,6 +208,10 @@ function observeVideo(video) {
 }
 
 
+/**
+ * Private API.
+ */
+
 function handleVideo(video) {
 	var xhr = new XMLHttpRequest();
 

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "cordova-plugin-iosrtc",
-  "version": "1.4.4",
+  "version": "1.4.5-pre",
   "description": "Cordova iOS plugin exposing the full WebRTC W3C JavaScript APIs",
   "author": "Iñaki Baz Castillo at eFace2Face, inc. (https://eface2face.com)",
   "license": "MIT",

diff --git a/plugin.xml b/plugin.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
 		id="cordova-plugin-iosrtc"
-		version="1.4.4">
+		version="1.4.5-pre">
 
 	<name>iosrtc</name>
 	<description>Cordova iOS plugin exposing the full WebRTC W3C JavaScript APIs</description>