The WholeCallRecorder property

class UASWholeCallFileRecorder

The CallChannel object uses the class described below to provide whole call recording functionality. The CallChannel object has a public property called WholeCallRecorder of this type. Please see the tutorial for an example on how to use this class.

class Cause

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

Recording termination causes:

ERROR

record has stopped due to an error.

SILENCE

record has stopped due to a silence timeout.

SIZE

record has stopped due to the maximum file size being reached.

ABORTED

record has been aborted (probably because stop was called).

HANGUP

record ended due to a call hangup.

TIMEOUT

record stopped because a timer has expired.

NONE

record is in progress or record has not occurred.

Usage example:

state = channel.WholeCallRecorder.state()
if state != channel.WholeCallRecorder.State.RECORDING:
    # recording a call has terminated
    cause = channel.WholeCallRecorder.cause()
    if cause == channel.WholeCallRecorder.Cause.SILENCE:
        # recording stopped due to silence
        pass
class State

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

Record states:

RECORDING

recording is in progress.

IDLE

recording is not in progress.

ERROR

a record job failed

Usage example:

state = channel.WholeCallRecorder.state()
if state == channel.WholeCallRecorder.State.RECORDING:
    # recording a call 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.

record(filename, file_format='alaw', rate=8000, seconds_timeout=None, max_bytes=0, milliseconds_max_silence=0, milliseconds_initial_silence=0, dtmf_elim=True, recording_mode='mixed', cipher=None)

Record an entire call.

Required argument:
  • filename

    the name of the file to record.

Optional argument:
  • file_format

    the file format to use. Default is alaw.

  • rate

    the rate at which to record. Default is 8000.

  • seconds_timeout

    the amount of time allocated to the record job. Default is None seconds (no timeout).

  • max_bytes

    the maximum size allowed for the file. Default is 0 bytes (no limit).

  • milliseconds_max_silence

    the amount of silence (in milliseconds) after which to stop recording. Default is 0 seconds (no limit).

  • milliseconds_initial_silence

    the amount of silence (in milliseconds) to wait for audio before starting the recording. Default is 0 seconds (no limit).

  • dtmf_elim

    option to eliminate DTMF from the recording. Default is True.

  • recording_mode

    option to set the recording mode. Default is mixed.

  • cipher

    if the recorded file is to be encrypted, supply the cipher so it can be encrypted when recording is completed.

This function is provided to allow the recording of an entire call (both sides of the conversation) to a WAV 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.

If the whole call recorder state is already RECORDING, this function will raise an Error exception.

A whole call recorder cannot be started if the channel is currently using a transmitter function such as play() or play_dtmf(). Additionally, a whole call recorder cannot be started if the call channel is connected to another channel, if it is part of a conference or if it has been added to a music on hold resource. The whole call recorder must be started before these other functions are used.

The optional argument file_format is the audio codec in which to record the media. The default is alaw (G.711 A-law), other options are ulaw (G.711 mu-law), oki (OKI ADPCM), ima (IMA ADPCM) s16bit (signed 16-bit PCM) and u8bit (unsigned 8-bit PCM). Of those, 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 they can convert to the last without degradation.

The optional argument rate is the recording rate in Hz. The default is 8000, other options are 6000, 11000 and 11025. Of those, 8000 provides the best quality since it matches the sampling rate used on calls.

The recording will continue until one of the termination conditions applies. This could be that the maximum file size (max_bytes) has been reached; the silence timeout (milliseconds_max_silence) has been triggered or the initial silence timeout (milliseconds_initial_silence) has been triggered. To turn off the termination conditions, max_bytes=0 means no limit; milliseconds_max_silence=0 means no silence timeout and milliseconds_initial_silence=0 means no initial silence timeout.

The optional argument recording_mode is either mixed or separate. The default is mixed, which records a single channel containing a mix of both sides of the conversation. separate records each side of the conversation to a separate audio channel in the WAV file. When recording separate channels file_format must be one of alaw, ulaw, u8bit and s16bit , and max_bytes, milliseconds_max_silence and milliseconds_initial_silence are ignored.

This function will block until the recording has finished or a timeout (seconds_timeout) has expired.

Upon return, this function will return a termination cause.

Usage example:

# record until finished due to two seconds of silence
cause = channel.WholeCallRecorder.record(filename="recfile",
                                         milliseconds_max_silence=2000)
if cause == channel.WholeCallRecorder.Cause.SILENCE:
    # the recording job was terminated because of two seconds of silence
    pass
