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

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. This value specifies whether to reload the cache when the server starts.

OnStartReloadCacheVerifySource - Boolean. This value specifies whether to verify the source when reloading the cache.

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 - Cache store name.
  • Description - Text description of the cache store.
  • Path - Path to the storage location. 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 - Maximum size, in bytes of data, that is stored in this cache store. Values are specified in bytes, and 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 - Maximum rate at which content can be written to this 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. Values are expressed in bytes per second and the following units are supported: K (kilobytes), M (megabytes), G (gigabytes), or T (terabytes).
  • WriteRateMaxBucketSize - Value that works in concert with WriteRate to control how the write rate is throttled. This value should be set to 6 times the WriteRate. Values are specified in bytes and 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

      For re-streaming files from network-attached file systems, including network file systems and any device that's recognized as a disk by the operating system.
    • HTTP

      For re-streaming files from HTTP-based servers that support HTTP/1.1 range requests.
    • AmazonS3

      For re-streaming files from an Amazon S3 bucket.
    • Azure

      For re-streaming content from a Microsoft Azure blob storage account.
    • GoogleCloudStorage

      For re-streaming content from a Google Cloud Storage bucket connected to a Google service account.
  • Description - Text description of the Media Cache source under examination.
  • BasePath - Setting that works together with Prefix to control 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.flv is retrieved from the following URL: http://mycoolvideo.flv.
  • Prefix - Used to map the stream name to the source.
  • 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 - Maximum time, in milliseconds, that an item will remain in the cache unused. 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 - Minimum time, in milliseconds, that an item will remain in the cache unused if there are items waiting to enter the cache, and the cache is full.
  • 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).