talking_stick 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9d0ec4a547d57cdd27a4fdaf84c9d903d49e10a4
+  data.tar.gz: 6eeecae1fc08976b80259b980e86106b2ae75779
+SHA512:
+  metadata.gz: 173d28bc43ac5404146d61977c44ad2cec441d37d487dcc2b184d881a6887ee42aea88197160e240113ab5ea528cc737b06c96f03cb9c0eb24b9a4febb5facc9
+  data.tar.gz: 4985639dd6ed35028f8c2356af4fd2ac460370833260b0a86deb3c894364dfe87237b87b12cd9dfb9c0bb57f430027ce79f1bc73e365e85981695e364eb3474d

data/.gitignore

@@ -0,0 +1,15 @@
+.bundle/
+log/*.log
+pkg/
+spec/dummy/db/*.sqlite3
+spec/dummy/db/*.sqlite3-journal
+spec/dummy/log/*.log
+spec/dummy/tmp/
+spec/dummy/.sass-cache
+
+# Gemfile.lock is ignored in libraries
+/Gemfile.lock
+
+# Editor files
+.*.sw*
+*~

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,15 @@
+source 'https://rubygems.org'
+
+# Declare your gem's dependencies in talking_stick.gemspec.
+# Bundler will treat runtime dependencies like base dependencies, and
+# development dependencies will be added by default to the :development group.
+gemspec
+
+# Declare any dependencies that are still in development here instead of in
+# your gemspec. These might include edge Rails or gems from your path or
+# Git. Remember to move these dependencies to your gemspec before releasing
+# your gem to rubygems.org.
+
+# To use a debugger
+# gem 'byebug', group: [:development, :test]
+

data/LICENSE.md

@@ -0,0 +1,50 @@
+TalkingStick Copyright (C) 2015 Mojo Lingo LLC
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+adapter.js Copyright (c) 2014, The WebRTC project authors. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+  * Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+
+  * Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in
+    the documentation and/or other materials provided with the
+    distribution.
+
+  * Neither the name of Google nor the names of its contributors may
+    be used to endorse or promote products derived from this software
+    without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,111 @@
+# TalkingStick
+
+This gem provides basic [WebRTC](https://webrtc.org) communication in any Rails app.
+
+
+## Goals
+
+* Provide easy group-based (2 or more participants) audio/video communication
+* Allow selecting audio or audio+video
+* Pluggable signaling delivery technology
+* Plug & Play functionality - works out of the box
+* Focus on simplicity at the API level, while maximizing the possibilites of integrating communication into existing Rails apps
+
+## Installation
+
+Note that TalkingStick requires jQuery, and installs [jquery-rails gem](https://github.com/rails/jquery-rails) as a dependency.
+
+TalkingStick is built as a Rails Engine, and so follows those conventions.
+
+1. Add to Gemfile and update bundle
+```Ruby
+gem 'talking_stick'
+```
+
+Now run `bundle install` to download the gem.
+
+2. Mount the engine
+Add the following to your application's `config/routes.rb`:
+```Ruby
+mount TalkingStick::Engine, at: '/talking_stick'
+```
+
+3. Install and Run migrations
+To add the required models to your application, the migrations must be copied and run:
+```
+$ rake railties:install:migrations db:migrate
+```
+
+## How it works
+
+* Each group is assigned a unique ID
+* Rails app keeps track of participants in each room
+* Rails app notifies all room participants when one joins or leaves
+* Rails app proxies call setup between participants in each room
+
+## Providing your own signaling mechanism
+
+One of the critical decisions made by the standards bodies behind WebRTC was a decision to leave the signaling of WebRTC up to the application. This means that an application may use any means it desires to give the endpoints the data necessary to communicate directly.
+
+This plugin tries to be "batteries included", which means that we included a signaling mechanism that will work on any Rails server. As such, we could not rely on any particular push technology, such as Websockets or long polling. Thus, the default behavior is that the browser polls the Rails API for updates on connected peers. This works fine for small user bases, but obviously will not scale well.
+
+### Want help designing and deploying an efficient, scalable signaling mechanism for your application?
+[Contact Mojo Lingo](https://mojolingo.com/connect) today! As authors of this Gem, Mojo Lingo can help you get the most value out of WebRTC by integrating communications into your application and business processes.
+
+
+Alternatively, you can build your own by passing a "Signaling Engine" to the TalkingStick class.
+
+The [reference Signaling Engine](https://github.com/mojolingo/talking_stick/blob/master/app/assets/javascripts/talking_stick/talking_stick/rails_signaling.js) periodically polls the Rails API for signals, but can be replaced with any API-compatible implementation, including Websockets, XMPP, or anything you like.
+
+The Signaling Engine must implement the following methods. For each method where `guid` is specified, it represents the ID of the remote participant to which the information must be sent.
+
+* `connected`: Takes no parameters. Is called after the user's media is set up and the participant is registered to the room.
+* `sendICECandidate(guid, candidate)`: The second parameter is the ICE candidate. Called each time a new local ICE candidate is discovered by the browser. This must be sent to the remote participant.
+* `iceCandidateGatheringComplete(guid, candidates)`: Called when all ICE candidates have been gathered. This can be used in place of `sendICECandidate` to send all candidates at once, rather than trickling them in one-by-one (though trickling is generally a better user experience).
+* `sendOffer(guid, offer)`: Called when the local browser wants to initiate an offer to a remote party.
+* `sendAnswer(guid, answer)`: Called when the local browser wants to respond to a received offer.
+
+The Signaling Engine will also need to use the following methods to add new Partners to the conversation:
+
+* `TalkingStick.addPartner(partner)`
+
+```javascript
+var partner = {
+  guid: 'GloballyUniqueIdentifierForThisParter-Session',
+  joined_at: Date
+}
+```
+
+The `guid` should be unique not only for the remote participant, but also his connection into this session. If a single participant were to join two different rooms on the same server (for example), he would need two separate GUIDs, one for each room.
+
+The `joined_at` field signifies the date & time that the remote Participant joined the room. It is important that the `joined_at` Date object be provided by the remote party to avoid race conditions. The `joined_at` field is used internally by TalkingStick to manage the sequence of offers & answers.
+
+This function returns an instance of `TalkingStick.Partner`.
+
+* `TalkingStick.Partner.handleOffer(offer)` Pass in offer received from a Partner
+* `TalkingStick.Partner.handleAnswer(answer)` Pass in an answer received from a Partner
+* `TalkingStick.Partner.handleRemoteICECandidate(RTCIceCandidate)` Pass ICE candidates received from remote Partners in to instances of `TalkingStick.Partner`
+
+
+
+### Additional Methods
+
+* `TalkingStick.parters` The collection of `TalkingStick.Partners` to whom the local session is currently connected. Treat it as read-only.
+* `TalkingStick.log(level, obj[, obj ...])` Allows messages to be conditionally logged to the console. Valid levels are strings, and may be one of `trace`, `debug`, `notice`, `warning`, or `error`.
+
+## TODO
+
+See the [Pivotal Tracker story board](https://www.pivotaltracker.com/n/projects/1343190)
+
+## The Name
+
+The [Talking Stick] is a tradition among Native American (and other) cultures which specifies a simple yet effective way for facilitating group conversations. For more, see the [Wikipedia Article](https://en.wikipedia.org/wiki/Talking_stick), or this insightful blog post by [Rich Goidel](http://www.dangerouskitchen.com/shut-up-and-listen/).
+
+## Credits & Copyright
+
+* Original author: [Ben Klang](https://twitter.com/bklang), [Mojo Lingo LLC](https://mojolingo.com)
+
+This project is licensed under the MIT License. This project incorporates [Adapter.js from the WebRTC.org team](https://github.com/webrtc/adapter), which is licensed under the Apache license.
+
+Copyright 2015 Mojo Lingo LLC
+Portions copyright 2014 The WebRTC project authors

data/Rakefile

@@ -0,0 +1,32 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'TalkingStick'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+load 'rails/tasks/statistics.rake'
+
+Dir[File.join(File.dirname(__FILE__), 'tasks/**/*.rake')].each {|f| load f }
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+desc "Run all specs in spec directory (excluding plugin specs)"
+RSpec::Core::RakeTask.new(:spec => 'app:db:test:prepare')
+task :default => :spec
+
+Bundler::GemHelper.install_tasks
+

