XML - episodic TV metadata fields

Overview

Use this reference to prepare XML metadata for TV content. Roku organizes TV content as series > season > episode; see Content Type Definitions. Download the schema and annotated sample from the Roku XML Metadata Overview.

The fields title, brief_synopsis, short_synopsis, long_synopsis, cast, crew, and localizations appear at both the episode and series levels. The headings identify the level, for example, "Episode Title" and "Series Title".

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

Package Info

package

Identifies the schema version used by the package.

<package version="tv1.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>tv</type>

asset_id (Episode)

Unique identifier for an episode 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>episodeAssetIdHere</asset_id>

eidr

EIDR ID, if one exists.

<eidr></eidr>

tmsId

Gracenote ID, if one exists.

<tmsId></tmsId>

Episode Content Descriptors

Episode Title

Title of the episode. 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[Episode Title. Required.]]></title>

episodeNumber

Numerical position of the episode within its season. This determines the viewing order on the platform. Values must reflect original broadcast/exhibition order; production numbers must not be used. Integers only.

<episodeNumber>2</episodeNumber>

Episode brief_synopsis

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

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

Episode short_synopsis

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

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

Episode long_synopsis

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

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

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 (Episode)

Original date the episode 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 episode, in whole minutes.

<runtime>45</runtime>

rating (Episode)

Parental/content advisory rating from a rating source. A valid TV rating from the rating authority (ratingSystem) of the territory where the content will be available must be provided for each episode. 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 (Episode)

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>

Ad Breaks & Cue Points

adBreak start_time

Used to determine Ad Breaks for Ad Supported Content. Values must be accurate to the millisecond. If commercial blacks are present, provide the timecode at the midpoint. Not required for SVOD, but frame-accurate 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

Identifies in/out points of opening credits, 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. Attribute name must be type. Every cuePoint provided requires both start_time and end_time, regardless of type.

<cuePoint type="intro">

Episode Cast & Crew

Episode cast display_name

Name of a cast member for the episode. CDATA supported.

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

Episode crew display_name

Name of a crew member for the episode. 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>

Episode crew 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>

Episode Localizations

Episode localizations

Contains localized episode metadata: language, translated title, brief_synopsis, short_synopsis, and long_synopsis.

<localizations>

Episode localization name attribute

Defines the language of the localized fields within an episode localization block. Attribute name must be name; value must, at minimum, conform to a supported language code (region code recommended, e.g. es-MX vs. es-ES).

<localization name="es">

Localized Episode Title

Localized episode title. The restrictions on parenthetical information in Episode Title also apply. Must be accompanied by a localized short_synopsis. A localized long_synopsis is optional.

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

Localized Episode brief_synopsis

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

Localized Episode 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 episode. 250 characters maximum. Required]]></short_synopsis>

Localized Episode long_synopsis

Optional. CDATA supported. 500-character limit. If provided, it must accompany localized title and short_synopsis.

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

Series Block

series

Begins the block referencing metadata for the show to which the episode belongs. Roku follows the US definition of a series. Episodes nest as series > season > episode.

<series>

series_id

Immutable, unique identifier for a series. The partner generates and supplies the ID, which must match the series ID in the Avails document. 50-character limit.

<series_id>seriesIdHere</series_id>

Series Title

Title of the series. Include only the name as it should appear on the platform. Do not add parenthetical information that is not part of the title.

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

Series brief_synopsis

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

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

Series short_synopsis

CDATA supported. 250-character limit.

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

Series long_synopsis

Optional. CDATA supported. 500-character limit.

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

original_spoken_language

Original production language of the series. 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 series 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>

release_date (Series)

Original date the series was first made available, typically the release date of the first episode. Must include an accurate year of release at minimum.

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

genre

Genre classification. Each episode must be delivered with at least one supported genre via its series record. See the enumerated genre list.

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

tag (Series)

Tags categorize a series beyond its genre. The same rules as Episode tag apply: tags are case-sensitive, with no limit on their number and no predefined set.

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

Series cast display_name

Name of a cast member of the series. CDATA supported.

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

Series crew display_name

Name of a crew member of the series. CDATA supported.

Excel deliveries: Director is the only supported crew_member role.

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

Series crew role

Role of the crew member named in display_name. See the enumerated crew roles list. Case-sensitive.

<role>Director</role>

Series localizations

Contains localized series metadata for multilingual packages.

<localizations>

Series localization name attribute

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

<localization name="es">

Localized Series Title

Localized series title. The restrictions on parenthetical information in Series Title also apply. Must be accompanied by a localized short_synopsis. A localized long_synopsis is optional.

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

Localized Series brief_synopsis

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

Localized Series 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 series. 250 characters maximum. Required]]></short_synopsis>

Localized Series long_synopsis

Optional. CDATA supported. 500-character limit. If provided, it must accompany localized title and short_synopsis.

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

Season Block

season

Begins the block referencing metadata for the season of the series to which the episode belongs. Episodes nest as series > season > episode.

<season>

season_id

Immutable, unique identifier for a season. The partner generates and supplies the ID, which must match the season ID in the Avails document. 50-character limit.

<season_id>seasonIdHere</season_id>

seasonNumber

Numerical position of the season within the series. This determines the viewing order of its episodes. Values must reflect original broadcast/exhibition order. Integers only; must not be 0.

<seasonNumber>2</seasonNumber>

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 episode. 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 with the package (video, captions, audio, subtitles, artwork), described via asset/data_file pairs with attributes identifying type and role.

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 artwork files at either the episode or series level. asset type="artwork". <locale> and <file_name> are also required. See Artwork for full image delivery specifications.

Use the data_file attribute role="episode" for episode artwork and role="series" for series artwork.

<asset type="artwork">
  <data_file role="episode">

<asset type="artwork">
  <data_file role="series">

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, 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.

For artwork files specifically, the file_name tag's type attribute can be omitted (indicating key art), or set to type="background_image", type="boxcover", or type="poster".

<file_name>VideoFilename.mxf</file_name>

audio

Audio layout descriptor for the delivered video file.

<audio>stereoOnly</audio>