Skip to main content
Skip table of contents

Projects and versions [VC 21.3 GEN]

Manage projects.

Projects

Create a project collection

POST /collection/project

Creates a project collection with the given name and metadata.

Accepts:
Produces:

  • application/xml, application/json – URIListDocument

  • text/plain – CRLF-delimited list of ids

Example

NONE 
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>
HTML/XML 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <uri>VX-1</uri>
</URIListDocument>

Project versions

Manage 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:

  • application/xml, application/json – URIListDocument

  • text/plain – CRLF-delimited list of ids

Example

NONE 
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>
HTML/XML 
<?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 all project 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.

Role:

_collection_read

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

Role:

_collection_write

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

Role:

_collection_read

Delete a project version definition

DELETE /collection/(id)/definition/(format)

Deletes a binary representation of the project version.

Status Codes:

  • 404 Not found – Could not find the collection

Role:

_collection_write

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:
Role:

_collection_read

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:
Role:

_collection_write

Delete the asset definition

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

Deletes an asset document for a specific project version definition.

Status Codes:

  • 404 Not found – Could not find the collection

  • 404 Not found – Could not find the definition

Role:

_collection_write

Version definition extradata

Each version definition can also store arbitrary extradata.

Retrieve the extradata

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

Returns the extradata 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:

  • application/octet-stream – The binary extradata.

Role:

_collection_read

Update the extradata

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

Stores extradata for a specific project version definition.

Status Codes:

  • 404 Not found – Could not find the collection

  • 404 Not found – Could not find the definition

Accepts:

  • application/octet-stream – The binary extradata.

Role:

_collection_write

Delete the extradata

DELETE /collection/(id)/definition/(format)/extradata

Deletes the extradata for a specific project version definition.

Status Codes:

  • 404 Not found – Could not find the collection

  • 404 Not found – Could not find the definition

Role:

_collection_write

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 (string) – The location of the file to inspect.

  • type (string) – The file format.

Accepts:
Produces:

Example

NONE 
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>
HTML/XML 
<?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 (string) – The location of the file to import.

  • type (string) – The file format.

  • assignId (boolean) – True if external ids should be created for the items in this project, using the ids from the project. Default is false.

  • pauseFrame (integer) – 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:
Produces:

  • application/xml, application/json – URIListDocument

  • text/plain – CRLF-delimited list of ids

Role:

_import

Role:

_external_id_write

Example

NONE 
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>
HTML/XML 
<?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:

NONE 
GET /item/VX-8/sequence
HTML/XML 
<?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 (string) – The id of the project to create a new version for.

  • uri (string) – The location of the file to import.

  • type (string) – The file format.

  • assignId (boolean) – True if external ids should be created for the items in this project, using the ids from the project. Default is false.

Accepts:
Produces:

  • application/xml, application/json – URIListDocument with the id of the new project version.

  • text/plain – CRLF-delimited list of ids

Role:

_import

Role:

_collection_write

Role:

_external_id_write

Example

Creating a new project:

NONE 
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>
HTML/XML 
<?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.

NONE 
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>
HTML/XML 
<?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 (string) – The destination URI.

  • type (string) – The output format.

  • tag (string) – Comma separated list of shape tags specifying which shapes to reference in the output.

  • format (string) – 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 (boolean) – When set to true, any export problems will be returned and no file will be written. Default is false

  • content (string) – Comma-separated list of content to include in the output. Valid values are: markers, subtitles, sequences, * (default).

  • toSequence (boolean) – Export as a sequence with an item, instead of as a standalone item. Default is false

Status Codes:

  • 404 Not found – Invalid id

Accepts:
Produces:

  • application/xml, application/json – ExportResponseDocument containing the essence mapping, and any export problems (if a dry run.)

  • multipart/mixed – The response document and the export data. The uri parameter will be ignored.

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

NONE 
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>
HTML/XML 
<?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>
BASH 
$ cat /tmp/output.xml
HTML/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.

NONE 
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>
HTML/XML 
<?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>

Export a project or sequence

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

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

Query Parameters:

  • type (string) – The output format.

  • tag (string) – Comma separated list of shape tags specifying which shapes to reference in the output.

  • format (string) – 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 (boolean) – When set to true, any export problems will be returned and no file will be written. Default is false

  • content (string) – Comma-separated list of content to include in the output. Valid values are: markers, subtitles, sequences, * (default).

  • storage (string) – Comma-separated list of item paths in format storageId=path.

  • item (string) – Comma-separated list of item paths in format itemId=path.

  • toSequence (boolean) – Export as a sequence with an item, instead of as a standalone item. Default is false

Status Codes:

  • 404 Not found – Invalid id

Produces:

  • application/xml, application/json – ExportResponseDocument if dryRun=true.

  • */* – The export data, in the media type of the format, if dryRun=false.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close