data/app/assets/javascripts/talking_stick/application.js

@@ -0,0 +1,15 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or any plugin's vendor/assets/javascripts directory can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// compiled file.
+//
+// Read Sprockets README (https://github.com/rails/sprockets#sprockets-directives) for details
+// about supported directives.
+//
+//= require jquery
+//= require_tree .
+//= require talking_stick/adapter

data/app/assets/javascripts/talking_stick/talking_stick.js

@@ -0,0 +1,141 @@
+var TalkingStick = (function(self) {
+  self.guid         = undefined;
+  self.myStream     = undefined;
+  self.joinedAt     = undefined;
+  self._options = {
+    media: { audio: true, video: true },
+    localVideo: undefined, // Set this to the DOM element where video should be rendered
+    logLevel: 'error',
+  };
+
+  self.logLevels = [
+    'trace',
+    'debug',
+    'notice',
+    'warning',
+    'error',
+  ];
+
+  self.init = function(options) {
+    $.extend(self._options, options);
+
+    self.logLevelIdx = self.logLevels.indexOf(self._options.logLevel);
+    self.partners = {};
+    self.guid = self._options.guid || self.generateGUID();
+    self.signalingEngine = self._options.signalingEngine;
+    self.setupLocalVideo();
+    self.log('notice', 'TalkingStick initialized.');
+  };
+
+  self.log = function() {
+    var level = arguments[0];
+    var levelIdx = self.logLevels.indexOf(level);
+    if (levelIdx >= self.logLevelIdx) {
+      var args = Array.prototype.slice.call(arguments, 1);
+      args.unshift('[' + level + ']');
+      switch(levelIdx) {
+      case 4:
+        console.error.apply(console, args);
+        break;
+      case 3:
+        console.warn.apply(console, args);
+        break;
+      default:
+        console.log.apply(console, args);
+        break;
+      }
+    }
+  }
+
+  self.setupLocalVideo = function() {
+    var localVideo = $(self._options.localVideo);
+
+    self.prepareVideoElement(localVideo);
+
+    self.log('debug', 'Requesting user consent to access to input devices');
+    navigator.getUserMedia(self._options.media, function(stream) {
+      self.log('debug', 'User has granted access to input devices');
+      self.myStream = stream;
+
+      // The JS API requires the raw DOM element, not a jQuery wrapper
+      attachMediaStream(localVideo[0], stream);
+    }, self.errorCallback);
+  };
+
+  self.connect = function() {
+    // Tell the server we're ready to start contacting the other participants
+    var data = {
+      participant: {
+        guid: self.guid,
+      }
+    }
+    $.post(self._options.roomUrl + '/participants.json', data)
+    .success(function(data) {
+      self.log('notice', 'TalkingStick connected to the room.');
+      self.joinedAt = new Date(data.joined_at);
+      self.signalingEngine.connected();
+    })
+    .fail(function() { self.ajaxErrorLog('Error joining the room', arguments) });
+  };
+
+  
+  self.errorCallback = function(error) {
+    self.log('error', error);
+  };
+  
+  /*
+   * participant.guid
+   * participant.joined_at
+   */
+  self.addPartner = function(participant) {
+    self.log('debug', 'Adding new partner to this conversation', participant);
+    var partnerVideo = document.createElement('video');
+    self.prepareVideoElement(partnerVideo);
+    $('#partnerVideos').append(partnerVideo);
+    var options = {
+      videoElement: partnerVideo,
+      signalingEngine: self.signalingEngine,
+    }
+
+    partner = new TalkingStick.Partner(participant, options);
+    self.partners[participant.guid] = partner;
+
+    partner.connect(self.myStream);
+
+    if (partner.joinedAt < TalkingStick.joinedAt) {
+      self.log('trace', 'Sending Offer to', partner.guid);
+      // Send Offers to partners who joined before us.
+      // Expect partners who join after us to send us Offers.
+      partner.sendOffer();
+    }
+
+    return partner;
+  };
+
+  self.prepareVideoElement = function(el) {
+    el = $(el);
+
+    // Ensure video streams play as soon as they are attached
+    el.attr('autoplay', true);
+
+    // Prevent local audio feedback
+    el.attr('muted', true);
+  };
+
+  self.generateGUID = function () {
+    function s4() {
+      return Math.floor((1 + Math.random()) * 0x10000)
+        .toString(16)
+        .substring(1);
+    }
+    return s4() + s4() + '-' + s4() + '-' + s4() + '-' +
+      s4() + '-' + s4() + s4() + s4();
+  };
+
+  self.ajaxErrorLog = function(message, ajaxFailArgs) {
+    // ajaxFailArgs: 0: jqXHR; 1: textStatus; 2: errorThrown
+    self.log('error', message + ':', ajaxFailArgs[2]);
+  }
+
+  return self;
+}(TalkingStick || {}));

