Media File Options
Last revised on: November 30, 2009
This chapter covers the following topics:
•Deployment and Ongoing Management
•Co-Resident Call Server, Media Server, and Unified CVP VXML Server
•Bandwidth Calculation for Prompt Retrieval
•Configuring Caching and Streaming in Cisco IOS
•Configuring Caching and Streaming in Cisco IOS
•Branch Office Implications
Deployment and Ongoing Management
Voice prompts can be stored in the following locations:
•In flash memory on each local gateway
In this way, gateways do not have to retrieve .wav files for prompts, so WAN bandwidth is not affected. However, if a prompt needs to change, you must change it on every gateway. Cisco recommends that you store prompts in flash only for critical prompts such as error messages or other messages that can be used when the WAN is down.
•On an HTTP media server
In this way, each local gateway (if properly configured) can cache many or all prompts, depending on the number and size of the prompts (up to 100 MB of prompts). The best way to test whether your media server is appropriately serving the media files is to use a regular web browser such as Internet Explorer and specify the URL of a prompt on the media server, such as http://10.4.33.130/en-us/sys/1.wav. Your web browser should be able to download and play the .wav file without any authentication required.
Co-Resident Call Server, Media Server, and Unified CVP VXML Server
If your Call Server, Media Server, and Unified CVP VXML Server reside on the same hardware server and you have multiple co-resident servers, Unified CVP will not automatically use the same physical server for call control, VXML, and media file services. Just because the components are co-resident, that does not force one component to use the other co-resident components, and it is just as likely to use the components located on another server.
By default, the components are load-balanced across all of the physical servers and do not attempt to use the same server for all of the services. Over the course of thousands of calls, all of the components on all of the servers will be load-balanced and equally utilized, but for one particular call it is possible to be using several different physical servers. Because of this, for one particular call you can be using H.323/SIP call control on one server, VoiceXML on another server, and the media files on yet another server.
You can simplify management and troubleshooting by configuring Unified CVP to use the same physical server for all of these functions on a per-call basis. Of course, if there is only one server in the system, then this is not a concern. The instructions below show you how to configure Unified CVP so that it does use components on the same physical server instead of load-balancing and using a random server for each component.
Perform the following steps to choose the co-resident Unified CVP VXML Server in the ICM Script Editor:
1. When setting up the media_server ECC variable that specifies your Unified CVP VXML Server in the ICM script, use the Formula Editor to set the media_server ECC variable to concatenate("http://",Call.RoutingClient,":7000/CVP"), where Call.RoutingClient is the built-in call variable that ICM sets automatically for you. The routing client name in ICM is not necessarily the same as the Unified CVP Server's hostname (and usually is not the same).
2. You can then use the routing client name as a hostname in the VXML gateway. However, do not use non-compliant characters such as an underscore as part of the hostname because the router cannot translate the hostname to an IP address if it contains any non-complaint characters. Cisco also recommends using the ip hostname strict command in the router to prevent the use of invalid characters in the hostname. This will ensure that the hostname is acceptable to Unified CVP.
3. Configure the routing client hostname for every Unified CVP Server Routing Client.
Perform the following steps to choose the co-resident Media Server in Cisco Unified Call Studio:
1. In the ICM script, set one of the ToExtVXML array variables with the call.routingclient data, such as "ServerName=call.routingclient." This variable will be passed to the Unified CVP VXML Server, and the variable will be stored in the session data with the variable name ServerName.
2. In Cisco Unified Call Studio, use a substitution to populate the Default Audio Path. Add the Application_Modifier element found under the Context folder, and specify the Default Audio Path under the Settings tab in the following format:
If you are using Micro-Apps in conjunction with the Unified CVP VXML Server, you will have to pay careful attention to the media_server ECC variable in the ICM script because the same variable is used to specify both the VXML Server and the Media Server, but the contents of the variable uses a different format depending on which server you want to specify. The media_server ECC variable should be used as indicated below whenever you want to use a Micro-App for prompting. If you subsequently want to use the VXML Server, you will have to rewrite this variable by following the instructions above.
1. When setting up the media_server ECC variable that specifies your Media server in the ICM script, use the Formula Editor to set the media_server ECC variable to concatenate("http://",Call.RoutingClient), where Call.RoutingClient is the built-in call variable that ICM sets automatically for you. The routing client name in ICM is not necessarily the same as the Unified CVP Server's hostname (and usually is not the same).
2. You can then use the name of the routing client as a hostname in the VXML gateway. However, do not use non-compliant characters such as an underscore as part of the hostname because the router cannot translate the hostname to an IP address if it contains any non-complaint characters. Cisco also recommends using the ip hostname strict command in the router to prevent the use of invalid characters in the hostname. This will ensure that the hostname is acceptable to Unified CVP.
3. Configure the routing client hostname for every Unified CVP Server Routing Client.
Bandwidth Calculation for Prompt Retrieval
When prompts are stored on an HTTP media server, the refresh period for the prompts is defined on that server. The bandwidth consumed by prompts consists of the initial loading of the prompts at each gateway and of the periodic updates at the expiration of the refresh interval.
As an example of determining the bandwidth consumed by prompts, assume that a deployment has 50 prompts with an average size of 50 kB (50,000 bytes) each. Also assume that the refresh period for the prompts is defined as 15 minutes (900 seconds) on the HTTP media server. The WAN bandwidth required for prompts in this deployment can be calculated as follows:
(50 prompts) * (50,000 bytes/prompt) * (8 bits/byte) = 20,000,000 bits
(20,000,000 bits) / (900 seconds) = 22.2 kbps per branch
Configuring Caching and Streaming in Cisco IOS
The Cisco IOS VoiceXML Browser uses an HTTP client, which is a part of Cisco IOS. The client fetches VoiceXML documents, audio files, and other file resources. There are two key properties associated with playing audio prompts: caching and streaming. These two properties are closely related to each other, and they can affect system performance greatly when the router is under load.
Streaming and Non-Streaming
In non-streaming mode, the entire audio file must be downloaded from the HTTP server onto the router before the Media Player can start playing the prompt. This implies delay for the caller. If the audio file is relatively small, the caller should not notice any delay because downloading a small file should take only a few milliseconds. The delay of loading larger files can be overcome by using either caching or streaming mode.
In streaming mode, the Media Player "streams" the audio in "media chunks" from the HTTP server to the caller. As soon as the first chunk is fetched from the server, the Media Player can start playing. The advantage of streaming mode is that there is no noticeable delay to the caller, irrespective of the size of the audio prompt. The disadvantage of streaming mode is that, because of all of the back-and-forth interactions from fetching the media file in chunks, it deteriorates performance. Additionally, the ability to cache the files in memory reduces the advantage of streaming large files directly from the HTTP server.
The recommendation for a Unified CVP VoiceXML gateway is to use non-streaming mode for the prompts in combination with caching. The Cisco IOS command to configure non-streaming mode is:
There are two types of cache involved in storing media files: the IVR Media Player cache and the HTTP Client cache. The HTTP Client cache is used for storing files that are downloaded from the HTTP server. In non-streaming mode, the entire media file is stored inside the HTTP Client cache. In streaming mode, the first chunk of the media file is stored in the HTTP Client cache and in the IVR cache, and all subsequent chunks of the file are saved in the IVR cache only.
Because of the above recommendation to use only non-streaming mode, the IVR prompt cache is never used and the HTTP Client cache is the primary cache. The HTTP Client cache also has the advantage of being able to store 100 MB of prompts, whereas the IVR cache is limited to 16 MB.
To configure the HTTP Client cache, use the following IOS commands:
http client cache memory file <1-10000>
Where <1-10000> is the file size in kilobytes. The default maximum file size is 50 kB, but the recommended file size is 600 kB. Any file that is larger than the configured HTTP Client memory file size will not be cached.
http client cache memory pool <0-100000>
Where <0-100000> is the total memory size available for all prompts, expressed in kilobytes. A value of zero disables HTTP caching. The default memory pool size for the HTTP Client cache is 10 Mb. The recommended memory pool size is the total size of all prompts stored on the media server, up to 100 MB.
Caching Query URLs
A query is a URL that has a question mark (?) followed by one or more "name=value" attribute pairs in it. The Unified CVP VXML Server uses query URLs heavily when generating the dynamic VoiceXML pages that are rendered to the caller. Because each call is unique, data retrieved from a query URL is both wasteful of cache memory and a possible security risk because the query URL can contain information such as account numbers or PINs.
Query URL caching is disabled by default in Cisco IOS. To ensure that it is disabled, issue a show run command in Cisco IOS and ensure that the following Cisco IOS command does not appear:
TCP Socket Persistence
The overhead for opening and closing the TCP socket connections can take a toll on the system performance, especially when the applications issue many small requests one after another. To reduce this socket connection overhead, the client can keep the socket open after a previous application request is fulfilled, so that the next application can reuse the same connection. This is feasible as long as the two connections have the same host IP address and port number. This kind of connection is referred to as a persistent connection. As the name implies, the connection can last over a long period of time without being shut down.
To establish a persistent connection, both the client and the server must agree that the connection is going to be a persistent one. To configure the Cisco IOS HTTP Client to request a persistent connection from the server, configure the following command:
http client connection persistent
The HTTP Client manages its cache by the "freshness" of each cached entry. Whether a cached entry is fresh or stale depends on two numbers: Age and FreshTime. Age is the elapsed time since the file was last downloaded from the server. FreshTime is the duration that the file is expected to stay fresh in the HTTP Client cache since the file was last downloaded.
There are several variables that can affect the FreshTime of a file, such as HTTP message headers from the server and the cache refresh value configured via the command line interface (CLI).
The FreshTime of a file is determined in the following sequence:
1. When a file is downloaded from the HTTP server, if one of the HTTP message headers contains the following:
Cache-Control: max-age = <value in seconds>
Then the max-age is used as the FreshTime for this file.
2. If step 1 does not apply, but the following two headers are included in the HTTP message:
Expires: <expiration date time>
Date: <Current date time>
Then the difference (Expires - Date) is used as the FreshTime for this file.
3. The HTTP/1.1 spec, RFC 2616 (HyperText Transport Protocol), recommends that either one of the HTTP message headers as described in step 1 or 2 above should be present. If the server fails to send both 1 and 2 in its HTTP response, then take 10% of the difference between Date and Last-Modified from the following message headers:
Last-Modified: <last-modified date time>
Date: <Current date time>
So the FreshTime for this file is calculated as:
FreshTime = 10% * ((Date) - (Last-Modified))
4. The CLI allows the user to assign a FreshTime value to the files as a provisional value in case none of the message headers in steps 1 to 3 are present:
http client cache refresh <1-864000>
The default refresh value is 86400 seconds (24 hours). The configured HTTP Client cache refresh has no effect on files when any of the message headers in steps 1 to 3 are present. But if the resultant FreshTime from the CLI command calculation turns out to be less than the system default (which is 86400 seconds), the FreshTime will be set to the default value (86400 seconds). This command is also not retroactive. That is, the newly configured refresh value applies only to new incoming files, and it has no effect on the entries already in the cache.
Stale files are refreshed on an as-needed basis only. This means that a stale cached entry can stay in the cache for a long time until it is removed to make room for either a fresh copy of the same file or another file that needs its memory space in the cache.
A stale cached entry is removed on an as-needed basis when all of the following conditions are true:
•The cached entry becomes stale.
•Its refresh count is zero (0); that is, the cached entry is not being used.
•Its memory space is needed to make room for other entries.
When the Age exceeds the FreshTime and the file needs to be played, the HTTP Client will check with the media server to determine whether or not the file has been updated. When the HTTP Client issues a GET request to the server, it uses a conditional GET to minimize its impact on network traffic. The GET request includes an If-Modified-Since in the headers sent to the server. With this header, the server will either reply with a 304 response code (Not Modified) or return the entire file if the file was indeed updated recently.
Note that this conditional GET applies only to non-streaming mode. Under streaming mode, the HTTP Client always issues an unconditional GET; that is, no If-Modified-Since header is included in the GET request, thus resulting in an unconditional reload for each GET in streaming mode.
You can reload individual files into cache by issuing the following command:
test http client get http://10.0.0.130/en-us/sys/1.wav reload
Branch Office Implications
In most cases, customers implementing Unified CVP in branch office deployments expect a small footprint for hardware, and they will not have a local media server. Therefore, it is necessary to store some critical prompts in flash, such as error messages or other messages that are played to the caller when the WAN is down.
When recorded in G.711 mu-law format, typical prompts of average duration are about 10 to 15 kB in size. When sizing gateways for such implementations, size the flash memory by factoring in the number of prompts and their sizes, and also leave room for storing the Cisco IOS image.