James

A voice controlled electronic butler.

Installation

gem install james (OS X only, MacRuby needed; Install MacRuby using rvm install macruby. Then do rvm use macruby.)

Getting Started: Get James talking!

Create a file called time_dialog.rb. Copy this

James.dialog do

  hear 'What time is it?' => :time

  state :time do
    hear ['What time is it?', 'And now?'] => :time
    into { time = Time.now; "It is currently #{time.hour} #{time.min}." }
    exit {} # Optional, listed for completeness.
  end

end

into it. Then, in the Terminal, run

$ james time_dialog.rb

And have fun and write your own dialog! :)

What does it do?

The above example says that if James hears (hear) "What time is it?" that it should enter this conversation into state :time, the only state.

If he then hears "What time is it?" again, or "And now?", it will return to state :time.

When he enters (into), James executes the block in the dialog’s context. Whatever is returned from the block, James will say out lout. Everything else he will just think. (So it’s like Sinatra in rendering, just that James renders audio)

Here, he will just say the current time when entering the :time state.

Other examples can be found in /examples.

Some info

James consists of dialogs that are modeled as state machines. You navigate through these dialogs by talking to James.

He will then take action (looking up timetables, checking the weather etc.) and inform you. Or maybe just tell a joke.

If James is having difficulty understanding you, then you may need to calibrate the microphone or adjust other speech recognition settings. Open System Preferences and go to the Speech section, you should see a “Calibrate” button next to the option of which microphone to use.

Running James

Running it is easy. There are multiple options:

Using the james command

This is easiest. In the terminal, just call

$ james time_dialog.rb twitter_dialog.rb

and it will include the named dialogs, time_dialog.rb, twitter_dialog.rb.

Or a bit snappier

$ james {time,twitter}*.rb

to do the same as above.

Options are: -si (silent input), -so (silent output), -s (both).

$ james -s time_dialog.rb

for example will use audio for neither input nor output.

Programmatically

require 'rubygems'
require 'james'

# Your dialog goes here.

# This is needed to start James.
#
James.listen

in your script, and call it by using

$ ruby time_dialog.rb

Or, without the James.listen, use

$ ruby -rexamples/your_dialog.rb -rexamples/your_other_dialog.rb -e "James.listen"

on the command line.

Short Version

There is a short, anonymous dialog version, using James.dialog.

James.dialog do

  hear 'what time is it?' => :time

  state :time do
    hear ['What time is it?', 'And now?'] => :time
    into { time = Time.now; "It is currently #{time.hour} #{time.min}." }
  end

end

James.dialog will directly create a dialog instance from your definitions in the block and plug it into James.

Extended Version

Or there is an extended version, using initialize with parameters to set up some important stuff that needs other stuff for doing stuff, you know?

require 'james'

class TwitterDialog

  include James::Dialog

  def initialize user, password
    @client = Twitter.new user, password
  end

  hear 'What are the birds tweeting?' => :newsfeed

  state :newsfeed do
    hear 'Who mentions me?' => :mentions
    into do
      # Complicated feed loading
      #
      "People are saying this: #{@client.newsfeed(10).join(' ... ')}"
    end
  end

  state :mentions do
    hear ['What is generally said?', 'Back to newsfeed!'] => :newsfeed
    into do
      # Complicated feed loading
      "People are saying this: #{@client.mentions(10).join(' ... ')}"
    end
  end

end

James.use TwitterDialog.new('user', 'password')

James.listen

Contributions

Contributions are in the /examples folder.

After forking, in the james directory, run ./bin/james examples/time_dialog.rb to have your first successful experience! :)

Running the tests

rake

Roadmap

Add dialogs made by YOU :)

Ideas

Put it on a Mac Mini, attach a few microphones, distribute in the house.
Create a few useful dialogs, like a train timetable, or similar.
Sit on your sofa, and talk to James out loud.
Send us your dialogs :)

MIT License

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.

jbrahy / james Goto Github PK

james's Introduction