talking_stick 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9d0ec4a547d57cdd27a4fdaf84c9d903d49e10a4
-  data.tar.gz: 6eeecae1fc08976b80259b980e86106b2ae75779
+  metadata.gz: 81f6e10b86c1f1a61757f55d1938f636fe8b03d4
+  data.tar.gz: 26896201414612c81686e2f28640f085f4850fb9
 SHA512:
-  metadata.gz: 173d28bc43ac5404146d61977c44ad2cec441d37d487dcc2b184d881a6887ee42aea88197160e240113ab5ea528cc737b06c96f03cb9c0eb24b9a4febb5facc9
-  data.tar.gz: 4985639dd6ed35028f8c2356af4fd2ac460370833260b0a86deb3c894364dfe87237b87b12cd9dfb9c0bb57f430027ce79f1bc73e365e85981695e364eb3474d
+  metadata.gz: ac6e81d17687651c2edfb3fe21d2637eda9c838f78061a41a67c2317b8c97608291cfa9ba2da3d6b8be4adb2c1ea023f3fb44532c912acc85c282d91b8878064
+  data.tar.gz: a0b240e87cf62a9d5df4289391ee1cc0bd09d7a0903711f6c84f352c9768391765329f2fb9f19f3e953dbcb32af27c392ea5d572365d8ec3ab8539a139613710

data/.gitignore

@@ -13,3 +13,5 @@ spec/dummy/.sass-cache
 # Editor files
 .*.sw*
 *~
+
+.DS_Store

data/Changes.md

@@ -0,0 +1,5 @@
+# [1.0.0](https://github.com/mojolingo/talking_stick/compare/v0.0.1...v1.0.0) - [2016-01-02](https://rubygems.org/gems/talking_stick/versions/1.0.0)
+* First stable version of Talking Stick - see [README](https://github.com/mojolingo/talking_stick/blob/v1.0.0/README.md) for details
+
+# [0.0.1](https://github.com/mojolingo/talking_stick/releases/tag/v0.0.1) - [2015-05-17](https://rubygems.org/gems/talking_stick/versions/0.0.1)
+* Initial layout of the Rails engine...not much function yet

data/Guardfile

@@ -0,0 +1,44 @@
+guard :rspec, cmd: "bundle exec rspec" do
+  require "guard/rspec/dsl"
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # Feel free to open issues for suggestions and improvements
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+
+  # Rails files
+  rails = dsl.rails(view_extensions: %w(erb haml slim))
+  dsl.watch_spec_files_for(rails.app_files)
+  dsl.watch_spec_files_for(rails.views)
+
+  watch(rails.controllers) do |m|
+    [
+      rspec.spec.("routing/#{m[1]}_routing"),
+      rspec.spec.("controllers/#{m[1]}_controller"),
+      rspec.spec.("acceptance/#{m[1]}")
+    ]
+  end
+
+  # Rails config changes
+  watch(rails.spec_helper)     { rspec.spec_dir }
+  watch(rails.routes)          { "#{rspec.spec_dir}/routing" }
+  watch(rails.app_controller)  { "#{rspec.spec_dir}/controllers" }
+
+  # Capybara features specs
+  watch(rails.view_dirs)     { |m| rspec.spec.("features/#{m[1]}") }
+  watch(rails.layouts)       { |m| rspec.spec.("features/#{m[1]}") }
+
+  # Turnip features and steps
+  watch(%r{^spec/acceptance/(.+)\.feature$})
+  watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$}) do |m|
+    Dir[File.join("**/#{m[1]}.feature")][0] || "spec/acceptance"
+  end
+end

data/README.md

@@ -1,6 +1,6 @@
 # TalkingStick
 