data/app/assets/javascripts/talking_stick/talking_stick/partner.js

@@ -0,0 +1,100 @@
+TalkingStick.Partner = function(participant, options) {
+  this.gatheringCandidates = false;
+  this.guid          = participant.guid;
+  this.joinedAt      = new Date(participant.joined_at);
+  this.localICECandidates = [];
+  this._options      = {
+    videoElement: undefined, // Set this to the DOM element where video should be rendered
+  };
+  $.extend(this._options, options);
+  this.signalingEngine = this._options.signalingEngine;
+  this.videoElement    = this._options.videoElement;
+}
+
+TalkingStick.Partner.prototype.log = function() {
+  var level = arguments[0];
+  var args = Array.prototype.slice.call(arguments, 1);
+  args.unshift('[Partner ' + this.guid + ']');
+  args.unshift(level);
+  TalkingStick.log.apply(this, args);
+}
+
+TalkingStick.Partner.prototype.errorCallback = function() {
+  // Convert arguments to a real array
+  var args = Array.prototype.slice.call(arguments);
+  args.unshift('error');
+  this.log(args);
+}
+
+TalkingStick.Partner.prototype.setDescription = function(answer) {
+  this.log('trace', 'Setting remote description to', answer);
+  this.peerConnection.setRemoteDescription(new RTCSessionDescription(answer));
+};
+
+TalkingStick.Partner.prototype.connect = function(stream) {
+  this.log('trace', 'Creating new peer connection');
+  this.peerConnection = new RTCPeerConnection();
+
+  var partner = this;
+  this.peerConnection.onicecandidate = function() {
+    partner.handleLocalICECandidate.apply(partner, arguments);
+  }
+
+  this.peerConnection.addStream(stream);
+};
+
+TalkingStick.Partner.prototype.sendOffer = function() {
+  // Fix scope for "this" inside createOffer()
+  var partner = this;
+  this.peerConnection.createOffer(function(offer) {
+    partner.log('trace', 'Created PeerConnection Offer; ICE candidate collection starting', offer);
+    partner.gatheringCandidates = true;
+    partner.peerConnection.setLocalDescription(offer);
+    partner.signalingEngine.sendOffer(partner.guid, offer);
+  }, this.errorCallback);
+};
+
+TalkingStick.Partner.prototype.handleOffer = function(offer) {
+  this.log('debug', 'Processing Offer received from', this.guid);
+  this.peerConnection.setRemoteDescription(new RTCSessionDescription(offer));
+  var partner = this;
+
+  this.peerConnection.onaddstream = function(event) {
+    attachMediaStream($(partner.videoElement)[0], event.stream);
+  };
+  this.peerConnection.createAnswer(function(answer) {
+    partner.peerConnection.setLocalDescription(new RTCSessionDescription(answer));
+    partner.log('debug', 'Sending Answer to', partner.guid);
+    partner.signalingEngine.sendAnswer(partner.guid, answer);
+  });
+};
+
+TalkingStick.Partner.prototype.handleAnswer = function(answer) {
+  this.log('debug', 'Processing Answer received from', this.guid);
+  var partner = this;
+  this.peerConnection.onaddstream = function(event) {
+    attachMediaStream($(partner.videoElement)[0], event.stream);
+  };
+  this.peerConnection.setRemoteDescription(new RTCSessionDescription(answer));
+};
+
+TalkingStick.Partner.prototype.handleRemoteICECandidate = function(candidate) {
+  this.log('trace', 'Adding remote ICE candidate', candidate);
+  this.peerConnection.addIceCandidate(new RTCIceCandidate(candidate));
+};
+
+TalkingStick.Partner.prototype.handleLocalICECandidate = function(event) {
+  var candidate = event.candidate;
+  if (candidate) {
+    this.log('trace', 'Discovered local ICE candidate', candidate);
+    // Store and transmit new ICE candidate
+    this.localICECandidates.push(event.candidate);
+    this.signalingEngine.sendICECandidate(this.guid, event.candidate);
+
+  } else {
+    this.gatheringCandidates = false;
+    this.log('debug', 'ICE candidate collection complete');
+    this.signalingEngine.iceCandidateGatheringComplete(this.guid, this.localICECandidates);
+  }
+};
+