Speech recognition grammar object¶

class HighLevelGrammar¶

This class is used with the capture_input function.

The Grammar class represents a textual representation of grammars for use in speech recognition. The grammar defined here is used by Aculab Cloud speech recognition to determine what to listen for and, therefore, defines what a user may say.

The grammar can have a maximum of 2000 characters, but it should be kept simple to ensure a good recognition rate. The accuracy can be optimised by careful programming: designing the grammar to avoid confusable words, and prompting the caller in such a way as to ensure they respond in line with that grammar.

Optional argument:

formatted_grammar:
A grammar string that defines what the speech recognition will listen for.

The argument formatted_grammar, if provided, must adhere to the grammar rules:

The Speech Grammar Format:

All grammars must end with a semicolon.

The most basic grammar instructs the speech detector to listen for a single word, for example, door; will recognise the word door.

A sequence of words can be given, shut the door; will recognise that sequence of words.

Square brackets can be used to make a word optional, so, [please] shut the door; will recognise the sequence with or without the please.

The pipe symbol can be used to provide alternatives, door | gate; will recognise the word door or the word gate.

Round brackets can be used to group words and rules together, so, shut the (door | gate); will recognise “shut the door” or “shut the gate”; whereas, without the round brackets, shut the door | gate, will recognise the phrase “shut the door” or the single word “gate”.

Putting these rules together we can make, [please] shut the (door | gate);.

Capital letters are allowed but results will always be lower case. The non-alphabet characters permitted in words are: apostrophe, full stop (period), hyphen and underscore.

For more grammar rule options and examples please see the online documentation.

Usage example:

from prosody.uas.highlevel import HighLevelGrammar

my_grammar = HighLevelGrammar('yes [please] | no [thanks];')

create_from_alternatives(*alternatives)¶

Create a formatted grammar string from an array of alternatives.

Required argument:

alternatives:
The alternative strings to listen for.

Usage example:

# this example will create the grammar 'yes | no | maybe;'
my_grammar = channel.SpeechDetector.Grammar()
my_grammar.create_from_alternatives('yes', 'no', 'maybe')

create_from_predefined(predefined)¶

Several pre-defined grammars are available for you to use. Please check the website for more options.

Examples:

OneDigit
To recognise a single digit, zero to nine.
TwoDigits
To recognise two digits, zero to nine.
ThreeDigits
To recognise three digits, zero to nine.
FourDigits
To recognise four digits, zero to nine.
FiveDigits
To recognise five digits, zero to nine.
OneToThirtyOne
To recognise a single number, one to thirty one.
SixteenToNinetyNine
To recognise a single number, sixteen to ninety nine.
ZeroToNinetyNine
To recognise a single number, zero to ninety nine.

Usage example:

my_grammar = channel.SpeechDetector.Grammar()
my_grammar.create_from_predefined('OneDigit')

Speech recognition digit options¶

class HighLevelDigitInputOptions¶

This class is used with the capture_input function.

This is a configuration class for setting digit options when doing speech recognition in combination with digit recognition.

Optional arguments:

valid_digits
The string of valid digits. By default the set of valid digits is 0 to 9.
digit_count
The number of digits that will make up the number. Default is 0, no limit.
dtmf_end_digit
A digit from the set ‘0123456789#*’. This must not be the same as the help digit - which is not set in this class. Default is ‘#’.
seconds_digit_timeout
The number of seconds to wait for a digit input. Default is 5.

Usage example:

# Specify the valid digits.
from prosody.uas.highlevel import HighLevelDigitInputOptions
my_digit_input_options = HighLevelDigitInputOptions(valid_digits='12345')

The high level call channel¶

class HighLevelCallChannel¶

The high level channel API is supplied to make it easier to write applications that perform certain common tasks. It comes as a HighLevelCallChannel class that can be used to wrap a channel object and provide additional functions.

The HighLevelCallChannel wrapper can, for instance, be used to quickly create an IVR menu system or automate the process of connecting an incoming call to a new outbound call.

The high level channel API automates a lot of the complexity of some common tasks and also provides default behaviour that will suit most users. Thus turning a task that might otherwise require a few dozen lines of application code into just one or two lines.

