Developers
How can we help you?
The Superset metadata exporter
Many of the services and destinations you want to publish your metadata to have tightly defined and controlled metadata specifications, often in widely used formats such as CableLabs 1.1, 2.0, 3.0, YouTube, etc. The Metadata product fully supports delivering your metadata formatted for these specifications, and we have existing implementations of metadata exporters for the widely used formats above, as well as many more. However, some services are less restrictive or have not defined a format for the content and technical metadata you need to supply to them to get your content where it needs to go. How can you deliver your content to these services if you don’t know how your metadata needs to be formatted?
No Problem! For services such as these, we have built the Superset metadata exporter, allowing the delivery of content and technical metadata in a defined and structured format based around the Mediagenix On-Demand APIs. Using this metadata exporter allows you to take advantage of the great features of Metadata, including validation of your metadata prior to publication, mapping metadata values to values your destination service understands and allowing you to track the status of your metadata deliveries to the service alongside the others.
Outputs
Each generated XML is based upon a single schedule entry (sometimes referred to as scheduling). A schedule entry is defined as a single Title, on a single Platform with both put up and take down dates.
The generated XML contains metadata relating to the title you have scheduled and, if relevant, also includes metadata relating to the brand, series or collection and asset as well. This includes any metadata elements configured specifically for you, as well as images. You can find out more about the metadata hierarchy defined within Mediagenix On-Demand in the Metadata configuration document.
Importantly, as your requirements change and we configure different metadata fields for your account to reflect your new business requirements, the payload of the Exporter will update automatically to include the new fields, and any new publications you make will include these new fields.
Elements of the Superset metadata exporter
Like all our exporters, the Superset metadata exporter consists of 3 elements:
-
Metadata exporter: contains the logic to generate a valid XML document. -
Publisher: determines how the XML files and accompanying images, are delivered to you or the destination service. Common delivery methods include SFTP, FTP and HTTP POST. -
Mapping layer: is where the magic happens! Metadata configured for your account is mapped to the Exporter, and custom logic can be applied at this point to add requirements such as preventing publication unless a Medium Synopsis is present, or converting the Genre Kids to Family, as this is the Genre the target system expects to see. Any configuration within the mapping layer is handled during the implementation of the Superset metadata exporter on your account, when we configure the metadata exporter to produce XML meaningful to your requirements.
As with any other metadata exporter, publication can be prevented if metadata validation, defined in the mapping layer, is not passed.
Updates and deletes
Delivery workflows aren’t always simple, and sometimes schedules and metadata need to change after you’ve published it. Mediagenix On-Demand automatically understands the state of your publications (i.e. if you have previously published a particular piece of content to a platform.) When we configure the Superset metadata exporter for your account, we will agree with you on its behaviour for updating and deleting content, if required, and store this configuration within the publisher. An example would be to delete an existing file and replace it with a new file (together with associated images), if an update was required.
One of the existing options for deletes, when configured with the GenericSFTP publisher, is to generate and deliver an XML as described on Delete example when the user deletes schedule entries via the API or via the schedule page. This XML document will be delivered automatically if a previous publication exists and the schedule entry is not offline when it’s deleted.
Examples
Publish example
Below is a complete and valid example XML document, generated by the Superset Exporter. It has been broken into sections, with hyperlinks to the API documentation for each section. You can also download the complete XML example.
The first section relates to the scheduling. The scheduling is the date and time range when your content is scheduled to appear. Any metadata configured at the scheduling level will also be included within the payload:
<?xml version="1.0" encoding="UTF-8"?>
<scheduling>
<id type="integer">1514156</id>
<external-id>SE0000001</external-id>
<put-up type="datetime">2015-06-01T00:00:00+00:00</put-up>
<take-down type="datetime">2015-07-31T23:59:00+00:00</take-down>
<tags>tag1,tag2</tags>
<metadata type="document"/>
The second section relates to the platform. This is the place you are publishing your XML payload to, configured for your account:
<platform>
<id type="integer">2833</id>
<name>LatAm > BR > Amazon Fire</name>
</platform>
The next section relates to the brand. Brands are the top level of metadata within Mediagenix On-Demand. Any metadata configured for the account at Brand level will be included within the payload, as well as associated images. In this example, multiple language groups are configured for the metadata (and at other levels in the metadata hierarchy):
<brand>
<id type="integer">1791</id>
<name>Test brand</name>
<external-id>0000011</external-id>
<metadata type="document">
<show-actors type="array">
<show-actor>Bryan Cranston</show-actor>
<show-actor>Aaron Paul</show-actor>
</show-actors>
<show-writers type="array">
<show-writer>Vince Gilligan</show-writer>
</show-writers>
<show-directors type="array">
<show-director>Vince Gilligan</show-director>
</show-directors>
<show-producers type="array">
<show-producer>Vince Gilligan</show-producer>
</show-producers>
<en-show-display-name>English name</en-show-display-name>
<en-show-synopsis>English synopsis</en-show-synopsis>
<en-show-why-it-crackles>English why it crackles</en-show-why-it-crackles>
<en-show-genres type="array">
<en-show-genre>Adventure</en-show-genre>
</en-show-genres>
<es-show-display-name>Spanish name</es-show-display-name>
<es-show-synopsis>Spanish synopsis</es-show-synopsis>
<es-show-why-it-crackles>Spanish why it crackles</es-show-why-it-crackles>
<es-show-genres type="array">
<es-show-genre>Acción</es-show-genre>
</es-show-genres>
<pt-br-show-display-name>Portuguese name</pt-br-show-display-name>
<pt-br-show-synopsis>Portuguese synopsis</pt-br-show-synopsis>
<pt-br-show-why-it-crackles>Portuguese why it crackles</pt-br-show-why-it-crackles>
<pt-br-show-genres type="array">
<pt-br-show-genre>Ação</pt-br-show-genre>
</pt-br-show-genres>
</metadata>
<images type="array">
<image>
<id type="integer">828620</id>
<external-id>0987gs</external-id>
<width type="integer">214</width>
<height type="integer">120</height>
<encoding>png</encoding>
<aspect-ratio type="AspectRatio">16:9</aspect-ratio>
<type></type>
<file-name>packshot.png</file-name>
<file-size type="integer">922</file-size>
<file-md5>3878da767027720b0daff8c23cd3ae22</file-md5>
<link rel="file" href="https://example.com/image.png"/>
</image>
</images>
</brand>
The next section relates to the title group (also known as Series, Season or Collection). Any metadata fields configured for your account at Title Group level will be included in this section of the payload, as well as images relating to the content at Title Group level:
<title-group>
<id type="integer">36847</id>
<name>Test series</name>
<external-id>0000011</external-id>
<title-group-type>series</title-group-type>
<season-number type="integer">1</season-number>
<season-reference-id>Winter</season-reference-id>
<tags>tag1</tags>
<metadata type="document">
<en-group-display-name>English name</en-group-display-name>
<es-group-display-name>Spanish name</es-group-display-name>
<pt-br-group-display-name>Portuguese name</pt-br-group-display-name>
</metadata>
<images type="array">
<image>
<id type="integer">828618</id>
<external-id></external-id>
<width type="integer">214</width>
<height type="integer">120</height>
<encoding>png</encoding>
<aspect-ratio type="AspectRatio">16:9</aspect-ratio>
<type></type>
<file-name>packshot.png</file-name>
<file-size type="integer">922</file-size>
<file-md5>3878da767027720b0daff8c23cd3ae22</file-md5>
<link rel="file" href="https://example.com/image.png"/>
</image>
</images>
</title-group>
The next section relates to the title, or feature. As with the brand, scheduling and title group, any metadata fields configured for your account will be included in the payload:
<title>
<id type="integer">394212</id>
<name>Episode name</name>
<episode-number type="integer">1</episode-number>
<episode-reference-id>1a</episode-reference-id>
<external-id>0000011</external-id>
<title-type>episode</title-type>
<tags>tag1,tag2</tags>
<licensor>
<name>Sony Pictures Televison</name>
</licensor>
<metadata type="document">
<title-show-ad-before type="boolean">true</title-show-ad-before>
<title-original-release-air-date type="date">1999-01-01</title-original-release-air-date>
<dvd-release type="datetime">2012-02-12T23:00:00+00:00</dvd-release>
<title-slot-length>01:00:00</title-slot-length>
<title-very-long-description>
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque porta cursus lorem, ac gravida odio convallis id. Curabitur leo purus, posuere in convallis at, mattis in nibh. Aliquam ut eleifend lacus. Aliquam erat volutpat. Sed sem purus, consequat quis velit eget, consectetur pellentesque nisl. Vestibulum eu enim sit amet orci egestas tempus. Quisque accumsan elementum magna, vehicula dictum ipsum laoreet ac. Suspendisse efficitur quam orci, quis imperdiet lorem blandit sit amet. Sed aliquet fringilla leo, sed pharetra nulla fringilla non. Nulla tincidunt fermentum auctor. Maecenas sed nunc egestas, tempus neque.
</title-very-long-description>
<title-genres type="array">
<title-genre>Comedy</title-genre>
<title-genre>Drama</title-genre>
</title-genres>
</metadata>
<images type="array">
<image>
<id type="integer">828616</id>
<external-id>034234sd</external-id>
<width type="integer">214</width>
<height type="integer">120</height>
<encoding>png</encoding>
<aspect-ratio type="AspectRatio">16:9</aspect-ratio>
<type></type>
<file-name>packshot.png</file-name>
<file-size type="integer">922</file-size>
<file-md5>3878da767027720b0daff8c23cd3ae22</file-md5>
<link rel="file" href="https://example.com/image.png"/>
</image>
</images>
</title>
The next section relates to the asset, the particular editorial version of the content you are publishing. Again, as with the above sections, metadata fields configured for your account will be included here:
<asset>
<id type="integer">377364</id>
<external-id>A000011</external-id>
<name>394212A</name>
<description/>
<runtime type="duration">01:00:00.000</runtime>
<rating>G</rating>
<metadata type="document"/>
The next section, within the asset, relates to the renditions and their associated audio tracks and subtitles. If one or more rendition exists, the technical metadata will be included here:
<renditions type="array">
<rendition>
<id type="integer">11111</id>
<external-id>R000011</external-id>
<width type="integer">1280</width>
<height type="integer">720</width>
<encoding>H.264</encoding>
<format>anamorphic</format>
<aspect-ratio>4:3</aspect-ratio>
<color>color</color>
<scan>interlaced</scan>
<bit-rate>3750</bit-rate>
<file-name>VUBX_00289976_0181968_2.mpg</file-name>
<file-size type="integer">123123123</file-size>
<file-md5>24034d35f4e7c6f29038c87de74c2765</file-md5>
<runtime type="duration">1:00:00</runtime>
<audio-tracks type="array">
<audio-track>
<id type="integer">111111</id>
<language>en</language>
<original-version type="boolean">true</original-version>
<encoding>WMA9</encoding>
<mix-type>Stereo</mix-type>
<channels>2.0</channels>
</audio-track>
</audio-tracks>
<subtitles type="array">
<subtitle>
<id type="integer">11111</id>
<language>en</language>
<burnt-in type="boolean">false</burnt-in>
<for-the-hearing-impaired type="boolean">false</for-the-hearing-impaired>
<file-name>subs_en.srt</file-name>
<file-size type="integer">11112</file-size>
<file-md5>bcc3d8a6296cf50534b8864b3908e2f9</file-md5>
</subtitle>
</subtitles>
</rendition>
</renditions>
</asset>
</scheduling>
The last section relates to the playlist and related playlist entries.
<playlist>
<id type="integer">111111</id>
<playlist-entries type="array">
<playlist-entry>
<id type="integer">222222</id>
<position type="integer">1</position>
<asset>
<id type="integer">377364</id>
<external-id>A000011</external-id>
<type>Playlist Entry Asset</type>
<name>PLA01</name>
<description/>
<runtime type="duration">02:00:00.000</runtime>
</asset>
<segment>
<id type="integer">333333</id>
<external-id/>
<type>Playlist Entry Segment</type>
<start type="duration">00:00:00.000</start>
<finish type="duration">00:13:37.000</finish>
</segment>
</playlist-entry>
<playlist-entry>
<id type="integer">333333</id>
<position type="integer">2</position>
<asset>
<id type="integer">377365</id>
<type>Playlist Entry Asset</type>
<name>PLA02</name>
<description/>
<runtime type="duration">01:00:00.000</runtime>
</asset>
</playlist-entry>
</playlist-entries>
</playlist>
If values are empty for particular fields, as in some cases above, the elements are included in the XML with no value.
Delete example
The structure of the XML delete document is the same, but reduced to include only a subset of attributes and no metadata.
The first section relates to the scheduling.
<?xml version="1.0" encoding="UTF-8"?>
<scheduling>
<id type="integer">1514156</id>
<put-up type="datetime">2015-06-01T00:00:00+00:00</put-up>
<take-down type="datetime">2015-07-31T23:59:00+00:00</take-down>
<scheduling-type>archive</scheduling-type>
<method>delete</method>
The second section relates to the platform.
<platform>
<id type="integer">2833</id>
<name>LatAm > BR > Amazon Fire</name>
</platform>
The next section relates to the title, or feature.
<title>
<id type="integer">394212</id>
<name>Episode name</name>
<external-id>0000011</external-id>
</title>
The next section relates to the asset, the particular editorial version of the content you are publishing. This element is optional.
<asset>
<id type="integer">377364</id>
<external-id>A000011</external-id>
<name>394212A</name>
</asset>