Wowza Streaming Engine MediaCache.xml configuration reference

The Wowza Streaming Engine™ media server MediaCache.xml configuration file located at [install-dir]/conf/MediaCache.xml is used to configure the Media Cache system in Wowza Streaming Engine. Media Cache can retrieve content from either a web server or HTTP (the server must support HTTP/1.1 byte range requests) or network attached file system or any similar device that's recognized as a disk by the operating system. For more information about the Media Cache system, see Scale video-on-demand streaming with Wowza Streaming Engine Media Cache.

Note: The MediaCache.xml reference applies to the file as installed with the latest version of Wowza Streaming Engine. Some properties described may not apply to the file as installed with earlier versions of Wowza Streaming Engine.

Contents

---

MediaCache
MediaCacheStores
MediaCacheSources
Properties

XML reference

---

MediaCache

A container element for configuring the caching system.

WriterThreadPool - A container element for configuring the writer pool.

• PoolSize - Number of threads in the writer pool that are used to write media blocks to the caching system. This value should be set to twice the number of CPU cores on the machine.

ReadAheadThreadPool - A container element for configuring the readahead pool. The readahead system keeps a steady flow of bytes moving from the source to the cache to avoid stuttering during playback.

• PoolSize - Number of threads in the readahead pool that are used to read blocks from the cache source before they are requested. This value should be set to the number of CPU cores on the machine.

MaxPendingWriteRequestSize - Number of bytes of memory that can be occupied by blocks waiting to be written to storage. Think of this storage area as a temporary memory-based cache. Values are specified in bytes and the following units are supported: K (kilobytes), M (megabytes), G (gigabytes), or T (terabytes).

MaxPendingReadAheadRequestSize - Number of bytes of memory that can be occupied by blocks waiting to be written to the cache store. Values are specified in bytes and the following units are supported: K (kilobytes), M (megabytes), G (gigabytes), or T (terabytes).

GCFrequency - Time, in milliseconds, between cache-purging/cache-pruning sessions. Based on time-to-live settings, items stored in the cache are purged when they haven't been used in a given period of time—maximum time-to-live, or if there's content waiting to enter the cache—minimum time-to-live. The default value is 10000 (10 seconds).

ContextMapperClass - Reserved for future use (leave blank).

AddFileExtensionIfNeeded -  Indication of whether to include a file name extension. If true, and the stream name doesn't include a file name extension, then a file name extension is added. The value of this extension is based on the stream name prefix. Set this property to false to prevent the Media Cache from automatically adding file name extensions to cache items.

URLEscapeStreamNameSpaces - Boolean. If true, spaces in stream names are URL-escaped before being sent to the source HTTP server. The default value is true.

URLEscapeStreamNameAll - Boolean. If true, the entire stream name is URL-escaped before being sent to the source HTTP server. The default value is false.

OnStartReloadCache - Boolean. If true, Media Cache will reload the cache on restart. When false, the cache will be cleared on restart. The default value is false.

OnStartReloadCacheVerifySource - Boolean. Specifies whether to verify the source when reloading the cache. If false, the reload will go faster for items sourced from HTTP sources (item length will not be loaded from HTTP HEAD request and will instead be loaded from information in cache). The default value is true.

DebugLog - Boolean. When set to true, this turns on verbose logging for debugging.

MediaCacheStores

A container element for configuring cache stores.

MediaCacheStore - Descriptions of cache stores that are made available to Wowza Streaming Engine.

