Elvis 6 API - Previews

For all supported file types, Elvis generates previews to display in the Web clients and in API clients. The previews are all based on lightweight Web formats and can therefore be quickly displayed and navigated.

Generated previews

The following table shows the file formats that are generated for the various types of files:

File type	Preview file format
Images and PDFs	JPEG
Videos	mp3
Audio files	For Elvis 6.25 and lower: mp3, flv For Elvis 6.26 and higher: mp3, mp4, flv, m4a
Most documents	HTML

Default preview formats

Previews of an asset can be requested by using the asset ID or the assetPath, using the following syntax:

• Example using the asset ID:

http://demo.elvisdam.com/preview/5LMAQTW9qfhANn7f6JJVpl

• Example using the assetPath:

http://demo.elvisdam.com/preview/Demo%20Zone/Images/Travel/Architecture/Domein%20Hofstade.jpg

The default previews are equal to the previews in the Pro client.

File type	Preview format
Images	maxWidth_1600_maxHeight_1600.jpg
PDF or PowerPoint	maxWidth_1600_maxHeight_1600_page_0.jpg
Videos	maxWidth_480_maxHeight_360.mp4
Audio files	For Elvis 6.25 and lower: maxLength_600000.flv For Elvis 6.26 and higher: maxLength_3600000.mp4

Customized preview formats

By altering the preview URL, customized preview formats can be requested from the server such as a smaller JPEG preview, a different page of a PDF or a video preview in FLV format.

Note: Custom preview formats are not supported for HTML previews.

If these previews have not been generated yet, they will be generated on-the-fly by the server and stored in the Elvis Shared Data/renditionFileStore folder.

• Example using the asset ID:

http://demo.elvisdam.com/preview/5LMAQTW9qfhANn7f6JJVpl/previews/maxWidth_1600_maxHeight_1600.jpg

• Example using the assetPath:

http://demo.elvisdam.com/preview/Demo%20Zone/Images/Travel/Architecture/Domein%20Hofstade.jpg/previews/maxWidth_1600_maxHeight_1600.jpg

• Default preview with different extension:

preview.tiff

• Smaller preview for use on a Web page:

maxWidth_500_maxHeight_350.jpg

• Preview for page 3 of a PDF or slide 3 of a PowerPoint:

maxWidth_1600_maxHeight_1600_page_3.jpg

• HD (720p) preview for a video:

maxWidth_1280_maxHeight_720.mp4

• Flash video format preview:

maxWidth_640_maxHeight_480.flv

Using a custom file name

By default the file name of the requested image contains the parameters as supplied in the URL.

Example: maxWidth_1600_maxHeight_1600.jpg

To use a custom file name, add the following to the end of the URL:

file name/*/extension

• Examples using the asset ID:

http://demo.elvisdam.com/preview/5LMAQTW9qfhANn7f6JJVpl////my-custom-name.jpg

http://demo.elvisdam.com/preview/5LMAQTW9qfhANn7f6JJVpl/*/my-custom-name.jpg

• Example using the assetPath:

http://demo.elvisdam.com/preview/5LMAQTW9qfhANn7f6JJVpl/previews/maxWidth_1600_maxHeight_1600.jpg////my-custom-name.jpg

http://demo.elvisdam.com/preview/5LMAQTW9qfhANn7f6JJVpl/previews/maxWidth_1600_maxHeight_1600.jpg/*/my-custom-name.jpg

Changing the file name separator

In case a different separator needs to be used (for example by changing it back to 4 forward slashes), add the following property to the cluster-config.properties file:

downloadUrlFilenameSeparator=

Example: downloadUrlFilenameSeparator=////

Supported properties

maxWidth and maxHeight

• Description: Sets the maximum width and/or height of the preview. The aspect ratio will always remain the same. If the original asset fits within the supplied dimensions, the original width and height will be used for generating the preview. It is allowed to just supply one of the dimensions.
• Applicable file types: Images, videos, PDFs, presentations and layouts.
• Value: numeric.
• Example:

