The xmlns (for XML namespace) attribute is required and is needed for schema validation. It is used to declare the namespace (and associated schema) to which the tags in the XML are expected to conform. The namespace must be http://apple.com/itunes/importer.
The version attribute is required and should refer to the version of the specification used to create the metadata.
Packages created to this specification must indicate version="film5.3". The “film” portion of the attribute must be in lowercase letters.
<language>en-US</language>
Language (required)
The primary language of the metadata for this package. Fields such as title and synopsis are expected to appear in this language.
As a best practice when specifying a language, use the region subtag (for example, the US of en-US) only when it conveys helpful information, such as spelling variations between countries. For example, there is generally not a need to distinguish between Japanese as used in one country versus another, so you should use only the language code subtag (ja) instead of the language code and region subtags (ja-JP). In cases where specifying a region is appropriate, use the hyphen character to combine a language subtag with a region subtag. This identifies both the language and the specific location where the language is used. For English with American spelling, use en-US; for English with British spelling, use en-GB.
The language codes are formatted according to the best practices recommended by the Internet Engineering Task Force (IETF) in a group of documents known collectively as BCP 47, and in particular, RFC 5646, which is part of BCP 47. An overview of these best practices is provided here: https://www.w3.org/International/articles/language-tags/. See Language Codes for a list of common codes.
This value should be the Apple-defined provider shortname given for partner identification. The value must match the provider name used in Transporter (the value that is after -s in the Transporter command). The value supplied with the <provider> tag is case-sensitive. For example, if the provider shortname is Paramount, the value in the <provider> tag must be Paramount; not paramount or PARAMOUNT. Note that it is the value you pass as an argument to Transporter, not the value in the XML, that determines the account you are delivering to. Contact your Technical Representative for this value.
Video Metadata Fields
<video>
Video (required)
Begins the video element. Only one video element can be defined per film XML.
<type>film</type>
Video Type (required)
This value indicates how Apple should process this video. The only accepted value for video type is “film.”
<subtype>feature</subtype>
Video Subtype (required; can be updated)
This value indicates how Apple should represent this video in the Apple TV app. The accepted values are:
feature: This is to identify full-length films.
short: This is to identify short films.
Short films must be identified as short with the <subtype> tag as this sets up the correct pricing. See Table 1: Wholesale Price Tiers for further information.
Vendor Offer Code (optional; 1-100 bytes, see restrictions; can be updated)
An identifier which will be reported back through sales reporting channels.
Restrictions: The vendor offer code can only contain alphanumeric characters and underscore marks; it cannot contain spaces, dashes, ampersands, other punctuation, or symbols. The vendor offer code is case-sensitive and must not start with an underscore. Vendor offer codes can be numeric, but they are treated as strings, not numbers; a vendor offer code of '00000000012345' is not the same as '12345'.
<vendor_id>09736156444</vendor_id>
Vendor Identifier (required, 1-100 bytes, see restrictions)
The permanent value that uniquely identifies this film separately from any other film given by the provider. This ID is used for tracking your assets and sales reporting.
Restrictions: The vendor identifier can only contain alphanumeric characters and underscore marks; it cannot contain spaces, dashes, ampersands, other punctuation, or symbols. The vendor identifier is case-sensitive and must not start with an underscore. If a Vendor ID is numeric, it is treated as a string, not numbers; a vendor identifier of '00000000012345' is not the same as '12345'. Vendor IDs must be at least six ASCII characters in length but have a limit of 100 ASCII characters.
Use the provider review start date to specify when a film becomes available to be reviewed in Extras Previewer and Apple Partner Media Review. Specifying the provider review start date prevents playback in these apps until that date occurs.
If the provider review start date is not specified, then the film is available immediately in Extras Previewer and Apple Partner Media Review.
<isan>0000-0000-03B6-0000-O-0000-0000-2</isan>
ISAN Identifier (optional, 1-50 bytes)
The International Standard Audiovisual Number (ISAN) for this film. ISAN is an industry standard used to uniquely identify audiovisual works.
For more information on ISAN, see the ISAN website. Note that ISAN is required for certain films sold in Switzerland. See Regional Requirements for more information.
ISAN values should contain dashes as defined by the ISAN specification. The optional version subcomponent is ignored.
<eidr>10.5240/CFC2-B507-CE22-B3D4-F32F-2</eidr>
EIDR (optional)
The EIDR (Entertainment Identifier Registry) is a universal, unique identifier system for movie and television assets. Any level of EIDR is accepted in this field, so long it is in valid format. For more information, see the EIDR website.
The format of the EIDR identifier is 10.5240/XXXX-XXXX-XXXX-XXXX-XXXX-C, where:
10.5240 represents the standard prefix of an EIDR value
X represents a hexadecimal digit
C represents the check character
<upc>09736156444</upc>
UPC (optional)
The Universal Product Code (UPC) for this film if the film is sold as physical media in stores.
<countries_of_origin>
<country primary="true">US</country>
<country>CA</country>
</countries_of_origin>
Countries of Origin (optional if using the <country> tag; otherwise required, ISO-3166-1 country code)
The ISO 3166-1 alpha 2 code of the country (or countries) where the content originates from, for example: the country where the film was primarily produced, where the main authors and workers reside, where the main producer is established, and so on. Such determination must be made in accordance with applicable law. You must specify at least one country of origin and that country should be the primary country of origin.
You can supply additional countries as needed to associate all the countries involved in developing and creating the video. To deliver more than one country, use the <countries_of_origin> tag, and then specify each individual country using a <country> tag. One country is designated as the primary country using the primary="true" attribute. Specifying secondary countries is optional, but you should list all countries associated with the filming.
The country of origin may differ from the production country, which is the country that provided most of the funds for production. Both the country of origin (supplied either with the <country> tag or the <countries_of_origin> tag) and production country are required.
If there is only one country associated with the content, you can supply the country using the existing <country> tag (<country>US</country>), or you can use the new <countries_of_origin> tag, listing one country as primary: <country primary="true">US</country>. Currently, both the <country> tag and <countries_of_origin> tag are supported, and you must deliver one or the other. The <countries_of_origin> tag is optional, but at some point in the future, it will be required. If you do not supply the <countries_of_origin> tag at that time, you will see a warning message that the tag is required. At a date in the future, the delivery will fail.
You can’t use both the <country> tag and the <countries_of_origin> tag in the same delivery. If you do, delivery will fail.
<production_countries>
<country primary="true">US</country>
</production_countries>
Production Countries (required, ISO-3166-1 country code)
The ISO 3166-1 alpha 2 code of the country (or countries) responsible for the primary source of funds for the film production. You must specify at least one production country and that country should be the country that provided most of the funds (for example, from national lotteries and other subsidies). Such determination must be made in accordance with applicable law. You can supply additional production countries as needed. Supplying at least one production country is required and that country should be designated as the primary country using the primary="true" attribute.
The production country may differ from the country of origin, which is the country where the content originates from in accordance with applicable law. Both the country of origin (supplied either with the <country> tag or the <countries_of_origin> tag) and production country are required.
Specifies the language spoken by the actors in the film. The value used for locale is case-insensitive, even though the example shows the value in the format xx-XX, such as en-US.
In this example, the language the actors' lips are moving in is English as spoken in the United States, so en-US must be specified as the <original_spoken_locale>.
As a best practice when specifying a language, use the region subtag (for example, the US of en-US) only when it conveys helpful information, such as spelling variations between countries. For example, there is generally not a need to distinguish between Japanese as used in one country versus another, so you should use only the language code subtag (ja) instead of the language code and region subtags (ja-JP). In cases where specifying a region is appropriate, use the hyphen character to combine a language subtag with a region subtag. This identifies both the language and the specific location where the language is used. For English with American spelling, use en-US; for English with British spelling, use en-GB. See Language Codes for more information.
Note: This tag is different from the <language> tag. <original_spoken_locale> is the language the actors are seen speaking in. <language> is the primary language used for the metadata.
<title>Forrest Gump</title>
Title (required, 1-255 bytes; may be updated)
The name of this film. The information sent with this tag can be updated unless Apple has reviewed and confirmed the quality of the metadata.
Studio Release Title (required, 1-255 bytes; may be updated)
The original title of a film at its initial release, in any form, to the viewing public, in whichever country/region and language it has been first released. This is intended to tie together subsequent releases in different countries/regions and languages to the initial release of the film. When submitting the package for the initial release, you should set the <studio_release_title> value to the same value as <title>.
Note: The <studio_release_title> tag is required even if the original release title is the same that is provided with the <title> tag. Beginning November 2014, if you deliver a package and do not include the <studio_release_title> tag, you will see a warning.
The information sent with this tag can be updated unless Apple has reviewed and confirmed the quality of the metadata.
<synopsis>"Stupid is as stupid does," says Forrest Gump (played by Tom Hanks in an Oscar-winning performance) as he discusses his relative level of intelligence with a stranger while waiting for a bus. Despite his sub-normal IQ, Gump leads a truly charmed life, with a ringside seat for many of the most memorable events of the second half of the 20th century. Featured alongside Tom Hanks are Sally Field as Forrest's mother; Gary Sinise as his commanding officer in Vietnam; Mykelti Williamson as his ill-fated Army buddy who is familiar with every recipe that involves shrimp; and the special effects artists whose digital magic place Forrest amidst a remarkable array of historical events and people.</synopsis>
Synopsis (required; 1-4000 bytes; may be updated)
A general summary of the film’s content and story line. The information sent with this tag can be updated unless Apple has reviewed and confirmed the quality of the metadata.
Important: Size limits for string fields are expressed in bytes. For Roman alphabet characters, each character is one byte. For strings containing multi-byte characters (e.g., Japanese symbols), the number of allowed characters will be less than the byte limit, depending on the specific contents of the supplied string.
Theatrical Release Date (required if not providing <digital_only_release_date>)
This is the date the film was first released in theaters for the specified territory. If a film was not released theatrically, use the date it was first released physically. If a film was released digitally, use the <digital_only_release_date> tag (see the annotation below).
The date must be in the format YYYY-MM-DD where YYYY is the 4-digit year, MM is the 2-digit month, and DD is the two-digit day.
This field does not impact date of release or “street date” in the Apple TV app.
Important: If you do not know the exact theatrical release date, you can specify just the year in YYYY-01-01 format. The Apple TV app displays the date as YYYY.
Digital Only Release Date (required if not providing <theatrical_release_date>)
This is the date the film was first released digitally for the specified territory. Use this tag if the film was not released in theaters. Note that if you supply the <digital_only_release_date> tag, you cannot also supply the <theatrical_release_date> tag.
The date must be in the format YYYY-MM-DD where YYYY is the 4-digit year, MM is the 2-digit month, and DD is the two-digit day.
This field does not impact date of release or “street date” in the Apple TV app.
<genres>
Genres (required)
Films must specify at least one genre.
<genre code="COMEDY-00"/>
<genre code="DRAMA-00"/>
</genres>
Genre (required, multiple allowed; may be updated)
The genre must be selected from the set of allowed genres that are defined in Table 1: Film Genres. The information sent with this tag can be updated unless Apple has reviewed and confirmed the quality of the metadata.
All film genres have an Apple genre code, which is supplied using the attribute named code. The code attribute is required. The following are currently supported for delivering genre information:
Required method using the genre code:
<genre code="COMEDY-00"/>
Acceptable method using both the genre code and the genre label:
<genre code="COMEDY-00">Comedy</genre>
If you use this method, the genre identified by code and the genre identified by genre label must resolve to the same genre, for example, <genre code="COMEDY-00">Drama</genre> would be rejected.
Note that when you do a metadata lookup, both the genre and the genre code will be emitted regardless of which method you use to supply the genre.
<ratings>
Ratings (required; can be updated)
You must specify one or more ratings for your film content.
<rating system="mpaa" reason="for drug content, some sensuality and war violence" code="PG-13"/>
Rating (required; can be updated)
A valid rating from an accepted ratings system. More than one rating can be specified, but only one rating per ratings system is allowed. If the film is not rated, choose the appropriate rating for Unrated or Not Rated (see the Overview topic in the “Film Ratings, Advisories, and Genres” section for an explanation of Unrated and Not Rated). For countries or regions that do not have an Unrated or Not Rated classification, you must choose another rating. The information sent with this tag can be updated.
All film ratings have a short, plain-ASCII Apple rating code, which is supplied using the attribute named code. Standardizing on the Apple rating codes reduces errors resulting from typos and removes the need to enter escape codes for ratings in some languages.
The code attribute is required. The following are currently supported for delivering rating information:
Required method using the rating code:
<rating code="PG-13"/>
Acceptable method using both the rating code and the rating label:
<rating code="PG-13">PG-13</rating>
If you use this method, the rating identified by code and the rating identified by the rating label must resolve to the same rating, for example, <rating code="UR">PG-13</rating> would be rejected.
To view a list of rating codes, you can download it from Film Ratings.
</ratings>
<cast>
Cast (required)
Film content must specify any cast who performed work in the production. The Apple TV app can choose to display and cross-reference cast and crew for customer browsing.
Notes:
All tags within the <cast> block can be updated at any time.
To make changes for a cast member, you must deliver the entire <cast> block with all the <cast_member> blocks, even if you are not making changes to a particular cast member. To remove a cast member, deliver the entire <cast> block, omitting the cast member you want to remove. If you are not making changes to any cast members on a metadata update, leave out the entire <cast> block.
<cast_member billing="top">
Cast Member (required, multiple allowed)
A cast member in this film. List cast actors within the <cast> element block in the order in which you want them to appear in the Apple TV app. Be sure to designate actors who require top billing.
billing (optional)
If an actor requires top billing for this film, the attribute billing must have the value "top", otherwise you can omit this attribute. Note that only those actors with billing="top" are displayed in the Apple TV app.
Accepted values:
"top": Actor must appear in the Apple TV app in top billing positions.
"ordered" (default): Actor appears with all other actors listed, in order.
Important: If the billing attribute is blank and has no value, you must remove the attribute.
<display_name>Tom Hanks</display_name>
Display Name (optional if <apple_id> supplied, text, 1-250 bytes)
The actor’s name presented as it would be displayed when casually referring to the actor’s real name.
<apple_id>2672649</apple_id>
Apple ID (optional, numeric)
You can refer to the cast member by name (using the <display_name> tag) or by Apple identifier (using the <apple_id> tag). Apple assigns every cast member a unique Apple identifier; Apple recommends using the Apple identifier to avoid the ambiguity in cases where cast or crew members share the same name as other actors or crew members or music artists. You can supply the <display_name>, the <apple_id>, or both the <display_name> and <apple_id>. If you supply both tags, the <display_name> tag will be ignored in favor of the Apple identifier. If you do not know the cast member's Apple identifier, you can do a metadata lookup on an existing film and look for the <apple_id> tag. For any subsequent updates, you can use the <apple_id> tag instead of or in addition to the name, to avoid ambiguity.
<description format="plain">Forrest Gump leads a truly charmed life as he journeys through key events of the second half of the 20th century. Entirely without trying. For his portrayal of Forrest Gump, Tom Hanks earned the Academy Award for Best Actor, Golden Globe for Best Actor in a Motion Picture Drama, the BAFTA award for Best Actor and many more awards around the world. The titular film and character are based on the Winston Groom novel - "Forrest Gump".</description>
Description (optional)
Provides text related to the actor in the context of the film and the character he or she plays. The description can be a maximum of 4000 bytes.
The format attribute identifies the format of the text sent in the <description> tag. Currently, the format can be unformatted plain text ("plain"). Supplying the format is required if you are delivering the <description> tag.
<characters>
Characters (required)
Begins the block that describes the characters in the film played by this actor. The <characters> block is allowed only within a <cast_member> block; not within a <crew_member> block. There is no limit to the number of characters you can include in the <characters> block.
Note: To make changes for a character, you must deliver the entire <characters> block with all the <character> blocks, even if you are not making changes to a particular character. To remove a character, deliver the entire <characters> block, omitting the character you want to remove. If you are not making changes to any characters on a metadata update, leave out the entire <characters> block.
<character>
Character (required)
For each character in the film, supply the character metadata within a <character> block.
Notes:
If a character in a film is played by multiple actors, (for example, the character as a child and the character as an adult), each actor would have a different version of that character in their <characters> block. The <reference_id> for the characters must be different.
If the same actor plays multiple roles in a film, deliver each character role in its own <character> block within the <cast_member> block for the actor.
<reference_id>FORREST</reference_id>
Reference ID (required; 1-100 bytes; see restrictions)
A unique identifier for the character scoped within the film, which is used to refer to the character in an iTunes Extras or elsewhere in the cast/crew metadata, for example, in dub artist definitions (see the annotation for Dub Artist Crew in Multiple-Language Film Metadata Annotated). Character reference IDs must be unique within a film.
Restrictions: The reference ID can only contain alphanumeric characters and underscore marks; it cannot contain spaces, dashes, ampersands, other punctuation, or symbols. The reference ID is case-insensitive and must not start with an underscore. If a reference ID is numeric, it is treated as a string, not numbers; a reference ID of '00000000012345' is not the same as '12345'. Reference IDs have a limit of 100 bytes.
<character_name>Forrest Gump</character_name>
Character Name (required)
The name of the character the actor plays in the film using up to 256 bytes.
<character_note>Protagonist</character_note>
Character Note (optional)
The description of the character the actor plays in the film, using up to 1024 bytes. The description can be one-word to indicate the character type, for example, Protagonist, or it can be a descriptive phrase, for example, Nurse at park bench. The text value is case-sensitive.
The image of the cast member as he or she appears in the film, for example, an image of Forrest Gump, not Tom Hanks. In an animated film, use an image of the animated character played. The image must be square, PNG format (.png), and 1080 by 1080 pixels minimum.
Additional guidelines:
Image should show the face of the character, not a full-body shot
Actor should be in character
Do not send the image as a screenshot
Image must contain content suitable for a general audience (for example, no offensive gesturing, no nudity)
Image should be in color
</cast_member>
</cast>
<crew>
Crew (required)
Film content must specify any crew who performed work in the production. The Apple TV app can choose to display and cross-reference cast and crew for customer browsing.
Notes:
All tags within the <crew> block can be updated at any time.
To make changes for a crew member, you must deliver the entire <crew> block with all the <crew_member> blocks, even if you are not making changes to a particular crew member. To remove a crew member, deliver the entire <crew> block, omitting the crew member you want to remove. If you are not making changes to any crew members on a metadata update, leave out the entire <crew> block.
<crew_member billing="top">
Crew Member (required; multiple allowed)
A crew member in this film. List crew members within the <crew> element block in the order in which you want them to appear in the Apple TV app. Be sure to designate crew who require top billing. The role performed by the crew member should be specified.
billing (optional)
If a crew member requires top billing for this film, the attribute billing must have the value "top", otherwise you can omit this attribute. Note that only those crew members with billing="top" are displayed in the Apple TV app.
Accepted values:
"top": Person must appear in the Apple TV app in top billing positions.
"ordered" (default): Person appears with all other crew members listed, in order.
Important: If the billing attribute is blank and has no value, you must remove the attribute.
<display_name>Robert Zemeckis</display_name>
Display Name (optional if <apple_id> supplied, text; 1-250 bytes)
The crew member’s name presented as it would be displayed when casually referring to his or her real name.
<apple_id>274059420</apple_id>
Apple ID (optional; numeric)
You can refer to the crew member by name (using the <display_name> tag) or by Apple identifier (using the <apple_id> tag). Apple assigns every crew member a unique Apple identifier; Apple recommends using the Apple identifier to avoid the ambiguity in cases where cast or crew members share the same name as other actors or crew members or music artists. You can supply the <display_name>, the <apple_id>, or both the <display_name> and <apple_id>. If you supply both tags, the <display_name> tag will be ignored in favor of the Apple identifier. If you do not know the crew member's Apple identifier, you can do a metadata lookup on an existing film and look for the <apple_id> tag. For any subsequent updates, you can use the <apple_id> tag instead of or in addition to the name, to avoid ambiguity.
<roles>
<role>Director</role>
</roles>
Role (required; multiple allowed))
The role performed by this crew member. Currently, only the following roles are displayed in the Apple TV app (the role names must be in English in order to be imported, but the names will be localized if needed when displayed in the Apple TV app):
Co-Director
Director
Producer
Screenwriter
Composer
If a crew member has more than one role, specify each role in a separate <role> tag and place each role within the <roles> block in the order it should appear in the credits. Do not combine a crew member’s roles in one <role> tag, for example, do not use Producer/Screenwriter.
</crew_member>
</crew>
<chapters>
Chaptering (required)
Defines chapters within a video.
Note: Chapter titles and chapter artwork can be added or changed, however you must send all chapters, not just the ones being updated. Chapter artwork can be provided in an artwork file or specified by a timecode. See Chapter Update Examples for an XML example for updating chapters.
The format can be qt_text or one of the SMPTE formats illustrated in the Timecode Formats appendix. If you omit the <timecode_format> tag, the format defaults to qt_text.
Each chapter requires an artwork image, either an artwork file or a frame specified by a timecode. If you specify a timecode but use the qt_text format, the frame nearest the timecode is used for the chapter image: you cannot specify a frame for the chapter image using qt_text.
Important: The frame modes (for example, nonDrop and dropNTSC) are case-sensitive.
Defines the first chapter within the <chapters> tag.
There is no limit to the number of chapters you can define.
<start_time>00:00:00:00</start_time>
Chapter Start Time (required)
Specifies the start of each chapter as dictated by the <timecode_format> above. End time is inferred from the start time of the next defined chapter. Refer to Timecode Formats for <start_time> examples.
The first chapter must start at 00:00:00:00 and the chapters must be listed in chronological order.
<title locale="en-US">Forrest's Story Begins</title>
Chapter Title (required; 1-255 bytes; can be updated)
The title of the chapter. There is a 255-byte limit strictly enforced. The data is stored in the UTF-8 encoding, so for single-byte characters (such as those drawn from the ASCII character set), this equates to a 255-character limit; for multiple-byte (e.g., Japanese) characters, this can equate to as few as 71 characters.
Use the locale attribute to specify both the language and the optional region where the language is spoken.
As a best practice when specifying a language, use the region subtag (for example, the US of en-US) only when it conveys helpful information, such as spelling variations between countries. For example, there is generally not a need to distinguish between Japanese as used in one country versus another, so you should use only the language code subtag (ja) instead of the language code and region subtags (ja-JP). In cases where specifying a region is appropriate, use the hyphen character to combine a language subtag with a region subtag. This identifies both the language and the specific location where the language is used. For English with American spelling, use en-US; for English with British spelling, use en-GB. See Language Codes for more information.
Note: It is recommended that the chapters provided match what is on the DVD. In addition, include a chapter for film credits as the last chapter.
Artwork File (required, if providing an image file; can be updated)
The filename of the image to be used to represent this chapter. Do not include a path. You must provide the <file_name>, <size>, and <checksum>. Each chapter must have an associated image: either an artwork file or an artwork timecode. See the annotation below for how to deliver an artwork timecode.
Include the artwork files in the package directory along with the basic metadata file. Chapter images must be cropped (no letterbox, pillarbox, or windowbox). Each artwork file image must have a unique filename.
<artwork_time>00:07:45:23</artwork_time>
Artwork Time (required, if specifying a frame by timecode; can be updated)
The timecode of the frame to be used to represent this chapter. You must provide a valid timecode from within the chapter. Each chapter must have an associated image: either an artwork file or an artwork timecode. See the annotation above for how to deliver an artwork file.
In qt_text format, the frame nearest the timecode is used for the chapter image: you cannot specify a frame for the chapter image using qt_text.
Each artwork timecode must be unique.
</chapter>
</chapters>
<accessibility_info>
Accessibility Information (required for U.S. deliveries; can be updated)
Begins the block that describes the availability of closed captions for the film.
Note that the <accessibility_info> tag can also be delivered within the <assets> block in an asset-only update. See Alternate Audio Asset-Only Update Example for more information.
<accessibility role="captions" available="true"/>
Accessibility (required for U.S. deliveries; can be updated)
Indicates if closed captions are available.
Attributes include:
role: Refers to the data file for captions; "captions" is the only supported value.
available: Indicates availability of captions. Accepted values include "true" or "false". If you have delivered closed captions within the same package, the value cannot be "false".
An additional attribute, reason_code, is used to supply the reason closed captions are not included. See Basic Film Metadata Example without Closed Captions for more information. Note that the reason_code attribute is not allowed if available="true", and required when available="false".
Asset Metadata Fields
<assets>
Assets (required, multiple from a set; can be updated)
Begins the assets block that references the assets being delivered.
New files update by overwriting the previous files. A data file not referenced in the asset block on a redelivery is removed.
<asset type="full">
Asset (required)
Describes the type of asset being delivered. You can specify type="full" to indicate that the asset is the feature asset or type="preview" to indicate that the asset is the preview file. Only one full source asset can be delivered; but multiple preview sources assets can be delivered, one per territory.
Production Still Image Time (optional; can be updated)
Specifies the frame to use for the production still image that will be displayed on the product page for a film. Using the <production_still_image_time> tag on the full asset, you indicate the image time to use to cut the image from the full asset. The image time must be within the full source with a 16:9 aspect ratio. You can specify only one production still frame, which will be used for all territories.
The format can be qt_text (default) or one of the SMPTE formats illustrated in the Timecode Formats appendix. In qt_text format, the frame nearest the timecode is used for the preview image: you cannot specify a frame for the preview image using qt_text.
Note: This tag is not the same as the <preview_image_time> tag (custom previews) or the image_time attribute (defined previews), which are used to represent the image for the preview source, not the full source. You can deliver the <production_still_image_time> tag, as well as the <preview_image_time> tag (custom previews) or the image_time attribute (defined previews) and the specified frame times do not need to match.
You can also deliver the production still image as a custom file, however Apple prefers that you send the production still image cut from the full asset. If you need to send the image as a file instead, the image must have the minimum dimensions of 1920 x 1080, with a 16:9 aspect ratio (subject to change). Do not send both the frame time and a separate image file in the same delivery. To deliver the image as a separate data file, omit the <production_still_image_time> tag and deliver the following:
If you omit the production still image time and do not provide a separate image file, an image will be cut from the full or preview video source asset.
<data_file role="source">
Source Data File (required)
A data file element block must be included if the video source material is delivered electronically. A data file element specifies the electronically delivered media file describing the role of the associated file. Since the file sent is used as the source file for the Apple encode, the role is “source” and is required. If you do not specify the role, you will see a warning message that the role is required; at a date sometime in the future, if you do not specify the role, the delivery will fail.
In this block, the <locale>, <file_name>, <size>, and <checksum> tags and the "image.textless_master" attribute are required.
<locale name="en-US"/>
Locale Name (required for full source, preview source, and audio)
Identifies the language that is spoken in the audio on the source asset. The locale indicates the language and the optional region where the language is spoken.
As a best practice when specifying a language, use the region subtag (for example, the US of en-US) only when it conveys helpful information, such as spelling variations between countries. For example, there is generally not a need to distinguish between Japanese as used in one country versus another, so you should use only the language code subtag (ja) instead of the language code and region subtags (ja-JP). In cases where specifying a region is appropriate, use the hyphen character to combine a language subtag with a region subtag. This identifies both the language and the specific location where the language is used. For English with American spelling, use en-US; for English with British spelling, use en-GB.
The name of the data file included in this electronic delivery package. The name should be relative to the package (containing no path reference “C:\” or “/Macintosh HD/”) and must contain the file name extension (”.mov” in this example).
Important: File names are case sensitive. A file name can contain only alphanumeric characters (A-Z, a-z, 0-9) and these symbols: underscore ("_"), dash (“-”), and period (“.”). The file name must not start with an underscore, dash, or period and cannot contain spaces, other punctuation or symbols.
<size>2595225600</size>
File Size (required)
The size in bytes of the data file. Do not specify any commas nor period delimiters.
The MD5 checksum of the data file. See the Checksums section for more information.
<attribute name="crop.top">0</attribute>
Metadata-Based Cropping (required if video contains inactive pixels)
The crop rectangle for the full or preview video’s QuickTime source file. If the video’s QuickTime source file is delivered matted (letterbox, pillarbox, or windowbox), specify the crop rectangle to crop the inactive pixels.
Note: Crop dimensions are required for films that contain inactive pixels. When sending crop dimensions, send accurate dimensions without unnecessary cropping, especially horizontally. If your video does not contain inactive pixels (that is, it is not matted), you can set all the crop values to zero, or omit the crop dimension attribute tags. If you do not supply any crop dimensions, the values default to 0,0,0,0.
The name attribute specifies the side of the image to be cropped. Accepted values are:
crop.top: The number of whole pixels from the top of the encoded image to remove.
crop.bottom: The number of whole pixels from the bottom of the encoded image to remove.
crop.left: The number of whole pixels from the left of the encoded image to remove.
crop.right: The number of whole pixels from the right of the encoded image to remove.
The values must be integers that represent the number of whole pixels of the encoded image.
Note: If delivering texted content due to unavailability of textless source material, burned-in text that falls over inactive pixels must be maintained in the attribution of crop values. Additionally, an equal number of pixels that are applied to preserve burned-in text in one region, must also be equally applied to the opposite region so that content can be displayed proportionally.
Specifies whether the film contains burned-in text, such as narratives burnt into the visual picture or burned-in subtitles. Narrative text is text that appears on screen to supplement the plot of the story without the use of a narrator, such as “Paris early morning, 1935.” Opening title sequences, and credits are not considered “text” in this case; those are expected to be in the film.
This attribute is required for all films. Allowed values are true or false. In this example, the film has burned-in narrative and burned-in subtitles, so the attribute is set to false.
Use this attribute to specify whether the video content has varying aspect ratios. Allowed values are true or false. The value defaults to false if you omit this attribute. This attribute can be used on all video sources.
Set this attribute to true to have the asset analyzed to detect the active regions of the video. This option applies the Per Frame Rectangular Mask (PFRM). Using the metadata that is generated by the analysis, the video player’s canvas size grows or shrinks with the video content when viewed on Apple Vision Pro.
To remove metadata generated by a previous analysis, deliver an update with this attribute set to false.
To deliver Dolby Digital Plus audio, use the role role="audio.7_1" attribute with the <data_file> tag. The 7.1 surround audio is optional and is delivered as a role for the full asset.
Note: The video source can only contain 2.0 stereo and an optional 5.1 surround audio; 7.1 surround audio cannot be combined with the source.
Use the "audio.surround.force_5_1_downmix" attribute indicate how to handle existing 5.1 surround audio.
When you deliver 7.1 surround audio and a 5.1 surround audio file, you do not need to supply the "audio.surround.force_5_1_downmix" attribute; however, if you do supply it, it must be set to false.
When you deliver 7.1 surround audio without a 5.1 surround audio file, you do not need to supply the "audio.surround.force_5_1_downmix" attribute; however, if you do supply it, it must be set to true. 5.1 surround audio will be automatically downmixed.
To deliver Dolby Atmos audio, use the role role="audio.object_based" attribute with the <data_file> tag. The Dolby Atmos audio is optional and is delivered as a role for the full asset.
Note: The video source can only contain 2.0 stereo and an optional 5.1 surround audio; Dolby Atmos audio cannot be combined with the source.
The <locale> tag should match the associated stereo audio locale (which could be the audio on the video source or an alternate audio). If the locales do not match, the availability of the Atmos audio will not be listed in the Apple TV app for the film.
Note: When you deliver a Dolby Atmos audio, you can choose to have Apple downmix it to 7.1, 5.1, and 2.0 formats. This allows you to deliver a single Atmos audio file and derive all of the other formats (7.1, 5.1, and/or stereo). See Dolby® Vision-Only (No SDR) Delivery with Embedded Audio for an example.
<data_file role="captions">
Closed Captioning Data File (required for U.S. deliveries; can be updated)
A data file element block must be included if the captions are delivered for the associated video. The "captions" role specifies that the delivered file is intended to be used as the closed captioning file for the Apple encode. This role must be specified, or the package will be rejected.
In this block, the <file_name>, <size>, <checksum>, and <locale> tags are required.
Important: If the content does not include closed captions, you must provide the reason why captions are not included. See the annotations for the <accessibility_info> tag in Basic Film Metadata without Closed Captions Annotated for more information.
<file_name>09736156444-english.scc</file_name>
File Name (required)
The name of the caption file included in this delivery package. The name should be relative to the package (containing no path reference “C:\” or “/Macintosh HD/”) and must contain the file name extension (.scc in this example).
Important: File names are case sensitive. A file name can contain only alphanumeric characters (A-Z, a-z, 0-9) and these symbols: underscore ("_"), dash (“-”), and period (“.”). The file name must not start with an underscore, dash, or period and cannot contain spaces, other punctuation or symbols.
<size>9511</size>
File Size (required)
The size in bytes of the caption file. Do not specify any commas nor period delimiters.
The MD5 checksum of the caption file. See the Checksums section for more information.
<locale name="en-US"/>
Locale Name (required)
Identifies the language that is used for the captions on the full source asset. The locale indicates the language and the optional region where the language is spoken.
You must supply the <locale> tag for closed captions even if the language of the captions is the same as the language specified with the <language> tag.
When updating a closed caption file, make sure the locale matches the locale of the file you are replacing. If the previously-delivered file did not have a locale specified, you can deliver a new file with the new locale and the existing file will be replaced. If the previously-delivered file had a locale specified and you want to replace it with a new file that has a different locale, you must first remove the existing captions file (<data_file role="captions" remove="true">). Note that the full asset can have only one caption file. See Closed Captions Asset-Only Update Examples for an example XML.
See the annotation for <locale> on the source asset above for details on specifying a language.
Indicates the timecode offset for the closed captions. Apple requires that timecodes start at a program start of 00:00:00:00, which may necessitate that captions be offset if they have been mastered to tape timecode. To keep closed captions in sync on the encoded file, use the "program.start.timecode" attribute. The value is a SMPTE HH:MM:SS:FF timecode in non-drop frame with an optional negative (-) sign for negative offsets, for example, -01:00:00:00. This feature is supported for both non-drop and drop frame timecodes.
Audio Description (AD) Data File (optional; can be updated)
Begins the data file block that delivers an AD audio file. An Audio Description (AD) file allows visually-impaired customers to follow the film with audio that describes the plot and what is being displayed visually on the screen. The "audio.visually_impaired" role specifies that the delivered file is intended to be used as an alternate audio file for Audio Description for the Apple encode. If you are delivering an AD audio file, the file must be in 2.0 stereo and you can optionally deliver an additional AD file in 5.1 surround format (no 7.1 surround).
In this block, the <file_name>, <size>, <checksum>, and <locale> tags are required.
<locale name="en-US"/>
Locale Name (required)
Identifies the language that is used for the AD audio track. The locale indicates the language and the optional region where the language is spoken.
You must supply the <locale> tag for the AD audio track even if the language of the audio is the same as the language specified with the <language> tag. If you deliver a package and do not include the locale for the AD file, you will see a warning that the locale is missing and that English ("en") will be used by default.
Note: Audio Description (AD) files are accepted for all languages and Apple includes the Audio Description when creating bundles. To be included in a bundle, the locale of the audio description must match the locale of a corresponding source audio or alternate audio file. If you send an Audio Description file that doesn’t have a corresponding audio file, it does not go live in the Apple TV app. For example, if you deliver a movie in English with French alternate audio, French AD, English AD, and Spanish AD, a bundle for Canada would include English audio, French audio, English AD, and French AD; it would not include Spanish AD because there is no corresponding Spanish audio.
See the annotation for <locale> on the source asset above for details on specifying a language.
The frame to use for the preview image. You can specify an image for each territory. The format can be qt_text (default) or one of the SMPTE formats illustrated in the Timecode Formats appendix. In qt_text format, the frame nearest the timecode is used for the preview image: you cannot specify a frame for the preview image using qt_text.
The preview image time must be within the preview source. If you omit the preview image time, the image defaults to the first frame at 45 seconds into the preview.
Note: This <preview_image_time> tag is not the same as the <production_still_image_time> tag, which is used to represent the image for the full source asset, not the preview source.
<territories>
<territory>WW</territory>
</territories>
Preview Asset Territory (required)
The territories in which the supplied preview file can be distributed. At least one territory must be specified and that territory must be WW (World Wide). Using WW ensures that all territories will have a preview. You can supply additional territories as needed for any territory-specific previews that are to be delivered. This is a territory and not language-specific asset.
Must be a valid ISO 3166 alpha-2 country code or WW. Note that some countries in the ISO 3166 alpha-2 country list contain other countries (for example, United States includes Puerto Rico). For a list of ISO 3166-1 alpha-2 codes, see https://www.iso.org/obp/ui/#search/code/. For more information on ISO codes, see https://www.davros.org/misc/iso3166.html.
One preview file can be provided for each territory. As noted above in the annotation for the full asset, the <locale> tag is required. The movie preview length should be a maximum of 10 minutes.
Note: The preview can be a custom asset file delivered as a data file, or it can be a defined preview clipped from the source video and specified in the metadata using the <preview> tag. See the annotation for the <preview> tag in Multiple-Language Film Metadata Annotated.
See the annotations on the Full Asset for tag specifics.
<asset type="artwork">
Poster Image (required; can add new image and update existing images)
A poster image is required, as is the <locale>, <file_name>, <size>, and <checksum> for the provided file. Poster art size must have a 2:3 aspect ratio with the following size requirements:
Non-layered JPG and PNG (.jpg and .png) files must be at least 2000 x 3000 pixels.
Layered LSR .lsr files must have a minimum size of 2000 x 3000 pixels.
See 2:3 Poster Art in Transactional Artwork Specifications.
You can add a new poster image if the poster art file has not yet been delivered or if it is for a new territory. After a title has gone live on the Store, existing poster art can be updated, but these updates are subject to review by Apple and may not take effect immediately.
<territories>
<territory>WW</territory>
</territories>
Poster Image Territory (required)
The territories in which the supplied artwork file can be displayed. At least one territory must be specified and that territory must be WW (World Wide). Using WW ensures that all territories will have a poster image. You can supply additional territories as needed for any territory-specific poster art that is to be delivered. This is a territory and not language-specific asset.
Must be a valid ISO 3166 alpha-2 country code or WW. Note that some countries in the ISO 3166 alpha-2 country list contain other countries (for example, United States includes Puerto Rico). For a list of ISO 3166-1 alpha-2 codes, see https://www.iso.org/obp/ui/#search/code/. For more information on ISO codes, see https://www.davros.org/misc/iso3166.html.
<data_file>
<locale name="en-US"/>
Locale Name (required)
Identifies the language in which the text on the poster art appears. The locale indicates the language and the optional region where the language is spoken.
Specifying the <locale> for poster art is required. If you do not specify the locale, you will see a warning message that the <locale> tag is required. At a date in the future, if you do not specify the locale, the delivery will fail.
If the poster art displays more than one language, for example, poster art for Canada that shows both English and French, supply a <locale> tag for each language.
See the annotation for <locale> on the source asset above for details on specifying a language.
<file_name>09736156444.jpg</file_name>
File Name (required)
The name of the poster image file included in this electronic delivery package. The name should be relative to the package (containing no path reference “C:\” or “/Macintosh HD/”) and must contain the file name extension (”.jpg” in this example).
Important: File names are case sensitive. A file name can contain only alphanumeric characters (A-Z, a-z, 0-9) and these symbols: underscore ("_"), dash (“-”), and period (“.”). The file name must not start with an underscore, dash, or period and cannot contain spaces, other punctuation or symbols.
<size>6591649</size>
File Size (required)
The size in bytes of the poster image file. Do not specify any commas nor period delimiters.
The MD5 checksum of the poster file. See the Checksums section for more information.
</data_file>
</asset>
<asset type="artwork_16:9">
16:9 Poster Art (Strongly recommended. Required for Storefront promotion.)
Describes the type of asset being delivered. You must specify type="artwork_16:9" to indicate that the asset is the poster image in 16:9 format.
Other artwork you can deliver include (see annotations below):
backdrop_tall
backdrop_wide
single_color_content_logo
full_color_content_logo
16:9 poster art requires <territory> and <locale> tags. Backdrop art requires <territory> but <locales> are not supported. Logo art requires <locales> but <territory> is not supported.
<territories>
<territory>WW</territory>
</territories>
Poster Image Territory (required for 16:9 poster image)
The territories in which the supplied artwork file can be displayed. At least one territory must be specified. Apple recommends including WW to ensure all territories will have a poster image. You can supply additional territories as needed for any territory-specific poster art that is to be delivered. This is a territory and not language-specific asset.
Must be a valid ISO 3166 alpha-2 country code or WW. Note that some countries in the ISO 3166 alpha-2 country list contain other countries (for example, United States includes Puerto Rico). For a list of ISO 3166-1 alpha-2 codes, see https://www.iso.org/obp/ui/#search/code/. For more information on ISO codes, see https://www.davros.org/misc/iso3166.html.
Content Logo Art Data File (required, can be updated)
The data file block describes the content logo art asset. In this example, the artwork being delivered is a full-color logo.
Content logo art must be:
PNG (.png)
4320 x 1300 pixels
In this block, the <locale>, <file_name>, <size>, and <checksum> tags are required. Specifying a <territory> is not supported.
</asset>
<asset type="backdrop_wide">
Backdrop Art Asset (Strongly recommended. Required for Storefront promotion.)
Describes the type of asset being delivered. For backdrop art, you can specify:
backdrop_tall
backdrop_wide
<territories>
<territory>WW</territory>
</territories>
Backdrop Art Territory (required for backdrop art)
The territories in which the supplied artwork file can be displayed. At least one territory must be specified. Apple recommends including WW to ensure all territories have backdrop art. You can supply additional territories as needed for any territory-specific backdrop art that is to be delivered. This is a territory and not language-specific asset.
Must be a valid ISO 3166 alpha-2 country code or WW. Note that some countries in the ISO 3166 alpha-2 country list contain other countries (for example, United States includes Puerto Rico). For a list of ISO 3166-1 alpha-2 codes, see https://www.iso.org/obp/ui/#search/code/. For more information on ISO codes, see https://www.davros.org/misc/iso3166.html.
The data file block describes the backdrop art asset. In this example, the artwork being delivered is wide backdrop.
Backdrop art must be:
PNG (.png)
1680 x 3636 pixels for tall or 4320 x 3240 pixels for wide
In this block, the <file_name>, <size>, and <checksum> tags are required. Specifying a <locale> is not supported.
</asset>
</assets>
Film Products Metadata Fields
<products>
Products (required; can be updated)
Begins the products block that references each product being delivered by territory.
For metadata updates, territory clearances can be added or modified.
<product>
Product (required)
For each territory in which the film is to be sold for Electronic sell-through (EST) or rented, Video on Demand (VOD), a product must be defined.
<territory>US</territory>
Territory (required)
The territory in which this video product is cleared for sale or VOD. Must be a valid ISO 3166 alpha-2 country code. Note that some countries in the ISO 3166 alpha-2 country list contain other countries/regions (for example, United States includes Puerto Rico).
Note: Using WW as a territory in the <product> block is not accepted. Because price tiers are different in each territory, we cannot accept WW pricing. You must send each territory that is cleared for sale in its own <product> block.
Specifies whether or not this video can be sold for EST sale in the product’s territory. Accepted values are true and false.
Note: If <cleared_for_sale> is true, the <sales_start_date> element is required.
Important: For a video to be available only for rent in the Apple TV app, this element must be set to false.
To remove content from the Store, set <cleared_for_sale> to false for the specified <territory>. Send the <product> block with the <cleared_for_sale> and <territory> tags only; you do not need to supply any other tags within the <product> block.
<cleared_for_hd_sale>true</cleared_for_hd_sale>
Cleared for HD Sale (optional)
Specifies whether or not the video is cleared for HD EST sale in the product’s territory. Accepted values are true and false. This defaults to true, however as a best practice we strongly recommend that you explicitly send this tag to indicate true or false.
Notes
If <cleared_for_hd_sale> is true, the <sales_start_date> element is required.
Sale of HD EST is dependent on contracts. If you are unsure if you have a contract in place for sale of HD EST, contact your Technical Representative.
<wholesale_price_tier>3</wholesale_price_tier>
Wholesale Price Tier (required for EST; otherwise optional)
The wholesale price tier for the film. Must be a wholesale price tier number as specified in the contract with Apple.
Indicates the date when pre-orders are available in the film’s product territories.
The pre-order ends (and fulfills) on the regular sales start date of the product. If included, the pre-order date must be before the sales start date.
If a pre-order sales start date is not specified for a given territory, the pre-order will not be available in that territory. This element implicitly enables pre-ordering on a per-territory/product basis.
Indicates the date when the release date should no longer be suppressed in the Apple TV app.
After this date, the product’s sales start date is displayed in the Apple TV app during the pre-order window.
If included, the suppression lift date may be before the sales start date or the same as the sales start date.
<sales_start_date>2011-03-12</sales_start_date>
Sales Start Date (required)
The date this film is available for EST sale to customers in the specified territory only. This is also known as the “street date” of the video. This field must be in YYYY-MM-DD format.
In this example, the start date of 2011-03-12 results with the film being available for sale at midnight March 12, 2011.
<sales_end_date></sales_end_date>
Sales End Date (optional)
This field should not be included in most cases. It is not used to indicate your contract end date; if your contract expires, your content will come down from the Store automatically, regardless of whether this field is set or not.
Use this field only if this content will be available for a limited window of time. If used, the date must be in YYYY-MM-DD format.
To remove an end date previously delivered, send the tag without a value (called an “empty” tag) using one of the following:
<sales_end_date></sales_end_date>
<sales_end_date/>
<cleared_for_vod>true</cleared_for_vod>
Cleared for Video on Demand Sale (required for VOD)
Specifies whether or not the video is cleared for VOD rental in the product’s territory. Accepted values are true and false.
Note: When <cleared_for_vod> is true, the <available_for_vod_date> element is required.
Important: If this element is not specified, or is set to false, this video will not be available for rent in the Apple TV app.
<vod_type>New Release</vod_type>
Video on Demand Type (required for VOD)
Specifies whether the film is a new release or a library title.
Accepted values are as follows:
New Release. A new release title is a feature-length film that appeared in theaters.
Library. A library title is a feature-length film that is not a new release.
Important: Provide this value as specified by your contract. This element is required if <cleared_for_vod> is true.
The release date of the first physical product (for example, VHS, Beta, laserdisc, and DVD) or as specified in your contract. This field must be in YYYY-MM-DD format.
Important: This element is required for new releases (<vod_type>New Release</vod_type>). Note that it may be required for other EST and VOD types depending on your contract.
<cleared_for_hd_vod>true</cleared_for_hd_vod>
Cleared For HD Video on Demand (optional; can be updated)
Specifies whether or not this video is cleared for VOD in HD in the product’s territory. Accepted values are true and false.
Note: When <cleared_for_hd_vod> is true, the <available_for_vod_date> element is required.
