Metadata

Overview

Roku's transform engine converts partner metadata into the format used by its ingest system. Use the element and field names agreed upon during onboarding, and keep them consistent across deliveries. Whatever names you use, the data in every field must meet the Roku Channel Ingest Specification.

• If you already use an XML format to deliver content to other platforms, you may be able to repurpose it for Roku delivery.
• You may provide a sample of your existing metadata format during onboarding for Roku to evaluate its validity for ingest.
• Regardless of which format is delivered, all required elements/fields must be provided in the metadata deliverable.

Related Documentation

These requirements apply to all metadata delivery formats. For individual fields and delivery instructions, see:

• MovieLabs: MEC and MMC delivery
• Roku XML: Film, TV, and Clip field references
• Roku Excel: Film, TV, and Clip field references

---

Content Type Definitions

Roku Channel supports three content types: tv, film, and clip. All content must be delivered as one of these three types, and titles must be delivered under the same content type in which the program was originally released.

TV

Content structured in a series > season > episode hierarchy must be delivered under the TV specification.

• Series: a collection of programs/episodes released under a common title with a consistent narrative, characters, or theme. In North America, each year of a series is called a season; a series can span several seasons.
• Season: a group of programs/episodes released in one year, attributed to one series.
• Episode: a single self-contained narrative or informational segment of a series. An episode belongs to exactly one season of exactly one series.

Film

Stand-alone programs that are not part of a series/season/episode hierarchy must be delivered under the Film specification. These include feature films, stand-alone TV specials, and short films.

Clip

Short-form, stand-alone or ancillary titles intended as a companion to a longer program (e.g., sporting events, movies, TV series) must be delivered under the Clip specification.

Clips appear differently from films on Roku Channel:

• Runtime and title appear directly on the content tile, so viewers can see them without opening the clip.
• Clips do not have a content details page. Unlike Film, a viewer cannot click into a Clip to reach a synopsis or additional information screen.
• A Clip's synopsis is instead accessible by pressing the * (asterisk/options) button on the Roku remote.

---

Minimum Required Metadata by Content Type

brief_synopsis applies at the title, episode, and series levels, including localized versions. Required for Linear OTT distribution. It has a 100-character limit.

Long synopses are always optional, including localized versions. Closed captions are strongly preferred for all content; partners determine whether they are required for a specific delivery. When a sidecar caption file is supplied, include the captions file_name reference. See Closed captions and subtitles for file requirements.

Film / Clip: Required Fields

• provider
• content_type
• asset_id
• title
• release_date
• runtime
• genres
• rating
• rating_system
• short_synopsis
• video file_name
• key_art file_name

TV: Required Fields

Episode-level:

• provider
• content_type
• asset_id
• episode title
• episodeNumber
• episode release_date
• runtime
• rating
• rating_system
• episode short_synopsis
• video file_name
• episode thumbnail file_name

Series-level:

• series_id
• series title
• series release_date
• series genres
• series short_synopsis
• series key_art file_name

Season-level:

• season_id
• seasonNumber

TV requires metadata at three levels: series, season, and episode. Film and Clip require metadata for the individual title.

---

ID Requirements and Expectations

• Partners generate and supply all IDs. Roku does not assign them.
• Every clip and movie must be delivered with an asset_id.
• Every episode must be delivered with three IDs: asset_id, series_id, and season_id.
• IDs should be meaningful to your team, since they are how Roku positively identifies a title in its system.
• The asset_id in the ingest metadata must match the Title ID provided in the Avails document. This links the content across Roku's pipeline, from Avails submission through publication.
• Any update to a title already ingested into Roku's system must be accompanied by its asset_id.

All ID types share these rules:

• Maximum 50 characters
• Alphanumeric characters, hyphens, and underscores only
• Spaces or special characters in any ID will fail ingestion

---

Availability Sheets / Planners

• At onboarding, Roku requests an initial launch list of titles/episodes/clips currently available for licensing, plus a schedule for when content will be refreshed.
• For ongoing delivery, Roku requests:
  • Avails at least 60 days prior to the licensing window start
  • Content delivery at least 30 days before curation onto the channel

This lead time allows for processing and QC before the content goes live. Delivery capacity is coordinated after signing.

---

Availability Windows

By default, content becomes available at 12:00 AM (midnight) and expires at 11:59:59 PM in each user's local time zone. If a title must go live or expire at a specific time, that time must be included in the license window start/end values in the ingest metadata.

Roku supports two time designations:

Time Value Format

• Absolute times must be expressed in UTC. In the example above, 9:00 PM Eastern on November 1 is 1:00 AM UTC on November 2.
• If no time is provided, Roku assumes a relative start of 12:00:00 AM and a relative end of 11:59:59 PM.

---

Special Characters

Roku uses CDATA sections to allow special characters (e.g., ! @ # $ % ^ & * ( ) { } | [ ] ; : ' " ? / < >, as well as foreign character sets) within certain node values in the ingest XML. Roku highly recommends wrapping such data in CDATA sections to ensure proper ingest.

CDATA applies to metadata field values, such as titles and synopses. File names follow the separate File Delivery Specification.

Only the following nodes support CDATA sections:

• title
• brief_synopsis
• long_synopsis
• short_synopsis
• display_name

For nodes outside this list, the following characters must be escaped so Roku can read the XML:

Special characters must not be used in file names or file name references within XML or Excel metadata. See the File Naming Guidelines for the complete forbidden-character list for file names specifically.

---

Supported Metadata Formats

• XML is the preferred format.
• One complete XML file must be delivered for each movie, clip, or TV episode video file delivered.
• Metadata must be delivered using the method approved during onboarding, Aspera or S3, to the same folder location as its associated video, captions, and artwork files.

---

Music Cue Sheets

Music cue sheets for content distributed on Roku Channel may be submitted through the Music cue sheet submission form.

Do not submit music cue sheets with video package deliverables through Aspera. Cue sheets delivered with a video package are subject to deletion.

---

Glossary