Projects and versions

Projects

Create a project collection

POST /collection/project

Creates a project collection with the given name and metadata.

Accepts:
Produces:

Example

POST /collection/project
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ProjectDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <name>Untitled Project</name>
  <metadata>...</metadata>
</ProjectDocument>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <uri>VX-1</uri>
</URIListDocument>

Project versions

Create a project version collection

POST /collection/(id)/version

Creates a new project version collection for a specific project.

Status Codes:
  • 404 Not found – Could not find the collection
Accepts:
Produces:

Example

POST /collection/VX-1/version
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ProjectVersionDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <item>
    <id>VX-1</id>
  </item>
  <sequence>...</sequence>
  <metadata>...</metadata>
</ProjectVersionDocument>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <uri>VX-2</uri>
</URIListDocument>

Version definitions

List the available version definitions

GET /collection/(id)/definition

Returns the format of the definitions that have been stored for a specific project version.

Status Codes:
  • 404 Not found – Could not find the collection
Produces:
  • text/plain – A CLRF separated list of formats.

Update a project version definition

PUT /collection/(id)/definition/(format)

Updates a binary representation of the project version. The collection must be a project version collection.

Status Codes:
  • 404 Not found – Could not find the collection
Accepts:
  • application/octet-stream – The binary version definition

Retrieve a project version definition

GET /collection/(id)/definition/(format)

Retrieves a binary representation of the project version.

Status Codes:
  • 404 Not found – Could not find the collection
  • 404 Not found – Could not find the definition
Produces:
  • application/octet-stream – The stored version definition

Assets in project version definition

To be able to track which clips and sequences corresponds to which items in Vidispine, an essence mapping can be stored for each version definition. This mapping is required for Vidispine to be able to convert between different formats.

Retrieve the asset definition

GET /collection/(id)/definition/(format)/asset

Returns the asset document that has been stored for a specific project version definition.

Status Codes:
  • 404 Not found – Could not find the collection
  • 404 Not found – Could not find the definition
Produces:

Update the asset definition

PUT /collection/(id)/definition/(format)/asset

Stores an asset document for a specific project version definition. The document should identify the items and files referenced by the definition.

Status Codes:
  • 404 Not found – Could not find the collection
  • 404 Not found – Could not find the definition
Accepts:

Inspecting project files

Inspect a project file

POST /collection/project/inspect

Returns a document listing the sequences and assets referenced from a given project file.

Query Parameters:
 
  • uri – The location of the file to inspect.
  • type – The file format.
Accepts:
Produces:

Example

POST /collection/project/inspect?uri=file:///home/maria/sequence.xml&amp;type=finalcut
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<EssenceMappingDocument xmlns="http://xml.vidispine.com/schema/vidispine">
</EssenceMappingDocument>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ProjectFileDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <location>file:///home/maria/sequence.xml</location>
  <asset>
    <id>urn:uuid:8CED8AFE-1A67-4632-AB57-D5F5B1E0BC49</id>
    <name>Sequence 1</name>
    <type>sequence</type>
    <status>unknown</status>
  </asset>
  <asset>
    <id>urn:uuid:FCAD0878-7129-43DA-A8A0-696590EFE4DA</id>
    <name>Sample Clip B</name>
    <type>clip</type>
    <status>unknown</status>
    <file>
      <path>file://localhost/Users/maria/Sample%20Clip%20B.mov</path>
    </file>
  </asset>
  <asset>
    <id>urn:uuid:76BE320F-48E0-47A5-A076-227158C50024</id>
    <name>Clip A</name>
    <type>clip</type>
    <status>unknown</status>
    <file>
      <path>file://localhost/Users/maria/Movies/Vidispine/VX-1.mov</path>
    </file>
  </asset>
</ProjectFileDocument>

Importing projects and sequences

Import a sequence

POST /import/project/sequence

Creates a new item with a Vidispine sequence representations of the given file. The file must contain a single sequence.

The item will also have a sequence contain the original data from the file, together with an essence mapping for identifying the items and files referenced by the sequence.

Query Parameters:
 
  • uri – The location of the file to import.
  • type – The file format.
  • pauseFrame – When a rendering job is started, this parameter determines which frame the job will pause at. The job will resume when the sequence is updated.
Accepts-xml.-json:
 

EssenceMappingsDocument

Produces:

Example

POST /import/project/sequence?uri=file:///home/maria/sequence.xml&amp;type=finalcut
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<EssenceMappingsDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <asset id=”urn:uuid:76BE320F-48E0-47A5-A076-227158C50024” item=”VX-1”/>
  <file path="file://localhost/storage/VX-1.mov" hash="7b8d6ffe1ea468800578d6b7d4a09b012c461569"/>
