Actions

Customer application framework:play audio files

Revision as of 12:00, 20 November 2012 by Abrassard (talk | contribs)

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

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

Features for playing files

Load sharing

Playing a chain of multiple files

Providing choice between 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

Retrieved from "https://docs.telcobridges.com/index.php?title=Customer_application_framework:play_audio_files&oldid=12551"