Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/floere/james

Voice commanded servant for OSX
https://github.com/floere/james

Last synced: 2 days ago
JSON representation

Voice commanded servant for OSX

Awesome Lists containing this project

README 

        
h1. James



A voice controlled electronic butler.



h2. Installation



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



h2. 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! :)



h3. 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":http://github.com/floere/james/tree/master/examples.



h2. 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.



h2. Running James



Running it is easy. There are multiple options:



h3. 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.



h3. 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.



h2. 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.



h2. 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



h2. Contributions



Contributions are in the "/examples":http://github.com/floere/james/tree/master/examples folder.



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



h2. Running the tests



rake



h2. Roadmap



* Add dialogs made by YOU :)



h2. 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 :)



h2. MIT License



Copyright (c) 2011 Florian Hanke



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.