UC Import a file to VidiCore using URL

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:

CODE

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

CODE

<?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

CODE

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

CODE

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:

CODE

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:

CODE

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:

CODE

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>