Projects and versions¶
Projects¶
Create a project collection¶
-
POST
/collection/project
¶ Creates a project collection with the given name and metadata.
Accepts: - application/xml, application/json – ProjectDocument
Produces: - application/xml, application/json – URIListDocument
- text/plain – CRLF-delimited list of ids
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: - application/xml, application/json – ProjectVersionDocument
Produces: - application/xml, application/json – URIListDocument
- text/plain – CRLF-delimited list of ids
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.
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
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: - application/xml, application/json – EssenceMappingsDocument
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: - application/xml, application/json – EssenceMappingsDocument
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
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: - application/xml, application/json – EssenceMappingsDocument
Produces: - application/xml, application/json – ProjectFileDocument
Example¶
POST /collection/project/inspect?uri=file:///home/maria/sequence.xml&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.
- assignId – True if external ids should be created for the items in this project, using the ids from the project.
- 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: - application/xml, application/json – EssenceMappingsDocument
Produces: - application/xml, application/json – URIListDocument
- text/plain – CRLF-delimited list of ids
Role: _import
Role: _external_id_write
Example¶
POST /import/project/sequence?uri=file:///home/maria/sequence.xml&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.
- assignId – True if external ids should be created for the items in this project, using the ids from the project.
Accepts: - application/xml, application/json – EssenceMappingsDocument
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:
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&type=finalcut&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.
- content – Comma-separated list of content to include in the output. Possible
values are:
markers
,subtitles
,sequences
,*
(default). - toSequence – Export as a sequence with an item, instead of as a standalone item.
Status Codes: - 404 Not found – Invalid id
Accepts: - application/xml, application/json – ExportRequestDocument with details on the export.
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¶
POST /item/VX-6/sequence/export?uri=file:///tmp/output.xml&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&dryRun=true&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>
-
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 – 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.
- content – Comma-separated list of content to include in the output. Possible
values are:
markers
,subtitles
,sequences
,*
(default). - storage – Comma-separated list of item paths in format
storageId=path
. - item – Comma-separated list of item paths in format
itemId=path
. - toSequence – Export as a sequence with an item, instead of as a standalone item.
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
.