The FilePlayer property¶

class UASCallFilePlayer¶

A class that provides an API for playing a .wav file on a call.

The call channel object uses this class to provide file playback functionality. The call channel object has a public property called FilePlayer of this type. Please see the tutorial for examples on how to use this class.

Some of the examples given below will play a file. The file must reside on the cloud and can be manually uploaded via the file management page of cloud.aculab.com - while logged in to cloud.aculab.com, click Manage then Media Files.

Please also have a look at the Web Services API for instructions and examples on automatically uploading files to the cloud.

Please note, before working with media files it is important that you also read the section about media files which describes some of the effects of Eventual Consistency.

class Cause¶

Once a play job has ended and the play state has returned to IDLE or ERROR, the cause will be one of these.

Play termination causes are:

ERROR: play has stopped due to an error.
NORMAL: play has stopped normally.
BARGEIN: play has stopped due to a DTMF digit being detected.
ABORTED: play has been aborted (probably because stop was called).
HANGUP: play ended due to a call hang-up.
TIMEOUT: play stopped because a timer has expired.
NONE: play is in progress or play has not occurred.

Usage example:

cause = channel.FilePlayer.cause()
if cause == channel.FilePlayer.Cause.BARGEIN:
    # replay interrupted by DTMF
    pass

class State¶

The play state can be checked to determine whether a play job is in progress. When a play job ends, the play termination cause can be checked to find the reason why.

Play states are:

PLAYING: a play job is in progress.
IDLE: no play job is in progress.
ERROR: a play job failed.

Usage example:

state = channel.FilePlayer.state()
if state == channel.FilePlayer.State.PLAYING:
    # replay to a call is in progress
    pass

cause()¶

This function will return a cause.

When a particular job terminates, the reason why can be requested by calling this function.

If this function is called while a job is still running, the cause will be NONE.

play(filename, barge_in=False, cipher=None)¶

Play a media file to the current call channel.

Required argument:

filename
the name of the file to play.

Optional arguments:

barge_in
option to allow barge-in. Default is False.
cipher
if the file to play is encrypted, supply the cipher so it can be decrypted before playing.

This function is provided to play a pre-recorded .wav file to the current call channel. The following sampling rates are supported:

6000Hz

8000Hz,

11000Hz

11025Hz.

Of these, 8000Hz provides the best quality since it matches the sampling rate used on calls.

The following codecs are supported:

G.711 A-law

G.711 mu-law

OKI ADPCM

IMA ADPCM

16-bit PCM (signed 16-bit)

8-bit PCM (unsigned 8-bit)

Of these, G.711 A-law, G.711 mu-law and 16-bit PCM provide the best quality since the first two match those used on calls and the last can convert to them without degradation.

If barge_in is set to True, the playback may be interrupted by a DTMF key-press.

If the call state is IDLE, this function will raise a Hangup exception. If the call state is not IDLE but also not ANSWERED, this function will raise an Error exception.

If the play state is already PLAYING, this function will raise an Error exception. If the call channel already has an external audio source, e.g, it is connected to another call channel, this function will raise an Error exception.

This function will block until the playback has completed or a timeout has expired. The time allocated to play the file is the expected amount of time taken to play the file.

Upon return, this function will return a cause.

Usage example:

cause = channel.FilePlayer.play(filename='playfile.wav', barge_in=True)
if cause == channel.FilePlayer.Cause.BARGEIN:
    # play stopped due to DTMF
    pass

say(text, barge_in=False)¶

Say a text string (using text to speech) to the current call channel.

Required argument:

text
the text string to say.

Optional arguments:

barge_in
option to allow barge-in. Default is False.

This function is provided to speak a text string to the current call channel. This function will use text to speech (TTS) to turn the text string into a WAV file which is then played in the normal manner.

Please read the text to speech documentation which explains about escaping reserved characters and using unicode.

If barge_in is set to True, the playback may be interrupted by a DTMF key-press.

If the call state is IDLE, this function will raise a Hangup exception. If the call state is not IDLE but also not ANSWERED, this function will raise an Error exception.

If the play state is already PLAYING, this function will raise an Error exception. If the call channel already has an external audio source, e.g, it is connected to another call channel, this function will raise an Error exception.

This function will block until the WAV playback has completed or a timeout has expired. The time allocated to say the text is the expected amount of time taken to play the WAV file.

Upon return, this function will return a cause.

Usage example:

cause = channel.FilePlayer.say(text='good morning', barge_in=True)
if cause == channel.FilePlayer.Cause.BARGEIN:
    # play stopped due to DTMF
    pass

Please see the tutorial for more TTS examples.

say_start(text, barge_in=False, loop=False)¶

Begin speaking a text string (using text to speech) to the current call channel.

Required argument:

text
the text string to say.

Optional arguments:

