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
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
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: - application/xml, application/json – EssenceMappingsDocument
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
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.
- 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: Produces: - application/xml, application/json – URIListDocument
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.
Accepts: - application/xml, application/json – EssenceMappingsDocument
Produces: - application/xml, application/json – URIListDocument
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&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.
Status Codes: - 404 Not found – Invalid id
Accepts: - application/xml, application/json – ExportRequestDocument with details on the export.
Produces: - application/xml, application/json – ExportResponseDocument
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&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>