Customer application framework:play audio files - Revision history

Allyntree at 14:48, 12 September 2022

2022-09-12T14:48:06Z

← Older revision		Revision as of 10:48, 12 September 2022
Line 1:		Line 1:
			{{DISPLAYTITLE:Customer application framework:play audio files}}
	= Overview =		= Overview =
	The CAF (customer application framework) API offers functions to play or record audio files:		The CAF (customer application framework) API offers functions to play or record audio files:
Line 48:		Line 49:

	==== A relative path ====		==== A relative path ====
	Path ~~are~~ relative to tbstreamserver application's working directory:		Path is relative to tbstreamserver application's working directory:
	* ''/lib/tb/toolpack/setup/12358/2.7/apps/tbstreamserver/''		* ''/lib/tb/toolpack/setup/12358/2.7/apps/tbstreamserver/''
	(in the path above, replace ''12358'' by your [[System_id\|System Id]], and ''2.7'' by your current Toolpack major version)		(in the path above, replace ''12358'' by your [[System_id\|System Id]], and ''2.7'' by your current Toolpack major version)
Line 75:		Line 76:
	==== Syntax of file choice ====		==== Syntax of file choice ====
	Providing a file choice is done by created a coma-separated list of file choices, under parenthesis:		Providing a file choice is done by created a coma-separated list of file choices, under parenthesis:
	(first_path,second_path,third_path)		(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)		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)

Line 85:		Line 86:

	== ''RecordStream'' / ''MixerRecordStream'' ==		== ''RecordStream'' / ''MixerRecordStream'' ==
	Class ''CTBCMC_RECORD_ATTRIBUTE'' is used to build ~~recprd~~ attributes. Available attributes are:		Class ''CTBCMC_RECORD_ATTRIBUTE'' is used to build record attributes. Available attributes are:
	* ''AddRecFilePath'': Function to set the path of the file to record (Note: URI not supported when recording)		* ''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		* ''fRecordTones'': Indicates if tones (DTMF) must be recorded or suppressed from the recording
Line 143:		Line 144:
	* Each playing "index" can be controlled in an independent manner (started, stopped, paused, resumed)		* 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		* 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 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 ==		== Audio gain ==
Line 285:		Line 286:
	Notes:		Notes:
	* Reaching these levels of performance may require to update the Stream Server configuration to allow 2 transcoding CPU cores, and 512MB of RAM		* Reaching these levels of performance may require to update the Stream Server configuration to allow 2 transcoding CPU cores, and 512MB of RAM
	* CPU usage may appear non-linear in some cases, mostly because of effects of ~~HyperThreading~~ (the CPU has 2 ~~physcal~~ cores + 2 virtual "hyperthread" cores which don't have the same processing capacity as the physical cores)		* CPU usage may appear non-linear in some cases, mostly because of effects of Hyper Threading (the CPU has 2 physical cores + 2 virtual "hyperthread" cores which don't have the same processing capacity as the physical cores)

	=== Disk performance ===		=== Disk performance ===

Abrassard: /* Helpful variables to build play/file paths */

2014-06-05T20:24:32Z

Helpful variables to build play/file paths

← Older revision		Revision as of 16:24, 5 June 2014
Line 178:		Line 178:
	* ".wav" (no transcoding required, easier to open with audio editors due to standard "wav" file format)		* ".wav" (no transcoding required, easier to open with audio editors due to standard "wav" file format)

	= Helpful variables to build play/file paths =		= Helpful variables to build play or record file paths =
	When providing the a path to play or record a file, Toolpack will automatically replace some variables found in the path by appropriate value.		When providing the a path to play or record a file, Toolpack will automatically replace some variables found in the path by appropriate value.

Abrassard: /* Features for recording files */

2014-06-05T20:19:30Z

Features for recording files

@@ Line 177: / Line 177: @@
 * ".vox" (light-weight transcoding required, saves 2x disk space compared to .alaw files)
 * ".wav" (no transcoding required, easier to open with audio editors due to standard "wav" file format)
 = Performance =

Abrassard: /* A relative path */

2014-02-07T11:29:53Z

A relative path

← Older revision		Revision as of 07:29, 7 February 2014
Line 40:		Line 40:

	In a sequence of files to play, a mix of relative path, absolute path or URI can be used without restriction.		In a sequence of files to play, a mix of relative path, absolute path or URI can be used without restriction.

			==== An absolute path ====
			Absolute path can be used.
			Examples of absolute paths:
			/lib/tb/toolpack/pkg/prompts/welcome.vox
			c:/audio/test.pcm

	==== A relative path ====		==== A relative path ====

Abrassard: /* An absolute path */

2014-02-07T11:29:40Z

An absolute path

← Older revision		Revision as of 07:29, 7 February 2014
Line 55:		Line 55:
	* C++ API ''CTBCAFPlayAttributes::AddPlayList'' yields the same result: Using folder ''/lib/tb/toolpack/pkg/prompts/''		* C++ API ''CTBCAFPlayAttributes::AddPlayList'' yields the same result: Using folder ''/lib/tb/toolpack/pkg/prompts/''
	* C++ API ''CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath'' assumes a relative path (see above)		* C++ API ''CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath'' assumes a relative path (see above)

	~~==== 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 URI of a file on a HTTP server ====

Abrassard: /* A relative path */

