larynx 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Adam Meehan
+
+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.

data/README.rdoc

@@ -0,0 +1,191 @@
+= Larynx
+
+A framework to develop IVR applications in Ruby for the FreeSWITCH (FS) telephony platform. It is used
+with the FS event socket module to easily develop IVR applications in an asynchronous fashion.
+
+It offer some useful functions and classes on top the default FreeSWITCH dialplan commands to make
+application development easier.
+
+Larynx currently implements an 'outbound' socket listener for incoming calls to be handled. An 'inbound'
+module will probably follow soon enough.
+
+== Install
+
+On Rubygems.org:
+
+  sudo gem install larynx
+
+You will need to have the FreeSWITCH server installed somewhere you can control.
+
+== Example
+
+Simplest possible
+
+  Larynx.answer {|call|
+    call.speak 'Hello world! Or whoever you are.'
+  }
+
+Using the bare Application class, below is a guessing game.
+
+class Guess < Larynx::Application
+	def run
+		@number = rand(9) + 1
+    @guess = ''
+		@guesses = 0
+		get_guess
+	end
+
+	def get_guess
+		if @guesses < 3
+			speak(guess_prompt) { @guesses += 1 }
+		else
+			speak "Sorry you didn't guess it. It was #{@number}. Try again soon.", :bargein => false
+			hangup
+		end
+	end
+
+  def guess_prompt
+    @guesses == 0 ? 'Guess a number between 1 and 9.' : 'Have another guess.'
+  end
+
+	def check_guess
+		if @guess.to_i == @number
+			speak "You got it! It was #{@guess}. It took you #{@guesses} guesses.", :bargein => false
+			speak "Thanks for playing."
+			hangup
+		else
+			speak "No it's not #{@guess}."
+			get_guess
+		end
+	end
+
+	def dtmf_received(input)
+		@guess = input
+		check_guess
+	end
+end
+
+Larynx.answer {|call| Guess.run(call) }
+
+A more sophisticated example using the Form class
+
+  class Guess < Larynx::Form
+    field(:guess, :attempts => 3, :length => 1) do
+      prompt :speak => 'Guess a number between 1 and 9.', :interdigit_timeout => 6
+      reprompt :speak => 'Have another guess.', :interdigit_timeout => 6
+
+      setup do
+        @number = rand(9) + 1
+        @guesses = 0
+      end
+
+      validate do
+        @guesses += 1 if guess.size > 0
+        @number == guess.to_i
+      end
+
+      invalid do
+        if guess.size > 0
+          speak "No, it's not #{guess}.", :bargein => false
+        end
+      end
+
+      success do
+        speak "You got it! It was #{guess}. It took you #{@guesses} guesses.", :bargein => false
+        hangup
+      end
+
+      failure do
+        speak "Sorry you didn't guess it. It was #{@number}. Try again soon.", :bargein => false
+        hangup
+      end
+    end
+  end
+
+  Larynx.answer {|call| Guess.run(call) }
+
+The Form class wraps up many handy conventions into a pleasant DSL in which allows you to control the user
+interaction more easily.
+
+Save your app into file and run larynx comand to start the app server ready to receive calls.
+
+  $ larynx app.rb
+
+Now make a call to extension 2000 with a SIP phone. Your app should start.
+
+
+== Configure FreeSWTICH
+
+To set up a dialplan which connects to your app read http://wiki.freeswitch.org/wiki/Event_Socket
+
+Also take a look at the http://wiki.freeswitch.org/wiki/Event_socket_outbound for background.
+
+Example socket diaplan:
+
+  <include>
+     <extension name="outbound_socket">
+       <condition field="destination_number" expression="^2000$">
+         <action application="socket" data="localhost:8084 async full" />
+       </condition>
+     </extension>
+  </include>
+
+Which connects calls to destination number 2000 to your event socket app.
+
+
+== Global Hooks
+
+Larynx provides three globals hooks you can use to perform some action at each point.
+The are:
+
+  Larynx.connect {|call|
+    # you can choose to hangup the call here if you wish
+  }
+
+  Larynx.answer {|call|
+    # call is answered and ready to interact with the caller
+  }
+
+  Larynx.hungup {|call|
+    # finish off any logging or some such
+  }
+
+Mainly you just use the answer hook. From the examples you can see can start sending commands or
+start an application class running. You write an app just in this block but you don't want to.
+
+
+== Application Class
+
+The application adds a sprinkling of convenience for handling a call, plus you can store instance
+variables and create methods for structuring you app better.
+
+The application should define a run instance method which is used to kick it off when you call
+
+  MyApp.run(call)
+
+The class method initialises some things for you and then calls <tt>run</tt> on the instance. From
+there its up to you. You can use all the commands directly rather than call them on the call
+instance.
+
+== Form Class
+
+
+
+== Event Hooks
+
+The Application and Form classes have a couple of useful event hook methods available which are
+
+  class MyApp < Larynx::Application
+    def run
+    end
+
+    def dtmf_received(input)
+      # input is the button the user just pushed
+    end
+
+    def hungup
+      # application specific handling of a hangup
+    end
+  end
+
+

