UC Import a file to VidiCore using URL [VC UG]
URLs can be used to import media files into VidiCore. VidiCore will first copy the file to one of the configured storage, and then create a new item and shape containing that file
User could also create a placeholder
item and then import files later in a separate request.
Import a file directly
The following request can be use to import a file by URL:
curl -H Content-type:application/xml -d @metadata.xml http:///localhost:8080/API/import?uri=file:///path/to/file/demo.mxf
Note that a mandatory metadata document is include in this request to set the initial item metadata:
<MetadataDocument xmlns="<http://xml.vidispine.com/schema/vidispine">>
<!-- <timespan end="+INF" start="-INF"> -->
<!-- <field> -->
<!-- <name>title</name> -->
<!-- <value>This is an imported item!</value> -->
<!-- </field> -->
<!-- </timespan> -->
</MetadataDocument>
A PLACEHOLDER_JOB
will be created after the request:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<JobDocument xmlns="<http://xml.vidispine.com/schema/vidispine">>
<jobId>VX-11592</jobId>
<user>admin</user>
<started>2021-06-15T15:15:52.136Z</started>
<status>READY</status>
<type>PLACEHOLDER_IMPORT</type>
<priority>MEDIUM</priority>
</JobDocument>
And the newly created item id can be found by checking the job log:
curl -H Accept:application/xml http:///localhost:8080/API/job/VX-11592
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<JobDocument xmlns="<http://xml.vidispine.com/schema/vidispine">>
...
<data>
<key>item</key>
<value>VX-15092</value>
</data>
...
</JobDocument>
Import to a placeholder item
Besides importing using an URI directly, user could also create an item first, and then import files to those items in separate requests.
First, the user needs to create an item containing a placeholder shape by specifying some shape component information and the initial item metadata.
For example, the following request would create an item with 1 video component and 2 audio component:
curl -X POST -d@metadata.xml "localhost:8080/API/import/placeholder?video=1&audio=2"
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ItemDocument id="VX-15099" xmlns="<http://xml.vidispine.com/schema/vidispine"/>>
The item will container one placeholder holder shape that could be found using:
GET /API/item/VX-15099/shape?placeholder=true
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<URIListDocument xmlns="<http://xml.vidispine.com/schema/vidispine">>
<uri>VX-15188</uri>
</URIListDocument>
User could then import the video and audio components using:
POST /API/import/placeholder/VX-15099/video?uri=file:///path/to/video.mov
POST /API/import/placeholder/VX-15099/audio?uri=file:///path/to/audio1.mov
POST /API/import/placeholder/VX-15099/audio?uri=file:///path/to/audio2.mov
Once all the components in the placeholder shape has been fulfilled, the shape would become a "regular" shape, and can be found using: GET /API/item/VX-15099/shape
The container component in a placeholder import
A container component in VidiCore is conceptually similar to a media container (e.g.MP4, MXF, etc). It typically contains one or many video/audio streams.
A placeholder import to the container component will "auto-fill" missing video/audio components within that placeholder shape.
For example:
If a placeholder item is created with one container component and one video component, like:
POST /API/import/placeholder?container=1&video=1"
and a "container component import" was made using a video file
POST /API/import/placeholder/VX-15099/container?uri=file:///path/to/video.mov
then both the container component and video component will be fulfilled.
Meaning any subsequent "video component import" will fail:
POST /API/import/placeholder/VX-15099/video?uri=file:///path/to/video2.mov
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ExceptionDocument xmlns="<http://xml.vidispine.com/schema/vidispine">>
<invalidInput>
<context>job</context>
<explanation>No more components of that type is accepted</explanation>
<value>VIDEO_COMPONENT</value>
</invalidInput>
</ExceptionDocument>