2014-02-07T11:29:21Z

A relative path

← Older revision		Revision as of 07:29, 7 February 2014
Line 47:		Line 47:

	Examples of relative paths:		Examples of relative paths:
	prompts/my_prompt.wav		file://prompts/my_prompt.wav
	../../../audio_files/hello_world.alaw		file://../../../audio_files/hello_world.alaw

			==== A file name without a path ====
			When providing a file name without a path, there are two possible behaviors:
			* From routing scripts, the default "prompts" folder will be used: ''/lib/tb/toolpack/pkg/prompts/''
			* C++ API ''CTBCAFPlayAttributes::AddPlayList'' yields the same result: Using folder ''/lib/tb/toolpack/pkg/prompts/''
			* C++ API ''CTBCMC_PLAY_ATTRIBUTE::AddPlayFilePath'' assumes a relative path (see above)

	==== An absolute path ====		==== An absolute path ====

Abrassard: /* Failure recovery */

2013-07-02T10:52:44Z

Failure recovery

← Older revision		Revision as of 06:52, 2 July 2013
Line 308:		Line 308:
	** Drop the call		** Drop the call
	** etc...		** etc...


			= RAM caching =
			The tbstreamserver application will make maximum use of the RAM that it's been allowed to use (as defined in it's Web Portal configuration page).

			In fact, it's using available RAM to cache recently played files, so the next time they're played it's not required to read them from disk. This caching mechanism has the following advantages:
			* Increased performance per hard drive (number of play per second, and/or number of sustainable simultaneous playbacks)
			* Increased hard drive life span due to reduce number of head moves
			* Improved responsiveness (latency) for starting to play files during higher load or bursts of new files to play

			== RAM usage and Linux Swappiness ==
			However, modern operating systems (such as Linux) tend to swap out to hard drive portions of RAM that have not been accessed for long periods... and unfortunately, this can be the case for tbstreamserver's RAM cache. And having RAM cache swapped out to disk is the worse thing that can happen. It's actually much worse than not caching the file at all (it can even affect all playing channels by completely stalling the application for few seconds).

			To prevent that, Linux can be instructed NOT to swap out untouched portions of RAM aggressively. This is known as "swappiness".

			'''<big>It is highly recommended, for any system running tbstreamserver (or toolpack system in general) to set swappiness to close to 0</big>''' (the default being 60, which is definitely not suitable for any real-time software).

			You can find information on swappiness and how to modify it here:
			http://en.wikipedia.org/wiki/Swappiness

Abrassard: Added section about how to handle stream server failure

2013-06-17T10:24:55Z

Added section about how to handle stream server failure

← Older revision		Revision as of 06:24, 17 June 2013
Line 294:		Line 294:
	** Not too small to avoid large number of empty HTTP "GET" requests to re-validate file modification dates with the server		** Not too small to avoid large number of empty HTTP "GET" requests to re-validate file modification dates with the server
	** Not too large to avoid unnecessary delays when a file content is modified, before the Stream Server notices the file was changed		** Not too large to avoid unnecessary delays when a file content is modified, before the Stream Server notices the file was changed

			= Failure recovery =
			If the stream server application fails, or if the host on which it was running fails:
			* Call control application is notified that playbacks and recording are stopped:
			** OnStreamPlayingDone( with cause TBCMC_IVR_REASON_CODE_DISCONNECTED )
			** OnStreamRecordingDone( with cause TBCMC_IVR_REASON_CODE_DISCONNECTED )

			No action is automatically taken by Toolpack. The application will decide how to handle that interrupted playback or recording.
			* If another stream server is available (on another redundant host), the application may decide to:
			** Restart the playback from the beginning, or from the offset it had already reached in the played file
			** Restart the recording
			** For an IVR call, reset to "top" of the menu after playing a "sorry" prompt
			** Drop the call
			** etc...

Abrassard: /* Load sharing */

2013-06-17T10:13:00Z

Load sharing

← Older revision		Revision as of 06:13, 17 June 2013
Line 161:		Line 161:
	* First, see if a file with same path already exists on on of the Stream Servers. Override this file if found (to avoid two recorded files with the same path!)		* First, see if a file with same path already exists on on of the Stream Servers. Override this file if found (to avoid two recorded files with the same path!)
	* If file does not exist anywhere, the least loaded Stream Server is chosen		* If file does not exist anywhere, the least loaded Stream Server is chosen
			* If the file would be found on more than 1 stream server hosts (presumably because it happened to be recorded on a host while the other host was down, but that other host already had a copy of that file), then stream server will choose any of the stream servers for recording (based on load sharing) and will delete extra copies of that file with same path.

	== Live transcoding ==		== Live transcoding ==

Abrassard: /* Good example of well-balanced host hardware */

2013-05-23T12:45:30Z

Good example of well-balanced host hardware

← Older revision		Revision as of 08:45, 23 May 2013
Line 293:		Line 293:
	** Not too small to avoid large number of empty HTTP "GET" requests to re-validate file modification dates with the server		** Not too small to avoid large number of empty HTTP "GET" requests to re-validate file modification dates with the server
	** Not too large to avoid unnecessary delays when a file content is modified, before the Stream Server notices the file was changed		** Not too large to avoid unnecessary delays when a file content is modified, before the Stream Server notices the file was changed



	~~== Good example of well-balanced host hardware ==~~