Excel - episodic TV metadata fields

Overview

This reference describes the fields in the TV Excel metadata template. Fields follow Roku's series > season > episode hierarchy. For template downloads and rules on formatting, structure, row limits, and file format, see the Excel Metadata Overview.

Deliver the workbook and its referenced files using the Aspera or S3 delivery method approved during onboarding.

Each row represents a single episode. Fields are grouped by level (Series, Season, Episode) so you can identify which part of the hierarchy each field describes.

Fields are grouped into: Package Info, Series Block, Season Block, Episode Content Descriptors, Ad Breaks & Cue Points, Episode Cast & Crew, Assets, Artwork, and Availability.

Package Info

provider

Name of the content owner, studio, or network.

Excel Column	Accepted Values	Required
`provider`	Example: Roku Originals	Required

contentType

Content type of the package. For the TV Excel template, this value is episode (distinct from the tv value used to identify the TV content type elsewhere, e.g., in the TV XML Reference's /package/video/type field).

Excel Column	Accepted Values	Required
`contentType`	`episode`	Required

language

Language of the title, synopses, video, captions, subtitles, audio dubs, and artwork listed in the row. The value must use a supported language code. A region code is recommended to distinguish variants such as es-MX and es-ES.

Excel Column	Accepted Values	Required
`language`	One valid language value	Required

asset_id

Immutable, unique identifier for an episode. The partner generates or supplies this ID. It must match the Title ID in the Avails document so Roku can track the title through processing. 50-character limit.

Excel Column	Accepted Values	Required
`asset_id`	Alphanumeric characters, hyphens, and underscores only. 50 characters maximum.	Required

episode_eidr

EIDR ID for the episode, if one exists.

Excel Column	Accepted Values	Required
`episode_eidr`	Any valid episodic EIDR ID	Optional

episode_tms_id

Gracenote ID for the episode, if one exists.

Excel Column	Accepted Values	Required
`episode_tms_id`	Any valid episodic TMS ID	Optional

Series Block

series_id

Immutable, unique identifier for a series. The partner generates or supplies this ID. It must match the Series ID in the Avails document. 50-character limit.

Excel Column	Accepted Values	Required
`series_id`	Alphanumeric characters, hyphens, and underscores only. 50 characters maximum.	Required

series_title

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

Excel Column	Accepted Values	Required
`series_title`	Example: Series Title	Required

series_tms_id

Gracenote ID for the series, if one exists.

Excel Column	Accepted Values	Required
`series_tms_id`	Any valid Show TMS ID	Optional

series_release_date

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

Excel Column	Accepted Values	Required
`series_release_date`	ISO 8601 format: `YYYY-MM-DD`	Required

series_genres

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

Genre is specified only at the series level. There is no separate genre field for each episode. The TV XML Reference uses the same structure.

Excel Column	Accepted Values	Required
`series_genres`	See enumerated list. No more than 10 genres per title.	Required

series_tags

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

Excel Column	Accepted Values	Required
`series_tags`	Any string under 50 characters	Highly recommended

series_cast

Names of series cast members.

Excel Column	Accepted Values	Required
`series_cast`	Comma-separated list of `Firstname Lastname`	Preferred

series_directors

Name of the series director or directors.

Excel metadata currently supports only the director role for crew credits.

Excel Column	Accepted Values	Required
`series_directors`	Comma-separated list of `Firstname Lastname`	Preferred

series_brief_synopsis

A brief synopsis of the series, in the language defined in the language column. 100-character limit. Required for Linear OTT distribution.

Excel Column	Accepted Values	Required
`series_brief_synopsis`	Up to 100 characters	Required for Linear OTT distribution

series_short_synopsis

A short synopsis of the series, in the language defined in the language column. 250-character limit.

Excel Column	Accepted Values	Required
`series_short_synopsis`	250-character synopsis	Required

series_long_synopsis

An optional long synopsis of the series, in the language defined in the language column. 500-character limit.

Excel Column	Accepted Values	Required
`series_long_synopsis`	500-character synopsis	Optional

localized_series_brief_synopsis

A localized brief synopsis of the series, in the language defined in the localized_language column. 100-character limit. Required for Linear OTT distribution.

Excel Column	Accepted Values	Required
`localized_series_brief_synopsis`	Up to 100 characters	Required for Linear OTT distribution

Season Block

season_id

Immutable, unique identifier for a season. The partner generates or supplies this ID. It must match the Season ID in the Avails document. 50-character limit.

Excel Column	Accepted Values	Required
`season_id`	Alphanumeric characters, hyphens, and underscores only. 50 characters maximum.	Required

season_number

Numerical position of the season within the series. This determines the viewing order of its episodes. Values must reflect the original broadcast or exhibition order and must be integers greater than 0.

Excel Column	Accepted Values	Required
`season_number`	Integers greater than 0 only	Required

Episode Content Descriptors

episode_title

Title of the episode, in the language defined in the language column. Include only the name as it should appear on the platform. Do not add parenthetical information that is not part of the title.

Excel Column	Accepted Values	Required
`episode_title`	Example: Episode Title	Required

episode_number

Numerical position of the episode within its season. This determines the viewing order on the platform. Values must reflect the original broadcast or exhibition order; production numbers must not be used. Only integers are allowed.

Excel Column	Accepted Values	Required
`episode_number`	Integers only	Required

original_spoken_language

Original production language of the episode. The value must use a supported language code. A region code is recommended to distinguish variants such as es-MX and es-ES.

[!NOTE]
this field is not prefixed episode_ in the template, but applies at the episode level, not the series level.

Excel Column	Accepted Values	Required
`original_spoken_language`	One valid language value	Required

country_of_origin

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

[!NOTE]
this field is not prefixed episode_ in the template, but applies at the episode level, not the series level.

Excel Column	Accepted Values	Required
`country_of_origin`	One valid 2-character country code per ISO 3166-1 alpha-2	Preferred

episode_release_date

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

Excel Column	Accepted Values	Required
`episode_release_date`	ISO 8601 format: `YYYY-MM-DD`	Required

episode_runtime

Total runtime of the episode, in whole minutes.

Excel Column	Accepted Values	Required
`episode_runtime`	Integers only. Example: `22`	Required

rating_system and episode_ratings

rating_system holds the rating authority (e.g., USA_PR), and episode_ratings holds the corresponding rating value (e.g., TV-14) for that authority. A valid TV rating from the rating authority 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.

Rating is specified only at the episode level. There is no separate rating field for the series.

Excel Column	Accepted Values	Required
`rating_system`	See rating values by system and country	Required
`episode_ratings`	See rating values by system and country	Required

episode_tags

Freeform tags that describe the episode beyond its genre. The same rules apply as for series_tags.

Excel Column	Accepted Values	Required
`episode_tags`	Any string under 50 characters	Highly recommended

episode_brief_synopsis

A brief synopsis of the episode, in the language defined in the language column. 100-character limit. Required for Linear OTT distribution.

Excel Column	Accepted Values	Required
`episode_brief_synopsis`	Up to 100 characters	Required for Linear OTT distribution

episode_short_synopsis

A short synopsis of the episode, in the language defined in the language column. 250-character limit.

Excel Column	Accepted Values	Required
`episode_short_synopsis`	250-character synopsis	Required

episode_long_synopsis

An optional long synopsis of the episode, in the language defined in the language column. 500-character limit.

Excel Column	Accepted Values	Required
`episode_long_synopsis`	500-character synopsis	Optional

localized_episode_brief_synopsis

A localized brief synopsis of the episode, in the language defined in the localized_language column. 100-character limit. Required for Linear OTT distribution.

Excel Column	Accepted Values	Required
`localized_episode_brief_synopsis`	Up to 100 characters	Required for Linear OTT distribution

closed_captions

Indicates whether the delivered title contains closed captions. The Y/N flag is required for all content intended for Roku Channel in the US. Providing this flag does not by itself require a caption file; the partner determines whether captions are required for that delivery.

Excel Column	Accepted Values	Required
`closed_captions`	`Y` or `N`	Required

closed_captions_exemption

FCC exemption code for the closed caption requirement. Required in the US if closed_captions = N.

Code	Definition
1	The content has never aired on television in the United States.
2	The content has only aired on television in the United States without captions.
3	The content has not aired on television in the United States with captions since September 30, 2012.
4	The content does not consist of full-length video programming.
5	The content does not fall within a category of online programming that requires captions under FCC regulations (47 C.F.R. § 79.4(b)).
6	The FCC and/or U.S. Congress has granted an exemption from caption requirements for this content.

Excel Column	Accepted Values	Required
`closed_captions_exemption`	`1`, `2`, `3`, `4`, `5`, `6`	Required in US if `closed_captions` = `N`

Ad Breaks & Cue Points

Ad breaks and cue points are specified only at the episode level. There are no separate fields for the series.

episode_ad_breaks

Identifies ad breaks for ad-supported content. Values must be accurate to the millisecond. If the video contains black frames for a commercial break, provide the timecode at the midpoint of that interval. This field is not required for SVOD, but Roku can ingest frame-accurate data if available.

Excel Column	Accepted Values	Required
`episode_ad_breaks`	`HH:MM:SS.sss`	Preferred

episode_cue_points

Identifies the start and end times of opening credits, recaps, end credits, and behind-the-scenes footage. Values must be accurate to the millisecond.

Enter cue points as a single comma-separated text string in one cell. XML provides the same information in nested cuePoint elements; see the TV XML Reference.

Format: a comma-separated list of type=startTime>endTime pairs.

Example:

intro=00:05:10.253>00:07:15.123,recap=00:01:12.456>00:03:12.052

Excel Column	Accepted Values	Required
`episode_cue_points`	Format: `type=HH:MM:SS.sss>HH:MM:SS.sss`. Allowable `type` values: `ad overlay`, `behind the scenes`, `intro`, `recap`, `end`	Optional

Episode Cast & Crew

episode_cast

Names of cast members for the episode.

Excel Column	Accepted Values	Required
`episode_cast`	Comma-separated list of `Firstname Lastname`	Preferred

episode_director

Name of the episode's director or directors.

Excel metadata currently supports only the director role for crew credits.

Excel Column	Accepted Values	Required
`episode_director`	Comma-separated list of `Firstname Lastname`	Preferred

Assets

video_file_name

File name of the video, in the language defined in the language column, delivered using the approved method. Only one video is allowed per asset_id. The file name must exactly match the delivered file, including capitalization, and must not contain whitespace or special characters.

Excel Column	Accepted Values	Required
`video_file_name`	Example: `episodeVideoFile.mov`	Required

video_file_language

Primary language of the video file's spoken dialogue, visible text, or both. If there is no dialogue or visible text, use the language spoken by the intended audience. Also applies to closed_caption_file_name and forced_subtitle_file_name. Only one language is allowed.

Excel Column	Accepted Values	Required
`video_file_language`	One valid language value	Required

audio_layout

Audio layout descriptor for the delivered video file.

Excel Column	Accepted Values	Required
`audio_layout`	`stereoOnly`, `surroundOnly`, `stereoPlusSurround`, `surroundPlusStereo`	Optional

descriptive_audio_file_name

For audio description files only. File name of the descriptive audio file, in the language defined in descriptive_audio_language, delivered using the approved method. The file name must exactly match the delivered file, including capitalization, and must not contain whitespace or special characters.

Excel Column	Accepted Values	Required
`descriptive_audio_file_name`	Example: `movieDubFile.wav`	Required when providing a sidecar descriptive audio file for accessibility purposes

descriptive_audio_language

For audio description files only. Primary language of the audio file's spoken dialogue track. Only one language is allowed.

Excel Column	Accepted Values	Required
`descriptive_audio_language`	One valid language value	Required when providing descriptive audio files

closed_caption_file_name

Roku strongly prefers closed captions. The partner is responsible for determining whether captions are required for a specific delivery.

If supplied, enter the name of the closed caption file delivered using the approved method, in the language defined in the language column. The file name must exactly match the delivered file, including capitalization, and must not contain whitespace or special characters. Its language is derived from video_file_language.

Excel Column	Accepted Values	Required
`closed_caption_file_name`	Example: `episodeCaptions.srt`	Strongly preferred

forced_subtitle_file_name

File name of the forced narrative subtitle, in the language defined in video_file_language, delivered using the approved method. The file name must exactly match the delivered file, including capitalization, and must not contain whitespace or special characters. Its language is derived from video_file_language.

Excel Column	Accepted Values	Required
`forced_subtitle_file_name`	Example: `episodeForcedSubtitle.srt`	Required when providing forced narrative subtitles

Artwork

series_keyart_file_name

File name of the texted key art image, in the language defined in the language column, delivered using the approved method. The file name must exactly match the delivered file, including capitalization, and must not contain whitespace or special characters.

Excel Column	Accepted Values	Required
`series_keyart_file_name`	Example: `episodeKeyArt.jpg`	Required

series_boxcover_file_name

File name of the texted 4:3 boxcover image for the series, in the language defined in the language column, delivered using the approved method. The file name must exactly match the delivered file, including capitalization, and must not contain whitespace or special characters.

Excel Column	Accepted Values	Required
`series_boxcover_file_name`	Example: `episodeBoxArt.jpg`	Required for distribution to Howdy

series_poster_file_name

File name of the texted poster image, in the language defined in the language column, delivered using the approved method. The file name must exactly match the delivered file, including capitalization, and must not contain whitespace or special characters.

Excel Column	Accepted Values	Required
`series_poster_file_name`	Example: `seriesPoster.jpg`	Preferred

series_background_file_name

File name of the textless series-level background image, delivered using the approved method. The file name must exactly match the delivered file, including capitalization, and must not contain whitespace or special characters.

Excel Column	Accepted Values	Required
`series_background_file_name`	Example: `seriesBGimage.jpg`	Preferred

episode_background_file_name

File name of the textless episode-level background image, delivered using the approved method. The file name must exactly match the delivered file, including capitalization, and must not contain whitespace or special characters.

Excel Column	Accepted Values	Required
`episode_background_file_name`	Example: `episodeBGimage.jpg`	Preferred

Availability

All four fields below are preferred, as shown in the tables. None is required.

vod_type

Monetization type of the episode. You may enter multiple values separated by commas, provided territory, episode_start_date, and episode_end_date are identical across them.

Excel Column	Accepted Values	Required
`vod_type`	Example: `avod`, `svod`, `avod,svod`	Preferred

territory

Country codes for the territories where the content is available. You may enter multiple country codes separated by commas, provided vod_type, episode_start_date, and episode_end_date are identical across them.

Excel Column	Accepted Values	Required
`territory`	`US`, `CA`, `GB`, `MX`	Preferred

episode_start_date

Start date of content availability. The date must be before episode_end_date; the dates must not be the same.

Excel Column	Accepted Values	Required
`episode_start_date`	ISO 8601 format: `YYYY-MM-DDTHH:MM:SS`	Preferred

episode_end_date

End date of content availability. The date must be after episode_start_date; the dates must not be the same.

Excel Column	Accepted Values	Required
`episode_end_date`	ISO 8601 format: `YYYY-MM-DDTHH:MM:SS`	Preferred