==============================================
       iSpeech plugins for Asterisk
==============================================

These plugins provide access to iSpeech Text To Speech and Automatic Speech Recognition
services making them available for use with Asterisk PBX.
http://www.ispeech.org/

------------
Requirements
------------
Perl             The Perl Programming Language
libwww-perl      The World-Wide Web library for Perl (LWP)
IO::Socket::SSL  Perl module that implements an interface to SSL sockets.
URI::Escape      Perl module for "URI escaping".
format_mp3       Asterisk mp3 format support.

An API key from iSpeech: To obtain an API key please visit:
http://www.ispeech.org/developers and register for a developer account.

Internet access in order to contact iSpeech and get the speech and text data.

** Optional**
speex         patent-free audio compression format designed for speech.

------------
Installation
------------
To install copy ispeech-asr.agi and ispeech-tts.agi to your agi-bin directory.
Usually this is /var/lib/asterisk/agi-bin/
To make sure check your /etc/asterisk/asterisk.conf file

-----
Usage
-----

  agi(ispeech-tts.agi,"text",[voice],[intkey],[speed]):
This will invoke the iSpeech TTS engine, render the text string to speech and play it
back to the user. If 'intkey' is set the script will wait for user input.
Any given interrupt keys will cause the playback to immediately terminate and
the dialplan to proceed to the matching extension (this is mainly for use in IVR,
see README for examples). If 'speed' is set the speech rate is altered by that factor.


  agi(ispeech-asr.agi,[lang],[freeform],[model],[timeout],[intkey],[NOBEEP]):
