Create Shape On Placeholder Item (w/o Physical File Access) [ENT 21.4 IG]

Motivation

In some scenarios it may be required to create shapes on VidiCore items without VidiCore accessing the physical file behind the shape.

A possible scenario are files located on an archive storage which is not not accessible by VidiCore.

Another scenario would be to import files to VidiCore but avoiding load on VidiCore due to PLACEHOLDER_IMPORT jobs.

Workflow

This workflow should be used with extreme caution.

VidiCore’s structure of technical metadata is very detailled and is created in a consistent way by VidiCoder. Circumventing VidiCoder for filling in the technical metadata an lead to unwanted side-effects when such shapes are being processed at a later stage.

Create a placeholder item as described in Import A File Into A New Item [ENT 21.4 IG]‎.
Create a ShapeDocument containing all the relevant metadata. The simplest ShapeDocument would be an empty one. To populate the startTimeCode and durationTimeCode metadata fields you need at least these values in the ShapeDocument:

CODE

{
  "tag": ["original"],
  "containerComponent": {
    "duration": {
       "samples": 100000,
       "timeBase": {
         "numerator": 1,
         "denominator": 1000
       }
    },
    "startTimecode": 90,
    "roundedTimeBase" : 30,
    "metadata": [{
        "key": "componentOriginalFilename",
        "value": "mysource.mxf"
      }, {
        "key": "creation_time",
        "value": "2019-02-01 09:00:00"
      }
    ]
  }
}

You can directly specify the VidiCore file IDs in the document:

CODE

{
    "created": "0001-01-01T00:00:00",
    "essenceVersion": 0,
    "tag": ["original"],
    "containerComponent": {
        "duration": {
            "samples": 3299797,
            "timeBase": {
                "numerator": 1,
                "denominator": 1000
            }
        },
        "startTimecode": 1069935,
        "startTimestamp": {
            "samples": 0,
            "timeBase": {
                "numerator": 1,
                "denominator": 1000
            }
        },
        "roundedTimeBase": 30,
        "dropFrame": true,
        "file": [{
                "id": "FILE-VX-5429",
                "timestamp": "0001-01-01T00:00:00"
            }
        ],
        "id": null,
        "metadata": [{
                "key": "componentOriginalFilename",
                "value": "MAAAAA3FV4.mxf"
            }, {
                "key": "creation_time",
                "value": "2019-01-04 18:18:41"
            }
        ]
    },
    "videoComponent": [{
            "resolution": {
                "width": 1920,
                "height": 1080
            },
            "dropFrame": true,
            "timeBase": {
                "numerator": 1001,
                "denominator": 30000
            },
            "essenceStreamId": 1,
            "bitrate": 50000000,
            "duration": {
                "samples": 3299797,
                "timeBase": {
                    "numerator": 1,
                    "denominator": 1000
                }
            },
            "startTimestamp": {
                "samples": 0,
                "timeBase": {
                    "numerator": 1,
                    "denominator": 1000
                }
            },
            "file": [{
                    "id": "FILE-VX-5429",
                    "timestamp": "0001-01-01T00:00:00"
                }
            ],
            "id": null,
            "metadata": [{
                    "key": "componentOriginalFilename",
                    "value": "MAAAAA3FV4.mxf"
                }, {
                    "key": "creation_time",
                    "value": "2019-01-04 18:18:41"
                }
            ]
        }
    ],
    "audioComponent": [{
            "channelCount": 1,
            "timeBase": {
                "numerator": 1,
                "denominator": 48000
            },
            "itemTrack": "A1",
            "essenceStreamId": 2,
            "file": [{
                    "id": "FILE-VX-5429",
                    "timestamp": "0001-01-01T00:00:00"
                }
            ],
            "id": null,
            "metadata": null
        }, {
            "channelCount": 1,
            "timeBase": {
                "numerator": 1,
                "denominator": 48000
            },
            "itemTrack": "A2",
            "essenceStreamId": 3,
            "file": [{
                    "id": "FILE-VX-5429",
                    "timestamp": "0001-01-01T00:00:00"
                }
            ],
            "id": null,
            "metadata": null
        }, {
            "channelCount": 1,
            "timeBase": {
                "numerator": 1,
                "denominator": 48000
            },
            "itemTrack": "A3",
            "essenceStreamId": 4,
            "file": [{
                    "id": "FILE-VX-5429",
                    "timestamp": "0001-01-01T00:00:00"
                }
            ],
            "id": null,
            "metadata": null
        }, {
            "channelCount": 1,
            "timeBase": {
                "numerator": 1,
                "denominator": 48000
            },
            "itemTrack": "A4",
            "essenceStreamId": 5,
            "file": [{
                    "id": "FILE-VX-5429",
                    "timestamp": "0001-01-01T00:00:00"
                }
            ],
            "id": null,
            "metadata": null
        }, {
            "channelCount": 1,
            "timeBase": {
                "numerator": 1,
                "denominator": 48000
            },
            "itemTrack": "A5",
            "essenceStreamId": 6,
            "file": [{
                    "id": "FILE-VX-5429",
                    "timestamp": "0001-01-01T00:00:00"
                }
            ],
            "id": null,
            "metadata": null
        }, {
            "channelCount": 1,
            "timeBase": {
                "numerator": 1,
                "denominator": 48000
            },
            "itemTrack": "A6",
            "essenceStreamId": 7,
            "file": [{
                    "id": "FILE-VX-5429",
                    "timestamp": "0001-01-01T00:00:00"
                }
            ],
            "id": null,
            "metadata": null
        }, {
            "channelCount": 1,
            "timeBase": {
                "numerator": 1,
                "denominator": 48000
            },
            "itemTrack": "A7",
            "essenceStreamId": 8,
            "file": [{
                    "id": "FILE-VX-5429",
                    "timestamp": "0001-01-01T00:00:00"
                }
            ],
            "id": null,
            "metadata": null
        }, {
            "channelCount": 1,
            "timeBase": {
                "numerator": 1,
                "denominator": 48000
            },
            "itemTrack": "A8",
            "essenceStreamId": 9,
            "file": [{
                    "id": "FILE-VX-5429",
                    "timestamp": "0001-01-01T00:00:00"
                }
            ],
            "id": null,
            "metadata": null
        }
    ]
}

VidiCore will use the file IDs and populate the rest of the structure (file URI) etc. appropriately.

Please note that these JSON documents only serve as an orientation. They do not provide a fully functional solution.

Create the shape on the placeholder item via
POST /API/item/<itemId>/shape/create?updateItemMetadata=true
and supply the ShapeDocument as body.
If you are posting a shape with shape tag original the query parameter updateItemMetadata=true ensures that system-defined item metadata fields like mediaType, startTimeCode, durationTimeCode etc. are updated according to the contents of the ShapeDocument.