To use this class it must first be imported:

from prosody.uas.highlevel import HighLevelCallChannel

Usage example:

from prosody.uas import Hangup, Error
from prosody.uas.highlevel import HighLevelCallChannel

def main(channel, application_instance_id, file_man, my_log, application_parameters):
    high_level_channel = HighLevelCallChannel(channel, my_log)

Once the channel has been wrapped in this way, additional high level functions become available on the new object. All functions and attributes that would normally be available on the channel object are also available on the new high level object.

Please note that the high level channel API is still in beta and may change.

class CapturedInput(input_type, captured_input)¶

This class is used with the capture_input function.

This is the results class for capture_input. This class will contain the type of the captured input - which can be SPEECH or DIGITS - and the captured input itself, which will be a string of words or digits.

Please see the captured input function for a usage example.

call_and_connect(other_call, call_to=None, call_from='', seconds_timeout=120)¶

Connect two calls together. Optionally place an outgoing call prior to connecting.

The current call (the one invoking this function) will normally be an inbound call, other_call will be an outbound call. The other_call may already be connected, or it may still need to be placed.

Required argument:

other_call
a reference to the outbound channel to which the current call is to be connected.

Optional arguments:

call_to
the outbound call destination. Default is None.
call_from
the origin of the outbound call. Default is ‘’.
seconds_timeout
time allocated to make the outbound call. Default is 120.

This is the high level function that will invoke a full-duplex connection between the lines owned by two active calls.

The other_call can be an IDLE channel. If it is, this function will place an outbound call on the channel using the call_to and call_from parameters. If the other_call has already been placed and is in CALL_OUTGOING state or further, then call_from and call_to do not have to be provided.

The current call does not have to be in ANSWERED state when this function is called, but it does have to be progressing.

If the current call isn’t ANSWERED, this function will place ringing on the current call (if it is an inbound call) when the other_call is in RING_OUTGOING state; and it will answer the current call once the other_call is in ANSWERED state.

Once both calls are in ANSWERED state the lines will be connected.

If seconds_timeout is not None, a timeout will apply for making and connecting the calls. The function will return False if the timeout is reached and the calls have not been connected. The default timeout is 120 seconds. A timeout will not affect the state of the calls.

If the current call state goes to IDLE this function will raise a Hangup exception and the other call will be hung up.

If the other call state goes to IDLE and the current call is not ANSWERED, the current call will be rejected with the cause provided by the other call, and the function will return False.

If the other call state goes to IDLE and the current call is ANSWERED, the function will return False without affecting the current call.

For details on specifying the call_to and call_from parameters for PSTN or SIP destinations please see the online documentation for outbound calls.

This function will block until the calls have been connected, the timeout has been reached, or either of the call states has returned to IDLE.

This function will return True on success, else False.

Usage example:

from prosody.uas.highlevel import HighLevelCallChannel

def main(channel, application_instance_id, file_man, my_log, application_parameters):
    out_channel = channel.ExtraChannel[0]

    high_level_channel = HighLevelCallChannel(channel, my_log)
    if high_level_channel.call_and_connect(out_channel, call_to='sip:fred@127.0.0.1:5060;user=phone') is False:
        raise Hangup('Connect to outbound call failed')

    # the calls are connected, carry on

call_and_connect_to_conference(other_call, conference_room_name, talker_and_listener=True, conference_lifetime_control=None, conference_party_media_settings=None, seconds_timeout=120)¶

Connect a call to a conference.

The current call (the one invoking this function) will normally be an inbound call, other_call will be an outbound call call channel.

The other_call must not already be connected.

Required argument:

other_call
a reference to the outbound channel to which the current call is to be connected.
conference_room_name
the name of the conference room to which to add this party.

Optional arguments:

talker_and_listener:
whether the party is allowed to talk, as well as listen, in the conference. Default is True.
conference_lifetime_control:
whether the conference should start when this party enters.
conference_party_media_settings:
file and TTS play options, mute options.
seconds_timeout
time allocated to make the outbound call. Default is 120.

This is the high level function that will invoke a full-duplex connection between the lines owned by two active calls.

The other_call must be an IDLE channel. This function will place an outbound call on the channel using the conference_room_name parameter.