Customer application framework:play audio files

Overview

The CAF (customer application framework) API offers functions to play or record audio files:

On call legs (CTBCAFCallLeg):

• PlayStream()
• RecordStream()

On audio mixers (CTBCAFMixer):

• MixerPlayStream()
• MixerRecordStream()

It also offers callbacks, on the call flow and call behavior classes (based on CTBCAFCallFlow or CTBCAFCallBehavior) to notify the application when files have started playing/recording, and stopped playing/recording:

• OnStreamPlayingStarted()
• OnStreamPlayingDone()
• OnStreamRecordingStarted()
• OnStreamRecordingDone()
• OnMixerStreamPlayingStarted()
• OnMixerStreamPlayingDone()
• OnMixerStreamRecordingStarted()
• OnMixerStreamRecordingDone()

API parameters

PlayStream / MixerPlayStream

Class CTBCMC_PLAY_ATTRIBUTE is used to build play attributes. Available attributes are:

• AddPlayFilePath: Function to add a file to the list of files to play. Has some parameters:
  • File path (or URI) (see below)
  • Start/end offsets (optional)
  • Repeat count (optional) specific for this file in the sequence of files
• fAllowBargeInInterruption: Allow barge-in interruption (automatic stopping of playback upon detected DTMF)
• fPrepareForRecording: Prepare hardware resources for recording (pre-reserve recording resources). Provides performance gain when both playing/recording on a call leg or mixer.
• un32RepeatCount: Number of times to play the whole file sequence of files
• fNotifyStartOfNewFile: Asks for OnStreamPlayingStarted (or OnMixerStreamPlayingStarted) events for each file in the sequence of files (otherwise, one for the whole sequence)
• s8AudioGainDB: Gain (or loss) of audio level
• fAllowMixing: Allow this playing sequence to be mixed with another file sequence simultaneously playing to the same call leg (or mixer)
• un8PlayIndex: Sequence "index" (0 to 3) to assign to this playing sequence. Will replace a previous playing sequence using the same index, but will be mixed with simultaneously playing sequences with other indexes on the same call leg (or mixer).
• fPaused: Prepare the playback, but start paused until further notice.

Play path format

The format of the path used for playing files can be relative, absolute, or a URI of a file on a HTTP server.

In a sequence of files to play, a mix of relative path, absolute path or URI can be used without restriction.

A relative path

Path are relative to tbstreamserver application's working directory:

• /lib/tb/toolpack/setup/12358/2.7/apps/tbstreamserver/

(in the path above, replace 12358 by your System Id, and 2.7 by your current Toolpack major version)

Examples of relative paths:

 prompts/my_prompt.wav
 ../../../audio_files/hello_world.alaw

An absolute path

Absolute path can be used. Examples of absolute paths:

 /lib/tb/toolpack/pkg/prompts/welcome.vox
 c:/audio/test.pcm

The URI of a file on a HTTP server

The Stream Server application supports playing files that are located on a remote HTTP server. In that case, use a standard HTTP URI. Examples of HTTP URI for files on remote servers:

 http://www.my_files_server.com/ring_back_tone/user_1441.wav
 http://10.0.0.10:8080/dir/subdir/file.g723

Using file choice

The Stream Server application is able to choose the first available file among a list of files to choose from.

Choices can be a mix of relative path, absolute path or URI can be used without restriction.

Syntax of file choice

Providing a file choice is done by created a coma-separated list of file choices, under parenthesis:

(first_path,second_path,third_path)

As you can see, this allows the PlayStream API to be used to play a chain of files, each file in the chain can be a choice between multiple files (local, or on remote HTTP server)

Examples

• User custom file, with fall-back to default: (prompts/user_1441/ring_back_tone.wav,prompts/default/ring_back_tone.wav)
• User language, with default language: (prompts/fr/welcome.wav,prompts/en/welcome.wav,prompts/default/welcome.wav)
• Per day of the week prompts: (prompts/monday/menu.wav,prompts/week_day/menu.wav,prompts/default/menu.wav)
• HTTP server redundancy: (http://primary_server/prompts/welcome.wav,http://secondary_server/prompts/welcome.wav,prompts/service_unavailable.wav)

RecordStream / MixerRecordStream

Class CTBCMC_RECORD_ATTRIBUTE is used to build recprd attributes. Available attributes are:

• AddRecFilePath: Function to set the path of the file to record (Note: URI not supported when recording)
• fRecordTones: Indicates if tones (DTMF) must be recorded or suppressed from the recording
• fPrepareForPlaying: Prepare hardware resources for playing (pre-reserve playing resources). Provides performance gain when both playing/recording on a call leg or mixer.
• fPaused: Prepare the recording, but start paused until further notice.

Record path format

The format of the path used for recording files can be relative or absolute. But it cannot be a URI of a file on a HTTP server (not supported).