XML - shortForm clip metadata fields

Overview

Use this reference to prepare XML metadata for short-form clips, whether standalone or related to another program. See Content Type Definitions for details. Download the schema and annotated sample from the Roku XML Metadata Overview.

Clips also support fields that are not available for Film or TV: subType and parentInfo describe a clip's relationship to a parent program, and sports metadata fields (sportType, sportLeague, teams) describe sports clips. Sports metadata is optional for clips in general and required when delivering sports clips. Requirements for each field are listed below.

The fields are organized into Package Info, Content Descriptors, Cast & Crew, Localizations, Play Options / Availability, Assets, Parent Info, and Sports Metadata.

Package Info

package

Identifies the schema version used by the package.

<package version="clip1.0">

provider

Name of the content owner, studio, or network.

<provider>Roku Originals</provider>

language

Primary language of the package metadata. The value must use a supported language code. A region code is recommended to distinguish regional language variants, such as es-MX and es-ES.

<language>en</language>

type

Defines the content type of the package.

<type>clip</type>

subType

Identifies the clip's subtype. Use one of the values below to describe ancillary or related content. Roku does not create a system-level link between the clip and its parent program. You can provide descriptive metadata about that program in Parent Info.

<subType>trailer</subType>

asset_id

Unique identifier for a shortForm clip that must remain unchanged. The partner generates and supplies the ID. The ID in the ingest metadata must match the Title ID in the Avails document so the title can be tracked from Avails submission through publication. 50-character limit.

<asset_id>clipAssetIdHere</asset_id>

eidr

EIDR ID, if one exists.

<eidr></eidr>

tmsId

Gracenote ID, if one exists.

<tmsId></tmsId>

Content Descriptors

title

Title of the shortForm clip. Include only the name as it should appear on the platform. Do not add parenthetical information that is not part of the title (e.g., (Classic), (1987), (Season 1), (HD)).

<title><![CDATA[Clip Title. Required.]]></title>

brief_synopsis

A brief synopsis of the clip. CDATA supported. 100-character limit. Required for Linear OTT distribution.

<brief_synopsis><![CDATA[Brief clip summary. 100 characters maximum. Required for Linear OTT distribution.]]></brief_synopsis>

short_synopsis

A short synopsis of the content. CDATA supported. 250-character limit.

<short_synopsis><![CDATA[Short summary of clip. 250 characters maximum. Required]]></short_synopsis>

long_synopsis

Optional. A long synopsis of the content. CDATA supported. 500-character limit.

<long_synopsis><![CDATA[Long summary of clip. 500 characters maximum. Optional.]]></long_synopsis>

original_spoken_language

Original production language of the title. At minimum, must conform to a supported language code (region code recommended).

<original_spoken_language>en</original_spoken_language>

country_of_origin

The primary country where the clip was produced, and where the main creators, crew, and producers are established. Must conform to a supported ISO 3166-1 alpha-2 code.

<country_of_origin>US</country_of_origin>

closedCaptions

This Y/N field is required for all content intended for Roku Channel in the US. It reports whether captions are included; see Full Captions for caption-file delivery requirements.

<closedCaptions>Y</closedCaptions>

closedCaptionsExemption

FCC exemption code for the closed caption requirement. Required if closedCaptions = N.

<closedCaptionsExemption>1</closedCaptionsExemption>

release_date

Original date the content was first made available in any presentation. Must include an accurate year of release at minimum.

<release_date>YYYY-MM-DD</release_date>

runtime

Total runtime of the content, in whole minutes.

<runtime>3</runtime>

genre

Genre classification of the content. Each shortForm clip must be delivered with at least one supported genre. See the enumerated genre list.

<genres>
  <genre>drama</genre>
  <!-- Additional genres here-->
</genres>

rating

Parental/content advisory rating from a rating source. A valid movie or TV rating from the rating authority (ratingSystem) of the territory where the content will be available must be provided for each shortForm clip. If not rated by that territory's official authority, use a valid USA_PR rating instead, per tvguidelines.org guidelines (there is no official ratings body for USA_PR).

