UC Field Groups

Motivation

VidiCore field groups are used for modelling Segment Lists [C ARC] in an on-prem/hybrid/BYOC 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:

CODE

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:

CODE

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:

CODE

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:

CODE

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:

CODE

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:

CODE

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 :

CODE

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

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