A class that provides an API for recording media from a call.
The call channel object uses this class to provide file recording functionality. The call channel object has a public property called FileRecorder of this type. Please see the tutorial for examples on how to use this class.
Some of the examples given below will record a file. The file will reside on the cloud and can be manually downloaded 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 downloading files from 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.
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:
Usage example:
state = channel.FileRecorder.state()
if state != channel.FileRecorder.State.RECORDING:
# recording a call has terminated
cause = channel.FileRecorder.cause()
if cause == channel.FileRecorder.Cause.SILENCE:
# recording stopped due to silence
pass
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:
Usage example:
state = channel.FileRecorder.state()
if state == channel.FileRecorder.State.RECORDING:
# recording a call in progress
pass
Indicates whether any audio was detected during the record job.
This function should be called only after a record job has completed. If it is called during, or before, a record job it will return None.
If this function returns False, this is an indication that the recording contains no audio. It should contain only silence.
This function will return True if audio was detected during the record job.
Usage example:
# record until finished due to two seconds of silence
cause = channel.FileRecorder.record(filename="recfile",
milliseconds_max_silence=2000)
if cause == channel.FileRecorder.Cause.SILENCE:
# the recording job was terminated because of silence
if channel.FileRecorder.audio_detected_in_recording() is True:
# we did record some none-silence, there is audio in the file.
pass
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 a media file.
This function is provided to allow the recording of a WAV file to a filename specified in filename.
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 record state is already RECORDING, this function will raise an Error exception.
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; the initial
silence timeout (milliseconds_initial_silence) has been triggered or barge in has occurred. 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.
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.FileRecorder.record(filename="recfile",
milliseconds_max_silence=2000)
if cause == channel.FileRecorder.Cause.SILENCE:
# the recording job was terminated because of two seconds of silence
pass
Begin the recording of a media file.
This function is provided to allow the recording of a WAV file to a filename specified in filename.
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 record state is already RECORDING, this function will raise an Error exception.
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; the initial
silence timeout (milliseconds_initial_silence) has been triggered or barge in has occurred. To turn off the termination conditions, max_bytes=0 means no limit; milliseconds_max_silence=0 means no silence timeout and
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.FileRecorder.start(filename="recfile", milliseconds_max_silence=2000) == True:
# While recording, we can do something else; then wait until recording is complete.
cause = channel.FileRecorder.wait_until_finished()
if cause == channel.FileRecorder.Cause.SILENCE:
# recording stopped due to 2 seconds of silence
pass
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 a 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 record 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.FileRecorder.start(filename="recfile") == True:
# While recording, we can do something else; then stop the recording.
channel.FileRecorder.stop()
Wait until the current media recording is complete.
- 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 recording 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.FileRecorder.start(filename="recfile",
milliseconds_max_silence=2000) == True:
# While recording, we can do something else
# then wait until recording is complete.
cause = channel.FileRecorder.wait_until_finished()
if cause == channel.FileRecorder.Cause.SILENCE:
# the recording job was terminated because of silence
pass