maxWidth_800_maxHeight_600.jpg

cropWidth and cropHeight

• Description: Sets the width and/or height (in pixels) to which an image should be cropped.
• Note: Because the image processing engine on MacOS does not support cropping, this functionality only works on Windows and Linux servers; it does not work on a MacOS server.
• Applicable file types: Images.
• Value: numeric.
• Example:

cropWidth_500_cropHeight_400.jpg

With crop offset (see below):

cropWidth_500_cropHeight_400_cropOffsetX_750_cropOffsetY_800.jpg

cropOffsetX and cropOffsetY

• Description: Sets the crop x and/or y offset in pixels (from the top left corner).
• Note: Because the image processing engine on MacOS does not support cropping, this functionality only works on Windows and Linux servers; it does not work on a MacOS server.
• Applicable file types: Images.
• Value: numeric.
• Example:

cropOffsetX_750_cropOffsetY_800.jpg

With crop width and height (see above):

cropWidth_500_cropHeight_400_cropOffsetX_750_cropOffsetY_800.jpg

scale

• Description: Sets the width and height of the preview relative to the original size. The scale is in percentages from 1 to 100. If used in combination with maxWidth or maxHeight the image will be scaled with a maximum size.
• Applicable file types: Images.
• Value: 1 – 100.
• Example:

scale_50.jpg

PPI / DPI

• Description: The pixels per inch / dots per inch can be set to any desired value. When not set, the original PPI / DPI value of the file will be used. .
• Applicable file types: Images.
• Value: numeric.
• Example:

maxWidth_800_maxHeight_600_ppi_72.jpg

compression

• Description: TIFF compression.
• Applicable file types: Images.
• Value: uncompressed, packBits, LZW, ZIP and JPEG.
• Example:

maxHeight_600_compression_packBits.tiff

quality

• Description: JPEG compression quality 1 - 100.
• Applicable file types: JPEG images.
• Value: 1 – 100.
• Example:

scale_75_quality_12.jpg

maxLength

• Description: Limits the length of audio previews. The value is in milliseconds.
• Applicable file types: Audio files.
• Value: numeric.
• Example:

maxLength_60000.mp3

page

• Description: The page of the PDF or presentation to create a preview from. The value can range from 1 to the number of pages in the document. The preview will always have .jpg as extension.
• Applicable file types: PDFs, presentations and layouts.
• Value: numeric.
• Example:

maxWidth_1600_maxHeight_1600_page_3.jpg

embedMetadata

• Description: When set to true the metadata embedded in the original asset will be embedded in the generated preview. Note that for certain file types the embedding of metadata is not supported, for example for PNG files. By default the original metadata is not embedded.
• Applicable file types: Images, PDFs, presentations and layouts.
• Value: true or false
• Example:

maxWidth_800_maxHeight_600_ppi_72_embedMetadata_true.jpg

Extensions

• Description: The extension of the generated preview can be different from the original.
• Applicable file types: Images, PDFs, presentations and layouts.
• Value:
• Images: jpg, png, tiff
• Videos: flv, mp4
• Audio files: mp3, flv
• PDF, presentation, layout: jpg
• Example:

maxWidth_800_maxHeight_600.png

embedColorProfile

• Description: When set to true the color profile that is used to generate the preview is included.
• Applicable file types: Images.
• Value: true or false
• Example:

maxWidth_1600_maxHeight_1600_embedColorProfile_true.jpg

background

Info: This option requires Elvis 6.18 or higher.

• Description: Sets the background color for transparent images. If not specified, the output of PNG and TIFF images will be transparent.
• Applicable file types: Images.
• Value: An RGB hex triplet.
• Example:

maxWidth_800_maxHeight_600_background_F0F0F0.jpg

Document history

• 27 August 2020: Updated section 'Customized preview formats' by stating that previews are not cached but stored in the renditionFileStore folder.