Image sequences

Image sequences can be imported into Vidispine just like any other video file.

Overview

An image sequence is made up of multiple sequentially numbered images files. Typically each file represents a video frame.

All files in a sequence are represented using a single file in Vidispine. Such files have a type of FILE_SEQUENCE.

<FileDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <id>VX-5591787</id>
  <path>VX-5591787//.jpg</path>
  <uri>file:/srv/media/VX-5591787/*.jpg#file=0-49</uri>
  <state>CLOSED</state>
  <size>-1</size>
  <timestamp>2016-06-23T14:50:58.129+02:00</timestamp>
  <refreshFlag>1</refreshFlag>
  <storage>VX-1</storage>
  <metadata/>
  <range start="0" count="50"/>
  <type>FILE_SEQUENCE</type>
</FileDocument>

Importing image sequences

Image sequences can be imported using a sequence URI. For example, to import an image sequence whose sequence numbers are zero padded:

POST API/import?uri=file:///srv/data/take1/*.png#file=00000-15000
<JobDocument xmlns:ns0="http://xml.vidispine.com/schema/vidispine">
  <jobId>VX-127247</jobId>
  <user>admin</user>
  <started>2016-06-23T13:02:04.811Z</started>
  <status>READY</status>
  <type>PLACEHOLDER_IMPORT</type>
  <priority>MEDIUM</priority>
</JobDocument>

Detection of image sequences

To have image sequences detected on a storage, the storage must first be configured with one or more sequence patterns. Otherwise, individual files in the sequence will appear as separate files.

<StorageDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <id>VX-1879</id>
  <state>NONE</state>
  <type>LOCAL</type>
  <capacity>16851361792</capacity>
  <freeCapacity>16763961344</freeCapacity>
  <timestamp>2016-06-23T15:04:02.873+02:00</timestamp>
  <method>
    <id>VX-1829</id>
    <uri>file:///srv/media/</uri>
    <read>true</read>
    <write>true</write>
    <browse>true</browse>
    <lastSuccess>2016-06-23T15:04:02.878+02:00</lastSuccess>
    <type>NONE</type>
  </method>
  <sequence>
    <regex>.*-(\d+).png</regex>
  </sequence>
</StorageDocument>

Files that match the pattern and that have the same sequence key will appear as a single file with type FILE_SEQUENCE. These files can then be imported directly from the storage just like any other files.

POST /storage/file/VX-46264/import
Content-Type: application/xml

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <timespan start="-INF" end="+INF">
    <!-- any metadata to add to the item -->
  </timespan>
</MetadataDocument>

Sequence URIs

Any URI containing a file fragment is considered as a sequence URI, that is, as a URI that identifies multiple files in a sequence. A sequence URI should contain a wildcard character that identifies the location of the sequence number.

Syntax: file=[wildcard:][start[-end]][,...]

  • The default wildcard character is *. If the wildcard character is already present in the file name or path, then another wildcard character should be selected and specified in the file fragment.
  • The default starting index is 0.
  • The ending index is inclusive.
  • When importing sequences using the API, only the last range in the file fragment may be open. That is, file=0-10,40- is supported, but file=0-10,40-,10-20 is not.

Example:

  • file:///srv/media/inside-tardis/*.jpg#file=00000-90000
  • file:///srv/media/inside-tardis/X.jpg#file=X:00000-90000
  • http://media.example.com/?id=take1&num=*#file=0-

Sequence patterns

The sequence pattern element contains a <regex>, and a optional <numGroup>.

The value of the <regex> should be a valid java regex string with some restrictions:

  • There needs to be a \d+, which would match multiple digits. The matching digits will be used as the sequence number. The other parts will become the sequence key, which will be used to identify the sequence.

    Important

    A sequence number can only contain one or multiple digits. Only numbers and zero padded numbers are supported

  • \d+ needs to be in a capturing groups, if there are other groups. And in this case, <numGroup> needs to be set.

The value of <numGroup> is the index of the sequence number capturing group.

Some Examples:

<StorageDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <id>VX-1879</id>
  ...
  <sequence>
    <regex>.*-(\d+).png</regex>
    <numGroup>1</numGroup>
  </sequence>
</StorageDocument>
<StorageDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <id>VX-1879</id>
  ...
  <sequence>
    <regex>(.*)-(\d+).png</regex>
    <numGroup>2</numGroup>
  </sequence>
</StorageDocument>