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

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

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

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"/>>
CODE

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

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
CODE

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