Metadata updates (MDU) and file replacements

Overview

Roku processes updates automatically. You can submit an update whenever metadata or files need to change for a program already delivered to Roku Channel.

Every metadata update or file replacement must include these values exactly as originally delivered:

• Provider
• Asset ID
• Content Type

Roku manages metadata versions automatically. You do not need to include version information in the metadata.

Replacement file identification: Roku manages metadata record versioning automatically. Replacement files must use a unique filename or, for files referenced in a MovieLabs MMC, an accurate MD5 checksum. These requirements identify replacement files and are separate from metadata record versioning.

Excel Update Templates

Download the Excel update templates (ZIP) for Film, TV, and Clip metadata updates and media file replacements or additions.

Supported Fields for Automated Metadata Update (MDU)

Roku currently supports updating the following fields via automated MDU:

• TMS ID
• EIDR ID
• Titles (primary and localized)
• Brief synopses (brief_synopsis, primary and localized, including series)
• Short Descriptions (primary and localized)
• Long Descriptions (primary and localized)
• Release Date
• Series Titles
• Season Number
• Episode Number
• Language (and localized languages)
• Availability Windows
• License Types
• Countries
• Genres
• Provider Tags
• Content Ratings (system & rating)
• Credits
• Ad Breaks
• Cue Points

---

Metadata Update (MDU)

Metadata updates are processed the same way as new ingest content. To update metadata only (no file changes), follow the requirements below.

Requirements

• Metadata updates must be delivered in the same format as the original ingest metadata.
• Metadata updates must include the exact same Asset ID used at original ingest. For a list of existing asset IDs, contact [email protected].
• All file name references must be removed from a metadata-only update. This includes:
  • Source video file name
  • Closed captions file name
  • Subtitle file name
  • Audio dub file name
  • Key, background, and/or poster art file names

Field Groups

Some fields must be updated together, in complete groups. All required fields in a group must be provided, or the update will not process.

Metadata group:

brief_synopsis has a 100-character limit, including localized and series values. Required for Linear OTT distribution. The required fields in the metadata group still apply.

Availability group:

Procedure

1. Upload the metadata update using the delivery method approved during onboarding: the /prod folder in Aspera or the approved production location in S3.

If the update isn't reflected on Roku Channel within 24 hours, contact [email protected].

---

File Replacements and Additions

File replacements and additions are processed the same way as new ingest content.

• A file replacement replaces a file that currently exists in Roku Channel's library.
• A file addition adds a new file to an existing record, for example, adding localized subtitles or dubs to a title that didn't previously have them.

Requirements

• File replacements/additions must be delivered in the same format as the original ingest metadata.
• File replacements/additions must include the exact same Asset ID used at original ingest. For a list of existing asset IDs, contact [email protected].
• Replacement files must be delivered with a unique filename, both in the metadata and on the file itself. Adding a version suffix (_v2, _v3, etc.) is sufficient, for example, movie_title_v2.mov. Files referenced in a MovieLabs MMC may instead use an accurate MD5 checksum, as described under MovieLabs File Replacements.
• Replacement files must be delivered to the exact same folder as the original delivery.
• The metadata file must reference only files being replaced or added. Files not being replaced or added must not be delivered or referenced.
• If the source video file is replaced and its duration changes, any related files (captions, subtitles, audio dubs) should also be replaced to stay in sync.
• File replacements require language values to be provided in order to update properly.

MovieLabs File Replacements

The following requirements apply to replacement files referenced in a MovieLabs MMC. All general file-replacement requirements above continue to apply.

Identifying a Replacement

Each replacement file must provide at least one of the following so Roku can distinguish an intentional replacement from a duplicate delivery:

• A unique filename that differs from filenames previously delivered for that asset.
• An accurate MD5 checksum, supplied in the corresponding <manifest:ContainerReference> using <manifest:Hash method="MD5">.

If the previous filename is reused, an accurate MD5 checksum must be included. The checksum must be calculated from the exact replacement file being delivered; do not copy the checksum from an earlier version.

Using both a unique filename and an MD5 checksum is recommended, but either method is sufficient. Version suffixes or timestamps may be used to distinguish file versions, provided the complete filename follows the File Naming requirements.

Delivering the Replacement

• Deliver the replacement media file before the updated MMC. The file transfer must be complete before the MMC is delivered.
• The updated MMC must reference the replacement file. Its <manifest:ContainerLocation> value must match the delivered filename or location exactly, including case.
• When an MD5 checksum is supplied, it must appear in the same <manifest:ContainerReference> as the file to which it applies.
• Artwork referenced through a MEC <md:ArtReference> must have its corresponding MEC reference updated. The MMC hash instructions above apply to files referenced in an MMC.

A file delivered under a previously used filename without an updated MD5 checksum may be treated as a duplicate and may not replace the existing asset.

Files Supported for Automated Replacement/Addition

• Video file
• Series key art file
• Series poster art file
• Series background image file
• Episode image file
• Movie key art file
• Movie poster art file
• Movie background image file
• Shortform key art file
• Closed caption file
• Full subtitle file
• Forced narrative subtitle file
• Sidecar audio file (audio dubs and descriptive audio)

Procedure

1. Upload the file replacement/addition metadata using the delivery method approved during onboarding: the /prod folder in Aspera or the approved production location in S3.

---

Content Takedown

If rights change and content needs to be removed from Roku Channel immediately or on a future date, update the availability end date using the Metadata Update (MDU) process above.

• Explicit updates must be provided for every territory from which the content should be removed. A takedown in one territory does not automatically apply elsewhere.
• Be aware: end dates provided without an explicit time value will expire at 11:59:59 PM on that date (local time), per the default behavior described in the Metadata Overview's Availability Windows section.

---

Glossary