Customer application framework:play audio files
(→Providing choice between multiple files) |
(→Features for playing files) |
||
| 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 11:20, 20 November 2012
Contents |
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:
