Configuring supported file types in Media libraries

Extended image support in Refresh 10

Support for WebP and SVG images is available only after applying hotfix 13.0.115 (Kentico Xperience Refresh 10) or newer to your projects.

Media libraries support the following types of images: bmpgif, ico, png, wmf, jpgjpegtifftif, webp. These types of image files can be uploaded and displayed on your site by default.

The system detects audio and video files based on their MIME type (audio types starting with the audio/ prefix and video types starting with the video/ prefix). For successfully detected audio and video file types, the system renders appropriate HTML5 markup. The types of files that can be previewed or played on your site therefore depend on the web browser (modern HTML5 web browsers typically support one or more of the oggmp4, or webm video codecs, and mp3wav, or ogg audio codecs).

All other file types are recognized as documents, which means that you cannot play them as videos or display them as images. You can still store them in the library and users can download them on the live site.

Enabling upload of other file types

If you want to configure the system to allow upload of a custom file type into media libraries, you need to:

  1. Enable the custom file extensions to be uploaded into media libraries.
  2. (Optional) If you want to use the custom extension as an image, audio, or video file, you need to configure the system to recognize the extension as a media file.

Allowing upload of selected files into media libraries

To customize what media files and documents can be uploaded to media libraries:

  1. Open the Settings application.
  2. Navigate to the Content → Media category.
  3. Add the selected file extensions into the Media file allowed extensions setting (separated by semicolons).
  4. Save the changes.

Configuring custom detection of media file types

By default, the system can recognize and process any media type, if you have the right player for the given file type. You can allow custom file types to be recognized as media files via configuration keys. However, by adding the media file type configuration, you disable automatic detection and support for media file types other than those explicitly specified.

To configure specific file types to be recognized as media:

  1. Add the following keys into the appSettings section of your administration project’s web.config file.

     <add key="CMSImageExtensions" value="bmp;gif;ico;png;wmf;jpg;jpeg;tiff;tif;webp" /> 
     <add key="CMSAudioExtensions" value="wav;mp3" /> 
     <add key="CMSVideoExtensions" value="mp4;ogg" />
  2. Save the web.config file.

  3. Add the same keys with the same values to the configuration file of your live site project, depending on your development model:

    • web.config for MVC 5 projects

    • appsettings.json for ASP.NET Core projects (by default)

      apsettings.json example
        "CMSImageExtensions" : "bmp;gif;ico;png;wmf;jpg;jpeg;tiff;tif;webp",
        "CMSAudioExtensions" : "wav;mp3",
        "CMSVideoExtensions" : "mp4;ogg"

Files of the specified types are now recognized as media files of the corresponding type. For example, image files are offered in the Insert image dialog of the rich text editor.

Limited support for specific graphic formats

The WebP image format is supported by default in media libraries (and by page attachments). The SVG vector format for images is also supported. However, SVG images may host scripts or CSS and pose a security risk. If you wish to use the SVG image format, you need to manually enable support for the extension. 

Certain image features do not work for WebP and SVG files – the built-in image editor, automatic generating of image thumbnails, image resizing API (such as the WithSizeConstraint extension method when displaying images).

Other vector graphic formats (such as eps, pdf, ai) are not supported as image extensions in media libraries. These formats can be stored as documents and displayed on the live site, but the thumbnail preview and image editor is unavailable for such files.

MIME type mapping for WebP files

If you wish to use WebP images, make sure that you have a <mimeMap> MIME type mapping under the <staticContent> element in the web.config file of your administration project, as well as the live site project if using the MVC 5 development model.

  <remove fileExtension=".webp" />
  <mimeMap fileExtension=".webp" mimeType="image/webp" />