data/Rakefile

@@ -0,0 +1,55 @@
+require 'rubygems'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rubygems/specification'
+require 'spec/rake/spectask'
+require 'lib/larynx/version'
+
+GEM_NAME = "larynx"
+GEM_VERSION = Larynx::VERSION
+
+spec = Gem::Specification.new do |s|
+  s.name = GEM_NAME
+  s.version = GEM_VERSION
+  s.platform = Gem::Platform::RUBY
+  s.rubyforge_project = GEM_NAME
+  s.has_rdoc = true
+  s.extra_rdoc_files = ["README.rdoc"]
+  s.executables = ["larynx"]
+  s.summary = ""
+  s.description = s.summary
+  s.author = "Adam Meehan"
+  s.email = "adam.meehan@gmail.com"
+  s.homepage = "http://github.com/adzap/larynx"
+
+  s.require_path = 'lib'
+  s.autorequire = GEM_NAME
+  s.files = %w(MIT-LICENSE README.rdoc Rakefile) + Dir.glob("{lib,spec,examples}/**/*")
+end
+
+desc 'Default: run specs.'
+task :default => :spec
+
+spec_files = Rake::FileList["spec/**/*_spec.rb"]
+
+desc "Run specs"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = spec_files
+  t.spec_opts = ["-c"]
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+desc "install the gem locally"
+task :install => [:package] do
+  sh %{gem install pkg/#{GEM_NAME}-#{GEM_VERSION}}
+end
+
+desc "create a gemspec file"
+task :make_spec do
+  File.open("#{GEM_NAME}.gemspec", "w") do |file|
+    file.puts spec.to_ruby
+  end
+end

data/bin/larynx

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+unless defined?(Gem)
+  $:.unshift File.expand_path(File.dirname(__FILE__) + '/../lib')
+end
+
+require 'larynx'

data/examples/guess.rb

@@ -0,0 +1,39 @@
+class Guess < Larynx::Application
+	def run
+		@number = rand(9) + 1
+    @guess = ''
+		@guesses = 0
+		get_guess
+	end
+
+	def get_guess
+		if @guesses < 3
+			speak(guess_prompt) { @guesses += 1 }
+		else
+			speak "Sorry you didn't guess it. It was #{@number}. Try again soon.", :bargein => false
+			hangup
+		end
+	end
+
+  def guess_prompt
+    @guesses == 0 ? 'Guess a number between 1 and 9.' : 'Have another guess.'
+  end
+
+	def check_guess
+		if @guess.to_i == @number
+			speak "You got it! It was #{@guess}. It took you #{@guesses} guesses.", :bargein => false
+			speak "Thanks for playing."
+			hangup
+		else
+			speak "No it's not #{@guess}."
+			get_guess
+		end
+	end
+
+	def dtmf_received(input)
+		@guess = input
+		check_guess
+	end
+end
+
+Larynx.answer {|call| Guess.run(call) }

data/examples/guess_form.rb

@@ -0,0 +1,34 @@
+class Guess < Larynx::Form
+	field(:guess, :attempts => 3, :length => 1) do
+		prompt :speak => 'Guess a number between 1 and 9.', :interdigit_timeout => 6
+		reprompt :speak => 'Have another guess.', :interdigit_timeout => 6
+
+		setup do
+			@number = rand(9) + 1
+			@guesses = 0
+		end
+
+		validate do
+			@guesses += 1 if guess.size > 0
+			@number == guess.to_i
+		end
+
+		invalid do
+			if guess.size > 0
+				speak "No, it's not #{guess}.", :bargein => false
+			end
+		end
+
+		success do
+			speak "You got it! It was #{guess}. It took you #{@guesses} guesses.", :bargein => false
+			hangup
+		end
+
+		failure do
+			speak "Sorry you didn't guess it. It was #{@number}. Try again soon.", :bargein => false
+			hangup
+		end
+	end
+end
+
+Larynx.answer {|call| Guess.run(call) }

data/examples/multiple_apps.rb

@@ -0,0 +1,63 @@
+class Login < Larynx::Form
+  setup do
+    @user_id = '1234'
+    @pin = '4321'
+    @attempts = 0
+  end
+
+	field(:enter_id, :attempts => 3, :length => 4) do
+		prompt :speak => 'Please enter your 4 digit user ID.', :bargein => true
+
+    success do
+      next_field
+    end
+
+		failure do
+			speak "You have been unable to enter your user ID. Goodbye."
+			hangup
+		end
+	end
+
+	field(:enter_pin, :attempts => 3, :length => 4) do
+		prompt :speak => 'Now enter your 4 digit pin.', :bargein => true
+
+    success do
+      if valid_credentials?
+        speak "Credentials accepted."
+        Party.run(call)
+      else
+        failed_login
+      end
+    end
+
+    failure do
+      speak "You have been unable to enter your pin. Goodbye."
+      hangup
+    end
+  end
+
+  def valid_credentials?
+    enter_id == @user_id && enter_pin == @pin
+  end
+
+  def failed_login
+    @attempts += 1
+    if @attempts < 3
+      speak "Those credentials are invalid. Try again."
+      next_field :enter_id
+    else
+      speak "You have been able to login. Goodbye."
+      hangup
+    end
+  end
+end
+
+class Party < Larynx::Application
+  def run
+    speak 'Time to party!'
+    speak 'But all on your own. Goodbye.'
+    hangup
+  end
+end
+
+Larynx.answer {|call| Login.run(call) }

data/lib/larynx/application.rb

@@ -0,0 +1,24 @@
+module Larynx
+  class Application
+    attr_reader :call
+    delegate *Commands.instance_methods << {:to => :call}
+
+    def self.run(call)
+      app = self.new(call)
+      call.add_observer app
+      app.run
+    end
+
+    def initialize(call)
+      @call = call
+    end
+
+    def run
+      #override for setup
+    end
+
+    def log(msg)
+      app.call.log(msg)
+    end
+  end
+end

data/lib/larynx/call_handler.rb

@@ -0,0 +1,174 @@
+# FIXME interrupted commands callback can be fired out of order if new command sent on break
+module Larynx
+  class CallHandler < EventMachine::Protocols::HeaderAndContentProtocol
+    include Observable
+    include Commands
+
+    attr_reader :state, :session, :response, :input, :observers, :last_command
+
+    # EM hook which is run when call is received
+    def post_init
+      @queue, @input, @timers = [], [], {}
+      connect {
+        @session = Session.new(@response.header)
+        log "Call received from #{caller_id}"
+        Larynx.fire_callback(:connect, self)
+        start_session
+      }
+      send_next_command
+    end
+
+    def start_session
+      myevents {
+				linger
+				answer {
+					log 'Answered call'
+					Larynx.fire_callback(:answer, self)
+				}
+      }
+    end
+
+    def called_number
+      @session[:caller_destination_number]
+    end
+
+    def caller_id
+      @session[:caller_caller_id_number]
+    end
+
+    def interrupt_command
+      if @state == :executing && current_command.interruptable?
+        break!
+      end
+    end
+
+    def clear_input
+      @input = []
+    end
+
+    def execute(command, immediately=false)
+      log "Queued: #{command.name}"
+      if immediately
+        @queue.unshift command
+        send_next_command
+      else
+        @queue << command
+      end
+      command
+    end
+
+    def timer(name, timeout, &block)
+      @timers[name] = [RestartableTimer.new(timeout) {
+        timer = @timers.delete(name)
+        timer[1].call if timer[1]
+        notify_observers :timed_out
+        send_next_command if @state == :ready
+      }, block]
+    end
+
+    def cancel_timer(name)
+      if timer = @timers.delete(name)
+        timer[0].cancel
+        send_next_command if @state == :ready
+      end
+    end
+
+    def cancel_all_timers
+      @timers.values.each {|t| t[0].cancel }
+    end
+
+    def stop_timer(name)
+      if timer = @timers.delete(name)
+        timer[0].cancel
+        timer[1].call if timer[1]
+        send_next_command if @state == :ready
+      end
+    end
+
+    def restart_timer(name)
+      if timer = @timers[name]
+        timer[0].restart
+      end
+    end
+
+    def cleanup
+      break! if @state == :executing
+      cancel_all_timers
+      clear_observers!
+    end
+
+    def receive_request(header, content)
+      @response = Response.new(header, content)
+
+      case
+      when @response.reply? && !current_command.is_a?(AppCommand)
+        log "Completed: #{current_command.name}"
+        finalize_command
+        @state = :ready
+        send_next_command
+      when @response.executing?
+        log "Executing: #{current_command.name}"
+        run_command_setup
+        @state = :executing
+      when @response.executed? && current_command
+        finalize_command
+				unless interrupted?
+					@state = :ready
+					send_next_command
+				end
+      when @response.dtmf?
+        log "Button pressed: #{@response.body[:dtmf_digit]}"
+        handle_dtmf
+      when @response.speech?
+      when @response.disconnect?
+        log "Disconnected."
+        cleanup
+        notify_observers :hungup
+        Larynx.fire_callback(:hungup, self)
+        @state = :waiting
+      end
+    end
+
+    def handle_dtmf
+      @input << @response.body[:dtmf_digit]
+      interrupt_command
+      notify_observers :dtmf_received, @response.body[:dtmf_digit]
+      send_next_command if @state == :ready
+    end
+
+    def current_command
+      @queue.first
+    end
+
+    def interrupting?
+      current_command && current_command.command == 'break'
+    end
+
+    def interrupted?
+      last_command && last_command.command == 'break'
+    end
+
+    def run_command_setup
+      current_command.fire_callback :before
+    end
+
+    def finalize_command
+      if command = @queue.shift
+        command.fire_callback :after
+        @last_command = command
+      end
+    end
+
+    def send_next_command
+      if current_command
+        @state = :sending
+        send_data current_command.to_s
+      end
+    end
+
+    def log(msg)
+      LARYNX_LOGGER.info msg
+    end
+
+  end
+end

data/lib/larynx/callbacks.rb

@@ -0,0 +1,32 @@
+module Larynx
+  module Callbacks
+
+    def self.included(base)
+      base.extend ClassMethods
+      base.class_eval do
+        include InstanceMethods
+      end
+    end
+
+    module ClassMethods
+      def define_callback(*callbacks)
+        callbacks.each do |callback|
+          class_eval <<-DEF
+            def #{callback}(&block)
+              @callbacks ||= {}
+              @callbacks[:#{callback}] = block
+              self
+            end
+          DEF
+        end
+      end
+    end
+
+    module InstanceMethods
+      def fire_callback(callback, *args)
+        @callbacks && @callbacks[callback] && @callbacks[callback].call(*args)
+      end
+    end
+
+  end
+end