Revision as of 10:50, 20 November 2012

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.

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

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.

Features for playing files

Load sharing

Playing a chain of multiple files

Start/end offsets, repeat count

Pause/Resume

Live transcoding

Audio gain

Playing remote (HTTP) files

RAM caching

Features for recording files

Load sharing

Live transcoding

Performance

Expected performance

Simultaneous playing files

Number of file play per second

Typical bottlenecks

Good example of well-balanced host hardware