Document toolboxDocument toolbox


Entities in Vidispine [VC 21.3 GEN]

Before start playing with the API, a short introduction to the data model might be valuable. The figure Overview of the entities in Vidispine shows some of the entities that builds the assets in Vidispine.

The following image provides an overview of the entities in Vidispine.


The item is the central piece in the data model. This corresponds to an asset in other systems. The item is an abstraction of the physical content (essence) and holds information about the content (metadata). For information about how to create items, see Imports.

Other entities, further down in the hierarchy, may also hold metadata. The item has the richest functions for how metadata can be stored, searched, and indexed. For information about metadata on an item, see Item metadata.

The item also holds information about which users that are allowed to read and modify information (access control). For information about access control, see Access control for items, libraries, collections.


A shape is a physical rendition of an item.

  • For a video, it can be a low-resolution editing version, a web version, …

  • For a document, it can the the pages as images, extracted text, …

  • Etc.

For information about shapes, see Item shapes.

A shape can have one or several shape tags. The shape tags are used when Vidispine selects which files that are being transcoder, exported, thumbnailed, etc. A special shape tag is original, a shape tag that the imported source file gets. The shape tag also contains the recipe for how to create new shapes using the transcoder. For information about shape tags, see Shape tags and presets.


Each shape has one or more components. A media shape might for example contain:

  • A container component

  • Video components

  • Audio components

Each component corresponds to one file content. There may be several copies of the file however.

The component contains information (technical metadata) about codes, resolution, frame rate and more. For information about components, see Item shapes.

File and storage

The file entity represents a physical file on a file system. The file is stored on a storage. Vidispine manages all files, and knows which copies of a file that have been made, and how they relate.

For information about files and storages, see Storages.


A library is a list of items. A library can be created manually, by adding the items to a library, or dynamically, by adding search results to a library. Libraries are useful when performing batch operations. Libraries can also be used when creating rules.

For information about libraries, see Libraries.


A collection is a list of items, libraries, and/or collections. Collections may have metadata and access rights, which are applied to the items that belong to the collection. While the library is typically created from a search operation, the collection is often used like a file system folder, to organize items.

For information about collections, see Collections.