Only annotations for items added or changed for multiple-language films are included. For complete annotations, see the Basic Film Metadata Annotated.
Note: All tags within the <cast> and <crew> blocks can be updated at any time. However, when making changes, you must redeliver the entire block that includes all cast members or crew members; not just the ones you are changing.
The primary language of the metadata; that is, under the <video> tag level as opposed to under a <locale> tag. 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.
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, dubbed French and Spanish alternate audio tracks are supplied, but the language the actors' lips are moving in is English, so en-US must be specified as the <original_spoken_locale>. The movements of the actors’ lips do not match the supplied alternate audio.
If a video asset contains Chinese audio, the locale values must not contain script information. For example, the locale for Mandarin audio must be cmn, not cmn-Hant or cmn-Hans; the locale for Cantonese audio must be yue, not yue-Hant.
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.
<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>
Identifies the language (and optional region where the language is spoken) for localizing the title and synopsis.
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.
<title>Forrest Gump, o Contador de Histórias (Legendado)</title>
Title (required, 1-255 bytes; may be updated)
The localized name of this film for the locale specified. The information sent with this tag can be updated unless Apple has reviewed and confirmed the quality of the metadata.
<synopsis>(Legendado) "A vida é como uma caixa de bombons. você nunca sabe o que vai encontrar." Forrest Gump é um triunfo cinematográfico que se tornou um fenômeno. Tom Hanks apresenta uma impressionante interpretação como Forrest, um homem comum cuja simplicidade e inocência vão influenciar uma geração. Vencedor de seis prêmios da Academia®, incluindo Melhor Filme, Melhor Diretor (Robert Zemeckis) e Melhor Ator (Tom Hanks).</synopsis>
Synopsis (required, 1-4000 bytes; may be updated)
The localized general summary of the film’s content and story line for the locale specified. 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 (for example, Japanese symbols), the number of allowed characters will be less than the byte limit, depending on the specific contents of the supplied string.
</locale>
</locales>
. . .
<regions>
Regions (optional)
Regional variation in theatrical release dates (as displayed in the Apple TV app, not affect actual date of sale) and copyright can be specified using this mechanism.
<region>
Region (required)
A region must be specified for each territory (country) that requires localized copyright or theatrical release date information.
<territory>BR</territory>
Territory (required)
The territory for the corresponding copyright c-line and theatrical release date provided for this film. Must be specified as an ISO 3166 alpha-2 country code. Note that some countries in the ISO 3166 alpha-2 country list contain other countries (for example, United States includes Puerto Rico).
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 2-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.
</region>
</regions>
<genres>
<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"/>
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 in the “Film Ratings, Advisories, and Genres” section for an explanation of Unrated and Not Rated). For countries/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 in 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.
<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.
<locales>
<locale name="pt-BR">
<display_name>Tom Hanks</display_name>
<description format="plain">Forrest Gump leva uma vida verdadeiramente encantado como ele viaja através de eventos-chave da segunda metade do século 20. Totalmente sem tentar. Por sua interpretação de Forrest Gump, Tom Hanks ganhou o Oscar de Melhor Ator, o Globo de Ouro de Melhor Ator em Filme Dramático, o prêmio BAFTA de Melhor Ator e muitos mais prêmios em todo o mundo. O filme titular e caráter são baseados no romance de Winston Groom - "Forrest Gump".</description>
Localized Display Name and Description (optional)
For each locale, use the <display_name> tag to provide the localized actor’s name presented as it would be displayed when casually referring to the actor’s real name.
Provide the localized description related to the actor in the context of the film and the character he or she plays.
</locale>
</locales>
<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.
<character>
Character (required)
For each character in the film, supply the character metadata within a <character> block.
<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 below). 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
<locales>
<locale name="pt-BR">
<character_name>Forrest Gump</character_name>
<character_note>Protagonista</character_note>
Localized Character Name and Character Note (optional)
For each locale, provide the localized character name and character note.
</locale>
</locales>
</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.
<locales>
<locale name="pt-BR">
<display_name>Robert Zemeckis</display_name>
</locale>
<locale name="fr-FR">
<display_name>Robert Zemeckis</display_name>
</locale>
<locale name="fr-CA">
<display_name>Robert Zemeckis</display_name>
</locale>
</locales>
Localized Crew Members (optional; 1-250 bytes; can be updated)
Provide the display name for each crew member for each locale. The <locale name> tag is required within the <locales> tag and identifies the language (and optional region where the language is spoken) for localizing the crew members.
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.
<display_name> (required, text, 1-250 bytes)
For each locale, provide the crew member’s name presented as it would be naturally displayed when casually referring to an actor’s real name. Note that if you are supplying localizations for crew member names, you need to supply the <display_name> tag within the <locale> blocks regardless of whether or not you use the <apple_id> tag.
See Language Codes for more details on languages and codes.
<roles>
<role>Director</role>
</roles>
Role (required; multiple allowed))
The role performed by this crew member. The role names must be in English in order to be imported, and are localized if needed when displayed.
The following roles are 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.
The role performed by this crew member (Dub Artist in this example).
This example shows the dub artist crew member. Use the locale attribute to specify the language of the voiceover, in this case, it is in Brazilian Portuguese. You must also specify the character being dubbed using the character_reference attribute and the value specified in the <reference_id> tag (under the <character> block for the cast member). Note that the locale and character_reference attributes can be used only for crew members with the Dub Artist role.
</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.
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.
<chapters>
<chapter>
Chapter (required)
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.
<titles>
<title locale="en-US">Forrest's Story Begins</title>
<title locale="fr-FR">L'Histoire de Forest Commence</title>
<title locale="fr-CA">L'Histoire de Forest Commence</title>
</titles>
Localized Chapter Titles (required; 1-255 bytes; can be updated)
Titles of the chapters, one for each locale. The locale attribute is required. The value used for locale is case-insensitive, even though the example shows the value in the format xx-XX, such as en-US.
Each chapter must have the same number of localized titles. If one chapter has three localized titles, all the chapters must have titles localized in the same three languages.
If you are providing only one title, you do not need to use the <titles></titles> tags.
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. In this example, English closed captions are included and because one of the products is for the US territory, the metadata must indicate the closed captions availability, which is required for U.S. deliveries.
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".
reason_code: Supplies the reason closed captions are not included. Note that the reason_code attribute is not allowed if available="true", and required when available="false". Accepted values are:
- "NEVER_IN_US": Use this reason code for movies that have never been broadcast in the United States. This reason code is allowed only when delivering SDH.
- "IN_US_NO_CAPTIONS": Use this reason code for movies that have been broadcast in the United States, but never with captions. This reason code is allowed only when delivering SDH.
- "NO_CC_SDH_FOREIGN_LANGUAGE_ENGLISH_SUBS": Movies that are not in English and have not been broadcast in the U.S. can have SDH or subtitles in place of closed captioning and should use reason code NO_CC_SDH_FOREIGN_LANGUAGE_ENGLISH_SUBS. (See Basic Film Metadata Example without Closed Captions for how to deliver the reason code.)
In this example, the movie is in English and does not have closed captions; SDH can be delivered in place of closed captions.
The values for reason_code are case-sensitive.
<assets>
<asset type="full">
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 from the Apple TV app.
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 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: If a video asset contains Chinese audio, the locale values must not contain script information. For example, the locale for Mandarin audio must be cmn, not cmn-Hant or cmn-Hans; the locale for Cantonese audio must be yue, not yue-Hant.
Specifies whether or not 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 “Nevada, 1957.” 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.
<territory_exclusions role="audio">
<territory>CA</territory>
</territory_exclusions>
</data_file>
Territory Exclusion on Video Source Audio (optional)
Indicates that the <original_spoken_locale> audio embedded in the source video should not be made available in a particular territory. In this example, the provider does not have the rights to distribute the English audio on the source in Canada. The <territory_exclusions> block within the <data_file> block for the source video includes Canada (CA) to prevent the embedded audio from being available in Canada.
Note: Territory exclusions using the role attribute can only be specified on the source video to exclude the embedded audio; the role attribute must be supplied, and its value must be "audio".
You can remove embedded audio exclusions at any time. To remove a territory, deliver the <territory_exclusions role="audio"> block with the appropriate <territory> removed. To remove all territory exclusions, deliver an empty tag: <territory_exclusions role="audio"/> within the <data_file> block of the source video.
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 and it 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.
Territory and language-specific audio can be supplied using the "locale" metadata structure. If used, the language must be included to specify the language; the region where the language is spoken is optional. One audio file can be provided for each desired language (and region). The <locale> tag is required for localized audio assets.
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.
Apple recommends that you supply a consistent language locale for assets delivered for a territory. For example, if you supply audio for en-US, use the same locale (en-US, as opposed to en or en-GB) for any additional assets, such as subtitles, forced narratives, and so on.
Note: If a video asset contains Chinese audio, the locale values must not contain script information. For example, the locale for Mandarin audio must be cmn, not cmn-Hant or cmn-Hans; the locale for Cantonese audio must be yue, not yue-Hant.
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.
One 7.1 surround audio file can be provided for each desired language (and region). The <locale> tag is required for localized audio assets.
See the annotation directly above for information on specifying the language.
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.
Apple recommends that you supply a consistent language locale for assets delivered for a territory. For example, if you supply audio for en-US, use the same locale (en-US, as opposed to en or en-GB) for any additional assets, such as subtitles, forced narratives, and so on.
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.
One Dolby Atmos audio file can be provided for each desired language (and region). The <locale> tag is required for localized audio assets.
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 on the Store for the film.
Apple recommends that you supply a consistent language locale for assets delivered for a territory. For example, if you supply audio for en-US, use the same locale (en-US, as opposed to en or en-GB) for any additional assets, such as subtitles, forced narratives, and so on.
Indicates that an asset should not be made available in a particular territory. In this example, the provider does not have the rights to distribute the Spanish alternate audio in France and Canada. The <territory_exclusions> block within the <data_file> block of the alternate audio file includes France (FR) and Canada (CA) to prevent the audio component from being available in France or Canada.
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.
This is a video-only sequence containing one or more still credits specific to the locale-matched audio files. Dub credit sequences will be included at the end of the main program video for movies that include the associated audio. The locale value for the dubbed audio assets and the dubbing cards must match. The <locale> tag is required for dub card video.
Apple recommends that you supply a consistent language locale for assets delivered for a territory. For example, if you supply audio for en-US, use the same locale (en-US, as opposed to en or en-GB) for any additional assets, such as subtitles, forced narratives, and so on.
In this example, two dub card videos are included to match the two audio files: Latin American Spanish and French.
Note: If the dub card video resolution does not match video source resolution, you must supply different crop dimension attributes for dub cards to match the aspect ratio of the feature. This XML example shows how to deliver crop dimensions for dub card video:
Subtitles are delivered as a role for the full asset. The files must be in the iTT file format with the extension .itt. See iTunes Timed Text Example for information on the iTT file format.
The <locale> identifies the language in which the subtitles appear. The locale indicates both the language and the optional location 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.
Apple recommends that you supply a consistent language locale for assets delivered for a territory. For example, if you supply audio for en-US, use the same locale (en-US, as opposed to en or en-GB) for any additional assets, such as subtitles, forced narratives, and so on.
Indicates that an asset should not be made available in a particular territory. In this example, the provider does not have the rights to distribute the Brazilian Portuguese subtitles in France (until a certain date) or Canada. The <territory_exclusions> block within the <data_file> block of the subtitles file includes France (FR) and Canada (CA) to prevent the subtitles component from being available in France and Canada.
For France, the territory exclusion ends October 12, 2015 and that date is conveyed using the <territory_exclusion end_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 2-digit day.
A data file element block must be included if the SDH are delivered for the associated video. The "subtitles.hearing_impaired" role specifies that the delivered file is intended to be used as the SDH file for the film. The file must be in the iTT file format with the extension .itt. See iTunes Timed Text Example for information on the iTT file format.
When delivering SDH, you must also deliver an accessibility information reason code as follows:
A movie that is in English that does not have closed captions can be delivered with SDH in place of closed captions. (See the annotation for <accessibility_info> above for how to deliver the reason code.) Supply one of the following reason codes:
- "NEVER_IN_US": Use this reason code for movies that have never been broadcast in the United States. This reason code is allowed only when delivering SDH.
- "IN_US_NO_CAPTIONS": Use this reason code for movies that have been broadcast in the United States, but never with captions. This reason code is allowed only when delivering SDH.
A movie that is not in English and has never been broadcast in the United States doesn’t need captions, but must have either English subtitles or SDH. (See Basic Film Metadata Example without Closed Captions for how to deliver the reason code.) Supply the following reason code:
- "NO_CC_SDH_FOREIGN_LANGUAGE_ENGLISH_SUBS"
Apple recommends that you supply a consistent language locale for assets delivered for a territory. For example, if you supply audio for en-US, use the same locale (en-US, as opposed to en or en-GB) for any additional assets, such as subtitles, forced narratives, and so on.
Important: File names are case sensitive and spaces are not allowed.
The <locale> identifies the language of the text in the SDH file delivered in this <data_file> block. For a list of supported languages, see Multiple Language Support in the Apple Transactional Movies User Guide.
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. 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/regions (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.
Describes the type of asset being delivered. You specify type="preview" to indicate that the asset is the preview file. The preview source data file contains the preview length video and audio streams.
The <locale name> is required and it identifies the language that is spoken in the audio on the source asset, regardless of the territories in which it is to be sold. It indicates the language and the optional region where the language is spoken. The value used for locale is case-insensitive, even though the example shows the value in the format xx-XX, such as en-US.
One preview file can be provided for each territory. For each territory, the preview can have an optional data file for alternate audio or subtitles. You can deliver only one alternative audio OR one subtitles file, but not both. A forced subtitles file does not count toward the limit of one alternative audio or one subtitles file.
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 below.
Localized Preview Asset Source with Text (optional)
The preview source data file in this example contains text on the source (burned-in forced narrative and burned-in subtitles), so additional attributes must be delivered.
<attribute name="image.textless_master">false</attribute>: Because the preview contains text, this attribute must be sent with a value of false.
<attribute name="image.burned_forced_narrative.locale">en-US</attribute>: Required because the source contains burned-in forced narrative.
<attribute name="image.burned_subtitles.locale">en-US</attribute>: Required because the source contains burned-in subtitles.
<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.
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/regions (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.
Metadata-Based Preview Clipping (optional, multiple territories allowed; can be updated)
Begins the previews block that delivers the parameters for cutting a preview from the full video source.
You define a film preview by clipping a continuous segment of a film's video and audio. These previews can be used for territories for which you have not created a custom preview. Use the following attributes to specify the territory for the preview, the timecode format, the start and end times of the clip, and the frame to use for the preview image:
territory: indicate the territory for the preview clipping defined in the <preview> tag
timecode_format: defines the timecodes used for the start and end times. 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.
start_time: specifies the start of the preview clipping from the source video for this territory.
end_time: specifies the end of the preview clipping from the source video for this territory. Minimum clip duration is 45 seconds and maximum duration is 300 seconds.
image_time (required): specifies the frame to use for the preview image. The frame must be within the start_time and end_time. If you specify an image_time but use the qt_text format, the frame nearest the image_time is used for the preview image: you cannot specify a frame for the preview image using qt_text.
Note: The frame cut with the image_time attribute 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.
Replacing or removing a defined preview:
If a new defined <preview> has the same territory as an existing custom preview, you must supply the replace_custom="true" attribute. For example: <preview territory="FR" timecode_format="24/999 1000/nonDrop" start_time="00:55:13" end_time="00:58:27" replace_custom="true"/>
If a new defined <preview> has the same territory as an existing custom preview, you must supply the replace_custom="true" attribute. For example: <preview territory="FR" timecode_format="24/999 1000/nonDrop" start_time="00:55:13.02" end_time="00:58:27.00" image_time="00:55:45.12" replace_custom="true"/>
If you submit a custom preview for a territory that already has a defined preview, you must supply the remove="true" attribute for that territory on the preview definition. If you are requesting to remove a defined preview, there should be an existing custom or worldwide preview for that territory. For example: <preview territory="GB" remove="true"/>
</previews>
<products>
<product>
Product (required; can be updated)
For each territory in which the film is to be sold for Electronic sell-through (EST) or rented, Video on Demand (VOD), there must be a defined product.
<territory>US</territory>
Product Territory (required)
The product territory specifies where the film is cleared for sale or VOD and 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 allowed. Because price tiers are different in each territory, we cannot accept WW pricing. You must send each territory in its own <product> block.
Specifies whether or not this film 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> tag is required.
Important: For a video to be available only for rent in the Apple TV app, this tag 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.
<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.
<sales_start_date>2006-03-12</sales_start_date>
Sales Start Date (optional)
The date this film is available for EST purchase 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.
Note: The <sales_start_date> is required if <cleared_for_sale> is true.
Important: Omitting this tag will make the film available for sale immediately.
<cleared_for_vod>false</cleared_for_vod>
Cleared for Video on Demand Sale (required for VOD; otherwise optional)
Specifies whether the video is cleared for VOD rental in the product’s territory. Accepted values are true and false.
Important: If this tag is not specified, or is set to false, this video is not available for rent in the Apple TV app.
</product>
. . .
</products>
<cue_sheet>
Cue Sheet (optional; can be updated)
Provides a list of music played in a film.
<cue>
Cue (required within the <cue_sheet> block)
Defines a single musical piece played in a film. There can be multiple cue tags in a cue sheet.
<sequence_number>1</sequence_number>
Sequence Number (required within the <cue> block)
The order number for the musical piece in the film. This value should be unique for each musical piece listed in the cue sheet.
<time>
Time (required within the <cue> block)
The <time> tag describes when musical pieces appear in the production and their duration.
<start_timecode>00:00:27</start_timecode>
Start Time-code (optional)
Specifies the start time of the musical piece in the production.
Important: The format of this field is HH:MM:SS (hours:minutes:seconds).
<duration>00:02:39</duration>
Duration(required within the <cue> block)
Specifies the length of time the individual musical piece featured within the production.
Important: The format of this field is HH:MM:SS (hours:minutes:seconds).
</time>
<title>I'm Forrest…Forrest Gump</title>
Title (required within the <cue> block)
The title of the musical piece.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for track titles. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
<artists>
<artist>
<artist_name>Alan Silvestri</artist_name>
<apple_id>611137</apple_id>
<roles>
<role>Composer</role>
<role>Producer</role>
</roles>
</artist>
...
</artists>
Artists (required within the <cue> block)
Name or Apple identifier and roles for each artist in the musical piece. In this context, "artist" may be any contributor including non-performing persons (for example, producer) or composition-related contributors (for example, songwriter/lyricist or composer). Individual artists should be listed separately and not grouped together (for example, "Ella Fitzgerald", "Louis Armstrong" should be used instead of "Ella Fitzgerald and Louis Armstrong"). Note that you should always include composition-related contributor information to the extent you have it.
Artist
You can refer to the artist by name (using the <artist_name> tag or by Apple identifier (using the <apple_id> tag). Apple assigns every artist a unique Apple identifier; Apple recommends using the Apple identifier to avoid the ambiguity in cases where artists share the same name as other music artists, or film actors or crew members. You can supply the <artist_name>, the <apple_id>, or both the <artist_name> and <apple_id>. If you supply both tags, the <artist_name> tag will be ignored in favor of the Apple identifier. If you do not know the artist's Apple identifier, you can do a metadata lookup on an existing film or album 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.
Role
The following roles are accepted (other artist roles may be ignored):
Composer
DJ
Featuring
Narrator
Performer
Producer
Remixer
Songwriter
with
Artists with the roles listed above have their own artist page. The role names must be in English in order to be imported into the Store, but the names will be localized if needed when displayed on the Store.
If an artist is a featured artist on the musical piece, add the artist and assign the role: Featuring. This ensures that the film will show up on the featured artist’s page.
<isrc>USSM19913841</isrc>
ISRC (optional)
The ISRC (international standard recording code) for the musical piece. ISRCs must be unique across all recordings. It is normal for an ISRC to appear on the Store more than once if the same recording is included in more than one production (for example, an album, music video, TV episode, or film). In this case, the musical piece must have exactly the same audio. A re-recorded, remixed or otherwise different (no matter how similar) musical piece must have a unique ISRC.
Important: ISRCs must not include dashes and should remain only letters and numbers as in the example, USSM19913841.
<iswc>T0702670221</iswc>
ISWC (optional)
The ISWC (international standard work code) for musical pieces. This uniquely identifies intellectual property such as musical and literary works.
<copyright_cline>1994 Sony Music Entertainment Inc.</copyright_cline>
<copyright_pline>1994 Sony Music Entertainment Inc.</copyright_pline>
Copyright P-Line (optional; can be updated)
Performance copyright line for the piece. The format required is year followed by owner. The appropriate ℗ symbol will automatically be added and should not be included in the data. Some videos don't seem to have this P-line in the slate. Remove this tag if this is the case.
<usage>Signature</usage>
Usage (optional)
Specifies how the musical piece was featured in the production using one of the following values:
Background: Music that is not audible to the characters in the production, such as “mood music.”
Featured: Music played by featured performers, or as part of the action presented and audible to the characters, such as the character dancing to a song.
