Excel - film metadata fields
Field-by-field reference for the Film Excel template.
Overview
This reference describes the fields in the Film Excel metadata template. 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 movie. The language column identifies the language of the title, synopses, video, captions, subtitles, audio dub, and artwork in that row. See the Excel Metadata Overview.
Fields are grouped below into: Package Info, Content Descriptors, Ad Breaks & Cue Points, 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.
| Excel Column | Accepted Values | Required |
|---|---|---|
contentType | film | 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 | Valid language value | Required |
original_spoken_language
Original production language of the title. The value must use a supported language code. A region code is recommended.
| Excel Column | Accepted Values | Required |
|---|---|---|
original_spoken_language | Valid language value | Required |
country_of_origin
The primary country where the film was produced, and where the main creators, crew, and producers are established. Must conform to a supported ISO 3166-1 alpha-2 code.
| Excel Column | Accepted Values | Required |
|---|---|---|
country_of_origin | Valid 2-character country code per ISO 3166-1 alpha-2 | Preferred |
asset_id
Immutable, unique identifier for a movie. 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 |
eidr
EIDR ID, if one exists.
| Excel Column | Accepted Values | Required |
|---|---|---|
eidr | Any valid EIDR ID | Optional |
tms_id
Gracenote ID, if one exists.
| Excel Column | Accepted Values | Required |
|---|---|---|
tms_id | Any valid TMS ID | Optional |
Content Descriptors
title
Title of the movie, 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 (e.g., (Classic), (1987), (Season 1), (HD)).
| Excel Column | Accepted Values | Required |
|---|---|---|
title | Example: Movie Title | Required |
genres
Genre classification of the content. Each movie must be delivered with at least one supported genre. See the enumerated genre list.
| Excel Column | Accepted Values | Required |
|---|---|---|
genres | See enumerated list. No more than 10 genres per title. | Required |
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 (e.g., "Rom-Com" and "rom-com" are two distinct tags).
| Excel Column | Accepted Values | Required |
|---|---|---|
tags | Any string under 50 characters | Highly recommended |
runtime
Total runtime of the content, in whole minutes.
| Excel Column | Accepted Values | Required |
|---|---|---|
runtime | Integers only. Example: 90 | Required |
release_date
Original date the content was first made available in any presentation. Must include an accurate year of release at minimum.
| Excel Column | Accepted Values | Required |
|---|---|---|
release_date | ISO 8601 format: YYYY-MM-DD | Required |
rating_system and ratings
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 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).
| Excel Column | Accepted Values | Required |
|---|---|---|
rating_system | See rating values by system and country | Required |
ratings | See rating values by system and country | Required |
brief_synopsis
A brief synopsis of the movie, in the language defined in the language column. 100-character limit. Required for Linear OTT distribution.
| Excel Column | Accepted Values | Required |
|---|---|---|
brief_synopsis | Up to 100 characters | Required for Linear OTT distribution |
short_synopsis
A short synopsis of the content, in the language defined in the language column. 250-character limit.
| Excel Column | Accepted Values | Required |
|---|---|---|
short_synopsis | 250-character synopsis | Required |
long_synopsis
An optional long synopsis of the content, in the language defined in the language column. 500-character limit.
| Excel Column | Accepted Values | Required |
|---|---|---|
long_synopsis | 500-character synopsis | Optional |
localized_brief_synopsis
A localized brief synopsis of the movie, in the language defined in the localized_language column. 100-character limit. Required for Linear OTT distribution.
| Excel Column | Accepted Values | Required |
|---|---|---|
localized_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
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 |
|---|---|---|
ad_breaks | HH:MM:SS.sss | Preferred |
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
cuePointelements; see the Film 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 |
|---|---|---|
cue_points | Format: type=HH:MM:SS.sss>HH:MM:SS.sss. Allowable type values: ad overlay, behind the scenes, intro, recap, end | Optional |
Cast & Crew
cast
Names of cast members.
| Excel Column | Accepted Values | Required |
|---|---|---|
cast | Comma-separated list of Firstname Lastname | Preferred |
director
Name of the movie's director or directors.
Excel metadata currently supports only the director role for crew credits. The Film XML Reference lists the additional roles available in XML.
| Excel Column | Accepted Values | Required |
|---|---|---|
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: movieVideoFile.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 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 |
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 |
|---|---|---|
caption_file_name | Example: movieCaptions.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: movieForcedSubtitle.srt | Required when providing forced narrative subtitles |
Artwork
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 |
|---|---|---|
keyart_file_name | Example: movieKeyArt.jpg | Required |
background_file_name
File name of the textless 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 |
|---|---|---|
background_file_name | Example: movieBGimage.jpg | Preferred |
boxcover_file_name
File name of the texted 3:4 boxcover image for the movie, 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 |
|---|---|---|
boxcover_file_name | Example: movieBoxArt.jpg | Required for distribution to Howdy |
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 |
|---|---|---|
poster_file_name | Example: moviePoster.jpg | Preferred |
Availability
All four fields below are preferred, as shown in the tables. None is required.
territory
Country codes for the territories where the content is available. You may enter multiple country codes separated by commas, provided vod_type, license_start_date, and license_end_date are identical across them.
| Excel Column | Accepted Values | Required |
|---|---|---|
territory | US, CA, GB, MX | Preferred |
vod_type
Monetization type of the movie. You may enter multiple values separated by commas, provided territory, license_start_date, and license_end_date are identical across them.
| Excel Column | Accepted Values | Required |
|---|---|---|
vod_type | Example: avod, svod, avod,svod | Preferred |
license_start_date
Start date of content availability. The date must be before license_end_date; the dates must not be the same.
| Excel Column | Accepted Values | Required |
|---|---|---|
license_start_date | ISO 8601 format: YYYY-MM-DDTHH:MM:SS | Preferred |
license_end_date
End date of content availability. The date must be after license_start_date; the dates must not be the same.
| Excel Column | Accepted Values | Required |
|---|---|---|
license_end_date | ISO 8601 format: YYYY-MM-DDTHH:MM:SS | Preferred |
Updated about 5 hours ago