Actions

Customer application framework:play audio files: Difference between revisions

Line 89: Line 89:


= Features for playing files =
= Features for playing files =
Here is a list of features supported when playing files with ''PlayStream()'' or ''MixerPlayStream()'' API calls:
== Load sharing ==
== Load sharing ==
When a file play is requested, Toolpack will try to do load sharing among available Stream Server applications (on various Toolpack hosts):
* See which server has the most known files among the sequence of files to play
* If more than on server have the files, the least loaded Stream Server is chosen
== Playing a chain of multiple files ==
== Playing a chain of multiple files ==
== Providing choice between multiple files ==
== Providing choice between multiple files ==
== Start/end offsets, repeat count ==
== Start/end offsets, repeat count ==
Line 97: Line 105:
== Audio gain ==
== Audio gain ==
== Playing remote (HTTP) files ==
== Playing remote (HTTP) files ==
== RAM caching ==
== Caching ==
For performance reasons, different levels of caching are used when playing files:


= Features for recording files =
= Features for recording files =

Revision as of 12:12, 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.

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

Features for playing files

Here is a list of features supported when playing files with PlayStream() or MixerPlayStream() API calls:

Load sharing

When a file play is requested, Toolpack will try to do load sharing among available Stream Server applications (on various Toolpack hosts):

  • See which server has the most known files among the sequence of files to play
  • If more than on server have the files, the least loaded Stream Server is chosen

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

Caching

For performance reasons, different levels of caching are used when playing files:

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