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 here for details)
  • 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

When calling PlayStream() API, a sequence of multiple files can be provided. For each file in the sequence, a start offset, a end offset and a repeat count can be provided.

Providing choice between multiple files

As explained here, it's possible to provide multiple choices for a file to play, and the Stream Server application will play the first found file from the choices.

Start/end offsets, repeat count

For each file in a sequence of files to play, a start offset, a end offset and a repeat count can be provided. A global repeat count (for the whole sequence) can also be provided.

Pause/Resume

Playing streams can be paused or resumed at any time during a call flow, using the PauseStream(), ResumeStream(), MixerPauseStream() or MixerResumeStream() API calls. Pausing or resuming a stream does not modify any hardware resources, and thus has a minimal cost and impact on system performance.

Live transcoding

Stream server supports playing files from various formats. When a playing file is not already in TDM format (aLaw, 8Khz, mono), it will be transcoded "live" to TDM format.

Supported file formats are:

• ".alaw": Raw alaw encoded audio file (8khz, 8 bits, mono, alaw)
• ".ulaw": Raw ulaw encoded audio file (8khz, 8 bits, mono, ulaw)
• ".pcm" : Linear 16 bits PCM audio file (8khz, 16 bits, mono)
• ".g721": ADPCM 32Kbps, G721 encoding (Note: heavy CPU usage when transcoding)
• ".g723": ADPCM 24Kbps, G723 encoding (Note: heavy CPU usage when transcoding)
• ".g726": ADPCM 16Kbps, G726 encoding (Note: heavy CPU usage when transcoding)
• ".vox" : ADPCM 32Kbps encoding
• ".vox6": ADPCM 24Kbps (6Kbps sampling rate) encoding
• ".wav" : Microsoft Wave file format using any of the following options:
  • Encodings:
    • aLaw / uLaw
    • PCM 8 bits / 16 bits
    • ADPCM (G721 32Kbps, G723 24Kbps or G726 16Kbps, VOX)
  • Channels:
    • Mono / Stereo
  • Sample rate:
    • 8Khz, 11.025Khz, 16Khz, 22.05Khz, 44.1Khz or 48Khz

Audio mixing

The CAF PlayStream() and MixerPlayStream() API calls both support to manage multiple simultaneously playing sequence of files (using the un8PlayIndex attribute):

• Each play sequence is assigned an "index" (un8PlayIndex)
• Each playing "index" can be controlled in an independent manner (started, stopped, paused, resumed)
• Each playing "index" can have it's own independent audio gain
• Audio output of all simultaneously playing sequences (all "indexes") is mixed by the Stream Server application, and sent to TMedia units as one audio stream (and thus does not require increased Ethernet bandwidth on the LAN between Stream Server and TMedia)

Audio gain

An audio gain (or loss) can be provided to a playing file, in case some audio files on disk are known to have inappropriate level. This is also very useful when "mixing" multiple playing streams to the same call leg (or same audio mixer).

Playing remote (HTTP) files

The Stream Server is able to play files that are located to remote HTTP servers.

• Files are loaded from server chunk by chunk, when required (to avoid loading big files entirely when only beginning is being played)
• HTTP server download chunk size can be adjusted (smaller chunks more suitable for short call durations, longer chunks more efficient due to reduced number of HTTP download requests per second)
• A local disk cache is used on the Stream Server host to avoid loading multiple times recently accessed files from HTTP servers.
• File modification date checks are performed once in a while (can be configured) so Stream Server can detect if a cached file has been modified on the server
• Multiple download connections per server are used (can be configured) for increased performance, in particular when servers have multiple hard drives that can simultaneously perform multiple IO operations, or when network latency is high compared to available bandwidth

Caching

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

• Caching of remote HTTP files on local disk (size can be configured, we recommend 10GB to 1TB of local disk cache)
• Caching of recently played files into RAM (size can be configured, we recommend 1G to 10GB of RAM cache)
• Caching of known files (in order to Toolpack to always search all Stream Servers to know which server(s) have the requested file)