Imports [VC 21.3.1 GEN]

Importing is the process of registering essence/media with Vidispine. As Vidispine works with files and objects, either local or in the cloud, another way of putting it is to say that the media file(s) become under Vidispine’s supervision.

Vidispine does not support machine control or baseband video ingest . However, growing files are supported, including operations on items that are currently being ingested.

Importing items

There are several ways of importing media into Vidispine. Which one that is used depends on where the media is located, the order of operations, and what automation that is required.

On a high level, the different ways of importing are:

Regular import

This import uses a URI pointing outside of Vidispine storages to reference the source media. Vidispine will make a copy of the source material (and sidecar files given by the user) to a Vidispine storage.

The job type for this type of import is PLACEHOLDER_IMPORT. For reference information, see Import using a URI.

Raw import

Here, the caller supplies the material in the REST API call as data in the request body. This is useful when the data is stored as a file at the caller’s point, for example when the end user is uploading information in a web browser. It is also useful when the information resides in a location which Vidispine cannot reach, for example behind a firewall.

Vidispine supports partial upload, so the caller can split the input in multiple parts in order to better handle network problems or in order to parallelize uploads.

The job type for this type of import is RAW_IMPORT. Note that the job is not created until all parts of the file has been uploaded. For reference information, see Import using the request body.

File import

This import is used where the file is already located on a storage which is supervised by Vidispine. In this type of import, no copying takes place. Instead, a new item is created, and the file is associated with the file.

The job type for this type of import is RAW_IMPORT. For reference information, see Importing a file from a storage.

Auto-import

This is a special case of file import, where no explicit call has to be done for every file. The user sets up rules for how files are imported, and if any sidecar files are processed as well.

The job type for this type of import is AUTO_IMPORT. For reference information, see Auto-import rules.

Placeholder import

A placeholder import is an import where the placeholder item and a placeholder shape are created before any file is imported. When creating the placeholder shape, the caller gives item metadata and information about the components. The creation of the placeholder item is a synchronous operation, and the item id is immediately returned.

Using the item id, the caller can populate the placeholder shape with files, either by posting the URI or the raw content to the components of the shape. The placeholder import is the import method that gives the highest flexibility.

For reference information, see Placeholder imports.

Sidecar files

Sidecar files, containing metadata, subtitles, or other supplementary information, can be imported to an item either at the same time as the item is imported, or afterwards using an sidecar import job.

Steps of import operation

Every import job consists of a number of job steps. Some of the the job steps run in parallel, and some in sequence. These are the most important steps in an import job:

• Create entities. The item and the original shape is created. This will not take place if the caller already has created the item before the job (placeholder import).

• Transfer media. The media is transferred from the source URI to a Vidispine storage. This will not take place if the media is already located on a Vidispine storage (raw import, file import, auto-import).

• Initial media check. The media is checked using a shape deduction by the transcoder. The components of the original shape are created.

• Transcoding. Using the information about the original shape and all shape tags given by the caller at the invocation of the job, a transcoding task is created and given to the transcoder.

• A media check of all new shapes takes place, as soon as the transcoder has started to work.

• A final media check of the original media and transcoder shapes is done after the transcoder has finished.

• Any XMP, EXIF, or document metadata is extracted.

• Optionally, the original shape can be replaced by a transcoded shape. This is useful if one seeks to have one “house format” as the original shape format, and all incoming material of other types should be converted into the house format.

• Sidecar files are imported.

Transcoding

During import, the caller decides which shape tags that are to be created from the original media. By default, thumbnails are created according the to the shape tag definitions. The caller can choose which thumbnail service resource to use, if multiple resources are set up. This is done using the query parameter thumbnailService. In addition to thumbnails, full-resolution posters images can be created, by supplying a list of timecodes in the query parameter createPosters. The creation of thumbnails can be disabled by setting the query parameter thumbnails to false.

Notifications

As with all jobs in Vidispine, the caller can be notified about the job progress by HTTP messages or other actions. This is described in the Notifications section.

Adjusting import

The import API is very rich and contains several parameters. Fortunately, most of the time, the default values can be used.

Import settings

Settings that are used during imports can be set prior to starting an import job. An example of such a setting are access control lists. The settings can then be used by specifying the id of the settings profile using the query parameter settings.

Special job metadata values

Special instructions can be supplied to the import job via the the query parameter jobmetadata= { key = value }. Note that the equals sign is part of the value of the query parameter, so it has to be URL encoded (%3d)

Cut off start and end of video

Given that the video has SMPTE timecodes, an interval can be cut out using the metadata smpteTimeCode and lastSmpteTimeCode. If the video has no SMPTE timecode, the interval is calculated based on the first timestamp in the video.

Checksum on file transfer

Normally, the checksum of the imported files will be computed asynchronously in the background. For PLACEHOLDER_IMPORT jobs, by specifying the jobmetadata checksumMode%3Dtransfer, the checksum of files will be computed during the transfer step of the job. See checksumMode.