• Name – The name of the Media Cache store, which must be unique and can’t contain less-than (<), greater-than (>), colon (:), quotation (' and "), forward slash (/), backslash (\), pipe (|), question mark (?), asterisk (*), double-dot (..), and tilde (~) characters.
• Description – An optional text description of the Media Cache store.
• Path – The path to the storage location where files are cached. The path value must be unique and can't contain less-than (<), greater-than (>), quotation (' and "), backslash (\), pipe (|), question mark (?), and asterisk (*) characters. Always use forward slashes when defining paths, for example, ${com.wowza.wms.context.ServerConfigHome}/mediacache. Cached files are stored in a two-tier directory structure.
• MaxSize – (bytes) The maximum amount of data that is stored in this cache store. A general recommendation for determining the size of the store is to use the following equation:

  (average file size x number of unique streams played in the maximum time to live period) + 10–20%

  For example, if your average file size is 1 GB and you have 100 unique files played within the maximum time to live period, the maximum size of the store should be 110–120 GB. Logs show the number of unique files played within the maximum time to live period. The following units are supported: K (kilobytes), M (megabytes), G (gigabytes), or T (terabytes).
• Level1FolderCount – Number of first-level folders created to store cached items.
• Level2FolderCount – Number of second-level folders created to store cached items.
• FileCount – Number of items that can be stored in each level2 folder. For example, if the level1 folder count is set to 24, and the level2 folder count is set to 24, and the file count is set to 1000, then 24x24x1000 or 576000 (the product of 24x24x1000) files can be stored in this cache store.
• WriteRate – (bytes per second) The maximum rate that content can be written to the cache store. Throttling the write rate helps control the flow of content that enters the cache so that it doesn't overwhelm the file system, impeding the flow of content that's being served out of the cache. The following units are supported: K (kilobytes), M (megabytes), G (gigabytes), or T (terabytes).
• WriteRateMaxBucketSize – (bytes) The maximum amount of content that is cached before the write rate is throttled. This value should be set to six times the write rate. The following units are supported: K (kilobytes), M (megabytes), G (gigabytes), or T (terabytes).
• WriteRateFillFrequency – Refresh rate, in milliseconds, of the write rate control mechanism. This value works in concert with WriteRate to control how the write rate is throttled. This value should be set to 100.
• Properties – Custom properties with name, value, and type that can be added by the user. Properties can be retrieved by using the MediaCacheStore.getProperties() method.
  • Property – A container element for configuring custom properties.
    • Name – Name of the property.
    • Value – Value of the property as defined by the type.
    • Type – Type of property (Integer, Boolean, or String).

MediaCacheSources

A container element for configuring cache sources.

MediaCacheSource - Descriptions of sources of content that are made available to Wowza Streaming Engine.

• Name - Name of the source, used for logging purposes. This name isn't used to control streaming or the addressing of the content.
• Type - Identifies the Media Cache source type.

  Supported values:

  • File – Content is retrieved via standard file reads from network-attached file systems, including network file systems and any device that's recognized as a disk by the operating system.
  • HTTP – Content is retrieved via standard HTTP requests from HTTP-based servers that support HTTP/1.1 range requests. The HTTP connection can be encrypted using Secure Sockets Layer (SSL) certificates from a certificate authority.
  • AmazonS3 – Content is retrieved from an Amazon S3 bucket via HTTP requests that conform to Amazon S3 specifications. The HTTP connection can be encrypted using SSL certificates from a certificate authority.
  • Azure – Content is retrieved from a Microsoft Azure Blob storage account.
  • GoogleCloudStorage – Content is retrieved from a Google Cloud Storage Bucket connected to a Google service account.
• Description - Text description of the Media Cache source under examination.
• BasePath - The location where the content can be found. The base path along with the prefix controls how content is mapped back to a source configuration. To restream the content, the Prefix portion is replaced by the BasePath value. For example, if you set Prefix to content1/ and BasePath to http://, then the stream name: content1/mycoolvideo.mp3 is retrieved from the following URL: http://mycoolvideo.mp3.
• Prefix - The first part of the URL that clients use to access content from this source. The prefix must be unique across all sources and end with a forward slash (/).
• BaseClass - Full class path to the MediaCacheSource implementation that's used to deliver the content.

  Example values:

  • com.wowza.wms.mediacache.impl.MediaCacheItemFileImpl
    
    Use for file-based content.
  • com.wowza.wms.mediacache.impl.MediaCacheItemHTTPImpl
    
    Use for HTTP content.
• ReaderClass - Reserved for future use (leave blank).
• DefaultBlockSize - Size of the blocks in bytes of data that are read from the source to populate the cache. Values are specified in bytes and the following units are supported: K (kilobytes), M (megabytes), G (gigabytes), or T (terabytes).
• MaxTimeToLive -  (milliseconds) Maximum time that an item will remain in the cache when it hasn't been accessed regardless of space requirements. We recommend setting this to equal to the average duration of your content. The time-to-live counter starts when the last client to view the content stops viewing the content. If no other viewers view this content within the time-to-live window, the content is purged from the cache.
• MinTimeToLive -  (milliseconds) Minimum time that an item will remain in the cache when it hasn't been accessed, and space is needed. The default setting is 14400000 milliseconds or four hours. We recommend setting this as low as possible, to a few seconds. Lower values make it easier to remove items when the cache is full or to add new items to the cache when needed.
• ReadAhead - Boolean value that controls the use of the readahead function. If ReadAhead is set to true, content blocks are pre-populated in the cache based on the ReadAheadThreshold percentage. If set to false, no readahead occurs.
• ReadAheadThreshold - Percentage that controls when the request is made to read the next block. For example, if ReadAheadThreshold is set to 50 percent, then a successive content block is queued to be read when the current content block is read beyond the halfway mark.
• Properties - Custom properties with name, value, and type that can be added by the user to configure Media Cache sources.
  • Property - A container element for configuring custom properties.
    • Name - Name of the property.
    • Value - Value of the property as defined by the type.
    • Type - Type of property (Integer, Boolean, or String).

Properties

A container element for configuring custom properties

• Property - Custom properties with name, value, and type that can be added by the user for configuring Media Cache.
  • Name - Name of the property.
  • Value - Value of the property as defined by the type.
  • Type - Type of property (Integer, Boolean, or String).