UC Field Groups [C IG]
Motivation
VidiCore field groups are used for modelling Segment Lists [C ARC] in an Enterprise MAM Solution. Frontend applications like MediaPortal can display these segments and other frontend applications like MediaLogger can create or modify these segments. Segments can also be created by backend modules, e.g. via AI services.
The following section shows concrete examples for working with field groups on VidiCore level to properly model segments.
Workflow
Create Field Groups
Creating field groups is a standard VidiCore metadata operation:
PUT /API/item/<itemId>/metadata
<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<timespan start="50@PAL" end="125@PAL">
<group>
<name>V3_SampleSegmentList</name>
<field>
<name>V3_SegmentTitle</name>
<value>Title for segment 50-125</value>
</field>
<field>
<name>V3_SegmentDescription</name>
<value>Description for segment 50-125</value>
</field>
</group>
</timespan>
<timespan start="250@PAL" end="325@PAL">
<group>
<name>V3_SampleSegmentList</name>
<field>
<name>V3_SegmentTitle</name>
<value>Title for segment 250-325</value>
</field>
<field>
<name>V3_SegmentDescription</name>
<value>Description for segment 250-325</value>
</field>
</group>
</timespan>
</MetadataDocument>
Delete Field Groups
The VidiCore API call PUT /API/item/<itemId>/metadata
only adds or modifies the metadata fields and groups present in the MetadataDocument
. To delete a field group you need to specify the mode=”remove”
attribute:
PUT /API/item/<itemId>/metadata
<MetadataDocument xmlns="
<timespan start="50@PAL" end="125@PAL">
<group mode="remove">
<name>V3_SampleSegmentList</name>
</group>
</timespan>
</MetadataDocument>
Set Multiple Field Groups On The Same Timespan
In case segments from multiple segments are located on the same timecode interval they need to be put into the same <timespan>
element in the VidiCore MetadataDocument
. This results in multiple groups of the same name in the same timespan.
To initially set multiple groups on a timespan just supply multiple <group>
elements with the same name:
PUT /API/item/<itemId>/metadata
<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<timespan start="55@PAL" end="56@PAL">
<group>
<name>V3_SampleSegmentList</name>
<field>
<name>V3_SegmentTitle</name>
<value>Title for segment 55-56</value>
</field>
<field>
<name>V3_SegmentDescription</name>
<value>Description for segment 55-56</value>
</field>
</group>
<group>
<name>V3_AnotherSampleSegmentList</name>
<field>
<name>V3_AnotherSegmentTitle</name>
<value>Title for another segment 55-56</value>
</field>
<field>
<name>V3_AnotherSegmentDescription</name>
<value>Description for another segment 55-56</value>
</field>
</group>
</timespan>
</MetadataDocument>
To add another group to a timespan that already has one or multiple groups of the same name use the mode=”add”
attribute:
PUT /API/item/<itemId>/metadata
<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<timespan start="55@PAL" end="56@PAL">
<group mode="add">
<name>V3_SampleSegmentList</name>
<field>
<name>V3_SegmentTitle</name>
<value>Title for segment 55-56</value>
</field>
<field>
<name>V3_SegmentDescription</name>
<value>Description for segment 55-56</value>
</field>
</group>
</timespan>
</MetadataDocument>
Change An Existing Field Group
Existing field groups can be changed the same way as setting them initially (see above). However, when multiple groups of the same name are in the timespan then you need to tell VidiCore which of these groups to modify. This is done by specifying the group’s uuid
value:
PUT /API/item/<itemId>/metadata
<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<timespan start="55@PAL" end="56@PAL">
<group uuid="279fb721-9836-48c7-86ee-50088d004739">
<name>V3_SampleSegmentList</name>
<field>
<name>V3_SegmentTitle</name>
<value>Title for segment 55-56</value>
</field>
<field>
<name>V3_SegmentDescription</name>
<value>Description for segment 55-56</value>
</field>
</group>
</timespan>
</MetadataDocument>
The uuid
of a field group (as well as the uuids of all fields) always is returned as part of the MetadataDocument
when fetching metadata from VidiCore. VidiCore also returns them when applying metadata to an item or collection. However, VidiCore by default returns the complete MetadataDocument
which may be an expensive operation when dealing with complex metadata structures. To mitigate this you can use output projections to reduce the amount of data returned by VidiCore:
PUT /API/item/<itemId>/metadata;output-projection=uuidsonly
<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<timespan start="55@PAL" end="56@PAL">
<group>
<name>V3_LogEntry </name>
[...]
<group>
<name>V3_PlayerAction</name>
[...]
</group>
<group>
<name>V3_PlayerAction</name>
[...]
</group>
</group>
</timespan>
</MetadataDocument>
The output projection needs to be configured in VidiCore once and should match your metadata structure and use-case. The following example shows the output projection for a metadata group V3_LogEntry
which can contain one or multiple subgroups V3_PlayerAction
:
PUT /API/projection/uuidsonly/outgoing
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:vs="http://xml.vidispine.com/schema/vidispine">
<xsl:template match="/">
<metadata>
<xsl:for-each select="vs:MetadataListDocument/vs:item/vs:metadata/vs:timespan/vs:group[vs:name='V3_LogEntry']">
<xsl:sort select="substring(@change,4)" data-type="number" order="descending"/>
<xsl:if test="position()=1">
<LogEntry>
<uuid>
<xsl:value-of select="@uuid"/>
</uuid>
<xsl:for-each select="vs:group[vs:name='V3_PlayerAction']">
<PlayerAction>
<uuid>
<xsl:value-of select="@uuid"/>
</uuid>
</PlayerAction>
</xsl:for-each>
</LogEntry>
</xsl:if>
</xsl:for-each>
</metadata>
</xsl:template>
</xsl:stylesheet>
When using this output projection like shown above you will get a result like this:
<?xml version="1.0" encoding="UTF-8"?>
<metadata xmlns:vs="http://xml.vidispine.com/schema/vidispine">
<LogEntry>
<uuid>bdf41455-119c-4666-bad7-15dc1fb2e8e4</uuid>
<PlayerAction>
<uuid>ee40d2bb-5c55-43ba-8ce7-a114e6a8f8ab</uuid>
</PlayerAction>
<PlayerAction>
<uuid>d558f400-6fb1-47ea-b5c6-12c4e52b5f13</uuid>
</PlayerAction>
</LogEntry>
</metadata>