barge_in
option to allow barge-in. Default is False.

This function is provided to speak a text string to the current call channel. This function will use text to speech (TTS) to turn the text string into a WAV file which is then played in the normal manner.

Please read the text to speech documentation which explains about escaping reserved characters and using unicode.

If barge_in is set to True, the playback may be interrupted by a DTMF key-press.

If the call state is IDLE, this function will raise a Hangup exception. If the call state is not IDLE but also not ANSWERED, this function will raise an Error exception.

If the play state is already PLAYING, this function will raise an Error exception. If the call channel already has an external audio source, e.g, it is connected to another call channel, this function will raise an Error exception.

This function will block until the WAV playback has begun or a timeout has expired.

Upon return, this method will return True for success, otherwise False.

Usage example:

# Start saying some text.
if channel.FilePlayer.say_start(text="good morning") == True:
    # after playback has begun, we can do something else
    # and then wait for it to finish.
    cause = channel.FilePlayer.wait_until_finished()
else:
    # The function returned False, this probably means that
    # the acknowledgement to indicate that playback has begun
    # did not arrive in time, and the function has timed out.
    pass

Please see the tutorial for more TTS examples.

start(filename, barge_in=False, loop=False, cipher=None)¶

Begin playback of a media file to the current call channel.

Required argument:

filename
the name of the file to play.

Optional arguments:

barge_in
option to allow barge-in. Default is False.
loop
loop the play job. Default is False.
cipher
if the file to play is encrypted, supply the cipher so it can be decrypted before playing.

This function is provided to play a pre-recorded .wav file to the current call channel. The following sampling rates are supported:

6000Hz

8000Hz,

11000Hz

11025Hz.

Of these, 8000Hz provides the best quality since it matches the sampling rate used on calls.

The following codecs are supported:

G.711 A-law

G.711 mu-law

OKI ADPCM

IMA ADPCM

16-bit PCM (signed 16-bit)

8-bit PCM (unsigned 8-bit)

Of these, G.711 A-law, G.711 mu-law and 16-bit PCM provide the best quality since the first two match those used on calls and the last can convert to them without degradation.

If barge_in is set to True, the playback may be interrupted by a DTMF key-press.

If loop is True, playback will automatically restart when it finishes.

If the call state is IDLE, this function will raise a Hangup exception. If the call state is not IDLE but also not ANSWERED, this function will raise an Error exception.

If the play state is already PLAYING, this function will raise an Error exception. If the call channel already has an external audio source, e.g, it is connected to another call channel, this function will raise an Error exception.

This function will block until the playback has begun or a timeout has expired.

Upon return, this method will return True for success, otherwise False.

Usage example:

# Start playing a file.
if channel.FilePlayer.start(filename="playfile.wav") == True:
    # while the file is playing, we can do something else;
    # and then wait for it to finish.
    cause = channel.FilePlayer.wait_until_finished()
else:
    # The function returned False, this probably means that
    # the acknowledgement to indicate that playback has begun
    # did not arrive in time, and the function has timed out.
    pass

state()¶

This function will return the current state.

When a particular job is busy, its state can be tracked by calling this function.

If this function is called while when no job is in progress, the state will be IDLE.

stop()¶

Stop playback of a media file to the current channel.

Calling this method will abort any current playback. However, it is unnecessary to stop any media operation upon call hang-up, as that is done automatically.

If the call state is IDLE, this function will raise a Hangup exception. If the call state is not IDLE but also not ANSWERED, this function will raise an Error exception.

If the play state is not PLAYING, this function will simply return True. Otherwise, this call will block until the playback has stopped or a timeout has expired.

Upon return, this method will return True for success, otherwise False.

Usage example:

# Start playing a file (loop forever) and then stop it.
if channel.FilePlayer.start(filename="playfile.wav", loop=True) == True:
    # while the file is playing, we can do something else
    # ...
    # then stop it.
    channel.FilePlayer.stop()

wait_until_finished(seconds_timeout=0)¶

Wait until the current media playing is complete.

Optional argument:

seconds_timeout
the amount of time allocated to wait for the play job to terminate. Default is to use the estimated remaining amount of time to play file.

If the call state is IDLE, this function will raise a Hangup exception. If the call state is not IDLE but also not ANSWERED, this function will raise an Error exception.

This function will block until the current play job has finished or the timeout has expired. Giving a value of None for seconds_timeout will enable an infinite wait. If the timeout does expire, this function will return a cause of TIMEOUT.

Upon return, this function will return a cause.

Usage example:

# Start playing a file and then wait for it to finish.
if channel.FilePlayer.start(filename="playfile.wav") == True:
    # do something else for a bit
    cause = channel.FilePlayer.wait_until_finished()

The FilePlayer property¶

Table of Contents

Previous topic

Next topic