XML - film metadata fields

Overview

Use this reference to prepare XML metadata for films. Download the schema and annotated sample from the Roku XML Metadata Overview. The Metadata Overview explains content types, ID rules, and availability windows that apply to all content.

The fields are organized into Package Info, Content Descriptors, Ad Breaks & Cue Points, Cast & Crew, Localizations, Play Options / Availability, and Assets.

Package Info

package

Identifies the schema version used by the package.

<package version="film5.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 Spanish spoken in Mexico (es-MX) and Spain (es-ES).

<language>en</language>

type

Defines the content type of the package.

<type>film</type>

asset_id

Unique identifier for a movie 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>movieAssetIdHere</asset_id>

eidr

EIDR ID, if one exists.

<eidr></eidr>

tmsId

Gracenote ID, if one exists.

<tmsId></tmsId>

Content Descriptors

title

Title of the movie as it should appear on the platform. Do not add parenthetical information that is not part of the title, such as an original/remake indicator, release year, season, or video format (for example, (Classic), (1987), (Season 1), (HD)).

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

brief_synopsis

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

<brief_synopsis><![CDATA[Brief movie 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 movie. 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 movie. 500 characters maximum. Optional.]]></long_synopsis>

original_spoken_language

The original production language of the title. At minimum, the value must conform to a supported language code. As a best practice, include a region code as well (see language above for the es-MX / es-ES example).

<original_spoken_language>en</original_spoken_language>

country_of_origin

The primary country where the film was produced and where the main creators, crew, and producers are established. Value must conform to a supported ISO 3166-1 alpha-2 2-character country 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>120</runtime>

genre

Genre classification of the content. Each movie 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 movie. If the title hasn't been rated by that territory's official authority, include a valid rating from the USA_PR rating system instead. There is no official ratings body for USA_PR; use the guidelines at tvguidelines.org to assign the appropriate rating.

<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. Additional tags can give Roku more ways to group and recommend a title. There is no limit on the number of tags and no predefined tag set.

• Tags are case-sensitive: "Rom-Com" and "rom-com" are distinct tags. Use consistent capitalization.

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

Ad Breaks & Cue Points

adBreak start_time

Used to determine Ad Breaks for Ad Supported Content. Values must be accurate to the millisecond. If the video includes commercial blacks, provide the timecode at the midpoint of the commercial black. Not required for SVOD content, but frame-accurate adBreak data can be ingested if available.

<adBreaks>
  <adBreak>
    <start_time>00:03:15.000</start_time>
  </adBreak>
  <adBreak>
    <start_time>00:07:45.425</start_time>
  </adBreak>
<!-- Additional adBreaks here-->
</adBreaks>

cuePoint start_time and end_time

Used to identify the in/out points of opening credits, content recaps, end credits, and behind-the-scenes footage. cuePoint tags must include the type attribute. Values must be accurate to the millisecond.

<cuePoints>
	<cuePoint type="ad overlay">
		<start_time>00:09:10.456</start_time>
		<end_time>00:09:12.678</end_time>
	</cuePoint>
	<cuePoint type="behind the scenes">
		<start_time>00:07:08.123</start_time>
		<end_time>00:07:59.123</end_time>
	</cuePoint>
	<cuePoint type="intro">
		<start_time>00:01:08.123</start_time>
		<end_time>00:01:59.123</end_time>
	</cuePoint>
	<cuePoint type="recap">
		<start_time>00:21:08.123</start_time>
		<end_time>00:21:59.123</end_time>
	</cuePoint>
	<cuePoint type="end">
		<start_time>00:41:08.123</start_time>
		<end_time>00:41:59.123</end_time>
	</cuePoint>
</cuePoints>

cuePoint type attribute

Defines the type of a given cuePoint. The attribute name must be type, with one of the following values. Every cuePoint provided requires both start_time and end_time, regardless of type.

<cuePoint type="intro">

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.

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

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

role

Role of the crew member named in display_name. Every crew member included 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

Identifies the language of the fields in a localization block. The attribute name must be name, and its value must use a supported language code. A region code is recommended; see language.

<localization name="es">

localized title

Localized title of the movie, in the language specified by the enclosing localization block's name attribute. 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 Movie Title. Required.]]></title>

localized brief_synopsis

A localized brief synopsis of the movie. 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 movie summary. 100 characters maximum. Required for Linear OTT distribution.]]></brief_synopsis>

localized short_synopsis

Localized short synopsis, in the language specified by the enclosing localization block. 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 movie. 250 characters maximum. Required]]></short_synopsis>

localized long_synopsis

Optional. Localized long synopsis, in the language specified by the enclosing localization block. CDATA supported. 500-character limit. If provided, it must accompany localized title and short_synopsis.

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

Play Options / Availability

playOptions

Contains the package's 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 are allowed, provided vodType, licensePeriodStart, and licensePeriodEnd are identical across them.

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

vodType

Monetization type of the movie. Multiple vodType nodes are allowed, provided country, licensePeriodStart, and licensePeriodEnd are identical across them.

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

licensePeriodStart

Start date of content availability to Roku Channel users. One licensePeriodStart 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 to Roku Channel users. One licensePeriodEnd 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 individual file is described by an asset/data_file pair, with attributes identifying the asset's type and role.

assets

Begins the asset block.

<assets media_type="video">

Full Source (Video)

Describes the source video file. The asset tag's attribute must be type="full", and the data_file tag's attribute must be 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 (i.e., the source's original audio is not native to the distribution territory) or when complying 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 (i.e., the source's original audio is 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 artwork files. asset type="artwork". <locale> and <file_name> are also required. See Artwork for full image delivery specifications.

<asset type="artwork">
  <file_name>

<asset type="artwork">
  <file_name type="background_image">

<asset type="artwork">
  <file_name type="boxcover">

<asset type="artwork">
  <file_name type="poster">

A file_name without a type attribute represents key art. Explicit type values are only needed for background_image, boxcover, and poster.

locale

Identifies the language of the data_file. At minimum, the value must conform to a supported language code; include a region code as a best practice. Applicable to data_file roles source, captions, audio, 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 file_name 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>