Item shapes

A shape is a physical representation of an item. Each shape is made up out of one or more components that correspond to content of a file.


Each item will typically have at least a single shape, the original shape, along with one or more alternate representations of the asset.

  • For video, this can be a low-resolution version, a web version and a mobile version. Another example is if you have multiple versions of the same video, but each with different audio or text tracks. Those versions would then be separate shapes.
  • For text this could be the word processor document format, a PDF or a plain text version.

You will find that the information extracted and presented for video and audio files is richer than what’s provided for other type of files, such as PDFs or zip files. For the former information about the container and video- and audio streams is provided, while the latter is typically presented as a shape with a binary component.

To distinguish between different shapes you can use tags. These are described in the Shape tags and presets section.

Importing shapes

Vidispine will create an original shape when an item is first imported. To import additional shapes to an item, for example files created by an external transcoder, then that can be done by creating a SHAPE_IMPORT job.

A shape import job will:

  • Transfer content to a Vidispine supervised storage.
  • Media check the imported file.
  • Create a new shape and add it to the item.

Use the item shape resource to import new shapes. An image could for example be imported to and item, and tagged with the large-jpg tag, using:

POST /item/VX-12/shape?uri=file:///srv/ftp/the-doctor.jpg&tag=large-jpg
<JobDocument xmlns="">

Essence versions

If you have assets that change over time, and wish to track all of those versions, then you can use an item to represent the asset and then import each update to the asset as a new essence version on the item.

Vidispine will return the shapes and thumbnails for the latest essence version by default, but you can of course select to have older versions returned as well.

Creating a new essence version

New essence versions are created using ESSENCE_VERSION jobs. See Essence versions for the different ways of starting such jobs. For example, creating a new essence version for an item by providing the location of the new asset.

POST /item/VX-37/shape/essence?uri=file:///home/lisa/render-1.jpg
<JobDocument xmlns="">

This new image will then show up as the original shape of the item, and will be used as the input on any future transcodes. By viewing the shape we can see that this shape belongs to a new essence version. Note that the essence version numbers are zero-based.

<ItemDocument xmlns="" id="VX-37">

We can also see that there’s a new essence version by retrieving the essence versions for the items.

GET /item/VX-37/shape/version
<URIListDocument xmlns="">


An item can be transcoded either when it is imported or afterwards by using the item transcode resource. When transcoding an already imported item a TRANSCODE job will be used. A transcode job will:

  • Create any new entities, such as the new files that are about to appear.
  • Create a transcoding task and submits it to a transcoder.
  • Media check the new files and update the item.

The difference between transcoding while and after importing is that the former can be done in parallel to any transfers that may be needed, while the latter is a serial task as the input files, the files from the original shape of the item, should already exist on a storage managed by Vidispine.

Starting transcode jobs

The transcodes to perform are identified using shape tags that contains the transcode preset that the defines the desired outputs.

Use the tag parameter when starting an import job to transcode an item while it is being imported. See Transcoding for more information on the subject.

POST /import?uri=file:///srv/incoming/,android
<JobDocument xmlns="">

To transcode an existing item, use the transcode resource with the tag parameter as above.

POST /item/VX-191440/transcode?tag=lowres,android
<JobDocument xmlns="">

Transcode progress

The progress of the transcode is available from the job, both as progress on the transcode step and as key-value metadata on the job.

<task id="237">
  <progress total="100" unit="percent">75.0</progress>
    <description>Starting transcode</description>

And from the job metadata, where you will find the transcode* job metadata, that also includes the estimated time left and the progress expressed in the media time.



Thumbnails are by default created if an item is transcoded while being imported. To create thumbnails or posters for an item, use a THUMBNAIL job. A thumbnail job will:

  • Create a thumbnailing task and submit it to a transcoder.
  • Update the representative thumbnail of the item.

The location of the representative thumbnail is stored in the item metadata, so if you wish to present a number of items to a user, along with a thumbnail of each item, then it is recommended that you read the thumbnails from the representativeThumbnail metadata field instead of fetching all thumbnails for all items. There is also the representativeThumbnailNoAuth field that provides the thumbnail at a location that does not require authentication.

<timespan start="-INF" end="+INF">
  <field uuid="b578cfe7-cf8b-476f-866f-7027e0dba542" user="system" timestamp="2014-07-03T09:23:24.172+02:00" change="VX-1345770">
    <value uuid="a159d13c-4a70-4e6a-83fd-36a7b0ef25af" user="system" timestamp="2014-07-03T09:23:24.172+02:00" change="VX-1345770">/API/thumbnail/VX-2/VX-191440;version=0/0@PAL</value>
  <field uuid="12c6553d-7473-42bf-95b4-875afd1cac74" user="system" timestamp="2014-07-03T10:46:40.728+02:00" change="VX-1345771">
    <value uuid="9b70a04c-8755-426b-9446-3f4857cb87e1" user="system" timestamp="2014-07-03T10:46:40.728+02:00" change="VX-1345771">/APInoauth/thumbnail/VX-2/VX-191440;version=0/0@PAL?hash=b5424e9878940a333b6230817ae88eef</value>

Starting a thumbnail job

Use the thumbnail resource to create thumbnail jobs for an item.

POST /item/VX-191440/thumbnail?createThumbnails=true
<JobDocument xmlns="">

The thumbnails will be uploaded to the item as the job progresses. You can find them by inspecting the item. For example:

GET /item/VX-191440?content=thumbnail
<ItemDocument xmlns="" id="VX-191440">

If you wish to see which thumbnails were created by a specific thumbnail job, then you can check the thumbnails job metadata.


Analyzing media

Shapes can be analyzed to detect for example detect cropping and silence. See Shape analysis.