</EssenceMappingsDocument>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <uri>VX-8</uri>
</URIListDocument>

Retrieving the sequences:

GET /item/VX-8/sequence
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SequenceListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <sequence>
    <id>VX-1</sequence>
    <type>finalcut</type>
  </sequence>
  <sequence>
    <id>VX-2</sequence>
    <type>vidispine</type>
  </sequence>
</SequenceListDocument>

Import a project

POST /import/project

Creates a new project version containing the clips and sequences found in the given project file. Sequences in the file will be created as items having a Vidispine sequence representation.

Query Parameters:
 
  • collectionId – The id of the project to create a new version for.
  • uri – The location of the file to import.
  • type – The file format.
Accepts:
Produces:
Returns:

The id of the new project version.

Example

Creating a new project:

POST /collection/project
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ProjectDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <name>Marias Project</name>
  <metadata/>
</ProjectDocument>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <uri>VX-1</uri>
</URIListDocument>

Creating a new project version with the clips and sequences from a Final Cut Pro project.

POST /import/project?collectionId=VX-1&amp;type=finalcut&amp;uri=file:///storage/project.xml
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<EssenceMappingsDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <asset id=”urn:uuid:76BE320F-48E0-47A5-A076-227158C50024” item=”VX-1”/>
  <file path="file://localhost/storage/VX-1.mov" hash="7b8d6ffe1ea468800578d6b7d4a09b012c461569"/>
</EssenceMappingsDocument>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <uri>VX-2</uri>
</URIListDocument>

Exporting projects and sequences

Export a project or sequence

POST /collection/(id)/version/export
POST /item/(id)/sequence/export
POST /sequence/export

Exports the sequence or project to the requested output format and saves the result at the given location.

For POST /sequence/export the sequence must be specified in the request document.

Query Parameters:
 
  • uri – The destination URI.
  • type – The output format.
  • tag – A comma separated list of shape tags specifying which shapes to reference in the output.
  • format – A comma separated list of formats specifying which shapes to reference in the output. If both tag and format is given, then both must match.
  • dryRun – When set to true, any export problems will be returned and no file will be written.
Status Codes:
  • 404 Not found – Invalid id
Accepts:
Produces:
Returns:

A document containing the essence mapping, and any export problems (if a dry run.)

The storage(s) that should be used can be specified in the request, and should be ordered in descending priority. For each storage it is also possible to specify the path to where the files will be available, so that formats that reference files by path can contain a usable client-side path.

Example

POST /item/VX-6/sequence/export?uri=file:///tmp/output.xml&amp;type=finalcut
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ExportRequestDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <storage>
    <id>VX-1</id>
    <path>/Users/maria/Movies/Vidispine/</path>
  </storage>
</ExportRequestDocument>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ExportResponseDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <mappings>
    <file path="file:///Users/maria/Movies/Vidispine/VX-1.mov" hash="7b8d6ffe1ea468800578d6b7d4a09b012c461569" size="30346173"/>
    <asset id="480a5bd6-b89a-476c-be2f-c2ce23ba53e8" item="VX-1"/>
  </mappings>
</ExportResponseDocument>
$ cat /tmp/output.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE xmeml>
<xmeml version="5">
  ...
  <clip id="480a5bd6-b89a-476c-be2f-c2ce23ba53e8">
    <name>Item title</name>
    <uuid>480a5bd6-b89a-476c-be2f-c2ce23ba53e8</uuid>
    <file>
      ...
      <pathurl>file://localhost/Users/maria/Movies/Vidispine/VX-1.mov</pathurl>
    </file>
    ...
  </clip>
  ...
</xmeml>

Exporting to AAF without first transcoding the items to OP-Atom.

POST /item/VX-6/sequence/export?type=aaf&amp;dryRun=true&amp;tag=op-atom``
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ExportRequestDocument xmlns="http://xml.vidispine.com/schema/vidispine">
</ExportRequestDocument>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ExportResponseDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <problem>
    <type>missing-shape</type>
    <message>Found no shape matching the given format</message>
    <parameter>
      <key>item</key>
      <value>VX-1</value>
    </parameter>
    <parameter>
      <key>format</key>
      <value></value>
    </parameter>
    <parameter>
      <key>tag</key>
      <value>op-atom</value>
    </parameter>
  </problem>
  <mappings>
    <asset id="urn:uuid:11111111-2222-3333-4444-555555555555" item="VX-1"/>
  </mappings>
</ExportResponseDocument>