The FilePlayer property

class UASCallFilePlayer

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

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

UASCallFilePlayer.cause()

This function will return a cause.

When a play job terminates, the reason why can be requested by calling this function. If this function is called while a play job is still running, the cause will be NONE.

UASCallFilePlayer.play(filename, barge_in=False)

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.

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

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

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

If barge_in is set to True, the playback may be interrupted by a dtmf keypress.

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

UASCallFilePlayer.say_start(text, barge_in=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 begin speaking 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.

If barge_in is set to True, the playback may be interrupted by a dtmf keypress.

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

UASCallFilePlayer.start(filename, barge_in=False, loop=False)

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.

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

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

UASCallFilePlayer.state()

This function will return the current state.

When a play job is busy, its state can be tracked by calling this function. If this function is called while when no play job is in progress, the state will be IDLE.

UASCallFilePlayer.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()

UASCallFilePlayer.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()