Actions

Customer application framework:play audio files: Difference between revisions

Line 103: Line 103:


== Start/end offsets, repeat count ==
== 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 ==
== 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 ==
== 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.
== Audio gain ==
== Audio gain ==
== Playing remote (HTTP) files ==
== Playing remote (HTTP) files ==
== Caching ==
== Caching ==

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

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