<ratings>
  <rating system="MPAA" reason="For drug content, some sensuality and war violence.">PG-13</rating>
  <rating system="BBFC">12A</rating>
  <rating system="CHVRS">14A</rating>
</ratings>

tag

Tags categorize content beyond its genre. Roku's editorial team and recommendations engine use them to help viewers find content. There is no limit on the number of tags and no predefined tag set. Tags are case-sensitive, so use consistent capitalization.

<tags>
  <tag>energy</tag>
  <tag>dance</tag>
  <!-- Additional tags here-->
</tags>

Cast & Crew

cast display_name

Name of a cast member. CDATA supported.

<cast>
  <cast_member>
    <display_name><![CDATA[Harrison Ford]]></display_name>
  </cast_member>
<!-- Additional cast members here-->
</cast>

crew display_name

Name of a crew member. CDATA supported.

Excel deliveries: Director is the only supported crew_member role. XML supports the full crew role list.

<display_name><![CDATA[George Lucas]]></display_name>

role

Role of the crew member named in display_name. Every crew member must also include their role. See the enumerated crew roles list. Roles are case-sensitive.

<role>Director</role>

Localizations

localizations

Contains localized metadata for multilingual packages: language, translated title, brief_synopsis, short_synopsis, and long_synopsis.

<localizations>

localization name attribute

Defines the language of the localized fields within a localization block. Attribute name must be name; value must, at minimum, conform to a supported language code (region code recommended).

<localization name="es">

localized title

Localized title of the shortForm clip. The restrictions on parenthetical information in title also apply. Must be accompanied by a localized short_synopsis. A localized long_synopsis is optional.

<title><![CDATA[Localized Clip Title. Required.]]></title>

localized brief_synopsis

A localized brief synopsis of the clip. CDATA supported. 100-character limit. Required for Linear OTT distribution. The language is defined by the enclosing localization block's name attribute.

<brief_synopsis><![CDATA[Localized brief clip summary. 100 characters maximum. Required for Linear OTT distribution.]]></brief_synopsis>

localized short_synopsis

CDATA supported. 250-character limit. Must be accompanied by a localized title. A localized long_synopsis is optional.

<short_synopsis><![CDATA[Localized Short summary of clip. 250 characters maximum. Required]]></short_synopsis>

localized long_synopsis

Optional. CDATA supported. 500-character limit.

<long_synopsis><![CDATA[Localized Long summary of clip. 500 characters maximum. Optional.]]></long_synopsis>

Play Options / Availability

playOptions

Contains availability information: countries or territories, monetization type, and availability start and end dates.

<playOptions>

country

Country code of the territory where the content is available. Multiple country nodes allowed if vodType, licensePeriodStart, and licensePeriodEnd are identical across them.

<playOption>
  <country>US</country>
  <!-- Additional country nodes here -->
</playOption>

vodType

Monetization type of the shortForm clip. Multiple vodType nodes allowed if country, licensePeriodStart, and licensePeriodEnd are identical across them.

<playOption>
  <vodType>AVOD</vodType>
  <!-- Additional vodType nodes here -->
</playOption>

licensePeriodStart

Start date of content availability. One per playOption. Must be chronologically before licensePeriodEnd; the two must not be identical.

<playOption>
  <licensePeriodStart>YYYY-MM-DDTHH:MM:SS</licensePeriodStart>
</playOption>

licensePeriodEnd

End date of content availability. One per playOption. Must be chronologically after licensePeriodStart; the two must not be identical.

<playOption>
  <licensePeriodEnd>YYYY-MM-DDTHH:MM:SS</licensePeriodEnd>
</playOption>

Assets

The assets block references every file delivered as part of the package (video, captions, audio, subtitles, artwork), each described by an asset/data_file pair.

assets

Begins the asset block.

<assets media_type="video">

Full Source (Video)

Describes the source video file. asset type="full"; data_file role="source". <locale> and <file_name> are also required.

<asset type="full">
  <data_file role="source">

Full Captions

Describes closed captions for the source video file. asset type="full"; data_file role="captions". If a sidecar caption file is supplied, <locale> and <file_name> are required.

