Thumbnail resources [VC 21.3.1 GEN]

A thumbnail resource defines a location where the thumbnails will be stored. For details how the thumbnails are stored and for the supported location types see How thumbnails are saved on disk.

Adding a thumbnail resource

Add a thumbnail resource using POST /resource.

NONE

POST /resource
Content-Type: application/xml

<?xml version="1.0"?>
<ResourceDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <thumbnail>
    <path>file:///srv/thumbnails/</path>
  </thumbnail>
</ResourceDocument>

Reading thumbnails

The thumbnails in that directory will then be available from the API as described on Thumbnail resource handling. For example, all thumbnails can be listed using GET /thumbnail/(resource-id).

NONE

GET /thumbnail/VX-2

HTML/XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <uri>VX-1</uri>
  <uri>VX-3</uri>
  <uri>VX-4</uri>
  <uri>VX-7</uri>
</URIListDocument>

However, you would typically not access thumbnails from that resource directly. Instead, fetch thumbnails for an item using GET /item/(item-id)/thumbnailresource or using the thumbnail content parameter.

NONE

GET /item/VX-7/thumbnailresource

HTML/XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <uri>http://localhost:8080/API/thumbnail/VX-1/VX-7;version=0</uri>
</URIListDocument>

NONE

GET http://localhost:8080/API/thumbnail/VX-1/VX-7;version=0

HTML/XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <uri>0@PAL</uri>
</URIListDocument>

Thumbnail resource permissions

A thumbnail resource can be made read-only or read-protected, for example:

When migrating thumbnails from one location to another; to have new thumbnails written to one resource but old thumbnails still read from another resource.
As read-protected, in case the disk where thumbnails are stored needs to be taken offline. VS will then avoid serving thumbnails from that resource.

This is done using the mode element.

HTML/XML

<?xml version="1.0"?>
<ResourceDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <thumbnail>
    <path>file:///srv/thumbnails/</path>
    <mode>NONE</mode>
  </thumbnail>
</ResourceDocument>

Allowed values are:

READ_WRITE - full access (default)
READ - read-only
NONE - no access.

How thumbnails are saved on disk

The thumbnails can be stored either in a database form or as one file per thumbnails.

Thumbnails are stored in the resolution and format as requested when the thumbnails were created, and it’s not possible to for example request a thumbnail as a PNG if it has previously been created as a JPEG.

Database

The thumbnail path as specified in the ResourceDocument should have the format

path (e.g. /srv/media/thumbnails/), or
file URI (e.g. file:///src/media/thumbnails/)

Thumbnails are stored in a separate directory and database - one for each item. Vidispine will automatically migrate the databases during runtime if necessary, so no special action is required when updating Vidispine to a newer version or when restoring an old thumbnail backup on a newer system.

One file per thumbnail

The thumbnail path as specified in the ResourceDocument should have the format

URI with the direct+ prefix (e.g. direct+file:///src/media/thumbnails/

All URIs supported as Storage method URIs are supported.

Using a tree structure for thumbnails

Putting all files in the same directory of a storage can cause degraded performance on some file systems.

By setting the configuration property thumbnailHierarchy, the naming convention for the thumbnails’ folders is changed to site-id - number1 / number2. The number set in thumbnailHierarchy controls the size of number2.

The thumbnailHierarchy works in the same way as fileHierarchy does for files. See Using a tree structure for files for an example. The property works both for the database thumbnail storage and the direct thumbnail storage.

Changing the thumbnailHierarchy property will cause old thumbnails to be lost. If you need to change the value on a system in production, please contact Vidispine.