start(filename, file_format='alaw', rate=8000, max_bytes=0, milliseconds_max_silence=0, milliseconds_initial_silence=0, dtmf_elim=True, recording_mode='mixed', cipher=None)

Begin the recording of a media file.

Required argument:
  • filename

    the name of the file to record.

Optional argument:
  • file_format

    the file format to use. Default is alaw.

  • rate

    the rate at which to record. Default is 8000.

  • max_bytes

    the maximum size allowed for the file. Default is 0 bytes (no limit).

  • milliseconds_max_silence

    the amount of silence after which to stop recording. Default is 0 seconds (no limit).

  • milliseconds_initial_silence

    the amount of silence (in milliseconds) to wait for audio before starting the recording. Default is 0 seconds (no limit).

  • dtmf_elim

    option to eliminate DTMF from the recording. Default is True.

  • recording_mode

    option to set the recording mode. Default is mixed.

  • cipher

    if the recorded file is to be encrypted, supply the cipher so it can be encrypted when recording is completed.

This function is provided to start the recording of an entire call (both sides of the conversation) to a WAV 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.

If the whole call record state is already RECORDING, this function will raise an Error exception.

A whole call recorder cannot be started if the channel is currently using a transmitter function such as play() or play_dtmf(). Additionally, a whole call recorder cannot be started if the call channel is connected to another channel, if it is part of a conference or if it has been added to a music on hold resource. The whole call recorder must be started before these other functions are used.

The optional argument file_format is the audio codec in which to record the media. The default is alaw (G.711 A-law), other options are ulaw (G.711 mu-law), oki (OKI ADPCM), ima (IMA ADPCM) s16bit (signed 16-bit PCM) and u8bit (unsigned 8-bit PCM). Of those, 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 they can convert to the last without degradation.

The optional argument rate is the recording rate in Hz. The default is 8000, other options are 6000, 11000 and 11025. Of those, 8000 provides the best quality since it matches the sampling rate used on calls.

The recording will continue until one of the termination conditions applies. This could be that the maximum file size (max_bytes) has been reached; the silence timeout (milliseconds_max_silence) has been triggered or the initial silence timeout (milliseconds_initial_silence) has been triggered. To turn off the termination conditions, max_bytes=0 means no limit; milliseconds_max_silence=0 means no silence timeout and milliseconds_initial_silence=0 means no initial silence timeout.

The optional argument recording_mode is either mixed or separate. The default is mixed, which records a single channel containing a mix of both sides of the conversation. separate records each side of the conversation to a separate audio channel in the WAV file. When recording separate channels file_format must be one of alaw, ulaw, u8bit and s16bit , and max_bytes, milliseconds_max_silence and milliseconds_initial_silence are ignored.

This function will block until the recording has started or a timeout has expired.

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

Usage example:

# Start a record job that will terminate on 2 seconds of silence.
if channel.WholeCallRecorder.start(filename="recfile", milliseconds_max_silence=2000) == True:
    # While recording, we can do something else; then wait until recording is complete.
    cause = channel.WholeCallRecorder.wait_until_finished()
    if cause == channel.WholeCallRecorder.Cause.SILENCE:
        # recording stopped due to 2 seconds of silence
        pass
state()

This function will return the current state.

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

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

stop()

Stop a whole call record job.

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 a Error exception.

If the whole call recorder state is not RECORDING, this function will simply return True.

This function will block until the record job terminates or a timeout expires.

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

Usage example:

# Start a record job.
if channel.WholeCallRecorder.start(filename="recfile") == True:
    # While recording, we can do something else; then stop the recording.
    channel.WholeCallRecorder.stop()
wait_until_finished(seconds_timeout=120)

Wait until the current whole call recording job is complete.

Optional argument:
  • seconds_timeout

    the amount of time allocated to wait for the record job to terminate. Default is 120 seconds.

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 recorder terminates or the timeout expires. Giving a value of None for seconds_timeout will enable an infinite wait. If the timeout does expire, a cause of TIMEOUT will be returned.

Upon return, this function will return a termination cause.

Usage example:

# Start a record job that will terminate on 2 seconds of silence.
if channel.WholeCallRecorder.start(filename="recfile",
                              milliseconds_max_silence=2000) == True:
    # While recording, we can do something else
    # then wait until recording is complete.
    cause = channel.WholeCallRecorder.wait_until_finished()
    if cause == channel.WholeCallRecorder.Cause.SILENCE:
        # the recording job was terminated because of silence
        pass