Closed captions are strongly preferred for every delivery. The partner determines whether captions are required for the specific delivery.

<asset type="full">
  <data_file role="captions">

Full Audio

Describes audio delivered separately from the source video file (sidecar audio): a full language dub or a descriptive audio track for accessibility. asset type="full"; data_file role="audio" (translation dub) or role="audio description" (accessibility). <locale> and <file_name> are also required.

Sidecar audio may be required when localized assets are needed (source audio not native to the distribution territory) or to comply with FCC regulations.

<asset type="full">
  <data_file role="audio">

Full Subtitles

Describes sidecar subtitles for the source video file. asset type="full"; data_file role="subtitles". <locale> and <file_name> are also required.

Sidecar subtitles may be required when localized assets are needed (source audio not native to the distribution territory).

<asset type="full">
  <data_file role="subtitles">

Forced Subtitles

Describes sidecar forced narrative subtitles for the source video file. asset type="full"; data_file role="forced subtitles". <locale> and <file_name> are also required.

<asset type="full">
  <data_file role="forced subtitles">

Artwork

Describes the artwork files. asset type="artwork". <locale> and <file_name> are also required. See Artwork for full image delivery specifications.

Clips require one 16:9 key art image type, as described in the Artwork Specification. Clip artwork does not use separate background_image, boxcover, or poster variants.

<asset type="artwork">
  <data_file>

locale

Identifies the language of the data_file. At minimum, must conform to a supported language code (region code recommended). Applicable to data_file roles source, captions, audio, and subtitles, and asset type artwork.

<locale name="en"/>

file_name

Filename of the asset indicated by the enclosing data_file's role or type attribute. All values are case-sensitive and must include the proper file extension.

<file_name>VideoFilename.mxf</file_name>

audio

Audio layout descriptor for the delivered video file.

<audio>stereoOnly</audio>

Parent Info

parentInfo describes the program a clip comes from or relates to. Use it with a valid subType value. This metadata does not create a navigable link or an on-platform relationship between the clip and its parent program.

parentInfo

Begins the block providing parent information for the package.

<parentInfo>

parent contentType

Content type of the parent the clip is derived from or describes.

<parentInfo>
  <contentType>episode</contentType>
</parentInfo>

parent title

Title of the parent program, if the parent is a movie or series.

<parentInfo>
  <title>Title of Parent Movie or Series</title>
</parentInfo>

parent runtime

Runtime of the parent program, if the parent is a movie or episode.

<parentInfo>
  <runtime>45</runtime>
</parentInfo>

parent releaseDate

Release date of the parent movie, episode, or series.

<parentInfo>
  <releaseDate>YYYY-MM-DD</releaseDate>
</parentInfo>

parent tmsId

TMS ID of the parent movie, episode, or series.

<parentInfo>
  <tmsId>TMSID</tmsId>
</parentInfo>

parent seriesTitle

Series title of the parent program, if the parent is an episode.

<parentInfo>
  <seriesTitle>Parent Series Title</seriesTitle>
</parentInfo>

parent seasonNumber

Season number of the parent program, if the parent is an episode.

<parentInfo>
  <seasonNumber>2</seasonNumber>
</parentInfo>

parent episodeNumber

Episode number of the parent program, if the parent is an episode.

<parentInfo>
  <episodeNumber>14</episodeNumber>
</parentInfo>

Sports Metadata

Sports metadata is optional for clips in general. When delivering a sports clip, all of the following fields are required.

sportType

Name of the sport featured in the clip/highlight.

<sportType>Baseball</sportType>

sportLeague

Name of the sport league featured in the clip/highlight.

<sportLeague>MLB</sportLeague>

teams

Teams featured in the sport clip/highlight. Home and away teams are defined via the location attribute.

[!NOTE]
Roku currently supports participant metadata for team sports only. Support for individual sports, such as tennis and golf, is planned for a later date.

<teams>
	<team location="away">Chicago Cubs</team>
	<team location="home">St. Louis Cardinals</team>
</teams>