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

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

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

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

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

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

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

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