Records from the current channel untill 3 seconds of silence are detected
(this can be set by the user by the 'timeout' argument, -1 for no timeout) or the
interrupt key (# by default) is pressed. If NOBEEP is set, no beep sound is played
back to the user to indicate the start of the recording. For 'freeform' and 'model'
please refer to the ispeech API manual. 'freeform' defaults to 3 (Normal speech)
The recorded sound is send over to iSpeech ASR service and the
returned text string is assigned as the value of the channel variable 'utterance'.

The script sets the following channel variables:
status     : Return status. 0 means success, non zero values indicate different errors.
utterance  : The generated text string.
confidence : A value between 0 and 1 indicating how 'confident' the recognition engine
    feels about the result. Values bigger than 0.90 usually mean that the
    resulted text is correct.

--------
Examples
--------
sample dialplan code for your extensions.conf

;iSpeech TTS test
exten => 3,1,Answer()
exten => 3,n,agi(ispeech-tts.agi,"This is a test of the ispeech text to speech engine in asterisk.")
exten => 3,n,agi(ispeech-tts.agi,"Esta es una simple prueba en español.",usspanishfemale)
exten => 3,n,agi(ispeech-tts.agi,"这是一个简单的测试，在中国。有一个愉快的一天。",chchinesefemale)
exten => 3,n,Hangup()


;Speech recognition test
exten => 4,1,Answer()
exten => 4,n,agi(ispeech-tts.agi,"Please say something in English. When done press the pound key.")
exten => 4,n(record),agi(ispeech-asr.agi,en-US)
exten => 4,n,Noop(== Script returned: ${status} , ${confidence} , ${utterance} ==)
exten => 4,n,GotoIf($["${status}" = "0"]?success:fail)

exten => 4,n(success),GotoIf($["${confidence}" > "0.3"]?playback:retry)

exten => 4,n(retry),agi(ispeech-tts.agi,"Can you please repeat more clearly?")
exten => 4,n,goto(record)

exten => 4,n(playback),agi(ispeech-tts.agi,"The text you just said was...")
exten => 4,n,agi(ispeech-tts.agi,"${utterance}")
exten => 4,n,goto(end)

exten => 4,n(fail),agi(ispeech-tts.agi,"Failed to get speech data.")
exten => 4,n(end),Hangup()


;Voice dialing example
exten => 5,1,Answer()
exten => 5,n,agi(ispeech-tts.agi,"Please say the number you wish to dial.")
exten => 5,n(record),agi(ispeech-asr.agi,en-US,,phonenumber)
exten => 5,n,GotoIf($[$["${status}" = "0"] & $["${confidence}" > "0.3"]]?success:retry)

exten => 5,(success),agi(ispeech-tts.agi,"Dialing ${utterance}")
exten => 5,n,goto(${utterance},1)

exten => 5,n(retry),agi(ispeech-tts.agi,"Can you please repeat?")
exten => 5,n,goto(record)


;IVR test
exten => 6,1,goto(my_ivr,s,1)

[my_ivr]
exten => s,1,Answer()
exten => s,n,Set(TIMEOUT(digit)=5)
exten => s,n,Set(TIMEOUT(response)=8)
exten => s,n,agi(ispeech-tts.agi,"Welcome to my small interactive voice response menu.")
exten => s,n(start),agi(ispeech-tts.agi,"Please dial a digit.",,any)
exten => s,n,Waitexten()

exten => _X,1,agi(ispeech-tts.agi,"You just pressed ${EXTEN}. Try another one please.",,any)
exten => _X,n,Waitexten()

exten => i,1,agi(ispeech-tts.agi,"Invalid extension.")
exten => i,n,goto(s,start)

exten => t,1,agi(ispeech-tts.agi,"Request timed out.")
exten => t,n,goto(h,1)


-----------------------
TTS Supported Languages
-----------------------
Standard Voices				Name Alias
=================================================
US English Female			usenglishfemale (default)
US English Male				usenglishmale
UK English Female			ukenglishfemale
UK English Male				ukenglishmale
Australian English			Female auenglishfemale
US Spanish Female			usspanishfemale
US Spanish Male				usspanishmale
Chinese Female				chchinesefemale
Chinese Male				chchinesemale
Hong Kong Cantonese Female	hkchinesefemale
Taiwan Chinese Female		twchinesefemale
Japanese Female				jpjapanesefemale
Japanese Male				jpjapanesemale
Korean Female				krkoreanfemale
Korean Male					krkoreanmale
Canadian English Female		caenglishfemale
Hungarian Female			huhungarianfemale
Brazilian Portuguese Female	brportuguesefemale
European Portuguese Female	eurportuguesefemale
European Portuguese Male	eurportuguesemale
European Spanish Female		eurspanishfemale
European Spanish Male		eurspanishmale
European Catalan Female		eurcatalanfemale
European Czech Female		eurczechfemale
European Danish Female		eurdanishfemale
European Finnish Female		eurfinnishfemale
European French Female		eurfrenchfemale
European French Male		eurfrenchmale
European Norwegian Female	eurnorwegianfemale
European Dutch Female		eurdutchfemale
European Polish Female		eurpolishfemale
European Italian Female		euritalianfemale
European Turkish Female		eurturkishfemale
European Turkish Male		eurturkishmale
European German Female		eurgermanfemale
European German Male		eurgermanmale
Russian Female				rurussianfemale
Russian Male				rurussianmale
Swedish Female				swswedishfemale
Canadian French Female		cafrenchfemale
Canadian French Male		cafrenchmale

-----------------------
ASR Supported Languages
-----------------------
Language				Alias
=======================================
English (US)			en-US (default)
English (Canada)		en-CA
English (UK)			en-GB
English (Australia)		en-AU
Spanish (Spain)			es-ES
Spanish (Mexico)		es-MX
Italian (Italy)			it-IT
French (France)			fr-FR
French (Canada)			fr-CA
Polish (Poland)			pl-PL
Portuguese (Portugal)	pt-PT
Catalan (Catalan)		ca-ES
Chinese (Taiwan)		zh-TW
Danish (Denmark)		da-DK
German (Germany)		fr-FR
Finnish (Finland)		it-IT
Japanese (Japan)		ja-JP
Korean (Korea)			ko-KR
Dutch (Netherlands)		nl-NL
Norwegian (Norway)		nb-NO
Portuguese (Brazil)		pt-BR
Russian (Russia)		ru-RU
Swedish (Sweden)		sv-SE
Chinese (China)			zh-CN
Chinese (Hong Kong)		zh-HK

-----------------------
Security Considerations
-----------------------
These scripts contact iSpeech servers in order send the recorded voice or text and get back
the resulted data. Consider enabling SSL to encrypt all the traffic between
your pbx and iSpeech servers so no 3rd party can eavesdrop your communication.
To do so please set:
my $use_ssl = 1;
in to the 'User defined parameters' in each AGI script.

-------
License
-------
The iSpeech asterisk plugins are distributed under the GNU General Public
License v2. See LICENSE for details.

--------
Homepage
--------
http://zaf.github.io/asterisk-ispeech/