-This gem provides basic [WebRTC](https://webrtc.org) communication in any Rails app.
+This gem provides easy [WebRTC](https://webrtc.org) communication in any Rails app.
 
 
 ## Goals
@@ -17,45 +17,73 @@ Note that TalkingStick requires jQuery, and installs [jquery-rails gem](https://
 
 TalkingStick is built as a Rails Engine, and so follows those conventions.
 
-1. Add to Gemfile and update bundle
-```Ruby
-gem 'talking_stick'
-```
+1. Add to Gemfile and update the bundle
 
-Now run `bundle install` to download the gem.
+    ```Ruby
+    gem 'talking_stick'
+    ```
 
+    Now run `bundle install` to download and install the gem.
 2. Mount the engine
-Add the following to your application's `config/routes.rb`:
-```Ruby
-mount TalkingStick::Engine, at: '/talking_stick'
-```
+    Add the following to your application's `config/routes.rb`:
 
-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
-```
+    ```Ruby
+    mount TalkingStick::Engine, at: '/talking_stick'
+    ```
+3. Install and Run migration
+    To add the required models to your application, the migrations must be copied and run:
+    ```
+    $ rake railties:install:migrations db:migrate
+    ```
+
+4. Import Assets
+    Add the following to your application's `assets/javascripts/application.js`:
+
+    ```javascript
+    //= require talking_stick/application
+    ```
+    
+    And the following to your application's `assets/stylesheets/application.scss`:
+    
+    ```css
+    *= require talking_stick/application
+    ```
+
+5. **[optional]** Generate the default `participant` and `room` views which are then available for customization.  From your app's root directory:
+
+   ```
+   $ rails generate talking_stick:views
+   ```
+
+6. Videconference!
+    After booting Rails, point your browser to something like [http://localhost:3000/talking_stick/rooms](http://localhost:3000/talking_stick/rooms). From there you will be able to create and join rooms.
+
+For a better experience, we recommend also using [Bootstrap](http://getbootstrap.com). Easy installation of Bootstrap into Rails is available via [twitter-bootstrap-rails](https://github.com/seyhunak/twitter-bootstrap-rails).
 
 ## How it works
 
-* Each group is assigned a unique ID
+* Each room 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
+## Extending TalkingStick
+
+### 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.
+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 Server Sent Events. 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.
+[Contact Mojo Lingo](https://mojolingo.com/connect) today! As authors of this Gem, Mojo Lingo are experts in Real-Time Communications Applications. We can help you get the most value out of WebRTC by integrating communications into your application and business processes, and scale it to very large groups. [Learn more.](https://mojolingo.com)
 
 
+### Building Your Own Signaling Engine
+
 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 [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 else 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.
 
@@ -84,8 +112,7 @@ 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`
-
+* `TalkingStick.Partner.handleRemoteICECandidate(RTCIceCandidate)` Pass in ICE candidates received from remote Partners
 
 
 ### Additional Methods
@@ -93,13 +120,18 @@ This function returns an instance of `TalkingStick.Partner`.
 * `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`.
 
+### Events
+
+* `talking_stick.local_media_setup`: (no arguments) Triggered after local media has been initialized and drawn to the configured element
+* TODO: Document the rest of the events
+
 ## TODO
 
-See the [Pivotal Tracker story board](https://www.pivotaltracker.com/n/projects/1343190)
+See the [Pivotal Tracker story board](https://www.pivotaltracker.com/n/projects/1343190).  Contributions welcome!
 
 ## 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/).
+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
 
@@ -108,4 +140,7 @@ The [Talking Stick] is a tradition among Native American (and other) cultures wh
 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
+
+[Flikr2005](https://www.flickr.com/photos/flikr/371850310/) loading image courtesy Flickr user [Flikr](https://www.flickr.com/photos/flikr/)

data/app/assets/images/talking_stick/line-spinner.svg

@@ -0,0 +1 @@
+<svg width='120px' height='90px' xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" preserveAspectRatio="xMidYMid" class="uil-default"><rect x="0" y="0" width="100" height="100" fill="none" class="bk"></rect><rect  x='46.5' y='40' width='7' height='20' rx='5' ry='5' fill='#aea59e' transform='rotate(0 50 50) translate(0 -30)'>  <animate attributeName='opacity' from='1' to='0' dur='1s' begin='0s' repeatCount='indefinite'/></rect><rect  x='46.5' y='40' width='7' height='20' rx='5' ry='5' fill='#aea59e' transform='rotate(30 50 50) translate(0 -30)'>  <animate attributeName='opacity' from='1' to='0' dur='1s' begin='0.08333333333333333s' repeatCount='indefinite'/></rect><rect  x='46.5' y='40' width='7' height='20' rx='5' ry='5' fill='#aea59e' transform='rotate(60 50 50) translate(0 -30)'>  <animate attributeName='opacity' from='1' to='0' dur='1s' begin='0.16666666666666666s' repeatCount='indefinite'/></rect><rect  x='46.5' y='40' width='7' height='20' rx='5' ry='5' fill='#aea59e' transform='rotate(90 50 50) translate(0 -30)'>  <animate attributeName='opacity' from='1' to='0' dur='1s' begin='0.25s' repeatCount='indefinite'/></rect><rect  x='46.5' y='40' width='7' height='20' rx='5' ry='5' fill='#aea59e' transform='rotate(120 50 50) translate(0 -30)'>  <animate attributeName='opacity' from='1' to='0' dur='1s' begin='0.3333333333333333s' repeatCount='indefinite'/></rect><rect  x='46.5' y='40' width='7' height='20' rx='5' ry='5' fill='#aea59e' transform='rotate(150 50 50) translate(0 -30)'>  <animate attributeName='opacity' from='1' to='0' dur='1s' begin='0.4166666666666667s' repeatCount='indefinite'/></rect><rect  x='46.5' y='40' width='7' height='20' rx='5' ry='5' fill='#aea59e' transform='rotate(180 50 50) translate(0 -30)'>  <animate attributeName='opacity' from='1' to='0' dur='1s' begin='0.5s' repeatCount='indefinite'/></rect><rect  x='46.5' y='40' width='7' height='20' rx='5' ry='5' fill='#aea59e' transform='rotate(210 50 50) translate(0 -30)'>  <animate attributeName='opacity' from='1' to='0' dur='1s' begin='0.5833333333333334s' repeatCount='indefinite'/></rect><rect  x='46.5' y='40' width='7' height='20' rx='5' ry='5' fill='#aea59e' transform='rotate(240 50 50) translate(0 -30)'>  <animate attributeName='opacity' from='1' to='0' dur='1s' begin='0.6666666666666666s' repeatCount='indefinite'/></rect><rect  x='46.5' y='40' width='7' height='20' rx='5' ry='5' fill='#aea59e' transform='rotate(270 50 50) translate(0 -30)'>  <animate attributeName='opacity' from='1' to='0' dur='1s' begin='0.75s' repeatCount='indefinite'/></rect><rect  x='46.5' y='40' width='7' height='20' rx='5' ry='5' fill='#aea59e' transform='rotate(300 50 50) translate(0 -30)'>  <animate attributeName='opacity' from='1' to='0' dur='1s' begin='0.8333333333333334s' repeatCount='indefinite'/></rect><rect  x='46.5' y='40' width='7' height='20' rx='5' ry='5' fill='#aea59e' transform='rotate(330 50 50) translate(0 -30)'>  <animate attributeName='opacity' from='1' to='0' dur='1s' begin='0.9166666666666666s' repeatCount='indefinite'/></rect></svg>

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

@@ -0,0 +1,272 @@
+var TalkingStick = (function(self) {
+  self.guid         = undefined;
+  self.myStream     = undefined;
+  self.joinedAt     = undefined;
+  self.audioMuted   = false;
+  self.videoMuted   = false;
+  self.partners     = {};
+  self._options = {
+    media: { audio: true, video: true },
+    localVideo: '#localvideo',
+    partnerVideos: '#partnervideos',
+    connectionTimeout: 60000,
+    logLevel: 'error',
+    iceServers: [],
+  };
+
+  self.logLevels = [
+    'trace',
+    'debug',
+    'notice',
+    'warning',
+    'error',
+  ];
+
+  self.init = function(options) {
+    $.extend(self._options, options);
+
+    self.logLevelIdx = self.logLevels.indexOf(self._options.logLevel);
+    self.guid = self._options.guid || self.generateGUID();
+    self.localVideo = $(self._options.localVideo);
+    self.partnerVideos = $(self._options.partnerVideos);
+    self.signalingEngine = self._options.signalingEngine;
+    self.detectDevices();
+    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.trigger = function(name) {
+    name = 'talking_stick.' + name;
+    args = Array.prototype.slice.call(arguments, 1);
+    // Syntactic sugar: make it easy to pass a list of args as the only argument
+    // This is the "right way" per
+    // http://stackoverflow.com/questions/4775722/check-if-object-is-array
+    if (args.length == 1 && Object.prototype.toString.call(args[0]) === '[object Array]') {
+      args = args[0];
+    }
+    self.localVideo.trigger(name, args);
+  };
+
+  self.detectDevices = function() {
+    if (typeof MediaStreamTrack === 'undefined' || typeof MediaStreamTrack.getSources === 'undefined') {
+      self.log('warning', 'MediaStreamTrack is not defined.  We will not be able to offer device selection.');
+    } else {
+      MediaStreamTrack.getSources(self.handleDevices);
+    }
+  };
+
+  self.handleDevices = function(devices) {
+    var microphones = 1;
+    var cameras = 1;
+    devices = devices.map(function(device) {
+      // Devices (SourceInfo) objects are read-only
+      // Make a copy of the data here so we can apply default labels
+      var tsDevice = {
+        id: "" + device.id,
+        label: "" + device.label,
+        facing: "" + device.facing,
+        kind: "" + device.kind,
+      }
+      if (tsDevice.kind === 'audio' && tsDevice.label == '') {
+        tsDevice.label = "<%= I18n.t('microphone') %> " + microphones++;
+      } else if (tsDevice.kind === 'video' && tsDevice.label == '') {
+        tsDevice.label = "<%= I18n.t('camera') %> " + cameras++;
+      }
+      return tsDevice;
+    });
+    self.log('trace', 'Device enumeration complete', devices);
+    self.devices = devices;
+    self.trigger('devices_ready', devices);
+  };
+
+  self.applyDeviceSelections = function(sourceIds) {
+    self.log('info', "Changing devices at user's request.", sourceIds)
+    if (!!self.myStream) {
+      self.localVideo.src = null;
+      self.myStream.stop();
+    }
+
+    var newConstraints = {}
+    if (sourceIds.audio) {
+      newConstraints.audio = {
+        optional: [{
+          sourceId: sourceIds.audio
+        }]
+      }
+    }
+
+    if (sourceIds.video) {
+      newConstraints.video = {
+        optional: [{
+          sourceId: sourceIds.video
+        }]
+      }
+    }
+
+    $.extend(self._options.media, newConstraints);
+    self.setupLocalVideo();
+  }
+
+  self.setupLocalVideo = function() {
+    self.prepareVideoElement(self.localVideo);
+
+    // Prevent local audio feedback
+    // Chrome allows setting the attribute via jQuery; Firefox does not.
+    self.localVideo[0].muted = true;
+
+    self.log('debug', 'Requesting user consent to access to input devices');
+    getUserMedia(self._options.media, self._handleUserMedia, self._handleUserMediaFailure);
+  };
+
+  self.muteAudio = function() {
+    self.log('debug', 'User has requested audio be muted');
+    self.myStream.getAudioTracks()[0].enabled = false;
+  }
+
+  self.muteVideo = function() {
+    self.log('debug', 'User has requested video be muted');
+    self.myStream.getVideoTracks()[0].enabled = false;
+  }
+
+  self.unmuteAudio = function() {
+    self.log('debug', 'User has requested audio be unmuted');
+    self.myStream.getAudioTracks()[0].enabled = true;
+  }
+
+  self.unmuteVideo = function() {
+    self.log('debug', 'User has requested video be unmuted');
+    self.myStream.getVideoTracks()[0].enabled = true;
+  }
+
+  self.audioMuted = function() {
+    return !self.myStream.getAudioTracks()[0].enabled;
+  }
+
+  self.videoMuted = function() {
+    return !self.myStream.getVideoTracks()[0].enabled;
+  }
+
+  self._handleUserMedia = 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(self.localVideo[0], stream);
+
+    self.trigger('local_media_setup');
+  };
+
+  self._handleUserMediaFailure = function(error) {
+    switch(error.name) {
+    case 'PermissionDeniedError':
+      self.log('error', 'User declined access to camera & microphone');
+      break;
+    default:
+      self.log('error', error);
+    }
+  };
+
+  self.connect = function(name) {
+    // Tell the server we're ready to start contacting the other participants
+    var data = {
+      participant: {
+        guid: self.guid,
+        name: name
+      }
+    }
+    $.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.trigger('connected');
+    })
+    .fail(function() { self.ajaxErrorLog('Error joining the room', arguments) });
+  };
+
+  self.disconnect = function() {
+    $.each(self.partners, function(i, partner) {
+      partner.cleanup();
+    });
+    self.trigger('disconnected');
+  };
+
+  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')); // <video>
+    partnerVideo.attr('data-partner-guid', participant.guid); // <video data-partner-guid="abcd1234">
+    partnerVideo.attr('poster', "<%= image_path 'talking_stick/line-spinner.svg' %>"); // <video poster="talking_stick/line-spinner.svg"
+    self.prepareVideoElement(partnerVideo);
+    var options = {
+      videoElement: partnerVideo,
+      signalingEngine: self.signalingEngine,
+      iceServers: self._options.iceServers,
+    }
+
+    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({connectionTimeout: self.connectionTimeout});
+    }
+
+    self.trigger('new_partner', partner);
+    return partner;
+  };
+
+  self.prepareVideoElement = function(el) {
+    el = $(el);
+
+    // Ensure video streams play as soon as they are attached
+    el.attr('autoplay', 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 || {}));