Document toolboxDocument toolbox

Vidispine

Thumbnails [VC 21.3 GEN]

Owned by Andreas Schmidt
Aug 31, 2021
4 min read

Creating thumbnails and posters

Thumbnails and posters can be created by starting a thumbnail job.

Create a thumbnail job

POST /item/(item-id)/thumbnail

Creates a new thumbnail job with the specified parameters. Note that a job cannot both create thumbnails at specified intervals and posters. Creating thumbnails according to transcoder rules and creating posters is however allowed.

Changed in version 5.0: For multi-layer PSD/PSB files, only a thumbnail of all layers flattened will be generated by default.

Query Parameters:

  • createThumbnails (boolean) –

    • true - Creates thumbnails according to default transcoder rules.

    • t1, … - Thumbnails will be created on the specified, comma-separated, time codes.

    • false (default) - No thumbnails will be created.

  • createPosters (string) – A list of time codes to use for creating posters.

  • thumbnailWidth (integer) – The width of the thumbnails. If thumbnailWidth is specified, thumbnailHeight must also be specified.

  • thumbnailHeight (integer) – The height of the thumbnails. If thumbnailHeight is specified, thumbnailWidth must also be specified.

  • thumbnailPeriod (string) – Timecode string specifying the interval of the thumbnails. It should be a decimal integer when working with multi-page images/PDFs, meaning every N page(s).

  • posterWidth (integer) – The width of the posters.

  • posterHeight (integer) – The height of the posters.

  • posterFormat (string) –

    • jpeg (default) - Creates posters in JPEG format.

    • png - Creates posters in PNG format.

  • thumbnailService (string) – Identifies which thumbnail resource that should be used.

  • tag (string) – Include additional video settings from this transcode preset. Resolution settings in the tag are overridden by query parameters thumbnailHeight and thumbnailWidth.

  • version (integer) – A version number. For creating thumbnails for older versions of the item essence. Default is latest version.

  • sourceTag (string) – Comma-separated shape tags. The fist valid shape will be chosen as the source of the job. If non of the tags are valid, the original shape will be used.

  • resourceId (string) – The transcoder resource to use to execute the transcode.

  • notification (string) – The placeholder job notification to use for this job.

  • notificationData (string) – Any additional data to include for notifications on this job.

  • priority (string) – The priority to assign to the job. Default is MEDIUM .

  • jobmetadata (string[]) – Additional information for the job task.
Produces:
Role:

_job_write

Example

Creating thumbnails according to transcoder rules and posters at the time codes 50@PAL and 100@PAL.

POST /item/VX-123/thumbnail?createThumbnails=true&createPosters=50@PAL,100@PAL&sourceTag=mov,mp4
<JobDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <jobId>VX-1219</jobId>
   <user>admin</user>
   <started>2010-04-23T11:24:24.434+02:00</started>
   <status>READY</status>
   <type>THUMBNAIL</type>
   <priority>MEDIUM</priority>
</JobDocument>

Item thumbnail resources

The following requests deal with managing thumbnail resources for specific items.

List thumbnail resources for an item

GET /item/(item-id)/thumbnailresource

Return one or more poster resource URIs which can be used to manage the thumbnails for a specific item.

Query Parameters:

  • version (integer) – Return thumbnails from this essence version. By default thumbnails for the latest version will be returned.
Produces:

  • text/plain – CRLF-delimited list of thumbnail resource URIs

  • application/xml, application/json – URIListDocument of thumbnail resource URIs
GET /item/(item-id)/posterresource

Return one or more poster resource URIs which can be used to manage the posters for a specific item.

Query Parameters:

  • version (integer) – Return posters from this essence version. By default posters for the latest version will be returned.
Produces:

  • text/plain – CRLF-delimited list of thumbnail resource URIs

  • application/xml, application/json – URIListDocument of thumbnail resource URIs

Update or create a thumbnail resource for an item

PUT /item/(item-id)/thumbnailresource

If no thumbnail resources are defined for an item, create a resource and return it.

Produces:

  • text/plain – CRLF-delimited list of thumbnail resource URIs

  • application/xml, application/json – URIListDocument of thumbnail resource URIs
PUT /item/(item-id)/posterresource

If no poster resources are defined for an item, create a resource and return it.

Produces:

  • text/plain – CRLF-delimited list of thumbnail resource URIs

  • application/xml, application/json – URIListDocument of thumbnail resource URIs

Thumbnails and posters for an item share the same resource. Hence, if a resource is added for posters, it is automatically added for thumbnails as well.

Get a thumbnail sprite sheet for an item

New in version 5.6.

A thumbnail sprite sheet is a large image containing all of the thumbnails for an item, together with information about each thumbnail.

GET /item/(item-id)/thumbnail/spritesheet

Returns a thumbnail sprite sheet which contains a URI to the generated sprite sheet and the positions of the images.

Query Parameters:

  • noauth-url (boolean) –

    • true Return URIs that do not need authentication.

    • false (default) Return normal URIs
Request Headers:

  • If-Modified-None – Optional header containing ETag of previous call. If no changes to thumbnails have been done, a 304 Not Modified is returned.
Response Headers:

  • ETag – Contains the computed ETag of the response.
Produces:

Thumbnail resource handling

The following requests deal with managing collections of thumbnail URIs for a specific thumbnail resource.

List all thumbnails

GET {thumbnail-resource}

Returns thumbnail URIs on which further requests may be performed.

Query Parameters:

  • url (boolean) –

    • true - Return list of URLs.

    • false (default) - Return list of ids.

  • noauth-url (boolean) –

    • true Return URIs that do not need authentication.

    • false (default) Return normal URIs
Produces:

  • text/plain – CRLF-delimited list of thumbnail URIs.

  • application/xml, application/json – URIListDocument of thumbnail URIs
Role:

_thumbnail_read

Update or create a thumbnail

PUT {thumbnail-resource}/(time)

Create a new thumbnail at the specified time code. If a thumbnail with the specified time code already exists it is replaced.

Accepts:

  • image/png, image/jpeg – Image to insert
Produces:

  • text/plain – Informational status message.
Status Codes:

  • 400 – Given data was not valid image/png or image/jpeg
Role:

_thumbnail_write

Delete all thumbnails

DELETE {thumbnail-resource}

Remove all thumbnails handled by this resource.

Role:

_thumbnail_write

Thumbnail handling

The following requests concern handling a specific thumbnail.

Retrieve the image representation

GET {thumbnail-resource}/(time)

Return the image representation of this thumbnail.

Query Parameters:

  • hash (string) – The checksum of the image.

  • type (string) – Optional type.
Produces:

  • image/png, image/jpeg – Image of the thumbnail
Role:

_thumbnail_read

Delete a thumbnail

DELETE {thumbnail-resource}/(time)

Remove this thumbnail.

Role:

_thumbnail_write

Export a thumbnail

POST {thumbnail-resource}/(time)/export

Starts a job that writes the thumbnail or poster to a specific destination.

Query Parameters:

  • uri (string) – Required. URI of export location of thumbnail or poster

  • format (string) – Image format of destination. E.g. tiff.

  • notification (string) – The placeholder job notification to use for this job.

  • notificationData (string) – Any additional data to include for notifications on this job.

  • priority (string) – The priority to assign to the job. Default is MEDIUM .

  • jobmetadata (string[]) – Additional information for the job task.
Produces:
Role:

_thumbnail_read