This document specifies the package format for delivering transactional film content to Apple.
A package is a directory that contains the data necessary to describe a product: video files, poster image, and the metadata describing how to put it all together. Each package represents a film product.
For questions regarding other kinds of content, such as television, books, music, or music video, contact your Technical Representative.
Date/Version | Changes Made |
|---|---|
April 2026 - Version 5.3.22 | Added information on ratings and advisories for Türkiye. Added the |
For a complete history of changes, see Previous Spec Revisions.
Film Advisories
Added ratings and advisories for Türkiye. See Türkiye.
Film Profile: Provider Review End Date
Added the optional <provider_review_end_date> tag to specify the date when a film is no longer available to be reviewed in Apple Partner Media Review. See Basic Film Metadata Annotated.
Correction/Clarifications
Made additional minor updates and clarifications.
Audio, video, and image files must be provided in very specific sizes and formats. For complete details and all requirements, see Apple Video and Audio Asset Guide.
Note: Quality is important to Apple. We expect to receive the highest-quality assets available. Our product must meet or exceed the quality of the physical product already out in the marketplace. For example, if 5.1 surround sound or closed captions exist on the physical version of the product, those must be provided. If the physical product gives the chapters actual names (as opposed to Chapter 1, Chapter 2, and so on), then our product should have those same chapter titles.
All delivered metadata and asset files must be delivered in the .itmsp package format.
An .itmsp package is a directory whose name ends in ".itmsp" containing:
an XML file named metadata.xml that describes the delivered content using the structure documented in this specification
digitally encoded source materials (audio, videos, closed captioning, notes, and so on)
associated image files
Send your content to Apple in the package format, with one directory per film. For example, for a film whose vendor identifier is 09736156444, the package would be comprised of a directory named 09736156444.itmsp, and might contain the following files:
metadata.xml (xml-formatted metadata specific to this film)
09736156444-source.mov (video asset file for this film)
09736156444-preview.mov (trailer asset file for this film)
09736156444.jpg (poster for this film)
chapter01.jpg (chapter image asset file for this film; for brevity only one chapter image file is shown here)
09736156444-source-notes.pdf (QC notes for this film)
09736156444-english.scc (EIA 608 format closed caption file for this film)
The name for the package directory must match the <vendor_id> provided in the accompanying metadata file and should follow the format vendor_id.itmsp. The names of the files within the package can have any name, as long as the names correctly match the filenames provided in the accompanying XML. The metadata XML file must be immediately (at the top level) within the package directory. Vendor identifiers can only contain alphanumeric characters, must be at least six ASCII characters in length, and can contain underscores (“_”). Packages delivered with vendor identifiers that do not begin with an alphanumeric character, or that contain other characters will be rejected.
A schema is used to validate the XML document you send in an .itmsp package. The version of the schema consists of two numbers: a major number for the schema and a minor number to track changes to the that version of the schema. The schema version number is expressed as major.minor, for example 5.3. The revisions of the specifications are based on the schema version. Each time a specification is released for a specific schema version, the release is tracked using an additional number. The specification version number is expressed as major.minor.revision, for example 5.3.1. When specifying the version attribute in the <package> tag, match the schema version, not the specification revision. For example, if the specification has been revised, the spec version becomes 5.3.1, but the schema version remains 5.3 (so the attribute value is 5.3, not 5.3.1):
<package xmlns="http://apple.com/itunes/importer" version="film5.3">
Note that this information is for clarification purposes; the numbering schemes have not changed and do not affect the delivery process as long as you follow the numbering rules.
All metadata files must use UTF-8 Unicode character encoding. UTF-8 efficiently encodes non-Roman characters and helps to ensure that metadata displayed in the store is the same as was intended by the repertoire owner.
Note that simply including encoding="UTF-8" in your XML declaration is not sufficient. The file itself must also be correctly encoded for accented characters and punctuation to appear correctly.
This specification defines character lengths in bytes. Japanese language characters are represented in 3 bytes so be sure not to exceed the character lengths when including these characters.
Your metadata file should not contain a byte-order mark (BOM) as it is not necessary for UTF-8 encoded data files nor is it supported by Apple at this time. Incorrectly encoded metadata files or files that include a BOM will cause delays or may prevent your content from importing.
All content files delivered to Apple must include an industry-standard MD5 checksum, a measure that helps to guarantee that the asset files received by Apple are correct and complete. Once received, the MD5 checksum contained in the metadata file (one for each asset file provided) is compared against the actual file received by Apple. If any differences are detected, the asset file and the entire corresponding package are rejected. See the Helpful Tools section of this document for tools that can generate MD5 checksums for your content.
There should be no null data or empty tags in the XML except as noted in the annotated examples, for example, removing end dates using the <sales_end_date> and <unavailable_for_vod_date> tags. The XML must be formatted to use line breaks and indentations as demonstrated in the examples included in this document. xmllint is a Unix command line tool that may be helpful to ensure that the provided XML is correctly formatted. Read the Schema Validation Guide for more information.
Apple requires ratings for film content, including concert films. If a film has been rated by a film review board, use that rating, otherwise use Unrated or Not Rated (see the table below). For countries/regions that do not have an Unrated or Not Rated classification, you must choose another rating. For film content sold in the United States, the Motion Picture Association of America (MPAA) supported Classification and Rating Administration (CARA) Rating system is used.
Apple has expanded worldwide, and as a result, film ratings have been added for the many countries and regions. Because of the increased number of countries and regions, the ratings are available in a separate Film Ratings document. This file includes all the ratings that are accepted.
Note: Content delivered with restricted ratings (such as 17-NC and Unrated) does not go live in the Apple TV app.
For ratings and advisory requirements for specific countries, see:
To differentiate one rating system from another, a system context must be specified in the system attribute of the rating element in the XML.
The ratings board may provide a reason for rating content; that explanation may also be provided and presented to customers. A rating reason can only be supplied in the exact form given by the rating board; providers cannot write their own rating reason.
The following is an excerpt from a metadata.xml file showing a PG-13 rating with the MPAA reason for the United States:
<rating system="mpaa" reason="for drug content, some sensuality and war violence" code="PG-13">PG-13</rating>
Be aware of the distinction between Unrated and Not Rated; these two ratings have nearly opposite effects.
Rating | Significance |
|---|---|
Unrated |
|
Not Rated |
|
Important: Made-for-television movies may specify Television Parental Guidelines ratings. For more information, contact your Technical Representative.
Note that ratings should not be displayed on the poster image.
For information about specifying film genres, see:
All film genres have an Apple genre code. An attribute named code must be used with the <genre> tag to supply the Apple genre code. Standardizing on the Apple genre codes reduces errors resulting from typos. If you have a typo when using the code, the package submission fails. You can correct the code and re-deliver.
The code attribute is required.
Note: You must provide the genre code exactly as displayed in the Apple Genre Code column below. The AMG IDs are given in case they are useful when identifying or mapping to the appropriate genre. AMG Genre IDs are not accepted as genre codes.
Genre | Apple Genre Code | AMG ID |
|---|---|---|
Action & Adventure | ACTION-ADVENTURE-00 | genres 646 and 647 |
African | AFRICAN-00 | |
Anime | ANIME-00 | |
Bollywood | BOLLYWOOD-00 | |
Classics | CLASSICS-00 | |
Comedy | COMEDY-00 | genre 648 |
Concert Films | CONCERT-FILMS-00 | |
Documentary | DOCUMENTARY-00 | category 239 |
Drama | DRAMA-00 | genre 649 |
Foreign | FOREIGN-00 | |
Holiday | HOLIDAY-00 | |
Horror | HORROR-00 | genre 654 |
Independent | INDEPENDENT-00 | |
Kids & Family | KIDS-FAMILY-00 | genre 660 |
Made for TV | MADE-FOR-TV-00 | |
Middle Eastern | MIDDLE-EASTERN-00 | |
Music Documentaries | MUSIC-DOCUMENTARIES-00 | |
Music Feature Film | MUSIC-FEATURE-FILMS-00 | |
Musicals | MUSICALS-00 | |
Regional Indian | REGIONAL-INDIAN-00 | |
Romance | ROMANCE-00 | genre 948 |
Russian | RUSSIAN-00 | |
Sci-Fi & Fantasy | SCIFI-FANTASY-00 | genres 652 and 650 |
Short Films | SHORT-FILMS-00 | production style 2239 |
Special Interest | SPECIAL-INTEREST-00 | genres 1063, 1047, 1085 and category 1982 |
Sports | SPORTS-00 | genre 1101 |
Thriller | THRILLER-00 | genre 942 |
Turkish | TURKISH-00 | |
Urban | URBAN-00 | |
Western | WESTERN-00 | genre 656 |
The following genres are accepted only for customers in Japan.
Genre | Apple Genre Code |
|---|---|
Japanese Cinema | JAPANESE-CINEMA-00 |
Jidaigeki | JIDAIGEKI-00 |
Tokusatsu | TOKUSATSU-00 |
Korean Cinema | KOREAN-CINEMA-00 |
TV and films delivered for distribution in Brazil need a local rating. To obtain a rating, do one of the following:
Submit the film to the National Secretariat of Justice of the Brazilian Ministry of Justice (“NSJ”) for an official review and rating classification.
If the film has never received an official rating for distribution in Brazil or if the film is not subject to an official rating, you can designate the appropriate rating yourself using the guidance issued by the NSJ.
See the Practical Guide for full guidance.
The official website is at https://www.gov.br/mj/pt-br and the following email address can be used for contact: classificacaoindicativa@mj.gov.br
The NSJ also issues content descriptors that act as consumer advice and are specific to each film. For self-rated content, if a provider chooses to designate descriptors, they should be selected in line with the same guidance.
Submit the consumer advice to Apple using iTunes Connect or XML. Deliver the initials only, not the full advice.
Example: If a film is rated “12” and has been given the content descriptors "Drogas Lícitas” and "Violência" in Brazil:
In iTunes Connect, select the rating 12 and choose the advisory codes from the Content Advisories menu.
In XML, deliver the rating and advisories with the <rating> and <advisory> tags:
<ratings> <rating system="br-movies" code="12"/> <advisory system="br-movies" code="DL"/> <advisory system="br-movies" code="V"/> </ratings>Advisory Code | Brazilian Advisory (br) | English Advisory (en) | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
AC | Atos Criminosos | Criminal Acts | |||||||||
CS | Conteúdo Sexual | Sexual Content | |||||||||
D | Drogas | Drugs | |||||||||
DI | Drogas Ilícitas | Illegal Drugs | |||||||||
DL | Drogas Lícitas | Legal Drugs | |||||||||
L | Linguagem Imprópria | Inappropriate Language | |||||||||
M | Medo | Fear | |||||||||
N | Nudez | Nudity | |||||||||
PM | Procedimentos Médicos | Medical Procedures | |||||||||
SE | Sexo Explícito | Explicit Sex | |||||||||
TS | Temas Sensíveis | Sensitive Themes | |||||||||
V | Violência | Violence | |||||||||
VE | Violência Extrema | Extreme Violence | |||||||||
VF | Violência Fantasiosa | Fantasy Violence | |||||||||
Note: The English translations above are for guidance only, and are not required to be delivered.
India has consumer advice labels that are specific to each film. Where consumer advice has been issued, it must be displayed in the Apple TV app. The consumer advice labels are issued in the form of initials as follows:
AC — Alcohol Consumption | L — Language | PS — Photo or Pattern Sensitivity |
B — Imitable Behavior | MH — Mild Horror | R — Religiously Sensitive |
C — Criminal Activity | ML — Mild Language | SC — Sexual Content |
D — Drugs or Drug Use | MSD — Mild Suggestive Dialogue | SD — Suggestive Dialogue |
FV — Fantasy Violence | MT — Mild Themes | SV — Sexual Violence |
G — Gambling | MV — Mild Violence | T — Smoking or Tobacco Use |
GV — Graphic Violence | N — Nudity | V — Violence |
H — Horror | P — Prejudice |
Notes
Delivering an advisory is not required for films with a U rating; Apple will always display the advisory "Content Suitable for All Ages” for U-rated films.
The remaining ratings (U/A 7+, U/A 13+, U/A 16+, and A) require at least one advisory.
Submit the consumer advice to Apple using iTunes Connect or XML. Deliver the initials only, not the full advice.
Example: If a film is rated “U/A 16+ AC B T”:
In iTunes Connect, select the rating 16+ and choose the advisory codes from the Content Advisories menu.
In XML, deliver the reason with the <rating> tag and the advisories in <advisory> tags:
<ratings> <rating system="in-movies" reason="for alcohol consumption, imitable behavior, and smoking or tobacco use" code=“UA16+“/> <advisory system="in-movies" code="AC"/> <advisory system="in-movies" code="B"/> <advisory system="in-movies" code="T"/> </ratings>For films to be sold on the Store in Korea, both a rating and rating classification number are required. Advisories are required if issued by the Korea Media Rating Board (KMRB). A rating specifies the appropriate ages suitable for viewing the film. The advisory specifies any consumer advice about the film’s content.
For iTunes Extras, all videos must be rated. They must contain a burnt-in pre-roll that displays the rating. If your iTunes Extras are not appropriately rated, do not make them available in Korea.
Specify rating codes to indicate the ages for which the content is suitable and understandable. Consumers see the ratings associated with the film while browsing the Store. The rating system is specified using the system attribute of the <rating> tag in the XML. For Korea, the system attribute is "kr-movies".
Below is an example of delivering a rating:
<rating code="12" system="kr-movies" classification_number="2020-MF02500">12세 이상 관람가</rating>
You can deliver only one rating value for each rating system.
Note: The rating code 18 is deprecated.
Beginning May 1, 2024, partners can deliver content with the rating 19.
Content that was rated before May 1, 2024 can use the rating of 18.
Content that is rated on or after May 1, 2024 should use the rating 19 rather than 18.
Ratings code | Display value | Definition |
|---|---|---|
ALL | 전체관람가 | All ages 모든 연령에 해당하는 사람이 관람할 수 있는 영상물로, 등급분류 기준이 되는 7가지 고려요소가 없거나 매우 약하게 표현된 작품입니다. |
12 | 12세 이상 관람가 | 12 years or older 만 12세 이상의 사람이 관람할 수 있는 영상물로, 등급분류 기준이 되는 7가지 고려요소가 경미하고 간결하게 표현된 경우입니다. |
15 | 15세 이상 관람가 | 15 years or older 만 15세 이상의 사람이 관람할 수 있는 영상물로, 등급분류 기준이 되는 7가지 고려요소가 지속적이고 구체적으로 표현되지 않은 작품입니다. |
18 (deprecated) | 청소년 관람불가 | May not be viewed by youth under 18 years 고등학교에 재학중인 자를 포함하여 만 18세 미만의 자는 관람할 수 없는 영상물로, 등급분류 기준이 되는 7가지 고려요소가 구체적, 직접적,노골적으로 표현된 작품입니다. |
19 | 청소년 관람불가 | May not be viewed by youth under 19 years 고등학교에 재학중인 자를 포함하여 만 19세 미만의 자는 관람할 수 없는 영상물로, 등급분류 기준이 되는 7가지 고려요소가 구체적, 직접적,노골적으로 표현된 작품입니다. |
You can specify advisory codes to indicate violence, language, nudity, and other content. Consumers will see the advisory associated with the video while browsing the Store. The advisory system is specified using the system attribute of the <advisory> tag in the XML. For Korea, the system attribute is "kr-movies". You can supply one or more advisory codes as needed from the table below.
The table below lists the currently supported advisory codes. Note that these codes are valid only for the Korean system (system="kr-movies").
Advisory code | Advisory name | Use for content that contains |
|---|---|---|
T | 주제 Theme | Adult themes or medical procedures |
S | 선정성 Sex and nudity | Sex scenes and/or sexual references Nudity |
V | 폭력성 Violence | Violent themes |
L | 대사 Language | Coarse or crude language |
H | 공포 Horror | Horror or supernatural themes |
D | 약물 Drugs | Drug references and/or drug use |
B | 모방위험 Imitable Behavior | Dangerous behavior (such as suicide) |
In addition to advisory codes, you can supply an optional severity level for each advisory. The severity level will be displayed during the ratings pre-roll along with the content advisory.
The table below lists the currently supported severity level codes. Note that the severity levels are valid only for the Korean system (system="kr-movies").
Severity level code | Severity name |
|---|---|
low | 낮음 Low |
medium | 보통 Medium |
medium_high | 다소 높음 Medium high |
high | 높음 High |
very_high | 매우 높음 Very high |
Films delivered for distribution in New Zealand need an age-rating classification from the Film and Video Labeling Body (FVLB). The FVLB’s website is https://www.fvlb.org.nz. Note: The consumer advisories must specifically cover online distribution. A label issued for DVD distribution only is not sufficient. For the FVLB to issue a label for a film, the film must be reviewed and classified by the New Zealand Office of Film and Literature Classification, or have been given an unrestricted classification in Australia or the UK. For more information on the classification and labeling process, contact the FVLB at enquiries@fvlb.org.nz
In addition to the age-rating classification, the FVLB issues consumer advisories specific to each film. It is a legal requirement that the consumer advisories are displayed in the Apple TV app.
Submit the advisories to Apple using iTunes Connect or XML.
Example: If a film is issued with the following label by the FVLB: R16 Offensive language, sexual themes, and content that may disturb:
In iTunes Connect, select the rating R16. For the Advisory field, select the following: L Offensive Language (L), ST Sexual Themes (ST), and DIS Content that may disturb (DIS).
In XML, deliver the rating and advisories with the <rating> and <advisory> tags:
<ratings> <rating system="nz-oflc" code="R16"/> <advisory system="nz-oflc" code="L"/> <advisory system="nz-oflc" code="ST"/> <advisory system="nz-oflc" code="DIS"/> </ratings>The following list shows the consumer advisories and codes used in the ratings system "nz-oflc". Select all relevant advisories from this list.
Note: If a film’s advisories are represented by the items in this list, then the reason attribute on the <rating> tag is optional. For information not shown in this list, use the reason attribute to provide the information in a comma-separated values format.
Example: If a film is issued with the following label by the FVLB: R13 Deals with euthanasia. Contains offensive language & violence:
In iTunes Connect, select the rating R13. For the Rating Reason field, insert “Deals with euthanasia.” For the Advisory field, select the following: L Offensive Language (L) and V Violence (V).
In XML, deliver the rating and advisories with the <rating> and <advisory> tags:
<ratings> <rating system="nz-oflc" reason="Deals with euthanasia" code="R13"/> <advisory system="nz-oflc" code="L"/> <advisory system="nz-oflc" code="V"/> </ratings>AC — Animal cruelty | DV — Domestic violence | SI — Sexualised imagery |
AT — Adult themes | GV — Graphic violence | SNT — Supernatural themes |
BU — Bullying | H — Horror | SR — Sexual references |
BV — Bloody violence | L — Offensive language | SS — Scary scenes |
C — Cruelty | MS — Mass shooting | ST — Sexual themes |
CL — Coarse language | N — Nudity | SU — Suicide |
D — Drug references | PPS — Photo pattern sensitivity | SUT — Suicide themes |
DB — Dangerous behaviour | R — Rape | SV — Sexual Violence |
DI — Discrimination | S — Explicit sex scenes | SVT — Sexual violence themes |
DIS — Content that may disturb | SC — Sex scenes | V — Violence |
DU — Drug use | SH — Self-harm | WD — Wound detail |
New Zealand - “Not Rated”: To both ensure compliance with legal requirements in New Zealand, as well as to provide optimal guidance for Apple customers, the existing Not Rated option is no longer supported for New Zealand. All titles, including all documentaries and educational or other content, must be classified by the FVLB and rated accordingly.
Films delivered for distribution in South Africa need to be submitted to the Film and Publication Board (“FPB”) for an official review and rating. The FPB's website is at https://fpb.org.za and they can be contacted at the following email address: clientsupport@fpb.org.za
In addition to ratings, the FPB also issues consumer advice labels that are specific to each film. Where consumer advice has been issued, it must be displayed in the Apple TV app. The consumer advice labels are issued in the form of initials.
Submit the consumer advice to Apple using iTunes Connect or XML. Deliver the initials only, not the full advice.
Example: If a film is rated “16 L N P S V SV” by the FPB:
In iTunes Connect, select the rating 16 and choose the advisory codes from the Content Advisories menu.
In XML, deliver the rating and advisories with the <rating> and <advisory> tags:
<ratings> <rating system="za-movies" code="16"/> <advisory system="za-movies" code="L"/> <advisory system="za-movies" code="N"/> <advisory system="za-movies" code="P"/> <advisory system="za-movies" code="S"/> <advisory system="za-movies" code="V"/> <advisory system="za-movies" code="SV"/> </ratings>CT — Criminal Techniques | L — Language | S — Sexually Related Activity |
D — Substance Abuse | N — Nudity | SV — Sexual Violence |
H — Horror | P — Prejudice | V — Violence |
IAT — Imitative Acts and Techniques | PPS — Photo Pattern Sensitivity |
Türkiye has legal requirements for content age ratings and advisory pictograms for streaming services. These requirements mandate the display of specific advisory icons and text in standardized locations.
Advisory Code | English Advisory (en) | Türkiye Advisory (tr) | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
BB | Bad Behaviors | Olumsuz Örnek Oluşturabilecek Davranışlar | |||||||||
VF | Violence / Fear | Şiddet / Korku | |||||||||
X | Sexuality | Cinsellik | |||||||||
Notes
Ratings: G, 7+, 13+, and 18+
Advisories are encouraged but not required.
Submit the consumer advice to Apple using iTunes Connect or XML. Deliver the initials only, not the full advice.
Example: If a film is rated “18+ BB VF X”:
In iTunes Connect, select the rating 18+ and choose the advisory codes from the Content Advisories menu.
In XML, deliver the reason with the <rating> tag and the advisories in <advisory> tags:
<ratings> <rating system="tr-movies" reason="for bad behaviors, violence, and sexuality" code=“18+“/> <advisory system="tr-movies" code="BB"/> <advisory system="tr-movies" code="VF"/> <advisory system="tr-movies" code="X"/> </ratings>The ministry responsible for ratings in Vietnam requires that the following ratings and advisories be applied to movie titles available in the Apple TV app. You can download the rating systems and values from Film Ratings.
When provided by the ministry, include a valid advisory in your delivery.
Submit the advisories to Apple using iTunes Connect or XML.
Example: If a film is rated "T16" by the film ministry with a "Dangerous and easily imitable behaviors" advisory:
In iTunes Connect, select the rating T16 and choose the advisory codes from the Content Advisories menu.
In XML, deliver the rating and advisories with the <rating> and <advisory> tags:
<ratings> <rating system="vn-movies" code="T16"/> <advisory system="vn-movies" code="DB"/> </ratings>Advisory Code | Vietnamese Advisory (vi) | English Advisory (en) | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
DB | Hành vi nguy hiểm, dễ bắt chước | Dangerous and easily imitable behaviors | |||||||||
DR | Ma túy, chất kích thích, chất gây nghiện | Drugs, stimulants and addictive substances | |||||||||
HO | Kinh dị | Horror | |||||||||
NS | Khỏa thân, tình dục | Nudity and sex | |||||||||
TH | Chủ đề, nội dung | Theme and content | |||||||||
VI | Bạo lực | Violence | |||||||||
VL | Ngôn ngữ thô tục | Vulgar language | |||||||||
If a film is going to be made available for sale, it must be delivered with chaptering information. The information is comprised of metadata (chapter start time and title) and images. Chapter times must be chronologically ordered. If using qt_text as the timecode format, the first chapter stop must be at 00:00:00.000. If using a frame-accurate timecode format, the first chapter stop must be at 00:00:00:00. The last chapter stop must be before the end of the film. Apple recommends that the chapters provided match what is on the DVD. In addition, include a chapter for film credits as the last chapter.
For chapter images, you can either specify timecodes for specific frames to use for the chapter images or provide artwork files. If you provide artwork, deliver the chapter images with the same aspect ratio as the source, with matting removed, and a minimum width of 640 pixels. Chapter artwork images must be cropped (no letterbox, pillarbox, or windowbox). Each chapter filename must be unique.
If you create a new chapter, you must provide an artwork image. If you update a chapter and originally specified a timecode for the chapter image, continue to specify the timecode. If you update a chapter and originally provided an artwork file for the chapter image, you do not need to specify or provide the file (unless you change the artwork image).
Film content requires one full feature-length video asset and one preview video asset that contains the trailer. Each asset is comprised of a set of data files. The data files play specific roles for their asset. For example, the full asset must contain a data file which has a role called “source.”
Important: You must run the PSE (photosensitive epilepsy) test on your content prior to delivery.
The table below outlines the two expected assets, along with the required and expected data files. For more information on asset requirements, see Apple Video and Audio Asset Guide. Required asset and data files are marked with an asterisk (*).
Asset |
|---|
Type: full* The full asset contains the feature length video product. Only one of these can be specified. |
Data File | Description | |
|---|---|---|
Role: source | The full source data file contains the full length SDR video stream and optional audio stream. Only one of these can be specified. See Apple Video and Audio Asset Guide for complete details. | |
Role: source.hdr | With corresponding SDR: The full HDR source data file must be the same duration as the primary source video so that components such as subtitles and audio can be used with the corresponding HDR video. If you deliver embedded audio with the HDR source, you can use it as the primary audio instead of the embedded SDR audio (SDR locale and HDR locale must match). See HDR Delivery for complete details. Dolby Vision HDR: The full HDR source data file without a corresponding SDR video delivery. You can specify a tag to down-convert to SDR. See Dolby® Vision-Only (No SDR) Delivery with Embedded Audio for details. Only one HDR source data file can be specified. | |
Role: mapping.hdr | The accompanying mapping metadata XML file for Dolby® Vision. For initial delivery, both the source video file and the mapping file must be included or delivery will fail. See Metadata Annotations for HDR Dolby® Vision or for complete details. Only one mapping data file can be specified. | |
Role: stereo_video.left | When delivering SDR stereoscopic video, this data file is the left eye source video. See Stereoscopic Video Overview. | |
Role: stereo_video.right | When delivering SDR stereoscopic video, this data file is the right eye source video. See Stereoscopic Video Overview. | |
Role: stereo_video.hdr.left | When delivering HDR stereoscopic video, this data file is the left eye source video. See Stereoscopic Video Overview. | |
Role: stereo_video.hdr.right | When delivering HDR stereoscopic video, this data file is the right eye source video. See Stereoscopic Video Overview. | |
Role: stereo_video.hdr.mapping | When delivering stereoscopic video, this data file specifies the custom 3D HDR mapping file for 3D Dolby Vision Profile 20 content. See Stereoscopic Video Overview. | |
Role: stereo_video.parallax | When delivering stereoscopic video, this data file specifies parallax metadata to guide the placement of subtitles, SDH subtitles, closed captions, or other user interface elements. See Stereoscopic Video Overview. | |
Role: audio An optional data file for an alternative audio track | As primary audio: Supply audio to use in place of audio embedded with the source video. If supplying audio to use with the source, the audio must include both stereo and 5.1. See Basic Example SDR Delivery with Embedded Audio and an Alternate Audio File to see how to deliver a separate primary audio file. As additional languages: Supply additional audio languages to add to the film. Multiple audio files are accepted, one per locale. See Multiple-Language Film Metadata Example to see how to deliver alternate audio. The audio files must be in the QuickTime format and tagged as required by Apple Video and Audio Asset Guide. | |
Role: audio.7_1 An optional data file for Dolby Digital Plus audio track | Use this role to deliver 7.1 surround audio file(s) for the film. Multiple 7.1 surround audio files are accepted, one per locale. To learn how to deliver multiple audio files, see Multiple-Language Film Metadata Example. The audio files must be in the QuickTime format and tagged as required by Apple Video and Audio Asset Guide. | |
Role: audio.object_based An optional data file for Dolby Atmos audio track | Use this role to deliver Dolby Atmos audio source for the film. If you deliver a Dolby Atmos audio file, you can specify that you want Apple to downmix to other formats. This allows you to deliver a single Atmos audio file and derive all of the other formats (7.1, 5.1, and stereo). Multiple Dolby Atmos audio files are accepted, one per locale. To learn how to deliver multiple audio files, see Multiple-Language Film Metadata Example. The audio files must meet the requirements listed in Dolby Atmos Audio Source Profile. | |
Role: video.end.dub_credits An optional data file containing the credits associated with an audio track. | A video-only sequence containing one or more still credits specific to the locale-matched audio. 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 asset and the dubbing cards must match, with the exception of Chinese language dub cards, which use the script subtag. See Multiple-Language Film Metadata Example to see how to deliver dub card video. Refer to Apple Video and Audio Asset Guide for file requirements. | |
Role: captions An optional single caption file. | Closed captioning for the full asset. | |
Role: audio.visually_impaired | This data file is optional and contains an alternate audio track for Audio Description (AD). The audio provides a description of visual elements that are important in understanding what is occurring at the time, as well as the plot. Indicating a Example: Note that the | |
Role: subtitles | This data file contains the full set of timed subtitles. Indicating a Example: | |
Role: subtitles.hearing_impaired | This data file is optional and contains SDH (Subtitles for the Deaf and Hard-of-hearing) that provide textual versions of the dialogue, as well as sound effects, and song lyrics. Indicating a Example: | |
Role: forced_subtitles | This data file contains the set of subtitles that must be forced-displayed when the matching dubbed audio locale is played by a viewer. The forced-subtitles must be a subset of the full set of subtitles. Forced subtitles are tied to audio and automatically display in a player if that audio is selected for playback. Therefore, the locale value of any delivered forced subtitle file must be the same as its corresponding audio. For example, if the film’s audio is German, the German forced subtitle file must have a locale value of Indicating a Example: | |
Role: production_still_image | This data file contains the production still image as a custom file. Note that Apple prefers that you send the production still image cut from the full asset using the Example: | |
Role: card | The card data file is an image with the following requirements: JPG extension ( Apple will create a video using the image for playback on the Store. Currently, this data file is used for films for sale inside India to deliver the required authority (CBFC) Certificate. | |
Role: notes One or more optional data files to provide notes | The notes data file contains information about any known issues or characteristics of the full video. The data file must be in PDF format. Multiple files can be sent in the package. (If the QC notes contain less than 4,000 characters (approximately 2 double-spaced pages), you can deliver the notes with the |
Asset |
|---|
Type: preview* The preview asset contains the movie trailer or pre-sale merchandising asset. The preview can be a custom asset file, or it can be a defined preview clipped from the source video and specified in the metadata using the |
Data File | Description | |
|---|---|---|
Role: source* | The preview source data file contains the preview length video and audio streams. Multiple trailers are accepted, one per territory. | |
Role: source.hdr | With corresponding SDR: The preview HDR source data file must have the same start and duration as the primary preview source video so that components such as subtitles and audio can be used with the secondary preview video. If you deliver embedded audio with the HDR source, you can use it as the primary audio instead of the embedded SDR audio. See HDR Delivery for complete details. Dolby Vision HDR: The preview HDR source data file without a corresponding SDR video delivery. You can specify a tag to down-convert to SDR. See Dolby® Vision-Only (No SDR) Delivery with Embedded Audio for details. Only one HDR source data files can be specified. | |
Role: mapping.hdr | The accompanying mapping metadata XML file for Dolby® Vision. For initial delivery, both the source video file and the mapping file must be included or delivery will fail. See Metadata Annotations for HDR Dolby® Vision or for complete details. Only one mapping data file can be specified. | |
Role: audio Role: audio.7_1 An optional data file for an alternative audio track | As primary audio: Supply audio to use in place of audio embedded with the preview source video. If supplying audio to use with the source, the audio must include both stereo and 5.1. See Basic Example SDR Delivery with Embedded Audio and an Alternate Audio File to see how to deliver a separate primary audio file. As additional language: Deliver a data file to supply an alternate audio file The audio files must be in the QuickTime format and tagged as required by Apple Video and Audio Asset Guide. | |
Role: audio.object_based An optional data file for Dolby Atmos audio track | Use this role to deliver Dolby Atmos audio source for the preview. If you deliver a Dolby Atmos audio file, you can specify that you want Apple to downmix to other formats. This allows you to deliver a single Atmos audio file and derive all of the other formats (7.1, 5.1, and stereo). Multiple Dolby Atmos audio files are accepted, one per locale. To learn how to deliver multiple audio files, see Multiple-Language Film Metadata Example. The audio files must meet the requirements listed in Dolby Atmos Audio Source Profile. | |
Role: subtitles | For a component preview, you can deliver a data file with timed subtitles. Indicating a Example: Note: A preview can have either a subtitles data file or an audio data file, but not both (forced subtitles do not count toward the subtitle file limit). | |
Role: notes One or more optional data files to provide notes | The notes data file contains information about any known issues or characteristics of the preview video. The data file must be in PDF format. Multiple files can be sent in the package. (If the QC notes contain less than 4,000 characters (approximately 2 double-spaced pages), you can deliver the notes with the |
The optional 7.1 surround audio is delivered as a role for the full asset using role="audio.7_1". One 7.1 surround audio file can be provided for each desired language (and region). Use the required <locale> tag to indicate the language (and optional region) of the audio. In addition, you can indicate how to handle existing 5.1 surround audio using the "audio.surround.force_5_1_downmix" attribute. See the partial XML example below and see Multiple-Language Film Metadata Example for a complete example of how to provide 7.1 surround audio in the metadata.
<data_file role="audio.7_1"> <locale name="fr-FR"/> <file_name>09736156444-71-audio_FR.mov</file_name> <checksum type="md5">a765a9fc88ac893ead51366fbeb04d82</checksum> <size>8730177839</size> <attribute name="audio.surround.force_5_1_downmix">true</attribute></data_file>Initial Delivery
Keep the following in mind when delivering 7.1 surround audio the first time:
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.
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.
Update Delivery
If you are sending an update to a film, you can indicate how to handle existing 5.1 surround audio using the new "audio.surround.force_5_1_downmix" attribute:
To replace the existing 5.1 surround audio with a downmix from the 7.1 surround audio, send the 7.1 surround audio file and include the <attribute name="audio.surround.force_5_1_downmix"> tag with a value of true (see the partial XML example above). Note that you must remove the existing 5.1 audio before or at the same time as sending "audio.surround.force_5_1_downmix" set to true. See Overview of Asset Removal
To keep the original 5.1 surround audio, send the <attribute name="audio.surround.force_5_1_downmix"> tag with a value of false or omit the tag.
For more information on updating existing content, see 7.1 Surround Audio Asset-Only Update Example.
This section describes HDR (high dynamic range) video and provides delivery requirements for HDR video source (either Dolby® Vision or HDR10). The HDR source can be delivered in an asset-only update or with a new delivery. Dolby® Vision HDR video can be delivered without a corresponding SDR video and Apple can down-convert to SDR. For Dolby® Vision XML examples and annotations, see Metadata Example for HDR Dolby® Vision and Metadata Annotations for HDR Dolby® Vision. For HDR10 XML examples and annotations, see Metadata Example for HDR10 and Metadata Annotations for HDR10. For an XML example showing how to deliver HDR and SDR videos in the same delivery, see HDR and SDR Delivery Example.
For HDR and 4K source asset requirements, see Film HDR Source Profile in Apple Video and Audio Asset Guide.
The following terms are used in this section:
Primary video Refers to the SDR source video
Corresponding HDR video Refers to the HDR source video that corresponds to the delivered SDR video
Sidecar metadata Refers to the accompanying mapping metadata XML file for Dolby® Vision or HDR asset metadata for HDR10
Compared to current non-HDR standards, HDR video can display a wider range of color, brightness, and shades of darkness, which enhances details in the brightest and darkest areas in a video frame. These dynamic variations can change based on the target display and also for individual scenes within the video. To specify these variations, you must deliver additional metadata when delivering the HDR source video. This sidecar metadata lists the following:
Details of the display monitor used for mastering the HDR source
Display targets (their sizes, bit depth, color space, chroma formats, and so on)
Content luminance details
Changes in color corrections either to shots (scenes) or individual frames, if needed
Note: Detailed instructions on constructing this additional metadata are beyond the scope of this specification. For Dolby® Vision mapping metadata, refer to the confidential document “Dolby Content Mapping (CM) Metadata Format Specification Version 2.0.5.1” for CM version 2.9 metadata and to the confidential document “Dolby Vision Mastering Metadata Specification Version 4.0.2b” for CM version 4.0 metadata. (The version number is subject to change.) For HDR10 metadata, refer to "SMPTE ST 2086:2014" and the Blu-ray / DECE definitions of Maximum Content Light Level (MaxCLL) / Maximum Frame Average Light Level (MaxFALL) metadata.
The assets and files must meet certain requirements or delivery will fail. Keep the following in mind when preparing for delivery:
Currently, Dolby® Vision and HDR10 are the only HDR video formats accepted.
The HDR source video must match the requirements listed in Film HDR Source Profile in Apple Video and Audio Asset Guide in the appropriate section based on the format.
The HDR source video can be delivered with a new delivery or in an asset-only update delivery. For a new, complete delivery, you must deliver the primary video, the corresponding HDR video, and either the sidecar XML file or the required source attributes (ST 2086 / MaxCLL / MaxFALL), in addition to all data files and full metadata. In an asset-only delivery, you do not need to re-deliver the primary video, but it must be referenced by vendor ID (see the XML examples in Metadata Example for HDR Dolby® Vision and Metadata Example for HDR10.
The SDR and HDR source videos must have the same start points, and have the same number of black frames.
The HDR file must contain audio tracks. For information on how to use, ignore, or set the audio track as primary, see HDR and SDR Delivery Annotations.
The secondary source must be the same duration as the primary source so that components such as subtitles and audio can be used with the corresponding HDR video source.
The <locale> specified on the secondary HDR video must match the <locale> of the primary video.
The image.textless_master attribute value for the corresponding HDR video must be the same as the primary video.
For Dolby® Vision video source, this corresponding HDR video source must be used in conjunction with the sidecar metadata file. For initial delivery, both the source HDR video file and the mapping file must be included or delivery will fail. When you send an update to deliver a new source HDR, the mapping file should be supplied (either by sending it with the update delivery or by using the previously delivered mapping file). The mapping file, however, can be delivered (and updated) without specifying the source HDR.
For HDR10 video source, this corresponding HDR video source must be used in conjunction with the sidecar metadata attributes. For initial delivery, both the source HDR video file and the sidecar metadata attributes must be included or delivery will fail. When you send an update to deliver a new source HDR, the sidecar metadata attributes should be supplied with the update delivery. New values for the sidecar metadata attributes can be specified with the same corresponding HDR video source.
HDR10+ is generated from all HDR video source deliveries. No additional HDR metadata is required or can be submitted to create this format.
Important: All video must begin and end with at least one black frame. The SDR and HDR source videos must have the same start points, and have the same number of black frames. In addition, videos can only have empty edits in the last edit of the edit list; videos with empty edits other than the last edit will be blocked.
Currently, Dolby® Vision is the only HDR video format allowed for an HDR-only delivery.
The HDR source video must match the requirements listed in Film HDR Source Profile in Apple Video and Audio Asset Guide in the appropriate section based on the format.
Every package must have a primary audio source. This primary audio source must include the stereo mix as it is the base requirement.
When you deliver a Dolby Vision-only package, you can choose to include embedded audio or you can deliver the audio in a separate file.
To deliver a Dolby Vision-only package, you must use the attribute that indicates you want the HDR video to be down-converted to SDR: <attribute name="video.hdr.force_sdr_downconvert">true</attribute>. Apple will create the SDR video using the Dolby Vision SDR trim metadata.
If you deliver an HDR video source that has embedded audio and you deliver alternate audio files, you can use the "ignore_audio" attribute to indicate you do not want to use the embedded audio. Then you specify that the separate audio component should be considered the primary audio.
You can now deliver an SDR source without embedded audio. In this case, you deliver an alternate audio as a separate file and it will be used as the primary audio. If you deliver more than one alternate audio file, the audio file with the locale that matches the source video will be used as the primary audio, unless you specify a different locale as primary using <attribute name="primary_audio">true</attribute>. Note that there can only be one primary audio per package.
If you deliver an SDR video source that has embedded audio and you deliver alternate audio files, you can use the "ignore_audio" attribute to indicate you do not want to use the embedded audio. Then you specify that the separate audio component should be considered the primary audio.
Below are two examples of the existing and new SDR delivery methods (see the subsection below for HDR deliveries):
Current delivery method (will still be supported):
SDR source with embedded audio
Optional HDR source with embedded audio
Audio on the HDR source is ignored and the SDR audio is used
New delivery method with SDR source with no audio:
SDR source with no audio
Alternate audio is used as the primary audio and delivered with the <attribute name="primary_audio">true</attribute>
To improve the quality of the content offered in the Apple TV app, certain territories (listed in the table below) must meet a set of minimum requirements for movies. These requirements apply to deliveries of feature films only; concert films and short films are excluded.
To meet the minimum requirements, new film deliveries must have at least one of the following assets tagged (using the <locale> tag) with the language specified in the table below for both the full asset and preview:
Original audio or alternate audio
Full subtitles (.itt)
Burned-in subtitles
Territories/Countries/Regions | Language (specified in <locale> tag) |
|---|---|
U.S. United Kingdom Australia New Zealand | Any English ( |
Austria | German ( |
Bahrain | Arabic ( |
Brazil | Brazilian Portuguese ( |
Canada | Any English ( |
Egypt | Arabic ( |
France | Parisian French ( |
Germany | German ( |
Hong Kong 4 | Cantonese Audio ( |
Italy | Any Italian ( |
Japan 4 | Japanese ( |
Jordan | Arabic ( |
Korea 4 | Korean ( |
Latin America2 and Mexico | Latin American Spanish ( |
Lebanon | Arabic ( |
Macau 4 | Cantonese Audio ( |
Netherlands | Any Dutch ( |
Oman | Arabic ( |
Qatar | Arabic ( |
Russia 3,4 | Any Russian ( |
Saudi Arabia | Arabic ( |
Spain | Castilian Spanish ( |
Taiwan 4 | Mandarin Audio ( |
Thailand 4 | Thai ( |
Türkiye 3,5 | Any Turkish ( |
United Arab Emirates | Arabic ( |
1 The two asterisks (**) are placeholders for a region subtag and indicate that assets with the specified language subtag, and any region subtag (or no region subtag) will satisfy minimum storefront requirements. For example, if fr-** is required, that requirement can be fulfilled by fr, fr-FR, or fr-CA.
2 Latin America includes Argentina, Bolivia, Chile, Colombia, Costa Rica, Dominican Republic, Ecuador, El Salvador, Guatemala, Honduras, Nicaragua, Panama, Paraguay, Peru, and Venezuela.
3 The minimum requirements for this country CANNOT be overridden by your Apple Technical Representative.
4 Additional minimum requirements: poster art supplied with localized title, as well as localized Title and Synopsis.
5 Additional minimum requirements: only localized Synopsis is required.
6 The minimum storefront requirement can be fulfilled in a territory if both the Original Spoken Locale (OSL) language and audio is provided in the specified language.
In the territories/countries/regions listed in the table above, content that does not meet the requirements will not be available in the Apple TV app. If a film does not meet the territory, country, or region minimum requirements, you will see a notification on the film’s summary page and the Rights and Pricing page on iTunes Connect.
If your content does not meet the minimum requirements for a territory, country, or region, but you still want to make your content available, contact your Apple Technical Representative (Russia and Türkiye excluded).
For information on requirements and standards related to poster art and metadata, see the Movies Style Guide, particularly the sections on Art, Titles, and Synopsis.
Certain territories or regions have specific requirements. Details are listed below.
To make your content available in Colombia, you must provide the country of origin for your movies. Use the <countries_of_origin> tag when you deliver the metadata for a movie.
To make your content available in certain European countries (listed below), you must provide the country of origin (<countries_of_origin>), production country (<production_countries>), and the original spoken locale (<original_spoken_locale>) for your movies.
Below are the countries that require these fields:
Austria (AT), Belgium (BE), Bulgaria (BG), Croatia (HR), Cyprus (CY), Czech Republic (CZ), Denmark (DK), Estonia (EE), Finland (FI), France (FR), Germany (DE), Greece (GR), Hungary (HU), Iceland (IS), Ireland (IE), Italy (IT), Latvia (LV), Liechtenstein (LI), Lithuania (LT), Luxembourg (LU), Malta (MT), Netherlands (NL), Norway (NO), Poland (PL), Portugal (PT), Romania (RO), Slovakia (SK), Slovenia (SI), Spain (ES), Sweden (SE), and United Kingdom (GB).
The following rules apply to all films (regardless of where they are "from") that are sold to customers in India:
Copyright information delivered using the <copyright_cline> tag in the metadata must use the following wording: “Statutory declaration under section 52A of the Copyright Act, 1957 (as amended): We, [name of copyright holder] located at [insert address] hereby declare that we are the owners of the copyright for distributing this cinematography film, having secured necessary consent and license from the producer of the film.”
The copyright information can be set under the <video> level or within a <region> block delivered specifically for India. For example:
<video> . . . <copyright_cline>Statutory declaration under section 52A of the Copyright Act, 1957 (as amended): We, [name of copyright holder] located at [insert address] hereby declare that we are the owners of the copyright for distributing this cinematography film, having secured necessary consent and license from the producer of the film.</copyright_cline> . . .Or,
. . . <region> <territory>IN</territory> <copyright_cline>Statutory declaration under section 52A of the Copyright Act, 1957 (as amended): We, [name of copyright holder] located at [insert address] hereby declare that we are the owners of the copyright for distributing this cinematography film, having secured necessary consent and license from the producer of the film.</copyright_cline> <theatrical_release_date>2013-06-04</theatrical_release_date> </region> . . .Movies sold in India that contain a smoking and/or drinking alcohol health warning, should be tagged with a textless master reason code. To indicate that the film contains this burned-in text, a new attribute has been added for the source video. The tag is <attribute name="image.textless_master.reason_code"> and the allowed value is india_health_warning. This attribute is only allowed on data files with a "source" role.
<assets> <asset type="full"> <data_file role="source"> <locale name="hi"/> <file_name>09736156444-source.mov</file_name> <size>2595225600</size> <checksum type="md5">2a793a8b46037fe8aa29dd739b49911a</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">false</attribute> <attribute name="image.textless_master.reason_code">india_health_warning</attribute> </data_file>Movies in India must have either closed captions (CC) or subtitles for the deaf and hard-of-hearing (SDH) in addition to audio description (AD). This applies to any content, including new releases or library titles, that went live in the Apple TV app after February 6, 2026. The CC/SDH and AD files should match the locale of the original spoken language. For example, if the original spoken locale is en-US, the accessibility files should also be en-US. If the original spoken language of the content will not be made available with the content, the accessibility files should match the locale of one of the audio languages provided with the content.
The following rules apply to all films (regardless of where they are "from") that are sold to customers in Russia.
In addition to the minimum language assets described in the Minimum Storefront Requirements table, for each film for sale inside in Russia, you must provide:
A localized piece of poster art with all wording in Russian. This includes the film title and actors’ names, if present.
Localized title and synopsis written in Russian. This should be tagged with the correct Russian locale (see Multiple-Language Film Metadata Example for more information on delivering localized metadata).
Chapter titles must be localized in Russian. For example, “Chapter 1” becomes "глава 1". If the chapter title does not contain words, use numbers, for example: 1, 2, 3, and so on.
A localized preview with Russian language (audio or subtitled). The trailer must comply with the Trailers and Clips section of the Movies Style Guide (Trailers and Clips).
ISAN (International Standard Audiovisual Number) is an industry standard used to uniquely identify audiovisual works. ISAN values are required for certain movies sold in Switzerland.
To sell content to customers in Switzerland, you need to provide an ISAN or V-ISAN only for titles that meet the following requirements:
If the film is over 60 minutes long and meets one of the following:
The film was released in the Apple TV app (EST or VOD) after 1 January 2017
Or the film has been registered with the ISAN organization and assigned an ISAN or V-ISAN
For a previously-delivered film that does not have an ISAN value, you can send a metadata update and deliver the value in the <isan> tag, or you can add the ISAN value using iTunes Connect. If an ISAN value has already been delivered and you need to update it, edit it in iTunes Connect on the Worldwide Metadata tab for the movie.
For more information on ISAN, see the ISAN website.
Closed captions are required for all US feature deliveries, including shorts and concert films.
The only movies that are exempt from closed captions are:
Movies that are in English that have never been broadcast in the United States. These should be delivered with SDH and the NEVER_IN_US reason code.
Movies that are in English that have been broadcast in the United States but never with captions. This should be delivered with SDH and IN_US_NO_CAPTIONS reason code.
Movies that are not in English and have never been broadcast in the United States don’t need captions. These movies will need either English subtitles or SDH. Use the reason code NO_CC_SDH_FOREIGN_LANGUAGE_ENGLISH_SUBS for these movies.
Note: Movies can be delivered with both closed captions and subtitles for the deaf or hard-of-hearing (SDH). If you are delivering both, you don’t need to include a reason code.
If product offerings change at any point after initial delivery, an update can be sent using Transporter. The newly sent package is compared against the current offering and changes are automatically applied. A metadata-only update delivers the product information, but without including the assets. After a successful, initial upload of metadata and assets, you can make changes to the metadata by delivering a metadata-only update. You do not need to include any asset files with metadata-only deliveries and you can omit the <assets> block from the metadata.xml file.
If asset files are provided and properly referenced in the metadata, then the corresponding checksums will be compared to the checksums of the assets currently on file, and if any checksums are different, the assets will be updated as necessary. If the checksums are unchanged, then the import package (.itmsp) does not need to contain the asset files, even if they are listed in the metadata, because those asset files will be ignored.
Send an update when you need to:
Change the metadata. This update includes only the metadata tags; you do not need to include any assets. XML-only delivery/updates do not need to include the assets block (<asset>) of the XML.
Replace one or more assets. This update should include the XML with the assets block included, as well as the assets to be replaced. When delivering updated source video, keep in mind that the duration of the source video must match the durations of related components (such as subtitles, forced subtitles, alternate audio, SDH, AD, and CC). If the duration of the source video has changed, you must also deliver updates of any related components intended to track to the same timeline as the source video. Based on what has been delivered previously, Apple treats an asset as either an initial delivery or a replacement.
Remove one or more assets. For each asset you want to remove, use the attribute remove= "true":
<data_file role="source" remove="true">
See Remove Alternate Audio for an example.
The newly sent package is compared against the current offering and changes are automatically applied.
When video source is redelivered, you must verify conformance between source types, including SDR video, HDR video, and stereoscopic video sources.
Only the following fields will be updated via a package redelivery (fields that can be updated are noted in the annotations):
Ratings can be added or changed but not removed through updates unless Apple has reviewed and confirmed the quality of the metadata. Should ratings be mistakenly added, contact your Technical Representative for correction.
Advisories can be added or changed through updates. All advisory updates are additive only and do not modify the currently active advisories in the Apple TV app. If you mistakenly add advisories, contact your Technical Representative for correction.
Copyright © line can be added or changed through redelivery.
Chapter titles and chapter artwork can be added or changed, however you must send all chapters, not just the ones being updated.
The theatrical release date can be changed.
Video subtype (feature, short, or concert) can be changed.
The production company can be changed.
The title, synopsis, studio release title, and genres can be changed unless Apple has reviewed and confirmed the quality of the metadata.
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.
Cue sheet block can be added or changed but not removed through updates. Should a cue sheet be mistakenly added, contact your Technical Representative for correction.
Product block updates will add and modify territory clearances.
Items in the asset block (<asset>) will update by overwriting the previous file with the new file, including assets of type "artwork" (<asset type="artwork">).
If an update is to be metadata-plus-assets, all metadata must be correct and complete, and the <assets> block should be included, referencing any assets to be added, replaced, or removed.
Asset-only delivery/updates for assets (video, closed captions, and so on) can be sent independently of the metadata. Assets cannot be delivered unless the metadata has already been sent and imported. If the assets are sent before metadata has been delivered, the asset-only delivery will fail. Asset-only delivery/updates need only include any files that are to be delivered or replaced. Any files to be removed must be explicitly referenced by name, role, size, and checksum based on the most recent delivery to Apple. For a complete example, see Film Asset-Only New Delivery Example and Film Metadata-Only Update Example.
Important: Any changes should be considered “effective immediately” and cannot be made at a guaranteed date or time.
In general, users can configure their operating system to prefer one language or another for displaying localized text. For example, a user in France is likely to have their OS configured to prefer French. Additionally, the Apple TV app has a default language configured for each storefront, based on the country/region of that storefront. Each storefront also has a list of additional languages it supports. For example, the U.S. has English as its default language, but also supports Spanish. A user who signs into the Apple TV app in the U.S. with their OS language set to English will see the UI in English; a user who signs into the Apple TV app in the U.S. with their OS language set to Spanish will see the UI in Spanish. Whichever language is chosen to display the UI for a given user is called the user's storefront language.
When content such as a film title or synopsis is displayed, Apple first looks to see if the title of the film has been provided in the user's storefront language. If the title is not available in the user's storefront language, then the default language of the content in question is displayed (that is, the language provided in the <language> tag). For example, if the title of a film is provided with English as the default, and also localized in Spanish, then a user whose storefront language is Korean will see the English title; a user whose storefront language is Spanish will see the Spanish title.
The table below shows some of the supported storefront languages by territory:
Territory | Default Language | Other Supported Language |
|---|---|---|
Brazil | Portuguese | |
Canada | English | French |
France | French | |
Germany | German | |
Japan | Japanese | English |
United States | English | Spanish |
The Film profile is used for the delivery of all types of film content, including feature and concert films.
Cue sheets should be provided (if available) for short, feature, and concert films that are to be sold or rented outside of the United States. See Multiple-Language Film Metadata Example for an example of how to deliver cue sheets.
Each package represents a single downloadable video. It is not possible to combine content from different packages or to deliver source assets in segments.
Important: Contracts must be signed and in effect before any content may be sold or rented.
For questions regarding this document, contact your Technical Representative.
This section shows examples and annotations for delivering SDR source video in English. (To deliver videos in multiple languages, see Multiple Language Films.) You can deliver SDR source with or without embedded audio and you can choose to use the embedded audio or use an alternate audio file as the primary audio.
You can also deliver HDR source video. See Metadata Example for HDR Dolby® Vision.
Below is an example metadata.xml file for the feature film Forrest Gump. The film for this example is for sale and rental only in the United States, so a cue sheet is not being delivered for the music. Closed captions in English are being delivered.
Note: You can also deliver a Dolby Vision HDR-only package and have Apple down-convert the HDR video to SDR. See Dolby® Vision-Only (No SDR) Delivery with Embedded Audio for details.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <language>en-US</language> <video> <type>film</type> <subtype>feature</subtype> <vendor_offer_code>408CH98720X103</vendor_offer_code> <vendor_id>09736156444</vendor_id> <provider_review_start_date>2022-08-20</provider_review_start_date> <provider_review_end_date>2022-08-20</provider_review_end_date> <isan>0000-0000-03B6-0000-O-0000-0000-2</isan> <eidr>10.5240/CFC2-B507-CE22-B3D4-F32F-2</eidr> <upc>09736156444</upc> <countries_of_origin> <country primary="true">US</country> <country>CA</country> </countries_of_origin> <production_countries> <country primary="true">US</country> </production_countries> <original_spoken_locale>en-US</original_spoken_locale> <title>Forrest Gump</title> <studio_release_title>Forrest Gump</studio_release_title> <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> <production_company>Paramount Pictures</production_company> <copyright_cline>1994 Paramount Pictures</copyright_cline> <theatrical_release_date>2007-05-04</theatrical_release_date> <genres> <genre code="COMEDY-00"/> <genre code="DRAMA-00"/> </genres> <ratings> <rating system="mpaa" reason="for drug content, some sensuality and war violence" code="PG-13"/> </ratings> <cast> <cast_member billing="top"> <display_name>Tom Hanks</display_name> <apple_id>2672649</apple_id> <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> <characters> <character> <reference_id>FORREST</reference_id> <character_name>Forrest Gump</character_name> <character_note>Protagonist</character_note> <character_image> <data_file> <file_name>hanks_as_gump.png</file_name> <size>2813243</size> <checksum type="md5">4ec1addb1f4d3617718b3ebd1ae9ec96</checksum> </data_file> </character_image> </character> <!-- Additional character blocks here if needed for this cast member to handle cases where a cast member plays multiple characters in the film. --> </characters> </cast_member> <!-- Additional cast members here --> </cast> <crew> <crew_member billing="top"> <display_name>Robert Zemeckis</display_name> <apple_id>274059420</apple_id> <roles> <role>Director</role> </roles> </crew_member> <crew_member billing="top"> <display_name>Steve Starkey</display_name> <apple_id>274059432</apple_id> <roles> <role>Producer</role> </roles> </crew_member> <!-- Additional crew members here --> </crew> <chapters> <timecode_format>24/999 1000/nonDrop</timecode_format> <chapter> <start_time>00:00:00:00</start_time> <title locale="en-US">Forrest's Story Begins</title> <artwork_file> <file_name>chapter01.jpg</file_name> <checksum type="md5">ed93d0f3224a353a4cc8d4175d645130</checksum> <size>6591649</size> </artwork_file> </chapter> <chapter> <start_time>00:07:45:23</start_time> <title locale="en-US">Football at Alabama</title><!-- Chapter image can be provided in an artwork file or specified by a timecode. This chapter image is specified by a timecode. --> <artwork_time>00:07:45:23</artwork_time> </chapter><!-- Additional chapters here. --> </chapters> <accessibility_info> <accessibility role="captions" available="true"/> </accessibility_info> <assets> <asset type="full"> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-source.mov</file_name> <size>2595225600</size> <checksum type="md5">2a793a8b46037fe8aa29dd739b49911a</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">false</attribute> <attribute name="video_has_varying_active_region">false</attribute> <attribute name="image.burned_forced_narrative.locale">en-US</attribute> <attribute name="image.burned_subtitles.locale">en-US</attribute> </data_file> <!-- Production still --> <production_still_image_time format="24/999 1000/nonDrop">00:00:57:02</production_still_image_time> <!-- 7.1 Surround Audio --> <data_file role="audio.7_1"> <locale name="en-US"/> <file_name>audio_71.mov</file_name> <size>8730177839</size> <checksum type="md5">a765a9fc88ac893ead51366fbeb04d82</checksum> <attribute name="audio.surround.force_5_1_downmix">true</attribute> </data_file> <!-- Dolby Atmos Audio --> <data_file role="audio.object_based"> <locale name="en-US"/> <file_name>audio_atmos.wav</file_name> <size>1142644642</size> <checksum type="md5">bc5b28a6200e5273202b7609f626fec0</checksum> </data_file> <data_file role="captions"> <file_name>09736156444-english.scc</file_name> <size>9511</size> <checksum type="md5">5a793a8b46037fe8aa2bdd739b49911a</checksum> <locale name="en-US"/> <attribute name="program.start.timecode">-01:00:00:00 </attribute> </data_file> <data_file role="audio.visually_impaired"> <file_name>09736156444-ad.mov</file_name> <size>34866696</size> <checksum type="md5">a2db7f2f30c9744e98fa393e51cf6a93</checksum> <locale name="en-US"/> </data_file> </asset><!-- Required. World Trailer. Will be used where territory-specific trailer has not been provided --> <asset type="preview"> <preview_image_time format="24/999 1000/nonDrop">00:00:57:02</preview_image_time> <territories> <territory>WW</territory> </territories> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-US-preview.mov</file_name> <size>9987212</size> <checksum type="md5">739b43b793a8b46037fe8aa29dd9911e</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> </asset><!-- Required. World Poster Art. Will be used where territory-specific poster art has not been provided --> <asset type="artwork"> <territories> <territory>WW</territory> </territories> <data_file> <locale name="en-US"/> <file_name>09736156444.jpg</file_name> <size>6591649</size> <checksum type="md5">43e7dddfe4b8ab433ede429df86cabb2</checksum> </data_file> </asset><!-- 16:9 Poster Art. Strongly recommended. Required for Storefront promotion. Territory-specific and locale(s) are required --> <asset type="artwork_16:9"> <territories> <territory>WW</territory> </territories> <data_file> <locale name="en"/> <file_name>09736156444_16_9.lsr</file_name> <size>8743649</size> <checksum type="md5">ed356adfe29df86ca4b83ede4bb2ab43</checksum> </data_file> </asset> <asset type="artwork_16:9"> <territories> <territory>CA</territory> </territories> <data_file> <locales> <locale name="en-CA"/> <locale name="fr-CA"/> </locales> <file_name>09736156444_16_9_CA.lsr</file_name> <size>8743649</size> <checksum type="md5">bb6ca42ab439df8b83ed356adfe2ede4</checksum> </data_file> </asset><!-- Optional. Content Logo Art. Locale(s) are required (territories not supported) --> <asset type="full_color_content_logo"> <data_file> <locale name="en"/> <file_name>09736156444_fullcolor_logo.png</file_name> <size>65748</size> <checksum type="md5">9df86c4bb2aba4b83edeed356adfe243</checksum> </data_file> </asset> <asset type="backdrop_wide"> <territories> <territory>WW</territory> </territories> <data_file> <file_name>09736156444_backdrop_wide.png</file_name> <size>88748</size> <checksum type="md5">b26c4b3edeedaba4b89df8356adfe243</checksum> </data_file> </asset> </assets> <products> <product> <territory>US</territory> <cleared_for_sale>true</cleared_for_sale> <cleared_for_hd_sale>true</cleared_for_hd_sale> <wholesale_price_tier>3</wholesale_price_tier> <hd_wholesale_price_tier>1</hd_wholesale_price_tier> <preorder_sales_start_date>2011-02-10</preorder_sales_start_date> <release_date_suppression_lift_date>2011-01-13</release_date_suppression_lift_date> <sales_start_date>2011-03-12</sales_start_date> <cleared_for_vod>true</cleared_for_vod> <vod_type>New Release</vod_type> <available_for_vod_date>2012-11-12</available_for_vod_date> <unavailable_for_vod_date>2013-11-12</unavailable_for_vod_date> <physical_release_date>2007-08-01</physical_release_date> <cleared_for_hd_vod>false</cleared_for_hd_vod> </product> </products> </video></package>Package Metadata Fields |
XML Declaration (required) The character encoding of your document must be defined. Apple accepts only UTF-8 encoding as it efficiently encodes non-Roman characters. Important: The metadata.xml file must not contain a byte-order mark (BOM). |
Package Container (required) The 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 |
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 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. To provide metadata in multiple languages, see Multiple Language Films. |
Provider Metadata Fields |
Provider (required, Apple-supplied) This value should be the Apple-defined provider |
Video Metadata Fields |
Video (required) Begins the video element. Only one video element can be defined per film XML. |
Video Type (required) This value indicates how Apple should process this video. The only accepted value for video type is “film.” |
Video Subtype (required; can be updated) This value indicates how Apple should represent this video in the Apple TV app. The accepted values are:
Short films must be identified as |
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 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. |
Provider Review Start Date (optional) Use the provider review start date to specify when a film becomes available to be reviewed in 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 Apple Partner Media Review. |
Provider Review End Date (optional) Use the provider review end date to specify when a film is no longer available to be reviewed in Apple Partner Media Review. Specifying the provider review end date prevents playback in these apps after that date occurs. If the provider review end date is not specified, then the film is available in Apple Partner Media Review. |
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 (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:
|
UPC (optional) The Universal Product Code (UPC) for this film if the film is sold as physical media in stores. |
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 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 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. Notes:
|
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 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 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. |
Original Spoken Locale (required) Specifies the language spoken by the actors in the film. The value used for In this example, the language the actors' lips are moving in is English as spoken in the United States, so As a best practice when specifying a language, use the region subtag (for example, the Note: This tag is different from the |
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 Note: The The information sent with this tag can be updated unless Apple has reviewed and confirmed the quality of the metadata. |
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. |
Production Company (required; 1-255 bytes; can be updated) The customer-presentable name of the production company that created this film. Only one production company can be specified. |
Copyright © Line (optional; 1-1,000 bytes; can be updated) A specific copyright for this video. The format required is year followed by owner. The appropriate © symbol will automatically be added and should not be included in the data. If omitted, a default calculated copyright will be used based on the film’s theatrical release date and your customer-presentable provider name. |
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 The date must be in the format 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 |
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 The date must be in the format This field does not impact date of release or “street date” in the Apple TV app. |
Genres (required) Films must specify at least one genre. |
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 Required method using the genre code:
Acceptable method using both the genre code and the genre label:
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 (required; can be updated) You must specify one or more ratings for your film content. |
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 The Required method using the rating code:
Acceptable method using both the rating code and the rating label:
To view a list of rating codes, you can download it from Film Ratings. |
|
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:
|
Cast Member (required, multiple allowed) A cast member in this film. List cast actors within the billing (optional) If an actor requires top billing for this film, the attribute Accepted values:
Important: If the |
 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 (optional, numeric) You can refer to the cast member by name (using the |
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 |
Characters (required) Begins the block that describes the characters in the film played by this actor. The Note: To make changes for a character, you must deliver the entire |
Character (required) For each character in the film, supply the character metadata within a Notes:
|
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 (required) The name of the character the actor plays in the film using up to 256 bytes. |
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. |
Character Image (optional) 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 ( Additional guidelines:
|
|
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:
|
Crew Member (required; multiple allowed) A crew member in this film. List crew members within the billing (optional) If a crew member requires top billing for this film, the attribute Accepted values:
Important: If the |
 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 (optional; numeric) You can refer to the crew member by name (using the |
 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):
If a crew member has more than one role, specify each role in a separate |
|
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. |
Timecode format (optional, but recommended) Defines the timecodes used for the chapters. The format can be 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 Important: The frame modes (for example, For more information on timecode formats, see Timecode Formats. |
Chapter (required) Defines the first chapter within the There is no limit to the number of chapters you can define. |
Chapter Start Time (required) Specifies the start of each chapter as dictated by the The first chapter must start at |
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 As a best practice when specifying a language, use the region subtag (for example, the 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 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 (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 Each artwork timecode must be unique. |
|
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 (required for U.S. deliveries; can be updated) Indicates if closed captions are available. Attributes include:
An additional attribute, |
Asset Metadata Fields |
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 (required) Describes the type of asset being delivered. You can specify See Apple Video and Audio Asset Guide for more details. |
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 The format can be Note: This tag is not the same as the 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 <asset type="full"> <. . .> <data_file role="production_still_image"> <file_name>fearless.png</file_name> <size>111037</size> <checksum type="md5">96a2c3979611ea3966f19ff1ac4f28b0</checksum> </data_file> <. . .> </asset>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. |
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 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 See Language Codes for more details. |
File Name (required) 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. |
File Size (required) The size in bytes of the data file. Do not specify any commas nor period delimiters. |
Checksum (required) The MD5 checksum of the data file. See the Checksums section for more information. |
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
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. |
Textless Master (required) 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 |
Video Has Varying Active Region (optional) Use this attribute to specify whether the video content has varying aspect ratios. Allowed values are Set this attribute to To remove metadata generated by a previous analysis, deliver an update with this attribute set to |
<attribute name="image.burned_forced_narrative.locale">en-US</attribute>Forced Narrative Locale (required if full source contains forced narrative text) Specifies the locale of the narrative text. In this example, the attribute is required because the source contains burned-in narrative text. |
<attribute name="image.burned_subtitles.locale">en-US</attribute>Burned-In Subtitles Locale (required if full source contains burned-in subtitles) Specifies the locale of the burned-in subtitles. In this example, the attribute is required because the source contains burned-in subtitles. |
7.1 Surround Audio (optional) To deliver Dolby Digital Plus audio, use the role 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
For information on updating an existing film, see 7.1 Surround Audio Asset-Only Update Example. |
Dolby Atmos Audio (optional) To deliver Dolby Atmos audio, use the role 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 For audio file requirements, see Dolby Atmos Audio Source Profile. 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. |
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 In this block, the Important: If the content does not include closed captions, you must provide the reason why captions are not included. See the annotations for the |
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 ( 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. |
File Size (required) The size in bytes of the caption file. Do not specify any commas nor period delimiters. |
Checksum (required) The MD5 checksum of the caption file. See the Checksums section for more information. |
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 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 ( See the annotation for |
Timecode Offset (optional) 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 |
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 In this block, the |
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 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 See the annotation for |
|
Preview Image Time (optional) The frame to use for the preview image. You can specify an image for each territory. The format can be 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 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 Must be a valid ISO 3166 alpha-2 country code or |
Preview Asset Source (required) One preview file can be provided for each territory. As noted above in the annotation for the full asset, the 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 See the annotations on the Full Asset for tag specifics. |
Poster Image (required; can add new image and update existing images) A poster image is required, as is the
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. |
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 Must be a valid ISO 3166 alpha-2 country code or |
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 If the poster art displays more than one language, for example, poster art for Canada that shows both English and French, supply a See the annotation for |
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. |
File Size (required) The size in bytes of the poster image file. Do not specify any commas nor period delimiters. |
Checksum (required) The MD5 checksum of the poster file. See the Checksums section for more information. |
|
16:9 Poster Art (Strongly recommended. Required for Storefront promotion.) Describes the type of asset being delivered. You must specify Other artwork you can deliver include (see annotations below):
16:9 poster art requires |
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 |
16:9 Poster Image Data File (required, can be updated) The data file block describes the artwork asset. In this example, the artwork being delivered is 16:9 poster art. Allowed formats for 16:9 poster art include:
Poster art must be a minimum of 1920 x 1080 pixels; 3840 x 2160 pixels preferred. In this block, the |
|
Content Logo Art Asset (Strongly recommended. Required for Storefront promotion.) Describes the type of asset being delivered. For logo art, you can specify:
|
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:
In this block, the |
|
Backdrop Art Asset (Strongly recommended. Required for Storefront promotion.) Describes the type of asset being delivered. For backdrop art, you can specify:
|
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 |
Backdrop Art Data File (required, can be updated) The data file block describes the backdrop art asset. In this example, the artwork being delivered is wide backdrop. Backdrop art must be:
In this block, the |
|
Film Products Metadata Fields |
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 (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 (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 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. |
Cleared For Sale (required) Specifies whether or not this video can be sold for EST sale in the product’s territory. Accepted values are Note: If Important: For a video to be available only for rent in the Apple TV app, this element must be set to To remove content from the Store, set |
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 Notes
|
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. |
HD Wholesale Price Tier (optional) The wholesale price tier for an HD film. Must be a wholesale price tier number as specified in the contract with Apple. Note: This tag is not available to all providers or in all countries/regions. Refer to your contract to see if you may send this tag. |
Pre-Order Sales Start Date (optional) 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. |
Release Date Suppression Lift Date (optional) 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 (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 In this example, the start date of |
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 To remove an end date previously delivered, send the tag without a value (called an “empty” tag) using one of the following:
|
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 Note: When 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. |
Video on Demand Type (required for VOD) Specifies whether the film is a new release or a library title. Accepted values are as follows:
Important: Provide this value as specified by your contract. This element is required if |
Available for Video on Demand Date (required for VOD) The date this film is available for video-on-demand rental in the specified territory only. This field must be in |
Unavailable for Video on Demand Date (optional) The date the film is no longer available for video-on-demand rental in the specified territory only. This field must be in Important: Do not use your contract end date as the VOD end date. Enter the date when you are no longer able to offer this film. To remove a VOD end date previously delivered, send the tag without a value (called an “empty” tag) using one of the following:
|
Physical Release Date (optional) 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 Important: This element is required for new releases ( |
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 Note: When |
|
Below is an example metadata.xml file for a film that does not include closed captions. If a film does not include closed captions, you must use the <accessibility_info> tags to indicate why they are not included. The <accessibility> tag within the <accessibility_info> block must include the reason_code attribute; the available reason codes are described in the annotations below. For the sake of brevity, the example is an excerpt from a full metadata delivery. The example shows the tags relevant to accessibility; see the Basic Film Metadata Annotated for explanations of the remaining tags.
In this example, the language of the original film is French, and it is being shown in the U.S. The original film does not have closed captions, but because it does have English subtitles, those can be a substitute for the missing closed captions. The metadata must provide the reason closed captions have not been delivered.
Note that the <accessibility_info> tags can also be provided in an asset-only update within the <assets> block; see Closed Captions Asset-Only Update Examples.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <language>fr-FR</language> <video> <type>film</type> <vendor_id>09736156444</vendor_id><!-- NOTE: Some tags not related to accessibility have been omitted in this example (as indicated by the three dots) for brevity and focus; see the Basic Film Metadata Example for information on sending other tags. Do not omit this data from your package. --> . . .<!-- Begin accessibility tags. --> <accessibility_info> <accessibility role="captions" available="false" reason_code="NO_CC_SDH_FOREIGN_LANGUAGE_ENGLISH_SUBS"/> </accessibility_info> <assets> <asset type="full"> <data_file role="source"> <locale name="fr-FR"/> <file_name>09736156444-source.mov</file_name> <size>2028660952</size> <checksum type="md5">9dd73937fe8aa22a793a8b460b49911a</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file><!-- Subtitles can be used in place of captions --> <data_file role="subtitles"> <locale name="en-US"/> <file_name>Subtitles_EN_US.itt</file_name> <size>100259</size> <checksum type="md5">9df86c3e43e7b43ddeabb2ddfe4b8a42</checksum> </data_file><!-- Asset block does not include a data file for captions. --> </asset> </assets> . . . </video></package>These annotations cover only the <accessibility_info> tags for use with a video that does not include closed captions. When a video does not include closed captions, you must indicate the reason why they have not been included.
Accessibility Information (required for U.S. deliveries; can be updated) Begins the block that describes the availability of closed captions for the film. |
Accessibility (required for U.S. deliveries; can be updated) Indicates if closed captions are available. If closed captions are not available, use the Attributes include:
The values for |
Cue sheets provide a list of music played in a film. Cue sheets have been available for concert films, but are now deliverable for feature films. If a film contains music, you can optionally supply cue sheets that list the start time, duration, title, performers, and other details of a musical piece. Note that the information you supply for cue sheets is currently not supported for display on the Store. The following metadata example is an excerpt from a full metadata delivery. The example shows just a few tags to provide the context for using the <cue_sheet> block to supply cue sheets for the film. See Basic Film Metadata Example for an explanation of a full metadata delivery and see Concert Film Metadata Annotated for annotations on cue sheets. The only difference for feature films is that cue sheets are optional for all countries/regions.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <language>en-US</language> <video> <type>film</type> <subtype>feature</subtype> <vendor_offer_code>408CH98720X103</vendor_offer_code> <vendor_id>09736156444</vendor_id> <isan>0000-0000-03B6-0000-O-0000-0000-2</isan> <eidr>10.5240/CFC2-B507-CE22-B3D4-F32F-2</eidr> <upc>09736156444</upc> <countries_of_origin> <country primary="true">US</country> <country>CA</country> </countries_of_origin> <production_countries> <country primary="true">US</country> </production_countries> <original_spoken_locale>en-US</original_spoken_locale> <title>Forrest Gump</title> <!-- NOTE: Some tags have been omitted in this example (as indicated by the three dots) for brevity and focus. Do not omit those tags from your package. --> . . . <cue_sheet> <cue> <sequence_number>1</sequence_number> <time> <start_timecode>00:05:27</start_timecode> <duration>00:02:46</duration> </time> <title>Lovesick Blues</title> <artists> <artist> <artist_name>Hank Williams</artist_name> <apple_id>179722</apple_id> <roles> <role>Performer</role> <role>Creator</role> </roles> </artist> </artists> <isrc>ITL771650791</isrc> <copyright_cline>1997 Mercury Records Inc.</copyright_cline> <copyright_pline>1997 Mercury Records Inc.</copyright_pline> <usage>Featured</usage> </cue> <cue> <sequence_number>2</sequence_number> <time> <start_timecode>00:10:27</start_timecode> <duration>00:02:16</duration> </time> <title>Hound Dog</title> <artists> <artist> <artist_name>Elvis Presley</artist_name> <apple_id>197443</apple_id> <roles> <role>Performer</role> </roles> </artist> <artist> <artist_name>Jerry Leiber</artist_name> <apple_id>12251</apple_id> <roles> <role>Songwriter</role> </roles> </artist> <artist> <artist_name>Mark Stoller</artist_name> <roles> <role>Songwriter</role> </roles> </artist> </artists> <isrc>USRC10201414</isrc> <copyright_cline>1956 RCA Studios</copyright_cline> <copyright_pline>1956 RCA Studios</copyright_pline> <usage>Featured</usage> </cue><!-- Additional cue blocks here. --> </cue_sheet> . . . </video></package>In this delivery, the SDR source has embedded audio, but an alternate audio is delivered as a separate file and it will be used as the primary audio. In this case, use the "ignore_audio" attribute on the SDR source to indicate you do not want to use the embedded audio. Then you specify that the separate audio component should be considered the primary audio.
For the sake of brevity, the example is an excerpt from a full metadata delivery. The example shows the tags relevant to SDR delivery using an alternate audio file; see the Basic Film Metadata Annotated for explanations of the remaining tags.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <language>en-US</language> <video> <type>film</type> <vendor_id>09736156444</vendor_id><!-- NOTE: Some tags not related to this SDR example have been omitted (as indicated by the three dots) for brevity and focus; see the Basic Film Metadata Example for information on sending other tags. Do not omit this data from your package. --> . . .<!-- SDR asset with embedded audio. --> <assets> <asset type="full"> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-source.mov</file_name> <size>2028660952</size> <checksum type="md5">9dd73937fe8aa22a793a8b460b49911a</checksum> <attribute name="ignore_audio">true</attribute> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file><!-- Audio to be used as primary audio --> <data_file role="audio"> <locale name="en-US"/> <file_name>audio_09736156444.mov</file_name> <size>8730177839</size> <checksum type="md5">a765a9fc88ac893ead51366fbeb04d82</checksum> <attribute name="primary_audio">true</attribute> </data_file> </asset> </assets> . . . </video></package>These annotations cover only the tags for use with an SDR video with embedded audio and an alternate audio file.
Ignore Embedded Audio (optional if a video file has embedded audio and if delivering another primary audio file) In this example, the SDR video source includes embedded audio, but another audio file will be used as the primary audio. If you supply audio in stereo in another file and the SDR source has embedded audio, you can use the Note that |
Primary Audio (optional) In this example, the SDR video source includes embedded audio, but another audio file will be used as the primary audio. You can use the Note that Note: This primary audio should align with the primary audio locale you want for the package. For example, if the movie is dubbed in Russian and is sold only in Russia, the primary audio would be "ru" even though the video source is "en-US". |
In this delivery, the SDR source does not have embedded audio. An alternate audio is delivered as a separate file and it will be used as the primary audio. If you deliver more than one alternate audio file, the audio file with the locale that matches the source video will be used as the primary audio, unless you specify a different primary locale.
For the sake of brevity, the example is an excerpt from a full metadata delivery. The example shows the tags relevant to SDR delivery with no embedded audio; see the Basic Film Metadata Annotated for explanations of the remaining tags.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <language>en-US</language> <video> <type>film</type> <vendor_id>09736156444</vendor_id><!-- NOTE: Some tags not related to this SDR example have been omitted (as indicated by the three dots) for brevity and focus; see the Basic Film Metadata Example for information on sending other tags. Do not omit this data from your package. --> . . .<!-- SDR asset with no embedded audio. --> <assets> <asset type="full"> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-source.mov</file_name> <size>2028660952</size> <checksum type="md5">9dd73937fe8aa22a793a8b460b49911a</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file><!-- Audio to be used as primary audio, which should include both stereo and 5.1 --> <data_file role="audio"> <locale name="en-US"/> <file_name>audio_09736156444.mov</file_name> <size>8730177839</size> <checksum type="md5">a765a9fc88ac893ead51366fbeb04d82</checksum> <attribute name="primary_audio">true</attribute> </data_file> </asset> </assets> . . . </video></package>These annotations cover only the tags for use with an SDR video with no embedded audio.
Primary Audio (required if source does not have embedded audio) In this example, the SDR video source does not have embedded audio, and another audio file will be used as the primary audio. You must use the Note: This primary audio should align with the primary audio locale you want for the package. For example, if the movie is dubbed in Russian and is sold only in Russia, the primary audio would be "ru" even though the video source is "en-US". |
If you deliver a Dolby Atmos audio file, you can specify that you want Apple to downmix to other formats. This allows you to deliver a single Atmos audio file and derive all of the other formats (7.1, 5.1, and stereo). You use the following attributes on the Dolby Atmos source audio:
audio.transform_to.2_0
audio.transform_to.5_1
audio.transform_to.7_1
If you downmix Atmos audio to stereo (2.0) for the main locale, you must specify it as the primary audio using <attribute name="primary_audio">true</attribute> and you must also use ignore_audio on any video sources with embedded audio (HDR or SDR):
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <language>en-US</language> <video> <type>film</type> <vendor_id>09736156444</vendor_id><!-- NOTE: Some tags not related to this SDR example have been omitted (as indicated by the three dots) for brevity and focus; see the Basic Film Metadata Example for information on sending other tags. Do not omit this data from your package. --> . . .<!-- SDR asset with embedded audio. --> <assets> <asset type="full"> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-source.mov</file_name> <size>2028660952</size> <checksum type="md5">9dd73937fe8aa22a793a8b460b49911a</checksum> <attribute name="ignore_audio">true</attribute> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file><!-- Dolby Atmos audio to be used as primary audio --> <data_file role="audio.object_based"> <locale name="en-US"/> <file_name>audio_atmos.wav</file_name> <size>1142644642</size> <checksum type="md5">bc5b28a6200e5273202b7609f626fec0</checksum> <attribute name="audio.transform_to.2_0">true</attribute> <attribute name="audio.transform_to.5_1">true</attribute> <attribute name="audio.transform_to.7_1">true</attribute> <attribute name="primary_audio">true</attribute> </data_file> </asset> </assets> . . . </video></package>These annotations cover only the tags for use with Dolby Atmos audio.
Ignore Embedded Audio (required if a video file has embedded audio and if delivering another primary audio file) In this example, Dolby Atmos audio is being delivered and used to provide 2.0, 5.1, and 7.1 audio formats. The source video includes embedded audio, but the Dolby Atmos audio file will be used as the primary audio. In this case, you must use the Note that |
Dolby Atmos Audio (optional) To deliver Dolby Atmos audio, use the role This primary audio aligns with the primary audio locale you want for the package. For example, if the movie has dubbed Russian and is sold only in Russia, the primary audio would be “ru” even though the video source is “en-US”. Notes:
For audio file requirements, see Dolby Atmos Audio Source Profile. |
This section describes the package format for the delivery of stereoscopic video.
Note: Contact your Apple Technical Partner Representative before providing stereoscopic video content.
To deliver stereoscopic video content, you need to submit two video files:
Left-eye video file, optionally with an associated stereo audio track in a single QuickTime container
Right-eye video file with no audio track
These video files can be standard dynamic range (SDR) sources, or high dynamic range (HDR) sources, but not both for the same asset. If you use HDR sources, the HDR format type should be Dolby® Vision (specified as DolbyVision in the XML). When video source is redelivered you must verify conformance between source types including SDR video, HDR video, and stereoscopic video sources. See Apple Video and Audio Asset Guide for details.
Use the following XML tags to implement this delivery:
Specify the data_file roles:
Use <data_file role="stereo_video.left"> for the left-eye SDR source.
Use <data_file role="stereo_video.right"> for the right-eye SDR source.
Use <data_file role="stereo_video.hdr.left"> for the left-eye HDR source.
Use <data_file role="stereo_video.hdr.right"> for the right-eye HDR source.
Optionally use <data_file role="stereo_video.parallax"> to deliver a JSON file with parallax metadata to guide the placement of subtitles, SDH subtitles, closed captions, or other user interface elements in stereoscopic videos. See Video Parallax Metadata for information on the JSON file specification.
Optionally use <data_file role="stereo_video.hdr.mapping"> to deliver a custom 3D HDR mapping file for 3D Dolby Vision Profile 20 content. The sidecar metadata file must be CM version 4.0.
Use the attribute <attribute name="hero_eye"> to indicate which video source should be used for monoscopic purposes.
Use the product tag <available_for_3d_date> to specify the date when the stereoscopic video content is available for purchase.
For HDR source, if you don’t specify a stereo_video.hdr.mapping file, use the attribute <attribute name="hdr.max.display.luminance"> to specify the maximum brightness level. (You can use either the stereo_video.hdr.mapping file or the hdr.max.display.luminance attribute; you cannot use both.)
For the sake of brevity, the examples are excerpts from a full metadata delivery. The examples show the tags relevant to stereoscopic delivery; see the Basic Film Metadata Annotated for explanations of the remaining tags.
SDR Metadata Example
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"><!-- NOTE: Some tags not related to this stereoscopic example have been omitted (as indicated by the three dots) for brevity and focus; see the Basic Film Metadata Example for information on sending other tags. Do not omit this data from your package. --> . . . <video> . . .<!-- SDR asset with embedded audio. --> <assets> <asset type="full"> <data_file role="source"> <locale name="en-US"/> <file_name>source_16s.mov</file_name> <size>343376467</size> <checksum type="md5">301e72262aea7d504aca91abe229cded</checksum> <attribute name="crop.bottom">142</attribute> <attribute name="crop.left">2</attribute> <attribute name="crop.right">2</attribute> <attribute name="crop.top">142</attribute> <attribute name="image.burned_forced_narrative.locale">en-US</attribute> <attribute name="image.textless_master">false</attribute> </data_file> <!-- Left-eye video --> <data_file role="stereo_video.left"> <locale name="en-US"/> <file_name>baby_10s.mov</file_name> <size>192638012</size> <checksum type="md5">9514fd9fc52f5403058f2975d235b44d</checksum> <attribute name="hero_eye">false</attribute> <attribute name="crop.bottom">142</attribute> <attribute name="crop.left">2</attribute> <attribute name="crop.right">2</attribute> <attribute name="crop.top">142</attribute> <attribute name="image.burned_forced_narrative.locale">en-US</attribute> <attribute name="image.textless_master">false</attribute> </data_file> <!-- Right-eye video --> <data_file role="stereo_video.right"> <locale name="en-US"/> <file_name>129secs.mov</file_name> <size>290075587</size> <checksum type="md5">a0b20333d1a886443474f2adc41ee561</checksum> <attribute name="hero_eye">true</attribute> <attribute name="crop.bottom">142</attribute> <attribute name="crop.left">2</attribute> <attribute name="crop.right">2</attribute> <attribute name="crop.top">142</attribute> <attribute name="image.burned_forced_narrative.locale">en-US</attribute> <attribute name="image.textless_master">false</attribute> </data_file> </asset> <data_file role="stereo_video.parallax"> <file_name>custom-axis.json</file_name> <size>672</size> <checksum type="md5">3446f2f3575dbf5bad5d1b1336d9c763</checksum> </data_file> </assets> <products> <product> <territory>US</territory> . . . <sales_start_date>2024-01-01</sales_start_date> <available_for_4k_date>2024-01-01</available_for_4k_date> <available_for_3d_date>2024-03-01</available_for_3d_date> . . . </product> </products> </video></package>HDR Metadata Example
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"><!-- NOTE: Some tags not related to this stereoscopic example have been omitted (as indicated by the three dots) for brevity and focus; see the Basic Film Metadata Example for information on sending other tags. Do not omit this data from your package. --> . . . <video> . . . <assets> <asset type="full"> <data_file role="audio"> <locale name="en-US"/> <file_name>40s.mov</file_name> <size>46092828</size> <checksum type="md5">693c6a0c62a501573d5d720cd29a1988</checksum> <attribute name="primary_audio">true</attribute> </data_file> <data_file role="mapping.hdr"> <file_name>cake_4ab_HDR.xml</file_name> <size>34610</size> <checksum type="md5">546c8470ed7fd301b00355ed76e51240</checksum> </data_file> <data_file role="source.hdr"> <locale name="en-US"/> <file_name>PQ3-1.mov</file_name> <size>2208663620</size> <checksum type="md5">36a6d76d7972e9e08c4592dcd0a63439</checksum> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="crop.top">0</attribute> <attribute name="hdr.format">DolbyVision</attribute> <attribute name="video.hdr.force_sdr_downconvert">true</attribute> <attribute name="image.textless_master">true</attribute> <attribute name="ignore_audio">true</attribute> </data_file> <!-- Left-eye video --> <data_file role="stereo_video.hdr.left"> <locale name="en-US"/> <file_name>12s.mov</file_name> <size>252640295</size> <checksum type="md5">a92404cded82975e61143bcb3982d1a3</checksum> <attribute name="hero_eye">false</attribute> <attribute name="crop.bottom">142</attribute> <attribute name="crop.left">2</attribute> <attribute name="crop.right">2</attribute> <attribute name="crop.top">142</attribute> <attribute name="image.burned_forced_narrative.locale">en-US</attribute> <attribute name="image.textless_master">false</attribute> <attribute name="hdr.format">DolbyVision</attribute> </data_file> <!-- Right-eye video --> <data_file role="stereo_video.hdr.right"> <locale name="en-US"/> <file_name>9s.mov</file_name> <size>205055299</size> <checksum type="md5">5da3e974de660341f909e15bb97fceea</checksum> <attribute name="hero_eye">true</attribute> <attribute name="crop.bottom">142</attribute> <attribute name="crop.left">2</attribute> <attribute name="crop.right">2</attribute> <attribute name="crop.top">142</attribute> <attribute name="image.burned_forced_narrative.locale">en-US</attribute> <attribute name="image.textless_master">false</attribute> <attribute name="hdr.format">DolbyVision</attribute> </data_file> <data_file role="stereo_video.hdr.mapping"> <file_name>nines_HDR.xml</file_name> <size>24540</size> <checksum type="md5">1db2a6cfea099aa7966b1b4408dac1ec</checksum> </data_file> </asset> </assets> <products> <product> <territory>US</territory> . . . <sales_start_date>2024-01-01</sales_start_date> <available_for_4k_date>2024-01-01</available_for_4k_date> <available_for_3d_date>2024-03-01</available_for_3d_date> . . . </product> </products> </video></package>These annotations cover only the tags for delivering stereoscopic video.
Asset Level Tags |
Left and Right SDR Stereoscopic Videos (required for SDR deliveries) If you are delivering stereoscopic video sources to accompany an existing data source, then neither the left-eye nor the right-eye file is required to contain an audio track. The frame rate of the stereoscopic video sources does not need to match the frame rate of the existing data source. In these blocks, the |
Left and Right HDR Stereoscopic Videos (required for HDR deliveries) The HDR format should be Dolby Vision. Metadata for both the left-eye and right-eye must include this attribute:
If you are delivering stereoscopic video sources to accompany an existing data source, then neither the left-eye nor the right-eye file is required to contain an audio track. The frame rate of the stereoscopic video sources does not need to match the frame rate of the existing data source. In these blocks, the |
Hero Eye (optional) Use this attribute to indicate the video source that should be used for monoscopic purposes, as a fallback for when it is not possible to play the stereoscopic content. Note: Only one video source should specify the value |
Display Luminance (optional) For HDR source, use this attribute to specify the maximum brightness for the video source. Specify the value in nits, also know as candela per square meter (cd/m2). You can specify a value in the range from 48 (minimum value) to 1000 (maximum value). The default value is 48. Notes
|
3D HDR Sidecar Mapping File (optional) The data file block specifies the sidecar file and describes the role of the associated file. The maximum frame number (edit unit) referenced in the sidecar metadata file must be less than or equal to the last frame number of the secondary HDR video. This data file specifies a custom 3D HDR mapping file for 3D Dolby Vision Profile 20 content. Only Dolby Vision CM version 4.0 sidecar metadata files are supported. To deliver this 3D HDR sidecar mapping file, you must also deliver left and right HDR stereoscopic videos (data files with the roles In this block, the Note: If you specify a |
Product Level Tags |
Available for 3D Date (optional) The date the stereoscopic video content is available for purchase for the territory. The following rules apply:
|
Content providers can supply parallax metadata to describe horizontal disparity values associated with 2D areas of stereoscopic video frames. The metadata applies to the video content. The parallax metadata is used to guide the placement of subtitles, SDH subtitles, and closed captions in stereoscopic videos.
JSON Overview
This metadata is delivered as a JSON file. It is beyond the scope of this document to explain how to use the syntax of JSON in depth. At a minimum, follow these formatting rules:
Entities start and end with braces ({ and })
Key names are enclosed in quotes. Key names are case sensitive. Key names shown in this specification are reserved and should be used as specified.
A colon (:) separates the key name and the value, which defines a key/value pair
Key/value pairs ("key":value) are separated by commas (,)
Square brackets ([ and ]) enclose value (" ") or object ({ }) entries separated by a comma (,)
JSON File Structure
The top level object in the JSON file must be parallaxTimedMetadata. You can optionally include a userData object for information useful to content authors and tool developers. This userData object is ignored. (The maximum size you can use for the userData object is 2048 bytes.)
The parallaxTimedMetadata Object |
{ "parallaxTimedMetadata": { [Header] [Messages] }} |
The
|
The Header Section |
{ "parallaxTimedMetadata": { "version": string, "sampleRate": { "numerator": int, "denominator": int }, "sourceFilenames": [string], ...... }} |
The header section consists of three properties:
Note: The term Header isn’t an actual property name. This term is just used to describe these properties that are listed before the Messages section. |
The Messages Section |
{ "parallaxTimedMetadata": { ......, "messages": [ { "start": int, "duration": int, "parallaxContourMaps": [ { "operator": string, "integrated": bool, "rows": int, "columns": int, "values": [ double, ] } ] }, ...... ] }} |
The messages section starts with the The
The parallaxContourMaps Property The The
Note: To describe the whole frame as one value, set In the Terms for parallax timed metadata
|
Example diagram showing a 3x4 contour map This example diagram shows how three-rows-by-four-columns map to a frame with black borders. The numbers denote the tile indexes. In this example, there are twelve tile areas, with the values array numbered from 0 to 11.  |
Guidelines for Creating Parallax Metadata
These instructions are written for the placement of subtitles, but the same guidelines would apply for closed captions or other UI elements.
Depth conflict: When subtitles are placed at a depth farther to the viewer than the video content, they may intersect with each other and create a “depth conflict” effect. This effect can cause visual discomfort and should be avoided. To place subtitles closer to the viewer than the video content, the parallax values of subtitles should be more negative than the parallax values of video content. In abstract, the parallax values of subtitles are determined by the minimum value of minimum parallax in tiles overlapped with subtitles.
Stability: When the parallax values of subtitles change too frequently or too fast over time, the viewer may not be able to focus on the subtitles. Fast changes can also create a flickering effect, which should be avoided. Smooth the parallax values for each tile over time so that the difference of parallax values between any neighboring samples is smaller than 0.0005 (5e-4).
Floating subtitles: Do not place subtitles too far from the video content behind it. Parallax values for subtitles should not be significantly more negative than the parallax values for the video content.
To reduce the size of the JSON file:
Balance time and spatial resolution. Use "duration" to summarize neighboring frames with nearly identical parallax contour maps. Match the tile resolution with subtitle dimensions and parallax estimation accuracy. For example, while 50x50 tiles offer detailed granularity, they are excessive for low-resolution or smooth parallax contours. Instead, using 10x10 tiles can offer a good balance between granularity and file size. Use a 1x1 tile to represent constant parallax values.
Remove all whitespaces, indents, and line breaks in the file.
Round the values in the "values" arrays to no more than 5 decimal places.
Example JSON File
This JSON file is a simplified example. It includes whitespaces, indents, and line breaks to make it easier to read.
{ "parallaxTimedMetadata": { "version": "1.2", "sampleRate": { "numerator": 24000, "denominator": 1001 }, "sourceFilenames": ["left.mov", "right.mov"], "messages": [ { "start": 0, "duration": 1, "parallaxContourMaps": [ { "operator": "min", "rows": 3, "columns": 3, "values": [ 0.025, 0.025, 0.025, 0.025, -0.025, -0.025, -0.025, -0.025, -0.025 ] } ] }, { "start": 1, "duration": 3, "parallaxContourMaps": [ { "operator": "min", "rows": 1, "columns": 1, "values": [ 0.0 ] } ] } ] }}To deliver HDR Dolby® Vision video, two roles have been added for use with the <asset> tag: source.hdr and mapping.hdr. The following metadata example shows how to use the roles in an asset-only update. This example adds an HDR Dolby® Vision video to a previously-delivered film. The package delivered would consist of the "asset update" metadata file, the HDR Dolby® Vision source video, and the sidecar metadata file. The primary source must be referenced by vendor ID. To deliver the HDR and SDR video at the same time, see the example in HDR and SDR Delivery Example. You can also deliver a Dolby Vision HDR-only package without having to reference or deliver the SDR video. See Dolby® Vision-Only (No SDR) Delivery with Embedded Audio for details.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider><!-- The vendor_id referenced below is the vendor ID of the primary source video. --> <assets media_type="video" vendor_id="09736156444"> <asset type="full"> <data_file role="source.hdr"> <attribute name="hdr.format">DolbyVision</attribute> <locale name="en-US"/> <file_name>09736156444-hdr-source.mov</file_name> <size>3244032000</size> <checksum type="md5">9df86c3e43e7b43ddeabb2ddfe4b8a42</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> <data_file role="mapping.hdr"> <file_name>09736156444-mapping.xml</file_name> <size>16659</size> <checksum type="md5">df86c3eeabb2ddfe4b843e7b943dda42</checksum> </data_file> </asset> <asset type="preview"> <data_file role="source.hdr"> <attribute name="hdr.format">DolbyVision</attribute> <locale name="en-US"/> <file_name>09736156444-hdr-preview.mov</file_name> <size>9987212</size> <checksum type="md5">739b43b793a8b46037fe8aa29dd9911e</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> <data_file role="mapping.hdr"> <file_name>09736156444-preview-mapping.xml</file_name> <size>16659</size> <checksum type="md5">b8ddfe443e7df86c3eeabb2b943dda42</checksum> </data_file> </asset> </assets></package>Only the tags related to the HDR Dolby® Vision delivery are described. Refer to Basic Film Metadata Annotated for annotations on other tags.
Asset Level Tags |
Assets (required; can be updated) Begins the assets block that references the assets being delivered. In an asset-only update, the |
HDR Source Asset (required) The data file block specifies the source video file and describes the role of the associated file. In this example, the file sent is used as the HDR source, so the role must be The corresponding source video must be the same duration as the primary source video so that components such as subtitles and audio can be used with the corresponding HDR video. In this block, the |
HDR Format (required) In this example, the HDR video source is Dolby® Vision, which must be specified with the |
HDR Source Asset Locale (required) The locale for the HDR source video must match the locale of the primary video. If they do not match, delivery will fail. |
Textless Master (required) The value for textless master for the HDR source video must match the value for textless master primary video. If they do not match, delivery will fail. |
HDR Sidecar Mapping File (required) The data file block specifies the sidecar file and describes the role of the associated file. The maximum frame number (edit unit) referenced in the sidecar metadata file must be less than or equal to the last frame number of the secondary HDR video. For initial delivery, both the source HDR video file and the mapping file must be included or delivery will fail. When you send an update to deliver a new source HDR, the mapping file should be supplied (either by sending it with the update delivery or by using the previously-delivered mapping file). The mapping file, however, can be delivered (and updated) without specifying the source HDR. In this block, the Both Dolby Vision CM version 2.9 and CM version 4.0 sidecar metadata files are supported. |
HDR Preview Source Asset (required) The data file block specifies the preview source video file and describes the role of the associated file. In this example, the file sent is used as the HDR source, so the role must be The secondary preview source video must be the same duration as the primary preview source video so that components such as subtitles and audio can be used with the secondary preview video. In this block, the |
HDR Format (required) In this example, the HDR video source is Dolby® Vision, which must be specified with the |
HDR Preview Asset Locale (required) The locale for the HDR preview source video must match the locale of the primary preview video. If they do not match, delivery will fail. |
Textless Master (required) The value for textless master for the HDR source preview video must match the value for textless master primary preview video. If they do not match, delivery will fail. |
HDR Preview Sidecar Mapping File (required) The data file block specifies the sidecar file for the preview and describes the role of the associated file. The maximum frame number (edit unit) referenced in the sidecar metadata file must be less than or equal to the last frame number of the secondary HDR preview video. For initial delivery, both the HDR preview video file and the mapping file must be included or delivery will fail. When you send an update to deliver a new HDR preview, the mapping file should be supplied (either by sending it with the update delivery or by using the previously-delivered mapping file). The mapping file, however, can be delivered (and updated) without specifying the preview. In this block, the Both Dolby Vision CM version 2.9 and CM version 4.0 sidecar metadata files are supported. |
You can deliver Dolby Vision HDR video without a corresponding SDR video delivery and specify a tag to down-convert to SDR. Apple will create the SDR video using the Dolby Vision SDR trim metadata. Using this method is optional, but it could streamline the delivery process for you. When you deliver a Dolby Vision-only package, you can choose to include embedded audio or you can deliver the audio in a separate file.
Note: This delivery method is not available for HDR 10 videos.
To deliver a Dolby Vision-only package, you must use the attribute that indicates you want the HDR video to be down-converted to SDR: <attribute name="video.hdr.force_sdr_downconvert">true</attribute>.
This example shows how to deliver Dolby Vision HDR video without an SDR video delivery. When you deliver a Dolby Vision-only package, you can choose to include embedded audio or you can deliver the audio in a separate file. In this example, the HDR full source video includes embedded audio. Since there is no SDR audio in this delivery (the default audio source), the HDR source is used as the primary audio source. Both Dolby Vision CM version 2.9 and CM version 4.0 sidecar metadata files are supported.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <language>en-US</language> <video> <type>film</type> <subtype>feature</subtype> <!-- To save space, several tags have been omitted from this XML. See the Basic Example for all the tags. --> . . . <assets> <asset type="full"> <data_file role="source.hdr"> <attribute name="hdr.format">DolbyVision</attribute> <attribute name="video.hdr.force_sdr_downconvert">true</attribute> <locale name="en-US"/> <file_name>09736156444-hdr-source.mov</file_name> <size>3244032000</size> <checksum type="md5">9df86c3e43e7b43ddeabb2ddfe4b8a42</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> <data_file role="mapping.hdr"> <file_name>09736156444-mapping.xml</file_name> <size>16659</size> <checksum type="md5">df86c3eeabb2ddfe4b843e7b943dda42</checksum> </data_file> <!-- Other data files (such as captions, subtitles) go here --> </asset><!-- Required. World Trailer. Will be used where territory-specific trailer has not been provided --> <asset type="preview"> <data_file role="source.hdr"> <attribute name="hdr.format">DolbyVision</attribute> <attribute name="video.hdr.force_sdr_downconvert">true</attribute> <attribute name="primary_audio">true</attribute> <locale name="en-US"/> <file_name>09736156444-hdr-preview.mov</file_name> <size>9987212</size> <checksum type="md5">739b43b793a8b46037fe8aa29dd9911e</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> <data_file role="mapping.hdr"> <file_name>09736156444-preview-mapping.xml</file_name> <size>16659</size> <checksum type="md5">b8ddfe443e7df86c3eeabb2b943dda42</checksum> </data_file> </asset><!-- Required. World Poster Art. Will be used where territory-specific poster art has not been provided --> <asset type="artwork"> <territories> <territory>WW</territory> </territories> <data_file> <locale name="en-US"/> <file_name>09736156444.jpg</file_name> <size>6591649</size> <checksum type="md5">43e7dddfe4b8ab433ede429df86cabb2</checksum> </data_file> </asset><!-- 16:9 Poster Art. Strongly recommended. Required for Storefront promotion. Territory-specific and locale(s) are required --> <asset type="artwork_16:9"> <territories> <territory>WW</territory> </territories> <data_file> <locale name="en-US"/> <file_name>09736156444_16_9.lsr</file_name> <size>8743649</size> <checksum type="md5">ed356adfe29df86ca4b83ede4bb2ab43</checksum> </data_file> </asset> </assets> </video></package>Only the tags related to the Dolby® Vision HDR-only delivery are described. Refer to Basic Film Metadata Annotated for annotations on other tags.
Asset Level Tags |
HDR Source Asset (required) The data file block specifies the source video file and describes the role of the associated file. In this example, the file sent is used as the HDR source, so the role must be In this block, the |
HDR Format (required) In this example, the HDR video source is Dolby® Vision, which must be specified with the |
HDR Down-Convert to SDR (required for HDR-only deliveries) In this example, the HDR video source is being delivered without a corresponding SDR video. To deliver a Dolby Vision-only package, you must use this attribute that indicates you want the HDR video to be down-converted to SDR. |
HDR Sidecar Mapping File (required) The data file block specifies the sidecar file and describes the role of the associated file. The maximum frame number (edit unit) referenced in the sidecar metadata file must be less than or equal to the last frame number of the secondary HDR video. For initial delivery, both the source HDR video file and the mapping file must be included or delivery will fail. When you send an update to deliver a new source HDR, the mapping file should be supplied (either by sending it with the update delivery or by using the previously-delivered mapping file). The mapping file, however, can be delivered (and updated) without specifying the source HDR. In this block, the Both Dolby Vision CM version 2.9 and CM version 4.0 sidecar metadata files are supported. |
HDR Preview Source Asset (required) The data file block specifies the preview source video file and describes the role of the associated file. In this example, the file sent is used as the HDR source, so the role must be In this block, the |
HDR Format (required) In this example, the HDR preview source is Dolby® Vision, which must be specified with the |
HDR Down-Convert to SDR (required for HDR-only deliveries) In this example, the HDR preview source is being delivered without a corresponding SDR video. To deliver a Dolby Vision-only package, you must use this attribute that indicates you want the HDR video to be down-converted to SDR. |
HDR Preview Sidecar Mapping File (required) The data file block specifies the sidecar file for the preview and describes the role of the associated file. The maximum frame number (edit unit) referenced in the sidecar metadata file must be less than or equal to the last frame number of the secondary HDR preview video. For initial delivery, both the HDR preview video file and the mapping file must be included or delivery will fail. When you send an update to deliver a new HDR preview, the mapping file should be supplied (either by sending it with the update delivery or by using the previously-delivered mapping file). The mapping file, however, can be delivered (and updated) without specifying the preview. In this block, the Both Dolby Vision CM version 2.9 and CM version 4.0 sidecar metadata files are supported. |
To deliver HDR10 video, you must supply the source.hdr role with the hdr.format set to HDR10. A mapping file is not required; if you deliver a mapping file, delivery will fail. Instead, you provide the attributes in the metadata XML file as shown below. The following metadata example shows how to use the roles in an asset-only update. This example adds an HDR10 video to a previously-delivered SDR film. The package delivered would consist of the "asset update" metadata file, the HDR10 source video, and the required attributes. The primary source must be referenced by vendor ID.
Note: The chromaticity values listed in the example and annotations below are for a P3 display with D65 white point. For a BT.2020 display with D65, see the annotation on Metadata Annotations for HDR10 for examples of value formatting.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider><!-- The vendor_id referenced below is the vendor ID of the primary source SDR video. --> <assets media_type="video" vendor_id="09736156444"> <asset type="full"> <data_file role="source.hdr"> <locale name="en-US"/> <file_name>09736156444-hdr-source.mov</file_name> <size>3244032000</size> <checksum type="md5">9df86c3e43e7b43ddeabb2ddfe4b8a42</checksum> <attribute name="hdr.format">HDR10</attribute> <attribute name="hdr.red.chroma.x">0.6800</attribute> <attribute name="hdr.red.chroma.y">0.3200</attribute> <attribute name="hdr.green.chroma.x">0.2650</attribute> <attribute name="hdr.green.chroma.y">0.6900</attribute> <attribute name="hdr.blue.chroma.x">0.1500</attribute> <attribute name="hdr.blue.chroma.y">0.0600</attribute> <attribute name="hdr.whitepoint.chroma.x">0.3127</attribute> <attribute name="hdr.whitepoint.chroma.y">0.3290</attribute> <attribute name="hdr.max.display.luminance">1000</attribute> <attribute name="hdr.min.display.luminance">0.005</attribute> <attribute name="hdr.max.content.lightlevel">967</attribute> <attribute name="hdr.max.frame.avg.lightlevel">343</attribute> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> </asset> <asset type="preview"> <data_file role="source.hdr"> <locale name="en-US"/> <file_name>09736156444-hdr-preview.mov</file_name> <size>9987212</size> <checksum type="md5">739b43b793a8b46037fe8aa29dd9911e</checksum> <attribute name="hdr.format">HDR10</attribute> <attribute name="hdr.red.chroma.x">0.6800</attribute> <attribute name="hdr.red.chroma.y">0.3200</attribute> <attribute name="hdr.green.chroma.x">0.2650</attribute> <attribute name="hdr.green.chroma.y">0.6900</attribute> <attribute name="hdr.blue.chroma.x">0.1500</attribute> <attribute name="hdr.blue.chroma.y">0.0600</attribute> <attribute name="hdr.whitepoint.chroma.x">0.3127</attribute> <attribute name="hdr.whitepoint.chroma.y">0.3290</attribute> <attribute name="hdr.max.display.luminance">1000</attribute> <attribute name="hdr.min.display.luminance">0.005</attribute> <attribute name="hdr.max.content.lightlevel">967</attribute> <attribute name="hdr.max.frame.avg.lightlevel">343</attribute> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> </asset> </assets></package>Only the tags related to the HDR10 delivery are described. The attributes follow the SMPTE ST 2086 metadata guidelines. Refer to Basic Film Metadata Annotated for annotations on other tags.
Note: It is beyond the scope of this document to describe the details of the mastering display attributes. Refer to "SMPTE ST 2086:2014" and the Blu-ray / DECE definitions of Maximum Content Light Level (MaxCLL) / Maximum Frame Average Light Level (MaxFALL) metadata for further information. This document covers only how to deliver the attribute values.
Asset Level Tags |
Assets (required; can be updated) Begins the assets block that references the assets being delivered. In an asset-only update, the |
HDR Source Asset (required) The data file block specifies the source video file and describes the role of the associated file. In this example, the file sent is used as the HDR source, so the role must be The secondary source video must be the same duration as the primary source video so that components such as subtitles and audio can be used with the corresponding HDR video. In this block, the |
HDR Format (required) In this example, the HDR video source is HDR10, which must be specified with the |
HDR10 Chromaticity Attributes (required) The mastering display chromaticity attributes are required and include:
The value listed for each attribute above must be a number with 4 decimal places and the value must be between 0.0 and 1.0 inclusive. The chromaticity attributes can only be used for a source HDR file with format HDR10. For a BT.2020 mastering display with D65, the following values are expected: <attribute name="hdr.red.chroma.x">0.7080</attribute><attribute name="hdr.red.chroma.y">0.2920</attribute><attribute name="hdr.green.chroma.x">0.1700</attribute><attribute name="hdr.green.chroma.y">0.7970</attribute><attribute name="hdr.blue.chroma.x">0.1310</attribute><attribute name="hdr.blue.chroma.y">0.0460</attribute><attribute name="hdr.whitepoint.chroma.x">0.3127</attribute><attribute name="hdr.whitepoint.chroma.y">0.3290</attribute> |
HDR10 Min Luminance Attribute (required) The minimum luminance attribute is required and the value must be a number with up to 3 significant digits and up to 4 decimal places. Value must be greater than or equal to 0.0. The minimum luminance attribute can only be used for source HDR file with format HDR10. |
HDR10 Max Light Level Attribute (optional) The maximum light level attribute is optional. The value is an unsigned short integer. Value must be between 0 and 65535 inclusive. If you provide 0 (zero) as the value, Apple will compute the value based on the cropped source content and insert the calculated value in the encoded bitstream. The maximum light level attribute can only be used for source HDR file with format HDR10. |
HDR10 Max Frame Average Light Level Attribute (optional) The maximum frame average light level attribute is optional. The value is an unsigned short integer. Value must be between 0 and 65535 inclusive. If you provide 0 (zero) as the value, Apple will compute the value based on the cropped source content and insert the calculated value in the encoded bitstream. The maximum frame average light level attribute can only be used for source HDR file with format HDR10. |
HDR Preview Asset (required) The data file block specifies the preview video file and describes the role of the associated file. In this example, the file sent is used as the HDR source, so the role must be The secondary preview video must be the same duration as the primary preview video so that components such as subtitles and audio can be used with the corresponding HDR video. In this block, the |
HDR Format (required) In this example, the HDR preview video source is HDR10, which must be specified with the |
HDR10 Chromaticity Attributes (required) The mastering display chromaticity attributes are required and include:
The value listed for each attribute above must be a number with 4 decimal places and the value must be between 0.0 and 1.0 inclusive. The chromaticity attributes can only be used for a source HDR file with format HDR10. For a BT.2020 mastering display with D65, the following values are expected: <attribute name="hdr.red.chroma.x">0.7080</attribute><attribute name="hdr.red.chroma.y">0.2920</attribute><attribute name="hdr.green.chroma.x">0.1700</attribute><attribute name="hdr.green.chroma.y">0.7970</attribute><attribute name="hdr.blue.chroma.x">0.1310</attribute><attribute name="hdr.blue.chroma.y">0.0460</attribute><attribute name="hdr.whitepoint.chroma.x">0.3127</attribute><attribute name="hdr.whitepoint.chroma.y">0.3290</attribute> |
HDR10 Min Luminance Attribute (required) The minimum luminance attribute is required and the value must be a number with up to 3 significant digits and up to 4 decimal places. Value must be greater than or equal to 0.0. The minimum luminance attribute can only be used for source HDR file with format HDR10. |
HDR10 Max Light Level Attribute (optional) The maximum light level attribute is optional. The value is an unsigned short integer. Value must be between 0 and 65535 inclusive. If you provide 0 (zero) as the value, Apple will compute the value based on the cropped source content and insert the calculated value in the encoded bitstream. The maximum light level attribute can only be used for source HDR file with format HDR10. |
HDR10 Max Frame Average Light Level Attribute (optional) The maximum frame average light level attribute is optional. The value is an unsigned short integer. Value must be between 0 and 65535 inclusive. If you provide 0 (zero) as the value, Apple will compute the value based on the cropped source content and insert the calculated value in the encoded bitstream. The maximum frame average light level attribute can only be used for source HDR file with format HDR10. |
The following XML example shows how to deliver preorder information for HDR video in a metadata-only delivery before delivering that actual HDR asset.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <language>en-US</language> <video> <type>film</type> <subtype>feature</subtype> <vendor_offer_code>408CH98720X103</vendor_offer_code> <vendor_id>09736156444</vendor_id> <isan>0000-0000-03B6-0000-O-0000-0000-2</isan> <eidr>10.5240/CFC2-B507-CE22-B3D4-F32F-2</eidr> <upc>09736156444</upc> <countries_of_origin> <country primary="true">US</country> <country>CA</country> </countries_of_origin> <production_countries> <country primary="true">US</country> </production_countries> <original_spoken_locale>en-US</original_spoken_locale> <title>Forrest Gump</title> <studio_release_title>Forrest Gump</studio_release_title> <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> <production_company>Paramount Pictures</production_company> <copyright_cline>1994 Paramount Pictures</copyright_cline> <theatrical_release_date>2007-05-04</theatrical_release_date> <expected_hdr_formats> <hdr_format>dolby_vision</hdr_format> </expected_hdr_formats> <genres> <genre code="COMEDY-00"/> <genre code="DRAMA-00"/> </genres> <ratings> <rating system="mpaa" reason="for drug content, some sensuality and war violence" code="PG-13"/> </ratings> <cast> <cast_member billing="top"> <display_name>Tom Hanks</display_name> <apple_id>2672649</apple_id> <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> <characters> <character> <reference_id>FORREST</reference_id> <character_name>Forrest Gump</character_name> <character_note>Protagonist</character_note> <character_image> <data_file> <file_name>hanks_as_gump.png</file_name> <size>2813243</size> <checksum type="md5">4ec1addb1f4d3617718b3ebd1ae9ec96</checksum> </data_file> </character_image> </character> <!-- Additional character blocks here if needed for this cast member to handle cases where a cast member plays multiple characters in the film. --> </characters> </cast_member> <!-- Additional cast members here --> </cast> <crew> <crew_member billing="top"> <display_name>Robert Zemeckis</display_name> <apple_id>274059420</apple_id> <roles> <role>Director</role> </roles> </crew_member> <crew_member billing="top"> <display_name>Steve Starkey</display_name> <apple_id>274059432</apple_id> <roles> <role>Producer</role> </roles> </crew_member> <!-- Additional crew members here --> </crew> <chapters> <timecode_format>24/999 1000/nonDrop</timecode_format> <chapter> <start_time>00:00:00:00</start_time> <title locale="en-US">Forrest's Story Begins</title> <artwork_file> <file_name>chapter01.jpg</file_name> <checksum type="md5">ed93d0f3224a353a4cc8d4175d645130</checksum> <size>6591649</size> </artwork_file> </chapter> <chapter> <start_time>00:07:45:23</start_time> <title locale="en-US">Football at Alabama</title><!-- Chapter image can be provided in an artwork file or specified by a timecode. This chapter image is specified by a timecode. --> <artwork_time>00:07:45:23</artwork_time> </chapter><!-- Additional chapters here. --> </chapters> <accessibility_info> <accessibility role="captions" available="true"/> </accessibility_info> <products> <product> <territory>US</territory> <cleared_for_sale>true</cleared_for_sale> <cleared_for_hd_sale>true</cleared_for_hd_sale> <wholesale_price_tier>3</wholesale_price_tier> <hd_wholesale_price_tier>1</hd_wholesale_price_tier> <preorder_sales_start_date>2018-02-10</preorder_sales_start_date> <sales_start_date>2018-03-12</sales_start_date> <available_for_4k_date>2018-02-10</available_for_4k_date> <physical_release_date>2007-08-01</physical_release_date> <cleared_for_hd_vod>false</cleared_for_hd_vod> </product> </products> </video></package>Only the HDR tags specific to preorders are annotated. For other tags, see Basic Film Metadata Annotated.
Video Level Tags |
Expected HDR Formats (optional) If you want to allow preorders on a 4K video before delivering the asset, send a metadata-only package to supply the format of the video so that the format can be displayed on the Store during the preorder period. The value can be Note: If you want the format to be displayed during the preorder period, supply the availability date using the |
Product Level Tags |
Available for 4K Date (optional) The date the 4K video is available for purchase for the territory (this covers both 4K and HDR availability). The following rules apply:
Supplying the date is optional, but highly recommended as it ensures that the film will be labeled as 4K video in the Apple TV app during the preorder period even if you have not yet provided the 4K/HDR asset. The date delivered with the To remove a date previously delivered and not yet passed, send the tag without a value (called an “empty” tag) using one of the following:
Note that simply omitting the tag does not remove the date; you must submit the tag without a value. |
The following XML example shows how to deliver a 4K HDR video in a metadata-plus-assets delivery. The example uses the <available_for_4k_date> tag to indicate the date the 4K video is available for purchase in the Apple TV app for the territory.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <language>en-US</language> <video> <type>film</type> <subtype>feature</subtype> <vendor_offer_code>408CH98720X103</vendor_offer_code> <vendor_id>09736156444</vendor_id> <isan>0000-0000-03B6-0000-O-0000-0000-2</isan> <eidr>10.5240/CFC2-B507-CE22-B3D4-F32F-2</eidr> <upc>09736156444</upc> <countries_of_origin> <country primary="true">US</country> <country>CA</country> </countries_of_origin> <production_countries> <country primary="true">US</country> </production_countries> <original_spoken_locale>en-US</original_spoken_locale> <title>Forrest Gump</title> <studio_release_title>Forrest Gump</studio_release_title> <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> <production_company>Paramount Pictures</production_company> <copyright_cline>1994 Paramount Pictures</copyright_cline> <theatrical_release_date>2007-05-04</theatrical_release_date> <genres> <genre code="COMEDY-00"/> <genre code="DRAMA-00"/> </genres> <ratings> <rating system="mpaa" reason="for drug content, some sensuality and war violence" code="PG-13"/> </ratings> <cast> <cast_member billing="top"> <display_name>Tom Hanks</display_name> <apple_id>2672649</apple_id> <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> <characters> <character> <reference_id>FORREST</reference_id> <character_name>Forrest Gump</character_name> <character_note>Protagonist</character_note> <character_image> <data_file> <file_name>hanks_as_gump.png</file_name> <size>2813243</size> <checksum type="md5">4ec1addb1f4d3617718b3ebd1ae9ec96</checksum> </data_file> </character_image> </character> <!-- Additional character blocks here if needed for this cast member to handle cases where a cast member plays multiple characters in the film. --> </characters> </cast_member> <!-- Additional cast members here --> </cast> <crew> <crew_member billing="top"> <display_name>Robert Zemeckis</display_name> <apple_id>274059420</apple_id> <roles> <role>Director</role> </roles> </crew_member> <crew_member billing="top"> <display_name>Steve Starkey</display_name> <apple_id>274059432</apple_id> <roles> <role>Producer</role> </roles> </crew_member> <!-- Additional crew members here --> </crew> <chapters> <timecode_format>24/999 1000/nonDrop</timecode_format> <chapter> <start_time>00:00:00:00</start_time> <title locale="en-US">Forrest's Story Begins</title> <artwork_file> <file_name>chapter01.jpg</file_name> <checksum type="md5">ed93d0f3224a353a4cc8d4175d645130</checksum> <size>6591649</size> </artwork_file> </chapter> <chapter> <start_time>00:07:45:23</start_time> <title locale="en-US">Football at Alabama</title><!-- Chapter image can be provided in an artwork file or specified by a timecode. This chapter image is specified by a timecode. --> <artwork_time>00:07:45:23</artwork_time> </chapter><!-- Additional chapters here. --> </chapters> <accessibility_info> <accessibility role="captions" available="true"/> </accessibility_info> <assets media_type="video"> <asset type="full"> <data_file role="source.hdr"> <locale name="en-US"/> <file_name>09736156444-4K-source.mov</file_name> <size>3244032000</size> <checksum type="md5">9df86c3e43e7b43ddeabb2ddfe4b8a42</checksum> <attribute name="hdr.format">HDR10</attribute> <attribute name="hdr.red.chroma.x">0.6800</attribute> <attribute name="hdr.red.chroma.y">0.3200</attribute> <attribute name="hdr.green.chroma.x">0.2650</attribute> <attribute name="hdr.green.chroma.y">0.6900</attribute> <attribute name="hdr.blue.chroma.x">0.1500</attribute> <attribute name="hdr.blue.chroma.y">0.0600</attribute> <attribute name="hdr.whitepoint.chroma.x">0.3127</attribute> <attribute name="hdr.whitepoint.chroma.y">0.3290</attribute> <attribute name="hdr.max.display.luminance">1000</attribute> <attribute name="hdr.min.display.luminance">0.005</attribute> <attribute name="hdr.max.content.lightlevel">967</attribute> <attribute name="hdr.max.frame.avg.lightlevel">343</attribute> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> </asset> <asset type="preview"> <data_file role="source.hdr"> <locale name="en-US"/> <file_name>09736156444-4K-preview.mov</file_name> <size>9987212</size> <checksum type="md5">739b43b793a8b46037fe8aa29dd9911e</checksum> <attribute name="hdr.format">HDR10</attribute> <attribute name="hdr.red.chroma.x">0.6800</attribute> <attribute name="hdr.red.chroma.y">0.3200</attribute> <attribute name="hdr.green.chroma.x">0.2650</attribute> <attribute name="hdr.green.chroma.y">0.6900</attribute> <attribute name="hdr.blue.chroma.x">0.1500</attribute> <attribute name="hdr.blue.chroma.y">0.0600</attribute> <attribute name="hdr.whitepoint.chroma.x">0.3127</attribute> <attribute name="hdr.whitepoint.chroma.y">0.3290</attribute> <attribute name="hdr.max.display.luminance">1000</attribute> <attribute name="hdr.min.display.luminance">0.005</attribute> <attribute name="hdr.max.content.lightlevel">967</attribute> <attribute name="hdr.max.frame.avg.lightlevel">343</attribute> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> </asset> </assets> <products> <product> <territory>US</territory> <cleared_for_sale>true</cleared_for_sale> <cleared_for_hd_sale>true</cleared_for_hd_sale> <wholesale_price_tier>3</wholesale_price_tier> <hd_wholesale_price_tier>1</hd_wholesale_price_tier> <sales_start_date>2020-03-12</sales_start_date> <available_for_4k_date>2020-03-20</available_for_4k_date> <physical_release_date>2007-08-01</physical_release_date> <cleared_for_hd_vod>false</cleared_for_hd_vod> </product> </products> </video></package>Only the tags specific to 4K are annotated. For other tags, see Basic Film Metadata Annotated.
Product Level Tags |
Available for 4K Date (optional) The date the 4K video is available for purchase for the territory (this covers both 4K and HDR availability). The following rules apply:
To remove a date previously delivered and not yet passed, send the tag without a value (called an “empty” tag) using one of the following:
Note that simply omitting the tag does not remove the date; you must submit the tag without a value. |
The following asset-only update example shows how to deliver HDR and SDR videos in the same delivery. In this example, the HDR video source is HDR10 (Dolby Vision HDR titles can be down-mixed to SDR, so delivery of both HDR and SDR is not needed for Dolby deliveries). The HDR and SDR videos are delivered as separate data files on the full asset.
Note: If you deliver embedded audio with the HDR source and the SDR video also has embedded audio, you must indicate which audio to use by supplying the ignore_audio attribute on the data file of the video whose audio you do not want to use. In this example, the audio on the HDR video will be ignored.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider><!-- The vendor_id referenced below is the vendor ID of the previously-delivered primary source video. --> <assets media_type="video" vendor_id="09736156444"> <asset type="full"> <data_file role="source.hdr"> <locale name="en-US"/> <file_name>09736156444-hdr-source.mov</file_name> <size>3244032000</size> <checksum type="md5">9df86c3e43e7b43ddeabb2ddfe4b8a42</checksum> <attribute name="hdr.format">HDR10</attribute> <attribute name="hdr.red.chroma.x">0.6800</attribute> <attribute name="hdr.red.chroma.y">0.3200</attribute> <attribute name="hdr.green.chroma.x">0.2650</attribute> <attribute name="hdr.green.chroma.y">0.6900</attribute> <attribute name="hdr.blue.chroma.x">0.1500</attribute> <attribute name="hdr.blue.chroma.y">0.0600</attribute> <attribute name="hdr.whitepoint.chroma.x">0.3127</attribute> <attribute name="hdr.whitepoint.chroma.y">0.3290</attribute> <attribute name="hdr.max.display.luminance">1000</attribute> <attribute name="hdr.min.display.luminance">0.005</attribute> <attribute name="hdr.max.content.lightlevel">967</attribute> <attribute name="hdr.max.frame.avg.lightlevel">343</attribute> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute><!-- Embedded audio in HDR source will be ignored. --> <attribute name="ignore_audio">true</attribute> <attribute name="image.textless_master">true</attribute> </data_file><!-- SDR asset with embedded audio that will be used as primary audio. --> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-sdr-source.mov</file_name> <size>7842440399</size> <checksum type="md5">ed93d0f3224a353a4cc8d4175d645130</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="primary_audio">true</attribute> <attribute name="image.textless_master">true</attribute> </data_file> </asset> <asset type="preview"> <data_file role="source.hdr"> <locale name="en-US"/> <file_name>09736156444-hdr-preview.mov</file_name> <size>9987212</size> <checksum type="md5">739b43b793a8b46037fe8aa29dd9911e</checksum> <attribute name="hdr.format">HDR10</attribute> <attribute name="hdr.red.chroma.x">0.6800</attribute> <attribute name="hdr.red.chroma.y">0.3200</attribute> <attribute name="hdr.green.chroma.x">0.2650</attribute> <attribute name="hdr.green.chroma.y">0.6900</attribute> <attribute name="hdr.blue.chroma.x">0.1500</attribute> <attribute name="hdr.blue.chroma.y">0.0600</attribute> <attribute name="hdr.whitepoint.chroma.x">0.3127</attribute> <attribute name="hdr.whitepoint.chroma.y">0.3290</attribute> <attribute name="hdr.max.display.luminance">1000</attribute> <attribute name="hdr.min.display.luminance">0.005</attribute> <attribute name="hdr.max.content.lightlevel">967</attribute> <attribute name="hdr.max.frame.avg.lightlevel">343</attribute> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="ignore_audio">true</attribute> <attribute name="image.textless_master">true</attribute> </data_file> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-sdr-preview-source.mov</file_name> <size>44578423</size> <checksum type="md5">d645c8d41ed93d1303a4c0f3224a3575</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="primary_audio">true</attribute> <attribute name="image.textless_master">true</attribute> </data_file> </asset> </assets></package>Asset Level Tags |
Assets (required; can be updated) Begins the assets block that references the assets being delivered. In an asset-only update, the |
HDR Source Asset (required) The data file block specifies the source video file and describes the role of the associated file. In this example, the file sent is used as the HDR10 source, so the role must be The HDR source video must be the same duration as the SDR source video so that components such as subtitles and audio can be used for both HDR source and SDR source. In this block, the |
HDR Format (required) In this example, the HDR video source is HDR10, which must be specified with the |
HDR10 Chromaticity Attributes (required) The mastering display chromaticity attributes are required and include:
The value listed for each attribute above must be a number with 4 decimal places and the value must be between 0.0 and 1.0 inclusive. The chromaticity attributes can only be used for a source HDR file with format HDR10. For a BT.2020 mastering display with D65, the following values are expected: <attribute name="hdr.red.chroma.x">0.7080</attribute><attribute name="hdr.red.chroma.y">0.2920</attribute><attribute name="hdr.green.chroma.x">0.1700</attribute><attribute name="hdr.green.chroma.y">0.7970</attribute><attribute name="hdr.blue.chroma.x">0.1310</attribute><attribute name="hdr.blue.chroma.y">0.0460</attribute><attribute name="hdr.whitepoint.chroma.x">0.3127</attribute><attribute name="hdr.whitepoint.chroma.y">0.3290</attribute> |
HDR10 Min Luminance Attribute (required) The minimum luminance attribute is required and the value must be a number with up to 3 significant digits and up to 4 decimal places. Value must be greater than or equal to 0.0. The minimum luminance attribute can only be used for source HDR file with format HDR10. |
HDR10 Max Light Level Attribute (optional) The maximum light level attribute is optional. The value is an unsigned short integer. Value must be between 0 and 65535 inclusive. If you provide 0 (zero) as the value, Apple will compute the value based on the cropped source content and insert the calculated value in the encoded bitstream. The maximum light level attribute can only be used for source HDR file with format HDR10. |
HDR10 Max Frame Average Light Level Attribute (optional) The maximum frame average light level attribute is optional. The value is an unsigned short integer. Value must be between 0 and 65535 inclusive. If you provide 0 (zero) as the value, Apple will compute the value based on the cropped source content and insert the calculated value in the encoded bitstream. The maximum frame average light level attribute can only be used for source HDR file with format HDR10. |
Ignore Embedded Audio (optional if a video file has embedded audio and if delivering another primary audio file) In this example, the HDR video source includes embedded audio, but the audio on the SDR video will be used as the primary audio, so the value is set to true. Note that |
|
SDR Source Data File (required) The data file block specifies the SDR source video file and describes the role of the associated file. In this example, the file sent is used as the SDR source, so the role must be In this block, the |
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 See Language Codes for more details. |
File Name (required) The name of the SDR data file. 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. |
File Size (required) The size in bytes of the data file. Do not specify any commas nor period delimiters. |
Checksum (required) The MD5 checksum of the data file. See the Checksums section for more information. |
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
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. |
Primary Audio (optional) In this example, the SDR video source includes embedded audio, and it will be used as the primary audio. You use the Note: This primary audio should align with the primary audio locale you want for the package. For example, if the movie is dubbed in Russian and is sold only in Russia, the primary audio would be "ru" even though the video source is "en-US". |
Textless Master (required) 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 “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 |
|
HDR Preview Asset (required) The data file block specifies the preview video file and describes the role of the associated file. In this example, the file sent is used as the HDR source, so the role must be The secondary preview video must be the same duration as the primary preview video so that components such as subtitles and audio can be used with the corresponding HDR video. In this block, the |
HDR Format (required) In this example, the HDR preview video source is HDR10, which must be specified with the |
HDR10 Chromaticity Attributes (required) The mastering display chromaticity attributes are required and include:
The value listed for each attribute above must be a number with 4 decimal places and the value must be between 0.0 and 1.0 inclusive. The chromaticity attributes can only be used for a source HDR file with format HDR10. For a BT.2020 mastering display with D65, the following values are expected: <attribute name="hdr.red.chroma.x">0.7080</attribute><attribute name="hdr.red.chroma.y">0.2920</attribute><attribute name="hdr.green.chroma.x">0.1700</attribute><attribute name="hdr.green.chroma.y">0.7970</attribute><attribute name="hdr.blue.chroma.x">0.1310</attribute><attribute name="hdr.blue.chroma.y">0.0460</attribute><attribute name="hdr.whitepoint.chroma.x">0.3127</attribute><attribute name="hdr.whitepoint.chroma.y">0.3290</attribute> |
HDR10 Min Luminance Attribute (required) The minimum luminance attribute is required and the value must be a number with up to 3 significant digits and up to 4 decimal places. Value must be greater than or equal to 0.0. The minimum luminance attribute can only be used for source HDR file with format HDR10. |
HDR10 Max Light Level Attribute (optional) The maximum light level attribute is optional. The value is an unsigned short integer. Value must be between 0 and 65535 inclusive. If you provide 0 (zero) as the value, Apple will compute the value based on the cropped source content and insert the calculated value in the encoded bitstream. The maximum light level attribute can only be used for source HDR file with format HDR10. |
HDR10 Max Frame Average Light Level Attribute (optional) The maximum frame average light level attribute is optional. The value is an unsigned short integer. Value must be between 0 and 65535 inclusive. If you provide 0 (zero) as the value, Apple will compute the value based on the cropped source content and insert the calculated value in the encoded bitstream. The maximum frame average light level attribute can only be used for source HDR file with format HDR10. |
|
SDR Preview Source Data File (required) The data file block specifies the SDR source video file for the preview and describes the role of the associated file. In this example, the file sent is used as the SDR source, so the role must be In this block, the |
Locale Name (required for full source, preview source, and audio) Identifies the language that is spoken in the audio on the preview 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 See Language Codes for more details. |
File Name (required) The name of the SDR preview data file. 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. |
File Size (required) The size in bytes of the data file. Do not specify any commas nor period delimiters. |
Checksum (required) The MD5 checksum of the data file. See the Checksums section for more information. |
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
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. |
Preview Primary Audio (optional) In this example, the SDR preview source includes embedded audio, and it will be used as the primary audio. You use the Note: This primary audio should align with the primary audio locale you want for the package. For example, if the movie is dubbed in Russian and is sold only in Russia, the primary audio would be "ru" even though the video source is "en-US". |
Textless Master (required) Specifies whether or not the preview 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 |
|
The Apple TV app provides support for our Japanese customers with phonetic title fields in the metadata. Only films for sale in Japan can include phonetic title information.
This example shows the optional additions to metadata for a film whose native language is Japanese that are for sale in English-speaking countries.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <language>ja</language> <provider>Toho</provider> <video> <title>千と千尋の神隠し</title> <phonetic_title>セン ト チヒロ ノ カミカクシ</phonetic_title> ... </video></package>Only the additions for Japanese language support are described.
|
|
Title (required, 1-255 bytes; may be updated) The name of this film for the |
|
 Phonetic Film Title (required) The phonetic title tag is required when a Japanese title is provided. The reading (furigana) of the film title must be provided in full-width katakana or hiragana. If any meaningful separation units exist, they should be delimited using a space character. This phonetic information provides a better search experience for the user. Note: This tag is for Japanese phonetic titles only. Use this tag within the 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 (for example, Japanese) characters, this can equate to as few as 71 characters. |
This example shows the optional additions to metadata for non-Japanese language films that are for sale to customers in Japan. The only difference between this and the previous example is that the "native" <language> is English and the phonetic title tag provides the translation of the English title in Katakana. Also, the <phonetic_title> tag is placed within a <locale> tag instead of directly under the <video> tag.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <language>en-US</language> <provider>Miramax</provider> <video> <original_spoken_locale>en-US</original_spoken_locale> <title>Bridget Jones’s Diary</title> ... <locales> <locale name="ja"> <title>ブリジット・ジョーンズの日記</title> <phonetic_title>ブリジット ジョーンズ ノ ニッキ</phonetic_title> <synopsis>ヘレン・フィールディングのベストセラー小説を映画化したラブコメディ。ロンドンに暮らす32歳の独身女性・ブリジットは二日酔いで新年を迎え、しっかり生きるため日記をつけ始める。“ユニバーサル・シネマ・コレクション”。</synopsis> </locale> </locales> ... </video></package>
|
|
 Locales (optional) Provides a mechanism to specify both regional and language variation for film title and synopsis. |
|
 Locale Name (required within the <locales> tag) Identifies a language and an optional region where the language is spoken. As a best practice when specifying a language, use the region subtag (for example, the See Language Codes for more details. |
|
 Title (required, 1-255 bytes; may be updated) The localized name of this film for the locale specified. |
|
 Phonetic Film Title (required) The phonetic title tag is required when a Japanese title is provided. It provides the reading (furigana) of the film title in full-width katakana or hiragana. If any meaningful separation units exist, they should be delimited using a space character. This phonetic information provides a better search experience for the user. Note: This tag is for Japanese phonetic titles only. Use this tag within the 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 (for example, Japanese) characters, this can equate to as few as 71 characters. |
|
 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. |
|
A metadata-only delivery delivers the metadata with product information, but without including the video assets or chapters.
This example shows how to deliver only the metadata for new content (content that does not already exist in the Apple TV app). For complete details on updatable information, see Metadata and Asset Updates.
Metadata-only deliveries need to be in an .itmsp package, consisting only of the metadata.xml file. For example, a package for film with a Vendor Identifier 09736156444 would be delivered in a package directory titled "09736156444.itmsp" with only metadata.xml enclosed.
Note: Do not deliver chapter information in a metadata-only package for a new delivery. You can only add chapters to a delivery that includes the full asset, or if the full asset has been delivered previously. A metadata-only package for a new delivery that includes chapters will be blocked.
Below is an example metadata.xml file for a new metadata-only delivery of the feature film Forrest Gump.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <language>en-US</language> <video> <type>film</type> <subtype>feature</subtype> <production_company>Paramount Pictures</production_company> <vendor_id>09736156444</vendor_id> <isan>0000-0000-03B6-0000-O-0000-0000-2</isan> <upc>09736156444</upc> <countries_of_origin> <country primary="true">US</country> <country>CA</country> </countries_of_origin> <production_countries> <country primary="true">US</country> </production_countries> <original_spoken_locale>en-US</original_spoken_locale> <copyright_cline>1994 Paramount Pictures</copyright_cline> <theatrical_release_date>2007-05-04</theatrical_release_date> <title>Forrest Gump</title> <studio_release_title>Forrest Gump</studio_release_title> <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> <genres> <genre code="COMEDY-00"/> <genre code="DRAMA-00"/> </genres> <ratings> <rating system="mpaa" reason="for drug content, some sensuality and war violence" code="PG-13"/> </ratings> <cast> <cast_member billing="top"> <display_name>Tom Hanks</display_name> <apple_id>2672649</apple_id> <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> <characters> <character> <reference_id>FORREST</reference_id> <character_name>Forrest Gump</character_name> <character_note>Protagonist</character_note> <character_image> <data_file> <file_name>hanks_as_gump.png</file_name> <size>2813243</size> <checksum type="md5">4ec1addb1f4d3617718b3ebd1ae9ec96</checksum> </data_file> </character_image> </character> <!-- Additional character blocks here if needed for this cast member to handle cases where a cast member plays multiple characters in the film. --> </characters> </cast_member> <!-- Additional cast members here --> </cast> <crew> <crew_member billing="top"> <display_name>Robert Zemeckis</display_name> <apple_id>274059420</apple_id> <roles> <role>Director</role> </roles> </crew_member> <crew_member billing="top"> <display_name>Steve Starkey</display_name> <apple_id>274059432</apple_id> <roles> <role>Producer</role> </roles> </crew_member> <!-- Additional crew members here --> </crew> <accessibility_info> <accessibility role="captions" available="true"/> </accessibility_info> <products> <product> <territory>US</territory> <cleared_for_sale>true</cleared_for_sale> <cleared_for_hd_sale>true</cleared_for_hd_sale> <wholesale_price_tier>3</wholesale_price_tier> <preorder_sales_start_date>2006-02-10</preorder_sales_start_date> <sales_start_date>2006-03-12</sales_start_date> <cleared_for_vod>true</cleared_for_vod> <vod_type>New Release</vod_type> <available_for_vod_date>2007-11-12</available_for_vod_date> <unavailable_for_vod_date>2008-11-12</unavailable_for_vod_date> <physical_release_date>2007-08-01</physical_release_date> <cleared_for_hd_vod>false</cleared_for_hd_vod> </product> </products> </video></package>Video, audio, and artwork assets can be delivered independently of metadata. Assets cannot be delivered unless the metadata has already been sent and imported. If the assets are sent without previous metadata delivery, the asset delivery will fail.
Important: In order to deliver assets separately from the film's metadata, the correct vendor ID that references the already delivered metadata must be supplied in the metadata.xml file.
For any questions regarding asset-only delivery, please contact your Technical Representative.
Asset-only deliveries still need to be in an .itmsp package, but only consist of a short metadata file, the video assets, and the artwork. For example, a package for a film with a Vendor Identifier 09736156444 would be delivered in a package directory titled "09736156444.itmsp" and might look like this:
metadata.xml
09736156444-source.mov
09736156444-US-preview.mov
09736156444.jpg
09736156444-english.scc
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <assets media_type="video" vendor_id="09736156444"> <asset type="full"> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-source.mov</file_name> <size>2595225600</size> <checksum type="md5">2a793a8b46037fe8aa29dd739b49911a</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> <data_file role="captions"> <file_name>09736156444-english.scc</file_name> <size>9511</size> <checksum type="md5">5a793a8b46037fe8aa2bdd739b49911a</checksum> <locale name="en-US"/> <attribute name="program.start.timecode">-01:00:00:00 </attribute> </data_file> </asset> <asset type="preview"> <preview_image_time format="24/999 1000/nonDrop">00:00:57:02</preview_image_time> <territories> <territory>WW</territory> </territories> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-US-preview.mov</file_name> <size>9987212</size> <checksum type="md5">739b43b793a8b46037fe8aa29dd9911e</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> </asset> <asset type="artwork"> <territories> <territory>WW</territory> </territories> <data_file> <locale name="en-US"/> <file_name>09736156444_US.jpg</file_name> <size>6591649</size> <checksum type="md5">43e7dddfe4b8ab433ede429df86cabb</checksum> </data_file> </asset> </assets></package>If product offerings change at any point after initial delivery, an update can be sent using Transporter. The newly sent package is compared against the current offering and changes are automatically applied. A metadata-only update delivers the product information, but without including the assets. After a successful, initial upload of metadata and assets, you can make changes to the metadata by delivering a metadata-only update. You do not need to include any asset files with metadata-only deliveries and you can omit the <assets> block from the metadata.xml file.
If asset files are provided and properly referenced in the metadata, then the corresponding checksums will be compared to the checksums of the assets currently on file, and if any checksums are different, the assets will be updated as necessary. If the checksums are unchanged, then the import package (.itmsp) does not need to contain the asset files, even if they are listed in the metadata, because those asset files will be ignored.
Assets can be removed through an asset-only update or metadata-plus-assets update. In this case, you would include the <asset> block to specify which asset should be removed. See Remove Alternate Audio and Change Locale.
For complete details on what can be updated, see Metadata and Asset Updates.
Below is an example metadata.xml update file for the Basic Film Metadata Example. In this example, the update will replace the currently displayed <copyright_cline> for the United States, add a UK rating, and a U.S. sales start date. It also removes the clearance for HD sale. In the following example, only metadata changes are made (in bold), and all asset references have been removed.
You can also update chapter titles and images in the same package if you include the <chapters> block and if you include the chapter images. Chapter images can be provided in an artwork file or specified by a timecode. You must include all chapters, not just the one you are updating. In the following example, the package would include the metadata.xml file and chapter01.jpg. If you include the <chapters> block and provide artwork files for chapter images, but do not include the image files in the package, the images will not be replaced.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <language>en-US</language> <video> <type>film</type> <subtype>feature</subtype> <production_company>Paramount Pictures</production_company> <vendor_id>09736156444</vendor_id> <isan>0000-0000-03B6-0000-O-0000-0000-2</isan> <upc>09736156444</upc> <countries_of_origin> <country primary="true">US</country> <country>CA</country> </countries_of_origin> <production_countries> <country primary="true">US</country> </production_countries> <original_spoken_locale>en-US</original_spoken_locale> <copyright_cline>1995 Paramount Pictures</copyright_cline> <theatrical_release_date>2007-05-04</theatrical_release_date> <title>Forrest Gump</title> <studio_release_title>Forrest Gump</studio_release_title> <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> <genres> <genre code="COMEDY-00"/> <genre code="DRAMA-00"/> </genres> <ratings> <rating system="mpaa" reason="for drug content, some sensuality and war violence" code="PG-13"/> <rating system="bbfc" code="12A"/> </ratings> <cast> <cast_member billing="top"> <display_name>Tom Hanks</display_name> <apple_id>2672649</apple_id> <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> <characters> <character> <reference_id>FORREST</reference_id> <character_name>Forrest Gump</character_name> <character_note>Protagonist</character_note> <character_image> <data_file> <file_name>hanks_as_gump.png</file_name> <size>2813243</size> <checksum type="md5">4ec1addb1f4d3617718b3ebd1ae9ec96</checksum> </data_file> </character_image> </character> <!-- Additional character blocks here if needed for this cast member to handle cases where a cast member plays multiple characters in the film. --> </characters> </cast_member> <!-- Additional cast members here --> </cast> <crew> <crew_member billing="top"> <display_name>Robert Zemeckis</display_name> <apple_id>274059420</apple_id> <roles> <role>Director</role> </roles> </crew_member> <crew_member billing="top"> <display_name>Steve Starkey</display_name> <apple_id>274059432</apple_id> <roles> <role>Producer</role> </roles> </crew_member> <!-- Additional crew members here --> </crew> <chapters> <timecode_format>24/999 1000/nonDrop</timecode_format> <chapter> <start_time>00:00:00:00</start_time> <title locale="en-US">Forrest's Story Begins</title><!-- Chapter image can be provided in an artwork file or specified by a timecode. This chapter image is provided in an artwork file. --> <artwork_file> <file_name>chapter01.jpg</file_name> <checksum type="md5">ed93d0f3224a353a4cc8d4175d645130</checksum> <size>6591649</size> </artwork_file> </chapter> <chapter> <start_time>00:07:45:23</start_time> <title locale="en-US">Football at Alabama</title><!-- Chapter image can be provided in an artwork file or specified by a timecode. This chapter image is specified by a timecode. --> <artwork_time>00:07:45:23</artwork_time> </chapter> <!-- Additional chapters here. --> </chapters> <accessibility_info> <accessibility role="captions" available="true"/> </accessibility_info> <products> <product> <territory>US</territory> <cleared_for_sale>true</cleared_for_sale> <cleared_for_hd_sale>true</cleared_for_hd_sale> <wholesale_price_tier>3</wholesale_price_tier> <preorder_sales_start_date>2006-02-10</preorder_sales_start_date> <sales_start_date>2006-04-11</sales_start_date> <cleared_for_vod>true</cleared_for_vod> <vod_type>New Release</vod_type> <available_for_vod_date>2007-11-12</available_for_vod_date> <unavailable_for_vod_date>2008-11-12</unavailable_for_vod_date> <physical_release_date>2007-08-01</physical_release_date> <cleared_for_hd_vod>false</cleared_for_hd_vod> </product> </products> </video></package>After an initial import of the package, you can send a metadata update to add or modify territory rights and pricing. In the following example, new territory pricing and clearances are being added for Australia and New Zealand, and Canada is being removed. This update includes only the <products> block and the content identifier (for example, <vendor_id>) used when the film was first delivered. You do not need to include the <assets> block or any other tags in the <metadata> block.
To remove content, set <cleared_for_sale> to false for the specified <territory>. In the <product> block, supply only the <cleared_for_sale> and <territory> tags; you do not need to supply any other tags within the <product> block for the territory you are removing.
Note: Include only the territories you are adding, modifying, or removing; you do not need to deliver all territories.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <language>en-US</language> <video> <type>film</type> <vendor_id>09736156444</vendor_id> <isan>0000-0000-03B6-0000-O-0000-0000-2</isan> <upc>09736156444</upc> <products> <product> <territory>AU</territory> <sales_start_date>2006-10-01</sales_start_date> <cleared_for_sale>true</cleared_for_sale> <cleared_for_hd_sale>true</cleared_for_hd_sale> <wholesale_price_tier>3</wholesale_price_tier> <preorder_sales_start_date>2006-10-10</preorder_sales_start_date> <cleared_for_vod>true</cleared_for_vod> <vod_type>New Release</vod_type> <available_for_vod_date>2007-11-12</available_for_vod_date> <unavailable_for_vod_date>2008-11-12</unavailable_for_vod_date> <physical_release_date>2007-08-01</physical_release_date> <cleared_for_hd_vod>false</cleared_for_hd_vod> </product> <product> <territory>NZ</territory> <sales_start_date>2006-10-01</sales_start_date> <cleared_for_sale>true</cleared_for_sale> <cleared_for_hd_sale>true</cleared_for_hd_sale> <wholesale_price_tier>3</wholesale_price_tier> <preorder_sales_start_date>2006-10-10</preorder_sales_start_date> <cleared_for_vod>true</cleared_for_vod> <vod_type>New Release</vod_type> <available_for_vod_date>2007-11-12</available_for_vod_date> <unavailable_for_vod_date>2008-11-12</unavailable_for_vod_date> <physical_release_date>2007-08-01</physical_release_date> <cleared_for_hd_vod>false</cleared_for_hd_vod> </product> <product> <territory>CA</territory> <cleared_for_sale>false</cleared_for_sale> </product> </products> </video></package>Chapter titles and chapter artwork can be added or changed, however you must send all chapters on redelivery, not just the ones being updated. Two examples appear below: one where the previously-delivered artwork was incorrect, and the other that had a missing title locale.
Note: You can also send chapters with an asset-only update. See Film Asset-Only Update with Chapters.
In the following example, the second chapter was originally sent with an incorrect timecode for the artwork. Even though the error affects only one chapter, all chapters must be redelivered. Portions of the XML have been omitted for the sake of brevity.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <language>en-US</language> <video> . . . <!-- The second chapter has an updated artwork timecode; however, all chapters must be redelivered, not just the chapter with the updated artwork timecode. --> <chapters> <timecode_format>24/999 1000/nonDrop</timecode_format> <chapter> <start_time>00:00:00:00</start_time> <title locale="en-US">Forrest's Story Begins</title><!-- Chapter image can be provided in an artwork file or specified by a timecode. This chapter image is provided in an artwork file. --> <artwork_file> <file_name>chapter01.jpg</file_name> <checksum type="md5">ed93d0f3224a353a4cc8d4175d645130</checksum> <size>6591649</size> </artwork_file> </chapter> <chapter> <start_time>00:07:45:23</start_time> <title locale="en-US">Football at Alabama</title><!-- Chapter image can be provided in an artwork file or specified by a timecode. This chapter image is specified by a timecode. --> <artwork_time>00:07:46:14</artwork_time> </chapter> <!-- Remaining chapters here. --> </chapters> . . . </video></package>In the following multiple language example, the second chapter was missing a locale for the title. Even though the error affects only one chapter, all chapters must be redelivered. Portions of the XML have been omitted for the sake of brevity.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <language>en-US</language> <video> . . . <!-- The second chapter was missing a French title; however, all chapters must be redelivered, not just the chapter with the missing locale. --> <chapters> <timecode_format>24/999 1000/nonDrop</timecode_format> <chapter> <start_time>00:00:00:00</start_time> <titles> <title locale="en-US">Forrest's Story Begins</title> <title locale="de-DE">Die Geschichte von Forrest beginnt</title> <title locale="fr-FR">L'Histoire de Forest Commence</title> </titles><!-- Chapter image can be provided in an artwork file or specified by a timecode. This chapter image is provided in an artwork file. --> <artwork_file> <file_name>chapter01.jpg</file_name> <checksum type="md5">ed93d0f3224a353a4cc8d4175d645130</checksum> <size>6748922</size> </artwork_file> </chapter> <chapter> <start_time>00:07:45:23</start_time> <titles> <title locale="en-US">Football at Alabama</title> <title locale="de-DE">Fußball an Alabama</title> <title locale="fr-FR">Football en Alabama</title> </titles><!-- Chapter image can be provided in an artwork file or specified by a timecode. This chapter image is specified by a timecode. --> <artwork_time>00:07:45:23</artwork_time> </chapter> <!-- Additional chapters here. --> </chapters> . . . </video></package>Assets (including video, audio, artwork, and so on) can be delivered independently of metadata for asset-only updates. This is especially helpful if these assets need to be replaced in the Store due to encoding or other issues. Assets cannot be delivered unless the metadata has already been sent and imported. If the assets are sent without metadata to which it can be attached, delivery will fail.
Important: In order to deliver assets separately from the film's metadata, the correct vendor ID that references the already delivered metadata must be supplied in the metadata.xml file for asset-only updates. When delivering updated source video, keep in mind that the duration of the source video must match the durations of related components (such as subtitles, forced subtitles, alternate audio, SDH, AD, and CC). If the duration of the source video has changed, you must also deliver updates of any related components intended to track to the same timeline as the source video.
For any questions regarding asset-only delivery, contact your Technical Representative.
An asset-only update should only consist of a short metadata file along with the assets. All metadata must be correct and complete, and the <assets> block should be included referencing any assets to be added, replaced, or removed.
In the first example below, the full asset is being replaced and a new alternate audio file is being added.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <assets media_type="video" vendor_id="09736156444"> <asset type="full"> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-source.mov</file_name> <size>2595225600</size> <checksum type="md5">39b499112fe8aa29dd7a793a8b46037a</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> <data_file role="audio"> <locale name="de-DE"/> <file_name>audio_DE.mov</file_name> <size>4916659</size> <checksum type="md5">9df86c3e43e7b43ddeabb2ddfe4b8a42</checksum> </data_file> </asset> </assets></package>The example below shows an update to a film that was previously delivered without closed captions and with the <accessibility_info> set to ARCHIVAL_CONTENT, which is no longer supported. In addition to updating the video asset, this update includes the closed captions asset file.
Note that if you send an asset-only update and captions are not available, you can include the <accessibility_info> tag within the <asset> block.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <assets media_type="video" vendor_id="09736156444"> <asset type="full"> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-source.mov</file_name> <size>2595225600</size> <checksum type="md5">39b499112fe8aa29dd7a793a8b46037a</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> <data_file role="captions"> <file_name>captions.scc</file_name> <size>9511</size> <checksum type="md5">b46037fe5a793a839b49911a8aa2bdd7</checksum> <locale name="en-US"/> </data_file> </asset> </assets></package>Below is an example metadata.xml file to update crop dimensions for the video delivered in the Basic Film Metadata Example. Only the video asset along with the source data file should be referenced in the metadata. Only the metadata.xml should be included in the .itmsp package; you do not need to redeliver the video asset.
<?xml version="1.0" encoding="UTF-8"?> <package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <assets media_type="video" vendor_id="09736156444"> <asset type="full"> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-source.mov</file_name> <size>2595225600</size> <checksum type="md5">39b499112fe8aa29dd7a793a8b46037a</checksum> <attribute name="crop.top">5</attribute> <attribute name="crop.bottom">5</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> </asset> </assets></package>If you need to update chapter metadata along with the full video asset, you can send the <chapters> inside the <asset> block for the full source video in an asset-only update. In this example, only the full asset and chapter information is being updated. Note that if you need to update the chapter information, but not the full video asset, you can still use the <chapters> block inside the <video> block as described in Chapter Update Examples.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <assets media_type="video" vendor_id="09736156444"> <asset type="full"> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-source.mov</file_name> <size>2595225600</size> <checksum type="md5">2a793a8b46037fe8aa29dd739b49911a</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> <chapters> <timecode_format>24/999 1000/nonDrop</timecode_format> <chapter> <start_time>00:00:00:00</start_time> <title locale="en-US">Forrest's Story Begins</title><!-- Chapter image can be provided in an artwork file or specified by a timecode. This chapter image is provided in an artwork file. --> <artwork_file> <file_name>chapter01.jpg</file_name> <checksum type="md5">ed93d0f3224a353a4cc8d4175d645130</checksum> <size>2342355</size> </artwork_file> </chapter> <chapter> <start_time>00:07:45:23</start_time> <title locale="en-US">Football at Alabama</title><!-- Chapter image can be provided in an artwork file or specified by a timecode. This chapter image is specified by a timecode. --> <artwork_time>00:07:45:23</artwork_time> </chapter> </chapters> </asset> </assets></package>Below is an example metadata.xml file to update closed captions for the Basic Film Metadata Example. In the initial delivery, the <accessibility_info> was set to true. Because the closed captions asset is being re-delivered and the availability information has not changed, the <accessibility_info> block does not need to be supplied. Note that only the asset being replaced is referenced in the metadata. Only the metadata.xml and 09736156444-corrected-english.scc files should be included in the .itmsp package.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <assets media_type="video" vendor_id="09736156444"> <asset type="full"> <data_file role="captions"> <locale name="en-US"/> <file_name>09736156444-corrected-english.scc</file_name> <size>9613</size> <checksum type="md5">3a80375a79fe8aa2bb49911add739b46</checksum> <attribute name="program.start.timecode">-01:00:00:00</attribute> </data_file> </asset> </assets></package>In the example below, closed captions are being updated, but the locale of the new captions file is different from the locale on the existing captions file. When updating a closed caption file, the locale must match the locale of the file you are replacing. 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">).
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <assets media_type="video" vendor_id="09736156444"> <asset type="full"> <data_file role="captions" remove="true"> <locale name="en-US"/> <file_name>09736156444-english.scc</file_name> <size>9613</size> <checksum type="md5">3a80375a79fe8aa2bb49911add739b46</checksum> </data_file> <data_file role="captions"> <locale name="es"/> <file_name>09736156444-spanish.scc</file_name> <size>4521</size> <checksum type="md5">31eb41f44b1649d09d6cce6a88342024</checksum> <attribute name="program.start.timecode">-01:00:00:00</attribute> </data_file> </asset> </assets></package>Below is an example metadata.xml file to update the preview trailer for Basic Film Metadata Example. Only the preview asset along with associated data files should be referenced in the metadata. Only the metadata.xml and 03615649744-US-preview.mov file should be included in the .itmsp package.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <assets media_type="video" vendor_id="09736156444"> <asset type="preview"> <preview_image_time format="24/999 1000/nonDrop">00:00:57:02</preview_image_time> <territories> <territory>WW</territory> </territories> <data_file role="source"> <locale name="en-US"/> <file_name>03615649744-US-preview.mov</file_name> <size>9981365</size> <checksum type="md5">3a8b4608aa29dd9911e739b37fe43b79</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> </asset> </assets></package>The example below shows how to deliver a new audio data file for the video source, without having to redeliver the source video. This is useful for replacing a stereo audio file with a 5.1 audio file, or when replacing an audio file that has been rejected by Quality Control. The replacement audio file must have the same vendor ID and locale code as the full source video.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <assets media_type="video" vendor_id="09736156444"> <asset type="full"> <data_file role="audio"> <locale name="en-US"/> <file_name>audio_51.mov</file_name> <size>6654829</size> <checksum type="md5">3ddeabf86c3e43e7b4bb2ddfe49d8a42</checksum> </data_file> </asset> </assets></package>The example below shows how to deliver a new 7.1 surround audio data file for a film previously delivered.
The following summarizes the effects of updating existing content:
Existing film with 2.0, 7.1 surround audio, and 5.1 surround audio: If you send a new update with only 2.0 audio, only the 2.0 audio file is replaced, keeping the original 7.1 surround audio and 5.1 surround audio.
Existing film with 2.0, 7.1 surround audio, and downmixed 5.1: If you send 2.0 and 5.1 surround audio, only the 2.0 and 5.1 surround audio files are replaced, keeping the original 7.1 surround audio. The existing downmixed 5.1 surround audio will be replaced by the provided 5.1 surround audio.
Existing film with 2.0 and 5.1 surround audio: If you send 2.0 and 7.1 surround audio with "audio.surround.force_5_1_downmix" attribute set to true, you must remove the existing 5.1 audio before or at the same time as sending "audio.surround.force_5_1_downmix" set to true. See Overview of Asset Removal for information on removing an asset.
Existing film with 2.0 and 5.1 surround audio: If you send 2.0 and 7.1 surround audio with "audio.surround.force_5_1_downmix" attribute set to false or omit the tag, the original 5.1 surround audio file is kept as is.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <assets media_type="video" vendor_id="09736156444"> <asset type="full"> <data_file role="audio.7_1"> <locale name="en-US"/> <file_name>audio_71.mov</file_name> <size>8730177839</size> <checksum type="md5">a765a9fc88ac893ead51366fbeb04d82</checksum> <attribute name="audio.surround.force_5_1_downmix">true</attribute> </data_file> </asset> </assets></package>Below is an example metadata.xml file to update the German alternate audio for Multiple-Language Film Metadata Example. Only the audio asset along with associated data files should be referenced in the metadata. Only the metadata.xml and audio_DE.mov file should be included in the .itmsp package.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <assets media_type="video" vendor_id="09736156444"> <asset type="full"> <data_file role="audio"> <locale name="de-DE"/> <file_name>audio_DE.mov</file_name> <size>4916659</size> <checksum type="md5">9df86c3e43e7b43ddeabb2ddfe4b8a42</checksum> </data_file> </asset> </assets></package>You can re-use a previously-delivered video source as an audio file. This could be useful if you are delivering a new video source with embedded audio, but you want to use the embedded audio from a previously-delivered video source instead of the audio embedded in the new video source. In this case, neither stereo nor surround embedded audio will be used from the new video source. To re-use the previously-delivered video source as an audio file, you use two attributes: ignore_audio and reused_old_source. When delivering the new source, you would use the <attribute name="ignore_audio">true</attribute> on the data file. In the same delivery, you would supply the previously-delivered video source, but change the role from source to audio and use the <attribute name="reused_old_source">true</attribute> on the data file.
Below is an example of the XML used in the original delivery and then an example of the updated delivery:
Previously-delivered video source:
<asset type="full"> <data_file role="source"> <locale name="en-US"/> <file_name>full-source-with-good-audio.mov</file_name> <size>343376467</size> <checksum type="md5">301e72262aea7d504aca91abe229cded</checksum> </data_file></asset>Delivering new source and reusing old source audio:
<asset type="full"> <data_file role="source"> <locale name="en-US"/> <file_name>new-full-source-with-bad-audio.mov</file_name> <size>523996467</size> <checksum type="md5">5a793a8b46037fe8aa2bdd739b49911a</checksum> <attribute name="ignore_audio">true</attribute> </data_file> <data_file role="audio"> <locale name="en-US"/> <file_name>full-source-with-good-audio.mov</file_name> <size>343376467</size> <checksum type="md5">301e72262aea7d504aca91abe229cded</checksum> <attribute name="reused_old_source">true</attribute> </data_file> . . .</asset>Below are examples of asset-only updates to remove an alternate audio asset from the product and to change the <locale> of a previously delivered file. The correct vendor ID that references the already delivered metadata must be supplied in the metadata.xml file for asset removal updates
Note: When you need to update or change assets for an existing product, you can simply send an asset-only update and deliver a new asset with the same locale; you do not need to remove the asset using the remove="true" attribute. See the first XML example in Film Asset-Only Update Example which shows that a German audio file is being replaced.
This example shows how to remove the alternate German audio from the Multiple-Language Film Metadata Example. Only the audio asset along with associated data files is referenced in the XML. Only the metadata.xml need be included in the .itmsp package. The role, <filename>, <checksum>, and <size> provided are compared to the asset currently in the Apple TV app, and if the role attribute, <filename>, <checksum>, and <size> match, the asset is removed. Note that the asset could also be removed in a metadata-plus-asset update.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <assets media_type="video" vendor_id="09736156444"> <asset type="full"> <data_file role="audio" remove="true"> <locale name="de-DE"/> <file_name>audio_DE.mov</file_name> <size>4916659</size> <checksum type="md5">9df86c3e43e7b43ddeabb2ddfe4b8a42</checksum> </data_file> </asset> </assets></package>
Data File (required) A data file element block must be included if the asset is to be removed. For the audio data file, set the attribute In this block, the |
The following example shows how to change the <locale> on a source video. In this case, when the package was first delivered, the <locale> tag was incorrect. To correct the <locale>, the old source asset must be removed and redelivered with the correct <locale>. Only the source asset along with the associated data file need be referenced in the XML. The role, <filename>, <locale>, <checksum>, and <size> provided is compared to the asset currently in the Apple TV app, and if the role, <filename>, <locale>, <checksum>, and <size> match, the asset is removed. To add the source with the correct locale, include another <data_file> block within the same <asset> block as shown in the example below. Both the metadata.xml and the redelivered source asset must be included in the .itmsp package.
Important: There should be only one <asset> block for the same upload of the same video with the same type and territories. For example, the only way to change the locale of a source is to remove the existing source and add the new source; the <data_file> elements used to remove the source (remove="true") and the <data_file> elements used to add the source should go under the same <asset type="full"> block.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <assets media_type="video" vendor_id="09736156444"> <asset type="full"> <data_file role="source" remove="true"> <locale name="en-US"/> <file_name>09736156444-source.mov</file_name> <size>4916659</size> <checksum type="md5">9df86c3eabb2ddfe43e7b43dde4b8a42</checksum> </data_file> <data_file role="source"> <locale name="en-GB"/> <file_name>09736156444-source.mov</file_name> <size>4916659</size> <checksum type="md5">9df86c3eabb2ddfe43e7b43dde4b8a42</checksum> </data_file> </asset> </assets></package>
Data File (required) To change the locale, remove the asset with the incorrect locale. Include a data file element block for the asset to be removed. For the source data file, set the attribute Include another data file element block to re-deliver the asset with the correct locale. In both blocks, the |
The <comments> tag provides an alternative method for delivering quality control notes. If the QC notes contain more than 4,000 characters (approximately 2 double-spaced pages), deliver the notes as a PDF (see Deliver QC Notes as a PDF File).
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"><comments>This video contains macro blocking at 03:25.</comments> <provider>Paramount</provider> <language>en-US</language> <video> <type>film</type><!-- NOTE: The remaining tags under <video> have been omitted in this example (as indicated by the three dots) for brevity and focus. Do not omit this data from your package. --> . . . </video></package>
QC Notes (optional, 1-4,000 characters) Supplies the text of the quality control note. Use this tag when the notes are less than 4,000 characters (approximately 2 double-spaced pages). Important: Character counts are for standard 8-bit characters (that is, Roman alphabet). Fewer double-wide characters (for example, Japanese symbols) are allowed. |
The following examples show how to deliver and remove QC Notes for a full source video. QC Notes can also be delivered with a preview source video. The file must be in PDF format and there are no limitations on size of the file. Multiple QC notes can be delivered for the same "full" or "preview" video source, but the names must be different. To deliver multiple notes for an asset, each one must be in its own <data_file> block, and each <data_file> block should go under the same <asset> block. To replace a file, first remove it (see Remove QC Notes) and then redeliver it.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <assets media_type="video" vendor_id="09736156444"> <asset type="full"> <data_file role="notes"> <file_name>09736156444-source-notes.pdf</file_name> <size>12582912</size> <checksum type="md5">e5649a015c941c0f9d42f5c2054a25ab</checksum> </data_file> </asset> </assets></package>
Data File (required) A data file element block must be included to deliver notes. The vendor ID of the full or preview source must be referenced. In this block, the |
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <assets media_type="video" vendor_id="09736156444"> <asset type="full"> <data_file role="notes" remove="true"> <file_name>09736156444-source-notes.pdf</file_name> <size>12582912</size> <checksum type="md5">e5649a015c941c0f9d42f5c2054a25ab</checksum> </data_file> </asset> </assets></package>
Data File (required) A data file element block must be included to remove notes. The vendor ID of the full or preview source must be referenced. For the notes data file, set the attribute In this block, the |
Important: Keep in mind that the use of the remove="true" attribute is intended only for removing audio files permanently, changing the locale of a previously delivered asset, and removing QC notes. Using remove="true" for any other purpose can result in unintended changes to the language bundling of the final product.
This chapter describes the changes or additions to the Film Profile required to deliver concert film content to Apple.
The minimum length for concert film previews is 30 seconds; the maximum is 3 minutes.
Important: Sale of concert films is dependent on contracts. If you are unsure if you have a contract in place for sale of concert films, contact your Technical Representative.
The <vod_type> tag specifies whether the concert film is a new release or a library title. Provide this value as specified by your contract. This tag is required if <cleared_for_vod> is true.
Below is an example metadata.xml file for the concert film The Confessions Tour.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>WarnerMusicGroup</provider> <language>en-US</language> <video> <type>film</type> <subtype>concert</subtype> <vendor_id>075993999976</vendor_id> <isan>0000-0000-03B6-0000-O-0000-0000-2</isan> <upc>075993999976</upc> <country>US</country> <production_countries> <country primary="true">US</country> </production_countries> <original_spoken_locale>en-US</original_spoken_locale> <title>The Confessions Tour</title> <synopsis>The Confessions Tour features songs from throughout the dance diva's career but largely focuses on Confessions On A Dance Floor.</synopsis> <locales> <locale name="cmn-Hant"> <title>「自白巡演」</title> <synopsis>「自白巡演」收錄了這位舞蹈天后整個演藝事業的歌曲，但是主要集中在「舞池上的自白」這張專輯。</synopsis> </locale> <locale name="cmn-Hans"> <title>“自白巡演” </title> <synopsis>“自白巡演”包括的歌曲贯穿这位舞蹈天后的整个演艺事业，但是主要集中在《舞池上的自白》这张专辑。</synopsis> </locale> </locales> <production_company>Warner Bros.</production_company> <copyright_cline>2006 Warner Bros. Records Inc.</copyright_cline> <theatrical_release_date>2007-01-23</theatrical_release_date> <genres> <genre code="CONCERT-FILMS-00"/> </genres> <ratings> <rating system="mpaa" reason="Content contains adult material." code="UR"/> </ratings> <artists> <artist> <artist_name>Madonna</artist_name> <apple_id>20044</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> <locales> <locale name="cmn-Hant"> <artist_name>麥當娜</artist_name> </locale> <locale name="cmn-Hans"> <artist_name>麦当娜</artist_name> </locale> </locales> </artist> </artists> <chapters> <timecode_format>24/999 1000/nonDrop</timecode_format> <chapter> <start_time>00:00:00:00</start_time> <title>Future Lovers / I Feel Love</title> <artwork_file> <file_name>chapter01.jpg</file_name> <size>6591649</size> <checksum type="md5">ed93d0f3224a353a4cc8d4175d645130</checksum> </artwork_file> </chapter> <chapter> <start_time>00:08:27:23</start_time> <title>Like A Virgin</title> <artwork_file> <file_name>chapter02.jpg</file_name> <size>6591649</size> <checksum type="md5">86bed7ef05c34c1e85345f40d11137a9</checksum> </artwork_file> </chapter><!-- Additional chapters here. --> </chapters> <accessibility_info> <accessibility role="captions" available="true"/> </accessibility_info> <assets> <asset type="full"> <data_file role="source"> <locale name="en-US"/> <file_name>USWBV0700016_15384-source.mov</file_name> <size>2595225600</size> <checksum type="md5">2a793a8b46037fe8aa29dd739b49911a</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> <data_file role="captions"> <file_name>USWBV0700016_15384-english.scc</file_name> <size>9511</size> <checksum type="md5">5a793a8b46037fe8aa2bdd739b49911a</checksum> <locale name="en-US"/> </data_file> </asset> <asset type="preview"> <territories> <territory>WW</territory> </territories> <data_file role="source"> <locale name="en-US"/> <file_name>USWBV0700016_15384-preview.mov</file_name> <size>9987212</size> <checksum type="md5">3b793a8b46037fe8aa29dd739b49911e</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> </asset> <asset type="artwork"> <territories> <territory>WW</territory> </territories> <data_file> <locale name="en-US"/> <file_name>USWBV0700016.sca3.jpg</file_name> <size>6591649</size> <checksum type="md5">ddfe4b8ab433e43e7dde429df86cabb2</checksum> </data_file> </asset> </assets> <products> <product> <territory>US</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>203</wholesale_price_tier> <preorder_sales_start_date>2007-01-15</preorder_sales_start_date> <sales_start_date>2007-01-29</sales_start_date> <cleared_for_vod>true</cleared_for_vod> <vod_type>New Release</vod_type> <available_for_vod_date>2007-01-29</available_for_vod_date> <unavailable_for_vod_date>2008-11-12</unavailable_for_vod_date> <physical_release_date>2007-03-12</physical_release_date> </product> </products> <cue_sheet> <cue> <sequence_number>1</sequence_number> <time> <start_timecode>00:00:27</start_timecode> <duration>00:08:00</duration> </time> <title>Future Lovers / I Feel Love</title> <artists> <artist> <artist_name>Madonna</artist_name> <apple_id>20044</apple_id> <roles> <role>Performer</role> <role>Creator</role> </roles> </artist> <artist> <artist_name>Ahmadzai, Miruais</artist_name> <roles> <role>Creator</role> </roles> </artist> </artists> <isrc>USWB10606544</isrc> <iswc>T0723712091</iswc> <copyright_cline>2006 Warner Bros. Records Inc.</copyright_cline> <copyright_pline>2006 Warner Bros. Records Inc.</copyright_pline> <usage>Featured</usage> </cue> <cue> <sequence_number>2</sequence_number> <time> <start_timecode>00:08:27</start_timecode> <duration>00:04:13</duration> </time> <title>Like A Virgin</title> <artists> <artist> <artist_name>Madonna</artist_name> <apple_id>20044</apple_id> <roles> <role>Performer</role> </roles> </artist> <artist> <artist_name>Kelley, Thomas F.</artist_name> <roles> <role>Creator</role> </roles> </artist> <artist> <artist_name>Steinberg, William E.</artist_name> <roles> <role>Creator</role> </roles> </artist> </artists> <isrc>USWB10606545</isrc> <iswc>T0701016810</iswc> <copyright_cline>2006 Warner Bros. Records Inc.</copyright_cline> <copyright_pline>2006 Warner Bros. Records Inc.</copyright_pline> <usage>Featured</usage> </cue> <cue> <sequence_number>3</sequence_number> <time> <start_timecode>00:12:40</start_timecode> <duration>00:04:53</duration> </time> <title>Jump</title> <artists> <artist> <artist_name>Madonna</artist_name> <apple_id>20044</apple_id> <roles> <role>Performer</role> <role>Creator</role> </roles> </artist> <artist> <artist_name>Price, Stuart David</artist_name> <roles> <role>Creator</role> </roles> </artist> <artist> <artist_name>Henry, Joseph Lee</artist_name> <roles> <role>Creator</role> </roles> </artist> </artists> <isrc>USWB10606546</isrc> <iswc>T0725001626</iswc> <copyright_cline>2006 Warner Bros. Records Inc.</copyright_cline> <copyright_pline>2006 Warner Bros. Records Inc.</copyright_pline> <usage>Featured</usage> </cue> </cue_sheet> </video></package>Only annotations for items added or changed for concert films are included. For complete annotations, see Basic Film Metadata Annotated.
Video (required) Begins the video element. Only one video element can be defined per film XML. |
Video Subtype (required; can be updated) This value indicates how Apple should represent this video in the Apple TV app. The only accepted value for concert films is video subtype |
Country (required if not using <countries_of_origin>; , ISO-3166-1 country code) The ISO 3166-1 alpha 2 code of the country/region where the film was primarily produced. Notes:
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. |
Production Company (required; 1-255 bytes; can be updated) The customer-presentable name of the production company that created this concert film. Only one production company can be specified. If the concert film does not have an associated production company, supply the label name in the |
Theatrical Release Date (required) This is the date the concert film was first released in theaters for the specified territory. If a concert film was not released theatrically, use the date it was first released physically or digitally. The date must be in the format 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 |
Genre (required; may be updated) Concert films should use the |
Ratings (required; can be updated) You must specify one or more ratings for your concert film content. For complete details, see the Overview in the “Film Ratings, Advisories, and Genres” section. |
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 in the “Film Ratings, Advisories, and Genres” section 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 The Required method using the rating code:
Acceptable method using both the rating code and the rating label:
To view a list of rating codes, you can download it from Film Ratings. |
|
Video Artists (required) Name, primary status, and roles for each artist. In this context, "artist" may be any contributor including non-performing persons (for example, producer), or groups (for example, a band name). 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"), and individual members of a band may be listed (for example, both "Harry Connick, Jr. Trio" (primary) and "Harry Connick, Jr." may be specified for a production). Artist: You can refer to the artist by name (using the Role Use the
Additional roles (such as Lead Guitar, Lead Vocals, Producer) are optional, but highly recommended. See Recommended Contributor Roles for a list of recommended contributor roles. If your exact role is not mentioned in the tables, you can still deliver it. These recommendations are included to ensure commonly-used roles are formatted consistently. Note: You can use the following roles to designate the songwriter: Primary Status Primary status indicates whether or not the concert film appears on the artist’s page in the Apple TV app. Typically, there are one or two primary (lead) artists and several supporting artists. Primary status is reserved for the primary (lead) artists. Do not tag supporting artists or contributors as primary. 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 (for example, Japanese) characters, this can equate to as few as 71 characters. |
Cue Sheet (optional for U.S., otherwise required; can be updated) Provides a list of music played in a concert film. Important: Cue sheets are required for publishing purposes if the concert film will be sold or rented outside of the United States. If the concert film will only be sold in the U.S. market, then no cue sheet is required. |
Cue (required) Begins a description of a musical piece played in a concert film. There can be multiple cue elements in a cue sheet. |
Sequence Number (required) The order number for the musical piece in the concert film. This value should be unique for each musical piece listed in the cue sheet. |
Time (required) The time element describes when a musical piece appears in the production and its duration. |
Start Time-code (optional) Specifies the start time of the musical piece in the production. Note: The format of this value is HH:MM:SS (hours:minutes:seconds). |
Duration (required) Specifies the length of time the individual musical piece featured within the production. Note: The format of this value is HH:MM:SS (hours:minutes:seconds). |
|
Title (required) The title of the musical piece. This tag should be used for titles based on ISO Latin-1 and Latin-2 language (i.e., English, French). For details for other languages, refer to Multiple Language Films. 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 (required) 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 |
Role Use the
Additional roles (such as Lead Guitar, Lead Vocals, Producer) are optional, but highly recommended. See Recommended Contributor Roles for a list of recommended contributor roles. If your exact role is not mentioned in the tables, you can still deliver it. These recommendations are included to ensure commonly-used roles are formatted consistently. Note: You can use the following roles to designate the songwriter: Primary Status Primary status indicates whether or not the concert film appears on the artist’s page in the Apple TV app. Typically, there are one or two primary (lead) artists and several supporting artists. Primary status is reserved for the primary (lead) artists. Do not tag supporting artists or contributors as primary. |
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 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, USDP20707421. |
ISWC (optional) The ISWC (international standard work code) for musical works. This uniquely identifies intellectual property such as musical and literary works. |
Copyright © Line (optional; can be updated) Copyright line for the musical piece. The format required is year followed by owner. The appropriate © symbol will automatically be added and should not be included in the data. |
Copyright P-Line (optional; can be updated) Performance copyright line for the musical 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 have this P-line in the slate. Remove this tag if this is the case. |
Usage (optional) Specifies how the musical piece was featured in the production. Use one of the following values:
|
|
You can add metadata to supply information on cast and crew members in a concert film. The cast metadata is supplied in a <cast> block, with a <cast_member> block within the <cast> tag for each cast member; the crew metadata is supplied in a <crew> block, with a <crew_member> block within the <crew> tag for each crew member. For tag annotations, see the Basic Film Metadata Annotated section.
You can use any combination of the <artists> block, the <cast> block, and <crew> block as needed to ensure that all contributors involved in the concert film are specified. For concert films, the <artists> block is required, but the <cast> and <crew> blocks are optional.
Below is an example metadata.xml file for a concert film of a Gaetano Donizetti comic opera that features an actor in a non-singing role. The actor role is delivered in a <cast> block.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>CrownHillMusicGroup</provider> <language>en-US</language> <video> <type>film</type> <subtype>concert</subtype> <vendor_id>825993649974</vendor_id> <isan>0000-0000-03B6-0000-Z-0000-0000-6</isan> <countries_of_origin> <country primary="true">US</country> <country>CA</country> </countries_of_origin> <production_countries> <country primary="true">US</country> </production_countries> <original_spoken_locale>fr-FR</original_spoken_locale> <title>The Daughter of the Regiment</title> <synopsis>This whimsical, rollicking comedy follows Marie, a feisty young girl raised by a regiment of French soldiers high in the Alps. Filled with intoxicating arias, astonishing high notes and slapstick antics, the opera follows Marie as she grapples between her loyalty to her soldiers and the expectations of polite society.</synopsis> <production_company>Crown Hill</production_company> <copyright_cline>2011 Crown Hill Inc.</copyright_cline> <theatrical_release_date>2011-07-18</theatrical_release_date> <genres> <genre code="CONCERT-FILMS-00"/> </genres> <ratings> <rating system="mpaa" code="PG"/> </ratings> <artists> <artist> <artist_name>Juliette Blanchard</artist_name> <apple_id>852099</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> <artist> <artist_name>Alfredo Palianti</artist_name> <apple_id>530082</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> <artist> <artist_name>Gaetano Donizetti</artist_name> <apple_id>322699</apple_id> <roles> <role>Composer</role> </roles> <primary>true</primary> </artist> <!-- Additional artists here --> </artists> <cast> <cast_member billing="top"> <display_name>Beatrice Smythe</display_name> <apple_id>5388624</apple_id> <description format="plain">The Duchess of Crakentorp, (a non-singing role in Donizetti’s comic opera), arrives to find out whether Marie is worthy of marrying her nephew. The Duchess reads from a long list of qualities required. When the Duchess of Crakentorp and her nephew learn that Marie was raised by soldiers, they leave in a huff.</description> <characters> <character> <reference_id>CRAKENTORP</reference_id> <character_name>Duchess of Crakentorp</character_name> <character_note>Antagonist</character_note> <character_image> <data_file> <file_name>smythe_as_duchess.png</file_name> <size>36663243</size> <checksum type="md5">8b3ebd1ae9b3617714ec1addec961f4d</checksum> </data_file> </character_image> </character> </characters> </cast_member> <!-- Additional cast members here --> </cast> <crew> <crew_member billing="top"> <display_name>Pierre Majordome</display_name> <apple_id>77420922</apple_id> <roles> <role>Director</role> </roles> </crew_member> <!-- Additional crew members here --> </crew> <chapters> <timecode_format>24/999 1000/nonDrop</timecode_format> <chapter> <start_time>00:00:00:00</start_time> <title>Overture</title> <artwork_file> <file_name>chapter01.jpg</file_name> <size>6591649</size> <checksum type="md5">3a4cc8d4175d645130ed93d0f3224a35</checksum> </artwork_file> </chapter> <chapter> <start_time>00:07:16:10</start_time> <title>Act 1</title> <artwork_file> <file_name>chapter02.jpg</file_name> <size>6591649</size> <checksum type="md5">ef05c3486bed7c1e8531145f40d137a9</checksum> </artwork_file> </chapter><!-- Additional chapters here. --> </chapters> <accessibility_info> <accessibility role="captions" available="true"/> </accessibility_info> <assets> <asset type="full"> <data_file role="source"> <locale name="en-US"/> <file_name>daughter-regiment-source.mov</file_name> <size>2595225600</size> <checksum type="md5">6037fe8aa2a793a8b1a429dd739b4991</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> <data_file role="captions"> <file_name>daughter-regiment-english.scc</file_name> <size>9511</size> <checksum type="md5">7935a37fe8a8b460aa2b9b49911add73</checksum> <locale name="en-US"/> </data_file> </asset> <asset type="preview"> <territories> <territory>WW</territory> </territories> <data_file role="source"> <locale name="en-US"/> <file_name>daughter-regiment-preview.mov</file_name> <size>9987212</size> <checksum type="md5">6037fe8aa3b793a8b429911dd739b49e</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> </asset> <asset type="artwork"> <territories> <territory>WW</territory> </territories> <data_file> <locale name="en-US"/> <file_name>daughter-regiment.jpg</file_name> <size>6591649</size> <checksum type="md5">86cab33e43e7ddb2ddfe4b8ab4e429df</checksum> </data_file> </asset> </assets> <products> <product> <territory>US</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>203</wholesale_price_tier> <preorder_sales_start_date>2011-05-15</preorder_sales_start_date> <sales_start_date>2011-07-18</sales_start_date> <physical_release_date>2011-07-18</physical_release_date> </product> </products> <cue_sheet> <cue> <sequence_number>1</sequence_number> <time> <start_timecode>00:07:16</start_timecode> <duration>00:03:53</duration> </time> <title>L'ennemi s'avance</title> <artists> <artist> <artist_name>Alfredo Palianti</artist_name> <apple_id>530082</apple_id> <roles> <role>Performer</role> </roles> </artist> <artist> <artist_name>Antoinette Le Poulet</artist_name> <apple_id>588832</apple_id> <roles> <role>Performer</role> </roles> </artist> </artists> <isrc>USWB10606544</isrc> <copyright_cline>2011 Crown Hill Records Inc.</copyright_cline> <copyright_pline>2011 Crown Hill Records Inc.</copyright_pline> <usage>Featured</usage> </cue> <cue> <sequence_number>2</sequence_number> <time> <start_timecode>00:11:10</start_timecode> <duration>00:02:14</duration> </time> <title>Pour une femme de mon nom</title> <artists> <artist> <artist_name>Antoinette Le Poulet</artist_name> <apple_id>588832</apple_id> <roles> <role>Performer</role> </roles> </artist> </artists> <isrc>USWB10606545</isrc> <copyright_cline>2011 Crown Hill Records Inc.</copyright_cline> <copyright_pline>2011 Crown Hill Records Inc.</copyright_pline> <usage>Featured</usage> </cue> <cue> <sequence_number>3</sequence_number> <time> <start_timecode>00:13:25</start_timecode> <duration>00:02:10</duration> </time> <title>Sacre Nom</title> <artists> <artist> <artist_name>Juliette Blanchard</artist_name> <apple_id>852099</apple_id> <roles> <role>Performer</role> </roles> </artist> <artist> <artist_name>Alfredo Palianti</artist_name> <apple_id>530082</apple_id> <roles> <role>Performer</role> </roles> </artist> </artists> <isrc>USWB10606546</isrc> <copyright_cline>2011 Crown Hill Records Inc.</copyright_cline> <copyright_pline>2011 Crown Hill Records Inc.</copyright_pline> <usage>Featured</usage> </cue><!-- Additional cue blocks here. --> </cue_sheet> </video></package>This chapter describes the language support for film products. Apple accepts films with multiple language audio, subtitles, forced subtitles, and dub card videos. In addition, you can supply localizations for title, synopsis, cast, crew, and chapter titles. For example, you can deliver the film asset, audio assets in multiple languages, subtitles and forced subtitles in multiple languages, and multiple language localizations in one XML file for the film. You must also deliver a worldwide trailer and worldwide poster art. Apple arranges the components into bundles—each bundle is a sellable product, which means that there could be multiple bundles produced for the same vendor ID. Each bundle is composed of various combinations of the movie source and other assets included in the package; each bundle is similar to a physical product SKU. Bundles are designated by country/region.
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 film is to be sold or rented outside of the U.S. and the film contains music, you should deliver cue sheets, if available.
For information on bundles, see Multiple Language Support in the Apple Transactional Movies User Guide.
The following table describes the assets accepted for multiple language films.
Asset | Description |
|---|---|
Film source | The film’s ProRes source file should meet all the requirements defined in Apple Video and Audio Asset Guide. It is preferred that it contain the film’s audio in the language used at the time of the film’s creation (the language specified in the |
Alternate audio | Separate QuickTime movie file that contains audio only. Intended to supply dubbed audio. Allows customers to view the film with audio other than the language specified in the Apple accepts various audio languages and can combine them into bundles. For more information, see Multiple Language Support in the Apple Transactional Movies User Guide. |
Audio Description (AD) | A separate QuickTime movie file that contains audio only. Intended to supply AD audio. Allows visually-impaired customers to follow the film with audio that describes the plot and what is being displayed visually on the screen. Apple accepts AD in 2.0 stereo and optionally 5.1 surround (no 7.1 surround). 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 |
Closed captions | Text that describes all audio content in the video for deaf or hard-of-hearing customers. Closed captions include dialog, indications of who is speaking, and notations of music or sound effects. Apple currently accepts closed captions in .SCC format. Other formats may exist but they are not used by the Apple TV app at this time. Movies that are in English can be delivered with subtitles for the deaf or hard-of-hearing (SDH) if closed captions are not available. See Basic Film Metadata Example without Closed Captions for details. |
Full subtitles | A full translation of all the words spoken in the film used to assist the audience in translating the primary spoken audio in its entirety. Full subtitles can be turned on or off by the customer and can be used in any territory. Subtitles are delivered as an iTunes Timed Text (iTT) file. For a list of supported languages, see Multiple Language Support in the Apple Transactional Movies User Guide. |
Subtitles for the Deaf and Hard-of-hearing | The SDH file is an optional data file containing subtitles that provide textual versions of the dialogue, as well as song lyrics and sound effects. SDH can be turned on or off by the customer. Multiple SDH files can be delivered for a single film. The language of the SDH is specified using the Movies in English that have not aired or have aired without captions can be sent with English subtitles or SDH using the accessibility reason code: IN_US_NO_CAPTIONS or NEVER_IN_US. Movies that are not in English and have not been broadcast in the United States don’t need captions. These movies will need either English subtitles or SDH. Use the accessibility reason code NO_CC_SDH_FOREIGN_LANGUAGE_ENGLISH_SUBS for these movies. See Basic Film Metadata Example without Closed Captions for details. |
Forced subtitles | A partial translation of the words spoken in a film, or informative text that supplements the plot of the story or describes the setting without using a narrator. These subtitles cannot be turned on or off by the customer, and display sporadically to assist the audience with the narrative through location, dates, or to translate dialogue/text that differs from the primary spoken audio. The language of the forced subtitles will always match the audio language the customer has selected for playback. Forced subtitles are tied to audio and will automatically display in a player if that audio is selected for playback. Therefore, the locale value of any delivered forced subtitle file must be the same as its corresponding audio. For example, if the film’s audio is German, the German forced subtitle file must have a locale value of Text in forced subtitles must be duplicated in the full subtitle file of the same language because they do not automatically play back when the full subtitle is selected. Forced subtitle files delivered for audio languages which are not in the package will not be included in the bundle produced by the Apple video processing system. |
Dub card video | An optional data file containing the credits associated with an audio track. A video-only sequence containing one or more still credits specific to the locale-matched audio. 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 asset and the dubbing cards must match, with the exception of Chinese language dub cards, which use the script subtag. Refer to Apple Video and Audio Asset Guide for file requirements. |
The <territory_exclusions> tag can be used to exclude assets from particular territories. For example, you can exclude French audio from your film offering from the Canadian Store if you do not have distribution rights in Canada, and leave the rest of your worldwide storefront offerings untouched. See Multiple-Language Film Metadata Example for an XML example that includes the <territory_exclusions> tag.
Use the <territory_exclusions> tag on a per-territory basis with the following components:
Alternate audio: data_file role="audio"
7.1 surround audio: data_file role="audio.7_1"
Full Subtitles: data_file role="subtitles"
Audio embedded in the source video: data_file role="source"
You cannot use the <territory_exclusions> tag on data files with the following roles:
data_file role="captions"
data_file role="video.end.dub_credits"
data_file role="forced_subtitles"
data_file role="audio.visually_impaired"
data_file role="subtitles.hearing_impaired"
The following shows a snippet of the <assets> block. (The metadata example in Multiple-Language Film Metadata Example shows a complete <assets> block that includes territory exclusions for alternate audio and full subtitles, as well as an exclusion on the audio on the source video.) In the example below, the <original_spoken_locale> of the film is French, with English and German subtitles. The provider does not have the rights to the German subtitles in France, Canada, or Brazil, so three territory exclusions on the German subtitles are sent for France, Canada, and Brazil. For France, the exclusion ends on a certain date, which is indicated using the end_date attribute.
. . . <assets> . . . <asset type="full"> <!-- Subtitles --> <data_file role="subtitles"> <locale name="en-US"/> <file_name>09736156444-subtitles-US.itt</file_name> <size>100259</size> <checksum type="md5">9df86c3e43e7b43ddeabb2ddfe4b8a42</checksum> </data_file> <data_file role="subtitles"> <locale name="de-DE"/> <file_name>09736156444-subtitles-DE.itt</file_name> <size>100682</size> <checksum type="md5">3e7b43d9df86c3e4e4b8a42deabb2ddf</checksum> <territory_exclusions> <territory_exclusion end_date="2013-02-02">FR</territory_exclusion> <territory>CA</territory> <territory>BR</territory> </territory_exclusions> </data_file>. . .Keep the following in mind when delivering component (audio and full subtitles) exclusions:
You specify component exclusions on a per-country/region basis using the <territory_exclusions> block. You can include as many territories within the <territory_exclusions> block as needed for the component.
You can specify exclusions for a component that has already been delivered if the film is not yet live in the territory. (“Live” means that the film currently is or was previously available in that country/region as a pre-order, VOD, or EST.) If a film is already live, you can add exclusions the first time a component is delivered.
For example, suppose you have a film that is currently live in France with only French audio. You can later deliver Spanish audio with a territory exclusion for the Spanish audio in France. If you did not deliver the territory exclusion when the Spanish audio was first delivered, you could not later add an exclusion on the Spanish audio for France. However, you could specify an exclusion for the Spanish audio for a country/region that is not yet live.
You can specify territory exclusions for any country/region, even if that country/region does not offer transactional content.
You can specify territory exclusions on the <original_spoken_locale> audio that is embedded in the source video.
You can indicate that a particular exclusion for a territory should end on a specific date.
You can remove territory exclusions at any time. See Removing Territory Exclusions for more information.
See Multiple Language Support in the Apple Transactional Movies User Guide for examples and information on bundles.
Previews are required for all films in the Apple TV app and must be representative of the film. This ensures customers have the same expectation of the film after viewing the preview. Apple accepts two basic categories of territory designations for previews:
World (default)
Localized
A default (World) preview for every film is required. The World territory designation (WW) allows this preview to be available to any territory and therefore serve as a default. When a film is cleared in a new territory, the World preview will be used in the Apple TV app unless a localized preview has been provided.
A localized preview is intended to serve only specific territories. When a film has been delivered to Apple with a World preview and a localized preview, the localized preview will take priority in the designated territory.
For example, a film is delivered to Apple with a World preview and a localized preview for the UK. The film is cleared for sale in the UK and the United States. When the film appears in the Apple TV app, Apple uses the UK preview for customers in the UK and the World preview for customers in the U.S.
When working with Multiple Audio Language Worldwide films, use the following rules to determine the language of the preview:
The World preview should use the film’s <original_spoken_locale> audio.
Localized previews may be tailored for specific territories but they must be representative of the attributes of the film. For example, a localized preview should only use Spanish audio if the movie has Spanish as a language option. Likewise, it should only use French subtitles if the film has French subtitles as a viewing option.
Note: A preview can have either a subtitles data file or an audio data file, but not both. A forced subtitles file does not count toward the limit of one alternative audio or one subtitles file.
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. You can have more than one preview, one per territory.
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 <preview> tag and 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 (required). See Multiple-Language Film Metadata Example for an XML example of defining a preview.
Keep the following in mind when creating a preview clip:
You must specify a territory for each preview you are clipping.
Different territories can have different time segments; start time and end time are territory specific.
Time segments must be continuous; stitching of different time segments is not allowed.
Specify the timecode format (see Timecode Formats for supported formats) and make sure the times match the timecode format.
If a new defined <preview> has the same territory as an existing custom preview, you must supply the replace_custom="true" attribute.
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 defined previews, you must specify an image_time to use as the preview image. For a custom preview asset, the preview image will be cut from the first frame at 45 seconds into the preview if you do not specify a <preview_image_time>.
Minimum clip duration is 45 seconds and maximum duration is 300 seconds.
Make sure that a territory is specified only once in the metadata-based preview block.
If audio and forced subtitles in the same language are included in a package, they must both have the same locale value. For example, if English audio and English forced subtitles are to be provided to the customer, both must be the same dialect of English, that is, both UK English (en-GB) or both U.S. English (en-US). This is also true if the region is not provided. Content with (en) audio will need to have the forced subtitle tagged (en) rather than (en-US) or (en-GB).
In the Forrest Gump example below, the feature film source will be used to create EST and VOD products for four territories: United States, Brazil, Canada, and France. The copyright c-line and theatrical release date are territory specific. For each territory, title, synopsis, cast, crew, and chapter titles have been localized and ratings have been supplied. Separate poster art files and trailers will be used for BR and FR territories. The worldwide (WW territory) poster art file and trailer will be used in the US and CA territories because territory-specific assets have not been submitted for the United States and Canada. In this example, the worldwide poster art is in the LSR (.lsr) layered image format. A cue sheet has been added to the example; cue sheets are optional, but should be provided if available. For the sake of brevity, only two music works are shown within the cue sheet.
The package also includes both French and Latin American Spanish audio files. Subtitles and forced subtitles for multiple languages are included, as well as SDH in Spanish and English. In this example, English closed captions are not available and English SDH can be used in place of captions. Because one of the products is for the US territory where captioning is required, the metadata must indicate the reason code closed captions are not supplied, which is required for U.S. deliveries. The reason code indicates the SDH are supplied instead.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <language>en-US</language> <video> <type>film</type> <subtype>feature</subtype> <vendor_id>09736156444</vendor_id> <isan>0000-0000-03B6-0000-O-0000-0000-2</isan> <upc>09736156444</upc> <countries_of_origin> <country primary="true">US</country> <country>CA</country> </countries_of_origin> <production_countries> <country primary="true">US</country> </production_countries> <original_spoken_locale>en-US</original_spoken_locale> <title>Forrest Gump</title> <studio_release_title>Forrest Gump</studio_release_title> <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> <locales> <locale name="pt-BR"> <title>Forrest Gump, o Contador de Histórias (Legendado)</title> <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> </locale> <locale name="fr-FR"> <title>Forrest Gump (VOST)</title> <synopsis>"La vie, c’est comme une boîte de chocolats…On ne sait jamais sur quoi on va tomber." Tom Hanks est merveilleux dans ce film culte qui a touché le coeur de milliers de spectateurs. Forrest Gump est le symbole d’une époque, un candide dans une Amérique qui a perdu son innocence. Ce film a remporté 6 Oscars® dont celui du meilleur film, du meilleur réalisateur (Robert Zemeckis) et du meilleur acteur (Tom Hanks).</synopsis> </locale> <locale name="fr-CA"> <title>Forrest Gump</title> <synopsis>"La vie, c’est comme une boîte de chocolats…On ne sait jamais sur quoi on va tomber." Tom Hanks est merveilleux dans ce film culte qui a touché le coeur de milliers de spectateurs. Forrest Gump est le symbole d’une époque, un candide dans une Amérique qui a perdu son innocence. Ce film a remporté 6 Oscars® dont celui du meilleur film, du meilleur réalisateur (Robert Zemeckis) et du meilleur acteur (Tom Hanks).</synopsis> </locale> </locales> <production_company>Paramount Pictures</production_company> <copyright_cline>1994 Paramount Pictures</copyright_cline> <theatrical_release_date>2007-05-04</theatrical_release_date> <regions> <region> <territory>BR</territory> <copyright_cline>1994 Paramount Pictures</copyright_cline> <!-- In this region, the film was not released in theaters; it was released digitally --> <digital_only_release_date>2007-05-04</digital_only_release_date> </region> <region> <territory>FR</territory> <copyright_cline>1994 Paramount Pictures</copyright_cline> <theatrical_release_date>2007-06-04</theatrical_release_date> </region> <region> <territory>CA</territory> <copyright_cline>1994 Paramount Pictures</copyright_cline> <!-- In this region, the film was not released in theaters; it was released digitally --> <digital_only_release_date>2007-05-04</digital_only_release_date> </region> </regions> <genres> <genre code="COMEDY-00"/> <genre code="DRAMA-00"/> </genres> <ratings><!-- Note that when adding ratings, escape codes can be used. --> <rating system="mpaa" reason="for drug content, some sensuality and war violence" code="PG-13"/> <rating system="br-movies" reason="Drogas L[í]citas; Sexo; Viol[ê]ncia" code="14"/> <rating system="fr-cnc" code="-12"/> <rating system="ca-chvrs" code="14A"/> </ratings> <cast> <cast_member billing="top"> <display_name>Tom Hanks</display_name> <apple_id>2672649</apple_id> <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> <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> </locale> <locale name="fr-FR"> <display_name>Tom Hanks</display_name> <description format="plain">Forrest Gump mène une vie vraiment charmé comme il voyage à travers les événements clés de la seconde moitié du 20e siècle. Entièrement sans essayer. Pour son interprétation de Forrest Gump, Tom Hanks a obtenu l'Oscar du meilleur acteur, Golden Globe du meilleur acteur dans un film dramatique, le BAFTA du meilleur acteur et beaucoup plus de récompenses à travers le monde. Le film et le caractère titulaire sont basés sur le roman de Winston Groom - "Forrest Gump".</description> </locale> <locale name="fr-CA"> <display_name>Tom Hanks</display_name> <description format="plain">Forrest Gump mène une vie vraiment charmé comme il voyage à travers les événements clés de la seconde moitié du 20e siècle. Entièrement sans essayer. Pour son interprétation de Forrest Gump, Tom Hanks a obtenu l'Oscar du meilleur acteur, Golden Globe du meilleur acteur dans un film dramatique, le BAFTA du meilleur acteur et beaucoup plus de récompenses à travers le monde. Le film et le caractère titulaire sont basés sur le roman de Winston Groom - "Forrest Gump".</description> </locale> </locales> <characters> <character> <reference_id>FORREST</reference_id> <character_name>Forrest Gump</character_name> <character_note>Protagonist</character_note> <character_image> <data_file> <file_name>hanks_as_gump.png</file_name> <size>2813243</size> <checksum type="md5">4ec1addb1f4d3617718b3ebd1ae9ec96</checksum> </data_file> </character_image> <locales> <locale name="pt-BR"> <character_name>Forrest Gump</character_name> <character_note>Protagonista</character_note> </locale> <locale name="fr-FR"> <character_name>Forrest Gump</character_name> <character_note>Protagoniste</character_note> </locale> <locale name="fr-CA"> <character_name>Forrest Gump</character_name> <character_note>Protagoniste</character_note> </locale> </locales> </character> <!-- Additional character blocks here if needed for this cast member to handle cases where a cast member plays multiple characters in the film. --> </characters> </cast_member> <!-- Additional cast members here --> </cast> <crew> <crew_member billing="top"> <display_name>Robert Zemeckis</display_name> <apple_id>274059420</apple_id> <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> <roles> <role>Director</role> </roles> </crew_member> <crew_member billing="top"> <display_name>Claude Motta</display_name> <locales> <locale name="pt-BR"> <display_name>Claude Motta</display_name> </locale> <locale name="fr-FR"> <display_name>Claude Motta</display_name> </locale> <locale name="fr-CA"> <display_name>Claude Motta</display_name> </locale> </locales> <roles> <role locale="pt-BR" character_reference="FORREST">Dub Artist</role> </roles> </crew_member> <!-- Additional crew members here --> </crew> <!-- English, Portuguese, and French Inline Chaptering --> <chapters> <timecode_format>24/999 1000/nonDrop</timecode_format> <chapter> <start_time>00:00:00:00</start_time> <titles> <title locale="en-US">Forrest's Story Begins</title> <title locale="pt-BR">História Forrest começa</title> <title locale="fr-FR">L'Histoire de Forest Commence</title> <title locale="fr-CA">L'Histoire de Forest Commence</title> </titles><!-- Chapter image can be provided in an artwork file or specified by a timecode. This chapter image is provided in an artwork file. --> <artwork_file> <file_name>chapter01.jpg</file_name> <checksum type="md5">ed93d0f3224a353a4cc8d4175d645130</checksum> <size>6748922</size> </artwork_file> </chapter> <chapter> <start_time>00:07:45:23</start_time> <titles> <title locale="en-US">Football at Alabama</title> <title locale="pt-BR">Futebol em Alabama</title> <title locale="fr-FR">Football en Alabama</title> <title locale="fr-CA">Football en Alabama</title> </titles><!-- Chapter image can be provided in an artwork file or specified by a timecode. This chapter image is specified by a timecode. --> <artwork_time>00:07:45:23</artwork_time> </chapter> <!-- Additional chapters here. --> </chapters> <accessibility_info> <accessibility role="captions" available="false" reason_code="IN_US_NO_CAPTIONS"/> </accessibility_info> <!-- Assets --> <assets> <!-- Source Video --> <asset type="full"> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-source.mov</file_name> <size>2595225600</size> <checksum type="md5">2a793a8b46037fe8aa29dd739b49911a</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> <!-- Territory Exclusion on the Audio Embedded in the Source Video --> <territory_exclusions role="audio"> <territory>CA</territory> </territory_exclusions> </data_file> <!-- Production still --> <production_still_image_time format="24/999 1000/nonDrop">00:00:57:02</production_still_image_time> <!-- Dubbed Latin American Spanish Audio --> <data_file role="audio"> <locale name="es-419"/> <file_name>audio_ES_419.mov</file_name> <checksum type="md5">9df86c3e43e7b43ddeabb2ddfe4b8a42</checksum> <size>4916659</size> <!-- Territory Exclusions on the Spanish Audio --> <territory_exclusions> <territory>FR</territory> <territory>CA</territory> </territory_exclusions> </data_file> <!-- Dubbed French 5.1 Surround Audio --> <data_file role="audio"> <locale name="fr-FR"/> <file_name>audio_FR_FR.mov</file_name> <checksum type="md5">bdeea426ac79543b691a45507e9956c8</checksum> <size>5820197005</size> </data_file> <!-- Dubbed French 7.1 Surround Audio --> <data_file role="audio.7_1"> <locale name="fr-FR"/> <file_name>audio_71_FR_FR.mov</file_name> <checksum type="md5">a765a9fc88ac893ead51366fbeb04d82</checksum> <size>8730177839</size> <attribute name="audio.surround.force_5_1_downmix">false</attribute> </data_file> <!-- Dubbed French Dolby Atmos Audio --> <data_file role="audio.object_based"> <locale name="fr-FR"/> <file_name>audio_atmos_FR.wav</file_name> <size>1142644642</size> <checksum type="md5">bc5b28a6200e5273202b7609f626fec0</checksum> </data_file> <!-- Dub Card Video Latin American Spanish and French --> <data_file role="video.end.dub_credits"> <locale name="es-419"/> <file_name>dub_card_ES419.mov</file_name> <size>16201736340</size> <checksum type="md5">c5f39f1af9f2d3de4e85c06dec751f92</checksum> </data_file> <data_file role="video.end.dub_credits"> <locale name="fr-FR"/> <file_name>dub_card_FR.mov</file_name> <size>134071620361</size> <checksum type="md5">39f1af9f2d3dec5f4e85c06dec751f92</checksum> </data_file> <!-- Subtitles --> <data_file role="subtitles"> <locale name="da"/> <file_name>Subtitles_DA_DK.itt</file_name> <size>100259</size> <checksum type="md5">9df86c3e43e7b43ddeabb2ddfe4b8a42</checksum> </data_file> <data_file role="subtitles"> <locale name="pt-BR"/> <file_name>Subtitles_PT_BR.itt</file_name> <size>88474</size> <checksum type="md5">c123e860384b8b954f169c9af0cbe4df</checksum> <!-- Territory Exclusions on the Brazil Subtitles --> <territory_exclusions> <territory_exclusion end_date="2013-02-02">FR</territory_exclusion> <territory>CA</territory> </territory_exclusions> </data_file> <data_file role="subtitles"> <locale name="en-CA"/> <file_name>Subtitles_EN_CA.itt</file_name> <size>88634</size> <checksum type="md5">54f16038469c9af0cbc123e8b8b9e4df</checksum> </data_file> <!-- Additional Subtitles here--> <!-- Begin SDH here--> <data_file role="subtitles.hearing_impaired"> <locale name="en-US"/> <file_name>Subtitles_SDH_english.itt</file_name> <size>109511</size> <checksum type="md5">5a793a8b46037fe8aa2bdd739b49911a</checksum> </data_file> <data_file role="subtitles.hearing_impaired"> <locale name="es-419"/> <file_name>Subtitles_ES_419_SDH.itt</file_name> <size>100259</size> <checksum type="md5">9df86c3e43e7b43ddeabb2ddfe4b8a42</checksum> </data_file> <!-- Additional SDH here--> <!-- Forced Subtitles --> <data_file role="forced_subtitles"> <locale name="fr-FR"/> <file_name>Subtitles_FR_FR_Forced.itt</file_name> <size>1800</size> <checksum type="md5">a02809135b44f74015f775b3fcfe4120</checksum> </data_file> <data_file role="forced_subtitles"> <locale name="es-419"/> <file_name>Subtitles_ES_419_Forced.itt</file_name> <size>1738</size> <checksum type="md5">3dff0aa59b46b89e770f4614a70909f8</checksum> </data_file> <data_file role="forced_subtitles"> <locale name="en-US"/> <file_name>Subtitles_EN_US_Forced.itt</file_name> <size>1738</size> <checksum type="md5">b89e770f461xa59b464a7b89e770f4610909f8</checksum> </data_file> </asset> <!-- End Forced Subtitles--> <!-- Required. World Trailer. Will be used for all territories where a territory-specific trailer has not been specified. --> <asset type="preview"> <preview_image_time format="24/999 1000/nonDrop">00:00:57:02</preview_image_time> <territories> <territory>WW</territory> </territories> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-preview.mov</file_name> <size>9987212</size> <checksum type="md5">739b43b793a8b46037fe8aa29dd9911e</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> </asset><!-- Optional. Brazilian Trailer. When supplied, this trailer will be used in Brazil instead of the World file. --> <asset type="preview"> <territories> <territory>BR</territory> </territories> <data_file role="source"> <locale name="pt-BR"/> <file_name>09736156444-BR-preview.mov</file_name> <size>9986311</size> <checksum type="md5">a8b46039b43b793a29dd9911e37fe8a7</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> </asset><!-- Optional. French Trailer. When supplied, this trailer will be used in France instead of the World file. This trailer includes an alternate audio for Canadian English. --> <asset type="preview"> <territories> <territory>FR</territory> </territories> <data_file role="source"> <locale name="fr-FR"/> <file_name>09736156444-FR-preview.mov</file_name> <size>9787655</size> <checksum type="md5">603b43b7fe739798aed991a3a8b429d1</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> <!-- Dubbed Canadian English 5.1 Surround Audio --> <data_file role="audio"> <locale name="en-CA"/> <file_name>audio_EN_CA.mov</file_name> <checksum type="md5">bdeea426ac79543b691a45507e9956c8</checksum> <size>5820197005</size> </data_file> </asset><!-- Optional. Canadian Trailer with a texted master. --> <asset type="preview"> <territories> <territory>CA</territory> </territories> <data_file role="source"> <locale name="fr-CA"/> <file_name>09736156444-CA-preview.mov</file_name> <size>163638669192</size> <checksum type="md5">f4ca6297d8ea96c9d50cdf9b81da8540</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">false</attribute> <attribute name="image.burned_forced_narrative.locale">en-US</attribute> <attribute name="image.burned_subtitles.locale">en-US</attribute> </data_file> </asset> <!-- Required. World Poster Art. Will be used for all territories where a territory-specific poster art has not been specified --> <asset type="artwork"> <territories> <territory>WW</territory> </territories> <data_file> <locale name="en-US"/> <file_name>09736156444.lsr</file_name> <checksum type="md5">43e7dddfe4b8ab433ede429df86cabb2</checksum> <size>6591649</size> </data_file> </asset><!-- Optional. Brazilian Poster Art. When supplied, this poster art will be used in Brazil instead of the World file. --> <asset type="artwork"> <territories> <territory>BR</territory> </territories> <data_file> <locale name="pt-BR"/> <file_name>09736156444_BR.jpg</file_name> <checksum type="md5">a429df86ce7ddeddfe4b8abb433e43b2</checksum> <size>6591458</size> </data_file> </asset><!-- Optional. French Poster Art. When supplied, this poster art will be used in France instead of the World file. --> <asset type="artwork"> <territories> <territory>FR</territory> </territories> <data_file> <locale name="fr-FR"/> <file_name>09736156444_FR.jpg</file_name> <checksum type="md5">b433e43e7ddeddfe4b8a429df86cabb2</checksum> <size>6491589</size> </data_file> </asset> </assets> <!-- Defined previews --> <previews> <preview territory="US" timecode_format="24/999 1000/nonDrop" start_time="00:55:13.02" end_time="00:58:27.00" image_time="00:55:45.12"/> <!-- Additional territories as needed --> </previews> <products> <product> <territory>US</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>3</wholesale_price_tier> <sales_start_date>2006-03-12</sales_start_date> <cleared_for_vod>false</cleared_for_vod> </product> <product> <territory>FR</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>3</wholesale_price_tier> <sales_start_date>2007-04-12</sales_start_date> <cleared_for_vod>false</cleared_for_vod> </product> <product> <territory>BR</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>3</wholesale_price_tier> <sales_start_date>2007-05-01</sales_start_date> <cleared_for_vod>false</cleared_for_vod> </product> <product> <territory>CA</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>3</wholesale_price_tier> <sales_start_date>2007-04-12</sales_start_date> <cleared_for_vod>false</cleared_for_vod> </product><!-- Additional territories as needed --> </products> <cue_sheet> <cue> <sequence_number>1</sequence_number> <time> <start_timecode>00:00:27</start_timecode> <duration>00:02:39</duration> </time> <title>I'm Forrest…Forrest Gump</title> <artists> <artist> <artist_name>Alan Silvestri</artist_name> <apple_id>611137</apple_id> <roles> <role>Composer</role> <role>Producer</role> </roles> </artist> </artists> <isrc>USSM19913841</isrc> <iswc>T0702670221</iswc> <copyright_cline>1994 Sony Music Entertainment Inc.</copyright_cline> <copyright_pline>1994 Sony Music Entertainment Inc.</copyright_pline> <usage>Signature</usage> </cue> <cue> <sequence_number>2</sequence_number> <time> <start_timecode>00:02:66</start_timecode> <duration>00:00:57</duration> </time> <title>You're No Different</title> <artists> <artist> <artist_name>Alan Silvestri</artist_name> <apple_id>611137</apple_id> <roles> <role>Composer</role> </roles> </artist> </artists> <isrc>USSM19913842</isrc> <iswc>T0702824096</iswc> <copyright_cline>1994 Sony Music Entertainment Inc.</copyright_cline> <copyright_pline>1994 Sony Music Entertainment Inc.</copyright_pline> <usage>Background</usage> </cue> <!-- Additional musical pieces here --> </cue_sheet> </video></package>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.
|
Language (required) The primary language of the metadata; that is, under the As a best practice when specifying a language, use the region subtag (for example, the See Language Codes for more information. |
|
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 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 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. Notes:
|
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 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 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. |
Original Spoken Locale (required) Specifies the language spoken by the actors in the film. The value used for In this example, dubbed French and Spanish alternate audio tracks are supplied, but the language the actors' lips are moving in is English, so If a video asset contains Chinese audio, the locale values must not contain script information. For example, the locale for Mandarin audio must be Note: This tag is different from the |
See the annotations for these tags in the basic film example: Basic Film Metadata Annotated. |
Locales (optional) Provides a mechanism to specify localizations for film title and synopsis. See Language Codes for a list of common codes. |
Locale Name (required within the <locales> tag) 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 See Language Codes for more details. |
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 (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. |
|
. . . |
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 (required) A region must be specified for each territory (country) that requires localized copyright or theatrical release date information. |
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). 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. |
Copyright © Line (optional, 1-1,000 bytes; can be updated) A specific copyright for this video. The format required is year followed by owner. The appropriate © symbol will automatically be added and should not be included in the data. If omitted, a default calculated copyright will be used based on the film's theatrical release date and your customer presentable provider name. |
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 The date must be in the format 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 |
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 The date must be in the format This field does not impact date of release or “street date” in the Apple TV app. |
|
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 Required method using the genre code:
Acceptable method using both the genre code and the genre label:
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 (required; can be updated) You must specify one or more ratings for your film content. |
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 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 The Required method using the rating code:
Acceptable method using both the rating code and the rating label:
To view a list of rating codes, you can download it from Film Ratings. |
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:
|
Cast Member (required, multiple allowed) A cast member in this film. List cast actors within the billing (optional) If an actor requires top billing for this film, the attribute Accepted values:
Important: If the |
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 (optional, numeric) You can refer to the cast member by name (using the |
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 |
Localized Display Name and Description (optional) For each locale, use the Provide the localized description related to the actor in the context of the film and the character he or she plays. |
|
Characters (required) Begins the block that describes the characters in the film played by this actor. The |
Character (required) For each character in the film, supply the character metadata within a |
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 (required) The name of the character the actor plays in the film using up to 256 bytes. |
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. |
Character Image (optional) 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 ( Additional guidelines:
|
Localized Character Name and Character Note (optional) For each locale, provide the localized character name and character note. |
|
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:
|
Crew Member (required; multiple allowed) A crew member in this film. List crew members within the billing (optional) If a crew member requires top billing for this film, the attribute Accepted values:
Important: If the |
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 (optional; numeric) You can refer to the crew member by name (using the |
Localized Crew Members (optional; 1-250 bytes; can be updated) Provide the display name for each crew member for each locale. The As a best practice when specifying a language, use the region subtag (for example, the <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 See Language Codes for more details on languages and codes. |
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:
If a crew member has more than one role, specify each role in a separate |
Dub Artist Role (required, multiple allowed)) The role performed by this crew member ( This example shows the dub artist crew member. Use the |
|
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. |
Timecode Format (optional, but recommended) Defines the timecodes used for the chapters. The format can be 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 Important: The frame modes (for example, |
Chapter (required) Defines the first chapter within the There is no limit to the number of chapters you can define. |
Chapter Start Time (required) Specifies the start of each chapter as dictated by the The first chapter must start at |
Localized Chapter Titles (required; 1-255 bytes; can be updated) Titles of the chapters, one for each locale. The 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 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 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 (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 Each artwork timecode must be unique. |
|
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 |
Accessibility (required for U.S. deliveries; can be updated) Indicates if closed captions are available. Attributes include:
- - - 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 |
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 See Language Codes for more details. 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 |
Textless Master (required) 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 |
Territory Exclusion on Video Source Audio (optional) Indicates that the Note: Territory exclusions using the You can remove embedded audio exclusions at any time. To remove a territory, deliver the |
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 The format can be Note: This tag is not the same as the 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 <asset type="full"> <. . .> <data_file role="production_still_image"> <file_name>fearless.png</file_name> <size>111037</size> <checksum type="md5">96a2c3979611ea3966f19ff1ac4f28b0</checksum> </data_file> <. . .> </asset>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. |
Localized Audio (optional) 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 As a best practice when specifying a language, use the region subtag (for example, the Apple recommends that you supply a consistent language locale for assets delivered for a territory. For example, if you supply audio for See Language Codes for more details. 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 |
Localized 7.1 Surround Audio (optional) To deliver Dolby Digital Plus audio, use the role 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 See the annotation directly above for information on specifying the language. Use the
Apple recommends that you supply a consistent language locale for assets delivered for a territory. For example, if you supply audio for For information on updating an existing film, see 7.1 Surround Audio Asset-Only Update Example. |
Localized Dolby Atmos Audio (optional) To deliver Dolby Atmos audio, use the role 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 The Apple recommends that you supply a consistent language locale for assets delivered for a territory. For example, if you supply audio for For audio file requirements, see Dolby Atmos Audio Source Profile. |
Localized Audio Territory Exclusions (optional) 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 You can remove component exclusions at any time. See Removing Territory Exclusions for more information. |
Timecode Offset (optional) 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 |
Dub Card Video (optional) 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 Apple recommends that you supply a consistent language locale for assets delivered for a territory. For example, if you supply audio for 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:
|
Localized Subtitles (optional) Subtitles are delivered as a The As a best practice when specifying a language, use the region subtag (for example, the Apple recommends that you supply a consistent language locale for assets delivered for a territory. For example, if you supply audio for See Language Codes for more details. |
Subtitles Territory Exclusions (optional) 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 For France, the territory exclusion ends October 12, 2015 and that date is conveyed using the You can remove component exclusions at any time. See Removing Territory Exclusions for more information. |
Localized SDH (optional) A data file element block must be included if the SDH are delivered for the associated video. The When delivering SDH, you must also deliver an accessibility information reason code as follows:
Apple recommends that you supply a consistent language locale for assets delivered for a territory. For example, if you supply audio for Important: File names are case sensitive and spaces are not allowed. The |
|
Preview Image Time (optional) The frame to use for the preview image. You can specify an image for each territory. The format can be 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 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 Must be a valid ISO 3166 alpha-2 country code or |
Localized Preview Asset Source (required) Describes the type of asset being delivered. You specify The 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 See the annotations in Basic Film Metadata Annotated for tag specifics. |
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.
|
Poster Image (required; can add new image and update existing images) A poster image is required, as is the
See Apple Video and Audio Asset Guide for complete file requirements. 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. |
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 Must be a valid ISO 3166 alpha-2 country code or |
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 If the poster art displays more than one language, for example, poster art for Canada that shows both English and French, supply a See the annotation for |
|
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:
Note: The frame cut with the Replacing or removing a defined preview:
|
|
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. |
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 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 |
Cleared For Sale (required) Specifies whether or not this film can be sold for EST sale in the product’s territory. Accepted values are Note: If Important: For a video to be available only for rent in the Apple TV app, this tag must be set to To remove content from the Store, set |
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 (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 Note: The Important: Omitting this tag will make the film available for sale immediately. |
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 Important: If this tag is not specified, or is set to false, this video is not available for rent in the Apple TV app. |
. . .
|
Cue Sheet (optional; can be updated) Provides a list of music played in a film. |
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 (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 (required within the <cue> block) The |
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(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). |
|
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 (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 |
Role The following roles are accepted (other artist roles may be ignored):
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: |
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 (optional) The ISWC (international standard work code) for musical pieces. This uniquely identifies intellectual property such as musical and literary works. |
Copyright © Line (optional; can be updated) Copyright line for the musical piece. The format required is year followed by owner. The appropriate © symbol will automatically be added and should not be included in the data. |
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 (optional) Specifies how the musical piece was featured in the production using one of the following values:
|
. . .
|
You can remove component exclusions at any time. To remove a territory, deliver the <territory_exclusions> block with the appropriate <territory> removed. To remove all territory exclusions, deliver an empty tag: <territory_exclusions/> within the <data_file> block of the appropriate component.
The following asset-only update example shows how to remove territory exclusions. The previously delivered film had territory exclusions on the Spanish audio and on the Portuguese subtitles for both France and Canada. In the example below, the territory exclusion on the Spanish audio is being removed for Canada. The territory exclusion on the Portuguese subtitles is being removed for both France and Canada.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <assets media_type="video" vendor_id="09736156444"> <asset type="full"> <data_file role="audio"> <locale name="es-419"/> <file_name>audio_ES_419.mov</file_name> <checksum type="md5">9df86c3e43e7b43ddeabb2ddfe4b8a42</checksum> <size>4916659</size> <!-- Territory exclusion for Canada has been removed --> <territory_exclusions> <territory>FR</territory> </territory_exclusions> </data_file> <data_file role="subtitles"> <locale name="pt-BR"/> <file_name>Subtitles_PT_BR.itt</file_name> <size>88474</size> <checksum type="md5">c123e860384b8b954f169c9af0cbe4df</checksum> <!-- Territory exclusions for both France and Canada have been removed by sending an empty tag --> <territory_exclusions/> </data_file> </asset> </assets></package>
Localized Audio Territory Exclusions (optional) The territory exclusion for Canada on the Spanish alternate audio has been removed from the |
Subtitles Territory Exclusions (optional) The previous territory exclusions for both Canada and France on the Brazilian Portuguese subtitles have been removed from the ( |
This chapter introduces features related to the delivery of film content for Korea. It covers style guidelines, minimum storefront requirements, and XML tags specific to Korea, including: <watermark_end_date>, <burned_in_subtitles_end_date>, and <premium_end_date>.
For film ratings, advisories, and genres, see the Korea topic in the “Film Ratings, Advisories, and Genres” section.
To improve the quality of the content offered in the Apple TV app, film content must meet a set of minimum requirements. These requirements apply to new deliveries of feature films only; concert films and short films are excluded.
For any film for sale inside in Korea, you must provide:
Title and synopsis written in Korean. For non-Korean films, these should be tagged with the Korean locale (<locale name="ko"/>)
Localized poster art with all wording in Korean. This includes the film title and actors’ names, if present.
Localized cast and crew (if available)
For films in Korean, you must provide:
Full asset and preview asset in Korean and tagged as being in Korean (delivered with the locale tag on the data file for the source (<locale name="ko"/>)
A clean (textless) full source asset with a separate full subtitles (.itt) data file in Korean if you are using the burned-in subtitles content protection measure.
For non-Korean language films, you must deliver one of the following:
Original audio and/or alternate audio in Korean (preferred for children’s content)
Full subtitles (.itt) localized in Korean
A clean (textless) full source asset with a separate full subtitles (.itt) data file in Korean if you are using the burned-in subtitles content protection measure.
If your content does not meet the requirements, it will not be available on the Store and you will see a notification on the film’s summary page and the Rights and Pricing page on iTunes Connect.
This section provides styles and standards for distributing movies on the Store.
Korean localized title and synopsis must be delivered as part of the Multiple Language File (MLF) if Korean subtitled and dubbed version is available.
Korean cast and crew names must not have a space between the last name and first name. For example:
Correct:박소담
Incorrect:박 소담
Korean cast and crew names in English must start with last name (family name) and end with the first name, and must have a single-byte space between the first name and last name. For example:
Correct:Park So-dam
Incorrect:So-dam Park
Western cast and crew names must have a single-byte space between the first name and last name. For example:
Correct:윌 스미스
Incorrect:윌스미스
Strongly recommended that English cast and crew names be provided in addition to the Korean names.
The following metadata example is an excerpt from a full metadata delivery. The example shows just a few tags to provide the context for using the new tags; see the Basic Film Metadata Annotated for an explanation of a full metadata delivery.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>XYZ</provider> <language>ko</language> <video> <type>film</type> <subtype>feature</subtype> <vendor_id>1000</vendor_id> <isan>0000-0000-03B6-0000-O-0000-0000-2</isan> <upc>075993999976</upc> <country>KR</country> <production_countries> <country primary="true">KR</country> </production_countries> <original_spoken_locale>ko</original_spoken_locale><!-- NOTE: When delivering your content, you must deliver the title and synopsis in Korean to meet the minimum storefront requirements. --> <title>영화 제목</title> <synopsis>영화의 시놉시스</synopsis> <production_company>XYZ</production_company> <!-- NOTE: Some tags have been omitted in this example (as indicated by the three dots) for brevity and focus; see the Basic Example for information on sending other tags. Do not omit this data from your package. --> . . . <watermark_end_date>2021-06-22</watermark_end_date> . . . <ratings> <rating code="PG-13" reason="for drug content, some sensuality and war violence" system="mpaa"/> <rating code="18" system="kr-movies" classification_number="2019-MF01716"/> <advisory code="T" system="kr-movies"/> <advisory code="V" system="kr-movies" severity="very_high">폭력성</advisory> </ratings> . . . <!-- NOTE: To meet the minimum storefront requirements, you must deliver the full and preview assets in Korean. The asset should be clean (textless) --> <assets> <asset type="full"> <data_file role="source"> <locale name="ko"/> <file_name>335f917-source.mov</file_name> <size>2595225600</size> <checksum type="md5">fe82a79dd93a89b499aa211ab4603773</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> <!-- NOTE: If you are using the burned-in subtitles content protection measure, you must deliver the subtitles .itt file. --> <data_file role="subtitles"> <locale name="ko"/> <file_name>335f917-subtitles_ko.itt</file_name> <size>88474</size> <checksum type="md5">c123e860384b8b954f169c9af0cbe4df</checksum> </data_file> <!-- Additional data files here --> </asset> <asset type="preview"> <data_file role="source"> <locale name="ko"/> <file_name>335f917-preview-source.mov</file_name> <size>2235952</size> <checksum type="md5">2fe82a79da89b4ab460377399aad9311</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> <!-- Additional data files here --> </asset> <!-- Required. World Poster Art. Will be used for all territories where a territory-specific poster art has not been specified --> <asset type="artwork"> <territories> <territory>WW</territory> </territories> <data_file> <locale name="en-US"/> <file_name>0973615644_WW.lsr</file_name> <size>3259063</size> <checksum type="md5">3845c150f5be339517d8fcd6c6c5fa99</checksum> </data_file> </asset> <!-- NOTE: To meet the minimum storefront requirements you must deliver the poster art asset with the title in Korean (as specified with the <locale> tag) --> <asset type="artwork"> <territories> <territory>KR</territory> </territories> <data_file> <locale name="ko"/> <file_name>0973615644_KO.lsr</file_name> <size>5753871</size> <checksum type="md5">59f6eae8171a659ba429774e3a25c7a5</checksum> </data_file> </asset> <!-- 16:9 Poster Art. Required. Will be used for all territories where a territory-specific poster art has not been specified --> <asset type="artwork_16:9"> <territories> <territory>WW</territory> </territories> <data_file> <locale name="en-US"/> <file_name>0973615644_16x9_WW.lsr</file_name> <size>4324547</size> <checksum type="md5">a56fb4f4e4a2dff955e7a9042f3d25f0</checksum> </data_file> </asset> <asset type="artwork_16:9"> <territories> <territory>KR</territory> </territories> <data_file> <locale name="ko"/> <file_name>0973615644_16x9_KO.lsr</file_name> <size>3791302</size> <checksum type="md5">ca81ed682ab65dbf44dea56b6b163331</checksum> </data_file> </asset> </assets> <products> <product> <territory>KR</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>203</wholesale_price_tier> <preorder_sales_start_date>2021-04-01</preorder_sales_start_date> <sales_start_date>2021-05-21</sales_start_date> <cleared_for_vod>true</cleared_for_vod> <vod_type>New Release</vod_type> <available_for_vod_date>2021-07-25</available_for_vod_date> <unavailable_for_vod_date>2021-11-12</unavailable_for_vod_date> <physical_release_date>2021-01-11</physical_release_date> <cleared_for_hd_vod>true</cleared_for_hd_vod> <cleared_for_hd_sale>true</cleared_for_hd_sale> <hd_wholesale_price_tier>1</hd_wholesale_price_tier> <available_for_4K_date>2021-08-25</available_for_4K_date> <burned_in_subtitles_end_date>2021-02-12</burned_in_subtitles_end_date> </product> </products> <regions> <region> <territory>KR</territory> <theatrical_release_date>2021-01-11</theatrical_release_date> <premium_end_date>2021-03-11</premium_end_date> <copyright_cline>2021 XYZ Studios. All Rights Reserved.</copyright_cline> </region> </regions> </video></package>The following annotations describe the tags specific to content protection for Korea. See the Basic Film Metadata Annotated for an explanation of a full metadata delivery, including the delivery of the <assets> block.
Watermark End Date (optional) Supplies the date that watermarking should be removed from the video. Forensic watermarking is used to help identify pirated content. Customers do not see the watermarking. 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. Note: Once the date you deliver with this tag has passed, the watermark is removed and you cannot redeliver the tag with a new date to extend the watermarking. |
Ratings (required; can be updated) Supplies a valid rating from an accepted ratings system. You can specify more than one rating but only one rating per ratings system is allowed. 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 formats are currently supported for delivering rating information:
If you use the method immediately above, the rating identified by code and the rating identified by the rating label must resolve to the same rating, for example, The classification_number attribute is required for Korean ratings. More information on ratings can be found on http://ors.kmrb.or.kr/rating/inquiry_all_list.do. The reason attribute is optional for Korean ratings. See the ratings table in Korea for a list of valid rating codes for Korea. |
Advisories (optional; can be updated) Supplies valid advisory codes to indicate violence, language, nudity, and other content. Consumers will see the advisory associated with the film while browsing the Store. See the advisories table in Korea for a list of valid codes. The following formats are currently supported for delivering advisory information:
To deliver an optional severity level, use the severity attribute:
See the severity level codes table in Korea for a list of valid severity levels. To remove a previously-delivered severity level, redeliver the metadata, omitting the severity attribute:
To change a previously-delivered severity level, redeliver the metadata with the new severity level:
|
See the Basic Film Metadata Annotated for annotations on asset delivery. |
Film Products Metadata Fields Only the product tags related to Korean deliveries are annotated below. See the Basic Film Metadata Annotated for annotations on the remaining product tags. |
Product Territory (required; can be updated) A product block is required for the film to go live, and it designates the territory, pricing, and availability dates. Product information can be updated by redelivering the metadata. See the annotations in the Basic Film Metadata Annotated for details on delivering tags not covered in the document in the |
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 (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 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. |
Burned-In Subtitles End Date (optional) Indicates when the burned-in subtitles used for content protection should be removed from the film. If you supply this tag, you must also deliver full subtitles (.itt) in Korean and the video source must be textless. In this example, the burned-in subtitles will be displayed during the super-premium window, which begins the first day of the theatrical release and ends 4 weeks after the theatrical release. On the date supplied with the 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. Once the date you deliver with this tag has passed, the content protection subtitles are removed and you cannot redeliver the tag with a new date to extend the display of the subtitles. Notes:
|
|
Premium End Date The regions block delivers regional variations in premium end dates, theatrical release dates, and copyright. The premium end date Indicates the date after which the content is no longer considered premium. Content is generally considered super-premium during the first 4 weeks after the first day of theatrical release; content is generally considered premium during the first 8 weeks after the theatrical release. On the date supplied with this tag, Apple removes the super-premium/premium text from the product page and offers the product as non-premium content. 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. See the annotations in Multiple-Language Film Metadata Annotated for details on delivering tags not covered in the |
|
The following metadata example is an excerpt from a full metadata delivery.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <language>en-US</language> <video> <type>film</type> . . . <vendor_id>1234567</vendor_id> <isan>0000-0000-03B6-0000-O-0000-0000-2</isan> <upc>093999759976</upc> <country>KR</country> <production_countries> <country primary="true">KR</country> </production_countries> <original_spoken_locale>en-US</original_spoken_locale> <title>Movie title</title> <synopsis>Synopsis of the movie</synopsis><!-- NOTE: When delivering your content, you must deliver the title and synopsis in Korean to meet the minimum storefront requirements. --> <locales> <locale name="ko"> <title>영화 제목</title> <synopsis>영화의 시놉시스</synopsis> </locale> </locales> <!-- NOTE: Some tags have been omitted in this example (as indicated by the three dots) for brevity and focus; see the Basic Example for information on sending other tags. Do not omit this data from your package. --> . . . <watermark_end_date>2021-06-22</watermark_end_date> . . . <ratings> <rating code="PG-13" reason="for drug content, some sensuality and war violence" system="mpaa"/> <rating code="18" system="kr-movies" classification_number="2019-MF01716"/> </ratings> . . . <assets> <asset type="full"> <data_file role="source"> <locale name="ko"/> <file_name>335f917-source.mov</file_name> <size>2595225600</size> <checksum type="md5">fe82a79dd93a89b499aa211ab4603773</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> <!-- NOTE: If you are using the burned-in subtitles content protection measure, you must deliver the subtitles .itt file. --> <data_file role="subtitles"> <locale name="ko"/> <file_name>335f917-subtitles_ko.itt</file_name> <size>88474</size> <checksum type="md5">c123e860384b8b954f169c9af0cbe4df</checksum> </data_file> <!-- NOTE: To meet the minimum storefront requirements, you must deliver the full subtitles or alternate audio in Korean. --> <data_file role="subtitles"> <locale name="ko"/> <file_name>335f917-subtitles_ko.itt</file_name> <size>88474</size> <checksum type="md5">f0cbe4df954f169c123e860384b8bc9a</checksum> </data_file> <data_file role="audio"> <locale name="ko"/> <file_name>audio_ko.mov</file_name> <checksum type="md5">bdeea426ac79543b691a45507e9956c8</checksum> <size>5820197005</size> </data_file> <!-- Additional data files here --> </asset> <asset type="preview"> <data_file role="source"> <locale name="en-US"/> <file_name>335f917-preview-source.mov</file_name> <size>2235952</size> <checksum type="md5">2fe82a79da89b4ab460377399aad9311</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> <!-- Additional data files here --> </asset> <!-- Required. World Poster Art. Will be used for all territories where a territory-specific poster art has not been specified --> <asset type="artwork"> <territories> <territory>WW</territory> </territories> <data_file> <locale name="en-US"/> <file_name>0973615644_WW.lsr</file_name> <size>3259063</size> <checksum type="md5">3845c150f5be339517d8fcd6c6c5fa99</checksum> </data_file> </asset> <!-- NOTE: To meet the minimum storefront requirements you must deliver the poster art asset with the title in Korean (as specified with the <locale> tag) --> <asset type="artwork"> <territories> <territory>KR</territory> </territories> <data_file> <locale name="ko"/> <file_name>0973615644_KO.lsr</file_name> <size>5753871</size> <checksum type="md5">59f6eae8171a659ba429774e3a25c7a5</checksum> </data_file> </asset> <!-- 16:9 Poster Art. Required. Will be used for all territories where a territory-specific poster art has not been specified --> <asset type="artwork_16:9"> <territories> <territory>WW</territory> </territories> <data_file> <locale name="en-US"/> <file_name>0973615644_16x9_WW.lsr</file_name> <size>4324547</size> <checksum type="md5">a56fb4f4e4a2dff955e7a9042f3d25f0</checksum> </data_file> </asset> <asset type="artwork_16:9"> <territories> <territory>KR</territory> </territories> <data_file> <locale name="ko"/> <file_name>0973615644_16x9_KO.lsr</file_name> <size>3791302</size> <checksum type="md5">ca81ed682ab65dbf44dea56b6b163331</checksum> </data_file> </asset> </assets> <products> <product> <territory>KR</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>203</wholesale_price_tier> <preorder_sales_start_date>2021-04-01</preorder_sales_start_date> <sales_start_date>2021-05-21</sales_start_date> <cleared_for_vod>true</cleared_for_vod> <vod_type>New Release</vod_type> <available_for_vod_date>2021-07-25</available_for_vod_date> <unavailable_for_vod_date>2021-11-12</unavailable_for_vod_date> <physical_release_date>2021-01-11</physical_release_date> <cleared_for_hd_vod>true</cleared_for_hd_vod> <cleared_for_hd_sale>true</cleared_for_hd_sale> <hd_wholesale_price_tier>1</hd_wholesale_price_tier> <available_for_4K_date>2021-08-25</available_for_4K_date> <burned_in_subtitles_end_date>2021-02-12</burned_in_subtitles_end_date> </product> </products> <regions> <region> <territory>KR</territory> <theatrical_release_date>2021-01-11</theatrical_release_date> <premium_end_date>2021-03-11</premium_end_date> <copyright_cline>2021 Paramount Studios. All Rights Reserved.</copyright_cline> </region> </regions> </video></package>This chapter specifies the iTunes Timed Text (iTT) file format for delivering timed text content to Apple. The iTT file format is a subset of the Timed Text Markup Language, Version 1.0 from the World Wide Web Consortium (W3C). All iTT documents are TTML documents that use the restricted subset of TTML.
An iTT document specifies the font style, font color, text alignment, and layout of the timed text, as well as the text itself and the timing. The iTT format restricts what can be specified to make sure that the content is suitable for use as a subtitle track in transactional content.
To create iTT subtitles, use Final Cut Pro or a third-party captions-authoring app to output an iTT file.
Once the iTT document has been created and saved with the .itt extension, it is delivered as an asset in the <assets> block in either an asset-only update or with the full film metadata.xml.
Note: If you've never delivered subtitles before, contact your Technical Representative
The following terms are used in this chapter:
Subtitles: A full translation of all the words spoken in the film used to assist the audience in translating the primary spoken audio in its entirety. For example, a French film (in which the actors are speaking French) will be sold in two territories (Germany and Spain). Subtitles would be delivered in German and Spanish. The subtitle text can be turned on or off by the customer (as opposed to burned-in subtitles). Also called Full Subtitles. Subtitles are delivered as a separate iTT file.
SDH: A full translation of all the words spoken in the film, as well as sound effects (owl hooting, scream in distance, for example), and song lyrics. SDH can be turned on or off by the customer. For example, a French film (in which the actors are speaking French) will be sold in two territories (France and Canada). SDH could be delivered in French and English. SDH are delivered as separate files.
Forced Subtitles: A partial translation of the words spoken in a film, or informative text that supplements the plot of the story or describes the setting without using a narrator. This is not to be confused with burned-in subtitles/narratives. Forced subtitles are delivered as a separate file. Forced subtitles cannot be turned off and are necessary to understand what is going on in the film. Text in forced subtitles must be duplicated in the full subtitle file of the same language because they do not automatically play back when the full subtitle is selected.
Below is an example XML document in iTT format for delivering subtitles.
<?xml version="1.0" encoding="UTF-8"?><tt xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.w3.org/ns/ttml" xmlns:tt="http://www.w3.org/ns/ttml" xmlns:tts="http://www.w3.org/ns/ttml#styling" xmlns:ttp="http://www.w3.org/ns/ttml#parameter" xml:lang="en-US" ttp:timeBase="smpte" ttp:frameRate="24" ttp:frameRateMultiplier="999 1000" ttp:dropMode="nonDrop"> <head> <styling> <style xml:id="normal" tts:fontFamily="sansSerif" tts:fontWeight="normal" tts:fontStyle="normal" tts:color="white" tts:fontSize="100%"/> <style xml:id="bold" tts:fontFamily="sansSerif" tts:fontWeight="bold" tts:fontStyle="normal" tts:color="white" tts:fontSize="100%"/> <style xml:id="italic" tts:fontFamily="sansSerif" tts:fontWeight="normal" tts:fontStyle="italic" tts:color="white" tts:fontSize="100%"/> <style xml:id="yellow" tts:fontFamily="sansSerif" tts:fontWeight="normal" tts:fontStyle="normal" tts:color="rgb(255,255,0)" tts:fontSize="100%"/> </styling> <layout> <region xml:id="top" tts:origin="0% 0%" tts:extent="100% 15%" tts:textAlign="center" tts:displayAlign="before"/> <region xml:id="bottom" tts:origin="0% 85%" tts:extent="100% 15%" tts:textAlign="center" tts:displayAlign="after"/> </layout> </head> <body style="normal" region="bottom"> <div begin="-01:00:00:00"> <p begin="01:00:06:09" end="01:00:11:13"> <span style="bold">iPhone 4</span> is so much more than just a new product.</p> <p begin="01:04:16:15" end="01:04:25:00"> The <span style="bold">iPhone</span>, for a user, it is simplicity, it is easy to use. <br/>Behind it is <span style="italic"> <span style="yellow">intense</span> technology.</span> </p> </div> </body></tt>The symbol 
in the annotations indicates that the value must be delivered as specified to conform with the iTT format. The reference numbers (for example, §7.2.2) refer to the section in the TTML specification in which the element is explained.
XML Declaration (required) The character encoding of your document must be defined. Apple only accepts UTF-8 encoding as it efficiently encodes non-Roman characters. Important: The iTT file must not contain a byte-order mark (BOM). |
Document Container §7.1.1 (required) The |
Language §7.2.2 (required) This is the same format that is described for use in the |
Timecodes |
Timecode format (required) These attributes specify how the timecodes in the document should be interpreted. Note: Many software based video systems, including those from Apple, use the imprecise value of 29.97 as the frame rate for NTSC video. So although 1000 1001 would be the precise rate for NTSC, 999 1000 is used. The values to use for common formats are as follows: |
Frame Rate (frameRate) | Multiplier (frameRateMultiplier) | Description | Effective FPS |
|---|---|---|---|
30 | 1 1 | ATSC Video | 30 |
30 | 999 1000 | NTSC Video (Imprecise) | 29.97 |
25 | 1 1 | PAL Video | 25 |
24 | 1 1 | Film | 24 |
24 | 999 1000 | NTSC Film (Imprecise) | 23.976 |
Important: If one of these five does not match your frame rate, contact your Technical Representative. Each attribute is described in the rows that follow. |
Time Base §6.2.11 (required)
|
Frame Rate §6.2.4 (required)
|
Frame Rate Multiplier §6.2.5 (required)
Note: The TTML specification has changed the way the frameRateMultiplier is expressed by replacing the colon (:) with a space. For example, |
Drop Mode §6.2.3 (required)
Note: The convention of using a semicolon (;) separator for frames is not allowed to indicate drop frame. The |
Head Element |
Head §7.1.2 ( required) Begins the head element, which defines attributes to be used in the |
Styling §8.1.1 ( required) Defines the common color, weight, family and styles of the title texts. This section defines all styles to be used in the body of your document. |
Style §8.1.2 ( required) Defines the appearance of the title text. In the annotated example, four font styles are defined to set the appearance of the title text which will be used in the Each attribute is described in the rows that follow. |
XML ID ( required) The |
Font Family ( required)
More information about font families can be found in section 8.2.9 of the TTML specification. |
Font Weight §8.2.12 ( required)
|
Font Style §8.2.11 ( required)
|
Font Color §8.2.3 (further explained in §8.3.2) ( required)
Note: Only 100% opacity is supported. For example, neither More information about color values can be found in section 8.3.2 of the TTML specification. |
Font Size (required)
|
Layout §9.1.1 (required) Defines the location of the timed text within the frame. |
Region §9.1.2 (required)
Apple may vary positioning and wrapping in order to best present the content on the variety of supported screens and devices including televisions. The following image shows the top and bottom regions within a video frame:  Note: The assignment of a |
Body Element |
Body §7.1.3 (required) Begins the body element, used to determine the titles and their timings. Attributes defined in the The attribute The attribute |
Div §7.1.4 (required) Begins the section within the document where you enter the actual text of the timed titles and the timing. The optional timecode value supplied with the
The |
Example Paragraph 1 §7.1.5 Each Only one When displayed, the  Within A styled span element encloses the text that should be displayed in bold, overriding the default style. |
Example Paragraph 2 §7.1.5 When displayed, this  |
|
Tags related to subtitles are delivered in the <assets> block of the full metadata.xml. The metadata examples below show only the <assets> block portions to illustrate how to deliver subtitles and forced subtitles for a feature film. Only the tags specific to subtitles and forced subtitles are explained in the annotations. See Multiple Language Films for details on the remaining tags and to view the full metadata.xml.
The <file_name>, <size>, and <checksum> tags are required, but are not annotated below. See Multiple Language Films for details on those tags.
This data file contains the full set of timed subtitles. Indicating a locale is required.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <language>en-US</language> <provider>Miramax</provider> <video> ... <assets> <asset type="full"> <data_file role="subtitles"> <locale name="fr-FR"/> <file_name>09736156444-subtitles.itt</file_name> <size>100259</size> <checksum type="md5">9df86c3e43e7b43ddeabb2ddfe4b8a42</checksum> </data_file> </asset> ... </assets> ... </video></package>
Assets (required, multiple from a set; can be updated) Begins the assets block that references the assets being delivered. Subtitles can be delivered only with the full source. |
Data File (required) Subtitles are delivered as a |
Locale Name (required) Identifies the language in which the subtitles appear. The locale indicates both the language and the optional location where the language is spoken. In cases where specifying a region is appropriate, use the hyphen character to combine a language subtag with a region subtag. The value used for |
. . . |
The forced subtitles data file contains the set of subtitles that must be forced-displayed when a viewer plays the matching dubbed audio locale. The forced-subtitles must be a subset of the full set of subtitles. Indicating a locale is required and it must match the locale of the audio.
Text in forced subtitles must be duplicated in the full subtitle file of the same language because they do not automatically play back when the full subtitle is selected.
Because the forced subtitles are a subset of the full subtitles, all text within the <body> block must match their corresponding text in the full set of subtitles.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <language>en-US</language> <provider>Miramax</provider> <video> ... <assets> <asset type="full"> <data_file role="forced_subtitles"> <locale name="fr-FR"/> <file_name>09736156444-forcedsubtitles.itt</file_name> <size>4756</size> <checksum type="md5">3edea7b43d9df86c3e4fe4b8a42dbb2d</checksum> </data_file> </asset> ... </assets> ... </video></package>
Assets (required, multiple from a set; can be updated) Begins the assets block that references the assets being delivered. Forced subtitles can be delivered only with the full source. |
Data File (required) Forced subtitles are delivered as a |
Locale Name (required) Identifies the language in which the forced subtitles appear. The locale indicates both the language and the specific location where the language is spoken. The locale must be the same as the corresponding audio. In cases where specifying a region is appropriate, use the hyphen character to combine a language subtag with a region subtag. The value used for |
. . . |
To validate the iTT document, you need the iTunes Timed Text Schema Validation document (itunes-timed-text.complete.rnc). To validate the timed text iTT document, use available tools that support RelaxNG Condensed Schema validation.
The TTML schemas published by the W3C (https://www.w3.org/TR/ttml1/#ttml-schema-rnc can be used to validate that an iTT document meets base line conformance. But to verify that a document conforms to the more stringent requirements required by Apple, you must use the iTT schema.
The following shows an example of using the open source utility Jing (https://relaxng.org/jclark/jing.html) to validate a document against the DXFP schema, and then against the iTT schema. The following example document fails to validate as iTT because it uses a disallowed font style:
> java -cp isorelax.jar:saxon.jar:xercesImpl.jar:xml-apis.jar \ -jar jing.jar -c schemas/ttaf1-dfxp.rnc test_document.itt > java -cp isorelax.jar:saxon.jar:xercesImpl.jar:xml-apis.jar \ -jar jing.jar -c schemas/itunes-timed-text.complete.rnc test_document.itt /private/tmp/examples/test_document.idfxp:21:21: error: value ofattribute "tts:fontStyle" is invalid; must be equal to "italic" or "normal"For more information on validation, refer to the Schema Validation Guide.
All the following criteria must be met for a valid TTML document to also be a valid iTT document.
iTT filenames must use .itt as their file extension.
The only allowed and default value for the timeContainer attribute is par. Time expressions will be interpreted as relative to the temporal interval of their container, not their siblings.
Time values must be expressed as clock-time, as defined in section 10.3.1 of TTML, HH:MM:SS:FF, e.g. 01:12:23:10.
One difference from TTML, however, is that sub-frame notation is in clock-time expressions is not supported, and partial values such as 01:13:12:10.3 will not be accepted in iTT documents.
Time spans cannot be expressed as durations. All timings must be expressed with begin and end attributes. The dur attribute is not allowed.
Time spans also cannot overlap. The begin attribute of any given time container must not come before or be the same as the end of another. Time spans also cannot overlap.
Time expressions in span elements will be interpreted as being relative to those expressed in their containing element, as per section 10.2.4 of TTML. Values in time expressions that assume a non-zero start time may be accommodated by specifying the offset in the begin attribute of their parent div element. For example, the following example uses this offset to indicate that the titles are using start time of 01:00:00:00, and require adjustment before their values express the actual time they should appear in the video.
<div begin="-01:00:00:00"> <p begin="01:00:05:00" end="01:00:10:00"> This text should appear at 00:00:05:00 </p></div>Note: The Apple encoding process synchronizes subtitles relative to absolute zero in the media and not the QuickTime movie's timecode track. It is important that your time expressions match relative to the program start. Using the offset feature shown above is one way to ensure your existing timecodes easily match to the media.
The ttp:timeBase value (as defined in TTML §6.2.11) must be smpte.
The only allowed, and default, value for the ttp:markerMode attribute is continuous.
Timecodes may not specified with subframe units, and any that do will be rejected as invalid. The ttp:subframeRate may only be specified as "1", but will be ignored.
Metric notation is not allowed in time expressions. The ttp:tickRate attribute will be ignored.
As described in iTunes Timed Text Annotated, each paragraph can have only one line break, which means you are limited to two lines of text.
A single iTT document will be used to produce titles that will be displayed at many different resolutions. All spatial values must be expressed in a relative fashion, for example, 100% or 1em.
See the annotated example above for details regarding color values.
Given the wide variety of screens and devices the title may be displayed on, it is at the discretion of the player or playback device whether to use any colors that are specified.
This means that text with a color specified may display as in that color, or as white. Whether or not to display a title with any transparency is also at the discretion of the player or device.
If specified, the tts:backgroundColor must be set to "transparent".
The allowed values for the tts:direction attribute are ltr for left-to-right languages and rtl for right-to-left languages (Arabic and Hebrew).
Note: To indicate the direction of bi-directional text (such as Arabic and Hebrew), you can also use the escape character: U+200E LEFT-TO-RIGHT MARK or U+200F RIGHT-TO-LEFT MARK [1].
The only allowed (and default) value for the tts:unicodeBidi attribute is normal.
Style animations and marquis text are not supported, therefore the set element is disallowed.
If the tts:display attribute is set, the value must be auto.
The only (and default) value allowed for the tts:showBackground attribute is always.
Dynamic flow is not supported. The only allowed value for the tts:dynamicFlow attribute, if used, is none.
The allowed values for the tts:overflow attribute, if used, are visible (default) and hidden.
The only allowed value for the tts:zIndex parameter, if used, is 0.
The allowed values for the tts:writingMode attribute are lrtb and lr.
The only allowed (and default) value for the tts:visibility attribute is visible.
The allowed values for the lineHeight datatype are 1em or 100%.
The opacity attribute is not allowed.
Padding is not supported. The allowed values for the tts:padding attribute, if present, are 0px, 0em, and 0% — i.e. none.
Outlines are not supported. The only allowed value for the tts:textOutline attribute (if present) is none.
Cell Resolution is not supported. The ttp:cellResolution attribute is not allowed.
The allowed values for the tts:textDecoration datatype are none, underline, noUnderline, noOverline, noLineThrough.
If the tts:textAlign attribute is specified in a region or style element of the subtitle TTML, the only allowed value is center.
If the tts:displayAlign attribute is specified in a region or style, the only allowed values are "before" or "after". "center" may not be used.
Region assignment in a document is regarded as a preference. Text that is specified to be displayed the top text region may end up displayed in the bottom region, as usability concerns or device and software limitations require.
The assignment of a region to span elements is forbidden. Text cannot be displayed in both of the available regions simultaneously. All the text under a single <p> element will be displayed in either the top or bottom region. Which of these is chosen is determined by the value of the region parameter assigned to or inherited by their <p> element.
Inside a "p" element or a "span", all whitespace, tabs, and newlines between one line of text and the next will be interpreted to be a single space.
This chapter specifies the tags to use in an iTunes Timed Text Format (iTT) file to support ruby and vertical subtitles in Japanese. The chapter covers only the tags specific to delivering ruby and vertical subtitles. For information on the iTT format, see Overview. For more information on ruby, see http://www.w3.org/TR/ruby/.
Notes:
Non-Japanese content must use the standard iTunes Timed Text profile. The information provided in this chapter relates only to Japanese content.
Vertical Text and Rubies in the default position and alignment will be enabled for all subtitles.
Up to 3 lines of Japanese subtitles can be displayed in a single region using two line break tags (<br/>).
Advanced features such as Ruby Styles (position and alignment), Tate Chu Yoko (TC), bold, and italics may be limited depending on the device and operating system.
Ruby refers to text annotations that appear with other text, such as Japanese subtitles written in kanji paired with the phonetic reading of the kanji. The subtitles and the associated ruby text can be placed either vertically or horizontally. The kanji are considered the “ruby base text” and the phonetic annotations are considered the “ruby text.”
In addition to ruby support, extensions have been added to support vertical text, which could be used for subtitles for the dialogue or narrative text (such as time and place). You can also specify where the text should be positioned on the screen, either on the right or the left.
To support ruby and vertical text, several parameters have been added to the iTT format. See Ruby Annotations for details.
Ruby namespace
Ruby extension
Vertical extension
Writing mode parameters
Region parameters
Ruby container tag and attribute
Ruby base attribute value
Ruby text attribute value
Ruby annotations can be styled using ruby position and align. The sections below show the syntax and allowed values, as well as screenshot illustrations. The following is an example of styling ruby text:
<styling> <style xml:id="ruby-before" tts:fontFamily="sansSerif" tts:color="white" tts:fontStyle="normal" tts:fontSize="100%" tts:fontWeight="normal" ry:position="before"/></styling>See iTunes Timed Text Example for Ruby for a complete example and see iTunes Timed Text for Ruby Annotated for annotations.
ry:position=["before"|"after"]
Use ry:position to indicate the position of the ruby text with respect to the ruby base characters. Note that if you do not specify a value for ry:position, "before" will be used by default.
before
after
ry:align =["start"|"center"|"spaceBetween"|"spaceAround"]
Example
<styling> <style xml:id="ruby-before" tts:fontFamily="sansSerif" tts:color="white" tts:fontStyle="normal" tts:fontSize="100%" tts:fontWeight="normal" ry:align="start"/></styling>Use ry:align with the following attributes:
start
center
spaceBetween
The spaces between the characters are equal. Note that if you do not specify a value for ry:align, "spaceBetween" will be used by default.
spaceAround
This leaves half a character width of space on either side.
Keep the following in mind when delivering vertical text:
Include only ruby, Japanese characters, numbers, and full-width Latin characters in vertical text. Text in languages that are not normally displayed vertically, such as English, will need to be in full-width characters. Note that although Tate Chu Yoko (TC) is contained within vertical text, it is considered to be horizontal text and can only contain half-width numbers.
Use the characters specified in UTR (Unicode Technical Report) 50 to ensure proper placement and rotation for vertical subtitles.
The following principles apply to both vertical and horizontal character mapping:
Chidori Character Mapping: The following underscores will be mapped to spaces if used at the start of the subtitle line:
＿：U+FF3F：U+3000
_： U+005F：U+00A0
The following principles apply to vertical character mapping:
As a convenience for subtitle authors, Apple will map half-width characters in vertical character spans to full-width characters based on the Unicode CJK compatibility (UFE30) and Halfwidth and Fullwidth (UFF00) standards.
The rationale for this mapping is the comment in http://www.unicode.org/reports/tr11/:
“Wide characters behave like ideographs; they tend to allow line breaks after each character and remain upright in vertical text layout. Narrow characters are kept together in words or runs that are rotated sideways in vertical text layout.”
The following rules apply:
The Unicode CJK compatibility standard (http://www.unicode.org/charts/PDF/UFE30.pdf) overrides any mapping from Unicode Halfwidth and Fullwidth standard (http://www.unicode.org/charts/PDF/UFF00.pdf).
This mapping is not performed for characters within Tate Chu Yoko (TC) spans.
The table below is a reference for character mapping done in subtitle iTT files to support vertical subtitles.
ASCII | |||||
|---|---|---|---|---|---|
From Char | Hex | Dec | To Char | Hex | Dec |
! | 0021 | 33 | ！ | FF01 | 65281 |
" | 0022 | 34 | ＂ | FF02 | 65282 |
# | 0023 | 35 | ＃ | FF03 | 65283 |
$ | 0024 | 36 | ＄ | FF04 | 65284 |
% | 0025 | 37 | ％ | FF05 | 65285 |
& | 0026 | 38 | ＆ | FF06 | 65286 |
' | 0027 | 39 | ＇ | FF07 | 65287 |
( | 0028 | 40 | （ | FF08 | 65288 |
) | 0029 | 41 | ） | FF09 | 65289 |
* | 002A | 42 | ＊ | FF0A | 65290 |
+ | 002B | 43 | ＋ | FF0B | 65291 |
, | 002C | 44 | ， | FF0C | 65292 |
- | 002D | 45 | － | FF0D | 65293 |
. | 002E | 46 | ． | FF0E | 65294 |
/ | 002F | 47 | ／ | FF0F | 65295 |
0 | 0030 | 48 | ０ | FF10 | 65296 |
1 | 0031 | 49 | １ | FF11 | 65297 |
2 | 0032 | 50 | ２ | FF12 | 65298 |
3 | 0033 | 51 | ３ | FF13 | 65299 |
4 | 0034 | 52 | ４ | FF14 | 65300 |
5 | 0035 | 53 | ５ | FF15 | 65301 |
6 | 0036 | 54 | ６ | FF16 | 65302 |
7 | 0037 | 55 | ７ | FF17 | 65303 |
8 | 0038 | 56 | ８ | FF18 | 65304 |
9 | 0039 | 57 | ９ | FF19 | 65305 |
: | 003A | 58 | ： | FF1A | 65306 |
; | 003B | 59 | ； | FF1B | 65307 |
< | 003C | 60 | ＜ | FE3F | 65308 |
= | 003D | 61 | ＝ | FF1D | 65309 |
> | 003E | 62 | ＞ | FE40 | 65310 |
? | 003F | 63 | ？ | FF1F | 65311 |
@ | 0040 | 64 | ＠ | FF20 | 65312 |
A | 0041 | 65 | Ａ | FF21 | 65313 |
B | 0042 | 66 | Ｂ | FF22 | 65314 |
C | 0043 | 67 | Ｃ | FF23 | 65315 |
D | 0044 | 68 | Ｄ | FF24 | 65316 |
E | 0045 | 69 | Ｅ | FF25 | 65317 |
F | 0046 | 70 | Ｆ | FF26 | 65318 |
G | 0047 | 71 | Ｇ | FF27 | 65319 |
H | 0048 | 72 | Ｈ | FF28 | 65320 |
I | 0049 | 73 | Ｉ | FF29 | 65321 |
J | 004A | 74 | Ｊ | FF2A | 65322 |
K | 004B | 75 | Ｋ | FF2B | 65323 |
L | 004C | 76 | Ｌ | FF2C | 65324 |
M | 004D | 77 | Ｍ | FF2D | 65325 |
N | 004E | 78 | Ｎ | FF2E | 65326 |
O | 004F | 79 | Ｏ | FF2F | 65327 |
P | 0050 | 80 | Ｐ | FF30 | 65328 |
Q | 0051 | 81 | Ｑ | FF31 | 65329 |
R | 0052 | 82 | Ｒ | FF32 | 65330 |
S | 0053 | 83 | Ｓ | FF33 | 65331 |
T | 0054 | 84 | Ｔ | FF34 | 65332 |
U | 0055 | 85 | Ｕ | FF35 | 65333 |
V | 0056 | 86 | Ｖ | FF36 | 65334 |
W | 0057 | 87 | Ｗ | FF37 | 65335 |
X | 0058 | 88 | Ｘ | FF38 | 65336 |
Y | 0059 | 89 | Ｙ | FF39 | 65337 |
Z | 005A | 90 | Ｚ | FF3A | 65338 |
[ | 005B | 91 | ［ | FF3B | 65339 |
\ | 005C | 92 | ＼ | FF3C | 65340 |
] | 005D | 93 | ］ | FF3D | 65341 |
^ | 005E | 94 | ＾ | FF3E | 65342 |
_ | 005F | 95 | ＿ | FF3F | 65343 |
` | 0060 | 96 | ｀ | FF40 | 65344 |
a | 0061 | 97 | ａ | FF41 | 65345 |
b | 0062 | 98 | ｂ | FF42 | 65346 |
c | 0063 | 99 | ｃ | FF43 | 65347 |
d | 0064 | 100 | ｄ | FF44 | 65348 |
e | 0065 | 101 | ｅ | FF45 | 65349 |
f | 0066 | 102 | ｆ | FF46 | 65350 |
g | 0067 | 103 | ｇ | FF47 | 65351 |
h | 0068 | 104 | ｈ | FF48 | 65352 |
i | 0069 | 105 | ｉ | FF49 | 65353 |
j | 006A | 106 | ｊ | FF4A | 65354 |
k | 006B | 107 | ｋ | FF4B | 65355 |
l | 006C | 108 | ｌ | FF4C | 65356 |
m | 006D | 109 | ｍ | FF4D | 65357 |
n | 006E | 110 | ｎ | FF4E | 65358 |
o | 006F | 111 | ｏ | FF4F | 65359 |
p | 0070 | 112 | ｐ | FF50 | 65360 |
q | 0071 | 113 | ｑ | FF51 | 65361 |
r | 0072 | 114 | ｒ | FF52 | 65362 |
s | 0073 | 115 | ｓ | FF53 | 65363 |
t | 0074 | 116 | ｔ | FF54 | 65364 |
u | 0075 | 117 | ｕ | FF55 | 65365 |
v | 0076 | 118 | ｖ | FF56 | 65366 |
w | 0077 | 119 | ｗ | FF57 | 65367 |
x | 0078 | 120 | ｘ | FF58 | 65368 |
y | 0079 | 121 | ｙ | FF59 | 65369 |
z | 007A | 122 | ｚ | FF5A | 65370 |
{ | 007B | 123 | ｛ | FF5B | 65371 |
| | 007C | 124 | ｜ | FF5C | 65372 |
} | 007D | 125 | ｝ | FF5D | 65373 |
~ | 007E | 126 | ～ | FF5E | 65374 |
Brackets | |||||
|---|---|---|---|---|---|
From Char | Hex | Dec | To Char | Hex | Dec |
⦅ | 2985 | 10629 | ｟ | FF5F | 65375 |
⦆ | 2986 | 10630 | ｠ | FF60 | 65376 |
Hangul Variants | |||||
|---|---|---|---|---|---|
From Char | Hex | Dec | To Char | Hex | Dec |
ﾡ | FFA1 | 65441 | ㄱ | 3131 | 12593 |
ﾢ | FFA2 | 65442 | ㄲ | 3132 | 12594 |
ﾣ | FFA3 | 65443 | ㄳ | 3133 | 12595 |
ﾤ | FFA4 | 65444 | ㄴ | 3134 | 12596 |
ﾥ | FFA5 | 65445 | ㄵ | 3135 | 12597 |
ﾦ | FFA6 | 65446 | ㄶ | 3136 | 12598 |
ﾧ | FFA7 | 65447 | ㄷ | 3137 | 12599 |
ﾨ | FFA8 | 65448 | ㄸ | 3138 | 12600 |
ﾩ | FFA9 | 65449 | ㄹ | 3139 | 12601 |
ﾪ | FFAA | 65450 | ㄺ | 313A | 12602 |
ﾫ | FFAB | 65451 | ㄻ | 313B | 12603 |
ﾬ | FFAC | 65452 | ㄼ | 313C | 12604 |
ﾭ | FFAD | 65453 | ㄽ | 313D | 12605 |
ﾮ | FFAE | 65454 | ㄾ | 313E | 12606 |
ﾯ | FFAF | 65455 | ㄿ | 313F | 12607 |
ﾰ | FFB0 | 65456 | ㅀ | 3140 | 12608 |
ﾱ | FFB1 | 65457 | ㅁ | 3141 | 12609 |
ﾲ | FFB2 | 65458 | ㅂ | 3142 | 12610 |
ﾳ | FFB3 | 65459 | ㅃ | 3143 | 12611 |
ﾴ | FFB4 | 65460 | ㅄ | 3144 | 12612 |
ﾵ | FFB5 | 65461 | ㅅ | 3145 | 12613 |
ﾶ | FFB6 | 65462 | ㅆ | 3146 | 12614 |
ﾷ | FFB7 | 65463 | ㅇ | 3147 | 12615 |
ﾸ | FFB8 | 65464 | ㅈ | 3148 | 12616 |
ﾹ | FFB9 | 65465 | ㅉ | 3149 | 12617 |
ﾺ | FFBA | 65466 | ㅊ | 314A | 12618 |
ﾻ | FFBB | 65467 | ㅋ | 314B | 12619 |
ﾼ | FFBC | 65468 | ㅌ | 314C | 12620 |
ﾽ | FFBD | 65469 | ㅍ | 314D | 12621 |
ﾾ | FFBE | 65470 | ㅎ | 314E | 12622 |
ￂ | FFC2 | 65474 | ㅏ | 314F | 12623 |
ￃ | FFC3 | 65475 | ㅐ | 3150 | 12624 |
ￄ | FFC4 | 65476 | ㅑ | 3151 | 12625 |
ￅ | FFC5 | 65477 | ㅒ | 3152 | 12626 |
ￆ | FFC6 | 65478 | ㅓ | 3153 | 12627 |
ￇ | FFC7 | 65479 | ㅔ | 3154 | 12628 |
ￊ | FFCA | 65482 | ㅕ | 3155 | 12629 |
ￋ | FFCB | 65483 | ㅖ | 3156 | 12630 |
ￌ | FFCC | 65484 | ㅗ | 3157 | 12631 |
ￍ | FFCD | 65485 | ㅘ | 3158 | 12632 |
ￎ | FFCE | 65486 | ㅙ | 3159 | 12633 |
ￏ | FFCF | 65487 | ㅚ | 315A | 12634 |
ￒ | FFD2 | 65490 | ㅛ | 315B | 12635 |
ￓ | FFD3 | 65491 | ㅜ | 315C | 12636 |
ￔ | FFD4 | 65492 | ㅝ | 315D | 12637 |
ￕ | FFD5 | 65493 | ㅞ | 315E | 12638 |
ￖ | FFD6 | 65494 | ㅟ | 315F | 12639 |
ￗ | FFD7 | 65495 | ㅠ | 3160 | 12640 |
ￚ | FFDA | 65498 | ㅡ | 3161 | 12641 |
ￛ | FFDB | 65499 | ㅢ | 3162 | 12642 |
ￜ | FFDC | 65500 | ㅣ | 3163 | 12643 |
ﾠ | FFA0 | 65440 | ㅤ | 3164 | 12644 |
Halfwidth CJK punctuation | |||||
|---|---|---|---|---|---|
From Char | Hex | Dec | To Char | Hex | Dec |
｡ | FF61 | 65377 | 。 | 3002 | 12290 |
､ | FF64 | 65380 | 、 | 3001 | 12289 |
Fullwidth CJK punctuation | |||||
|---|---|---|---|---|---|
From Char | Hex | Dec | To Char | Hex | Dec |
－ | FF0D | 65293 | ︲ | FE32 | 65074 |
Fullwidth symbol variants | |||||
|---|---|---|---|---|---|
From Char | Hex | Dec | To Char | Hex | Dec |
¢ | 00A2 | 162 | ￠ | FFE0 | 65504 |
£ | 00A3 | 163 | ￡ | FFE1 | 65505 |
¬ | 00AC | 172 | ￢ | FFE2 | 65506 |
¯ | 00AF | 175 | ￣ | FFE3 | 65507 |
¦ | 00A6 | 166 | ￤ | FFE4 | 65508 |
¥ | 00A5 | 165 | ￥ | FFE5 | 65509 |
₩ | 20A9 | 8361 | ￦ | FFE6 | 65510 |
Halfwidth symbol variants | |||||
|---|---|---|---|---|---|
From Char | Hex | Dec | To Char | Hex | Dec |
￨ | FFE8 | 65512 | │ | 2502 | 9474 |
￩ | FFE9 | 65513 | ← | 2190 | 8592 |
￪ | FFEA | 65514 | ↑ | 2191 | 8593 |
￫ | FFEB | 65515 | → | 2192 | 8594 |
￬ | FFEC | 65516 | ↓ | 2193 | 8595 |
￭ | FFED | 65517 | ■ | 25A0 | 9632 |
￮ | FFEE | 65518 | ○ | 25CB | 9675 |
Halfwidth Katakana variants | |||||
|---|---|---|---|---|---|
From Char | Hex | Dec | To Char | Hex | Dec |
･ | FF65 | 65381 | ・ | 30FB | 12539 |
ｦ | FF66 | 65382 | ヲ | 30F2 | 12530 |
ｧ | FF67 | 65383 | ァ | 30A1 | 12449 |
ｨ | FF68 | 65384 | ィ | 30A3 | 12451 |
ｩ | FF69 | 65385 | ゥ | 30A5 | 12453 |
ｪ | FF6A | 65386 | ェ | 30A7 | 12455 |
ｫ | FF6B | 65387 | ォ | 30A9 | 12457 |
ｬ | FF6C | 65388 | ャ | 30E3 | 12515 |
ｭ | FF6D | 65389 | ュ | 30E5 | 12517 |
ｮ | FF6E | 65390 | ョ | 30E7 | 12519 |
ｯ | FF6F | 65391 | ッ | 30C3 | 12483 |
ｰ | FF70 | 65392 | ー | 30FC | 12540 |
ｱ | FF71 | 65393 | ア | 30A2 | 12450 |
ｲ | FF72 | 65394 | イ | 30A4 | 12452 |
ｳ | FF73 | 65395 | ウ | 30A6 | 12454 |
ｴ | FF74 | 65396 | エ | 30A8 | 12456 |
ｵ | FF75 | 65397 | オ | 30AA | 12458 |
ｶ | FF76 | 65398 | カ | 30AB | 12459 |
ｷ | FF77 | 65399 | キ | 30AD | 12461 |
ｸ | FF78 | 65400 | ク | 30AF | 12463 |
ｹ | FF79 | 65401 | ケ | 30B1 | 12465 |
ｺ | FF7A | 65402 | コ | 30B3 | 12467 |
ｻ | FF7B | 65403 | コ | 30B5 | 12469 |
ｼ | FF7C | 65404 | シ | 30B7 | 12471 |
ｽ | FF7D | 65405 | ス | 30B9 | 12473 |
ｾ | FF7E | 65406 | ス | 30BB | 12475 |
ｿ | FF7F | 65407 | ソ | 30BD | 12477 |
ﾀ | FF80 | 65408 | タ | 30BF | 12479 |
ﾁ | FF81 | 65409 | チ | 30C1 | 12481 |
ﾂ | FF82 | 65410 | ツ | 30C4 | 12484 |
ﾃ | FF83 | 65411 | テ | 30C6 | 12486 |
ﾄ | FF84 | 65412 | ト | 30C8 | 12488 |
ﾅ | FF85 | 65413 | ナ | 30CA | 12490 |
ﾆ | FF86 | 65414 | ニ | 30CB | 12491 |
ﾇ | FF87 | 65415 | ヌ | 30CC | 12492 |
ﾈ | FF88 | 65416 | ネ | 30CD | 12493 |
ﾉ | FF89 | 65417 | ノ | 30CE | 12494 |
ﾊ | FF8A | 65418 | ハ | 30CF | 12495 |
ﾋ | FF8B | 65419 | ヒ | 30D2 | 12498 |
ﾌ | FF8C | 65420 | フ | 30D5 | 12501 |
ﾍ | FF8D | 65421 | ヘ | 30D8 | 12504 |
ﾎ | FF8E | 65422 | ホ | 30DB | 12507 |
ﾏ | FF8F | 65423 | マ | 30DE | 12510 |
ﾐ | FF90 | 65424 | ミ | 30DF | 12511 |
ﾑ | FF91 | 65425 | ム | 30E0 | 12512 |
ﾒ | FF92 | 65426 | メ | 30E1 | 12513 |
ﾓ | FF93 | 65427 | モ | 30E2 | 12514 |
ﾔ | FF94 | 65428 | ヤ | 30E4 | 12516 |
ﾕ | FF95 | 65429 | ユ | 30E6 | 12518 |
ﾖ | FF96 | 65430 | ヨ | 30E8 | 12520 |
ﾗ | FF97 | 65431 | ラ | 30E9 | 12521 |
ﾘ | FF98 | 65432 | リ | 30EA | 12522 |
ﾙ | FF99 | 65433 | ル | 30EB | 12523 |
ﾚ | FF9A | 65434 | レ | 30EC | 12524 |
ﾛ | FF9B | 65435 | ロ | 30ED | 12525 |
ﾜ | FF9C | 65436 | ワ | 30EF | 12527 |
ﾝ | FF9D | 65437 | ン | 30F3 | 12531 |
ﾞ | FF9E | 65438 | ゙ | 3099 | 12441 |
ﾟ | FF9F | 65439 | ゚ | 309A | 12442 |
Glyphs for vertical variants | |||||
|---|---|---|---|---|---|
From Char | Hex | Dec | To Char | Hex | Dec |
‥ | 2025 | 8229 | ︰ | FE30 | 65072 |
— | 2014 | 8212 | ︱ | FE31 | 65073 |
– | 2013 | 8211 | ︲ | FE32 | 65074 |
― | 2015 | 8213 | ︱ | FE31 | 65073 |
- | 002D | 45 | ︲ | FE32 | 65074 |
_ | 005F | 95 | ︳ | FE33 | 65075 |
( | 0028 | 40 | ︵ | FE35 | 65077 |
) | 0029 | 41 | ︶ | FE36 | 65078 |
{ | 007B | 123 | ︷ | FE37 | 65079 |
} | 007D | 125 | ︸ | FE38 | 65080 |
〔 | 3014 | 12308 | ︹ | FE39 | 65081 |
〕 | 3015 | 12309 | ︺ | FE3A | 65082 |
【 | 3010 | 12304 | ︻ | FE3B | 65083 |
】 | 3011 | 12305 | ︼ | FE3C | 65084 |
《 | 300A | 12298 | ︽ | FE3D | 65085 |
》 | 300B | 12299 | ︾ | FE3E | 65086 |
〈 | 3008 | 12296 | ︿ | FE3F | 65087 |
〉 | 3009 | 12297 | ﹀ | FE40 | 65088 |
「 | 300C | 12300 | ﹁ | FE41 | 65089 |
」 | 300D | 12301 | ﹂ | FE42 | 65090 |
｢ | FF62 | 65378 | ﹁ | FE41 | 65089 |
｣ | FF63 | 65379 | ﹂ | FE42 | 65090 |
『 | 300E | 12302 | ﹃ | FE43 | 65091 |
』 | 300F | 12303 | ﹄ | FE44 | 65092 |
“ | 201C | 8220 | 〝 | 301D | 12317 |
” | 201D | 8221 | 〟 | 301F | 12319 |
﹑ | FE51 | 65105 | ﹅ | FE45 | 65093 |
[ | 005B | 91 | ﹇ | FE47 | 65095 |
] | 005D | 93 | ﹈ | FE48 | 65096 |
‾ | 203E | 8254 | ﹉ | FE49 | 65097 |
Miscellaneous | |||||
|---|---|---|---|---|---|
From Char | Hex | Dec | To Char | Hex | Dec |
ー | 30FC | 12540 | ︱ | FE31 | 65073 |
Multi-Character Mapping (vertical regions only) | |||||
|---|---|---|---|---|---|
From Char | Hex | Dec | To Char | Hex | Dec |
… | 2026 | 8230 | ··· | 30FB, 30FB, 30FB | 12539, 12539, 12539 |
⋮ | 22EE | 8942 | ··· | 30FB, 30FB, 30FB | 12539, 12539, 12539 |
Multi-Character Mapping (all regions) | |||||
|---|---|---|---|---|---|
From Char | Hex | Dec | To Char | Hex | Dec |
2E3A | 11834 | —— | 2014, 2014 | 8212, 8212 | |
2E3B | 11835 | ——— | 2014, 2014, 2014 | 8212, 8212, 8212 |
The examples below show how to display special marks and brackets.
Side Marks (Ellipsis / bouten):
A full-width KATAKANA MIDDLE DOT: 30FB (・) should be used when placing Side Marks (Ellipsis / bouten) as ruby.
<p begin="00:23:25:00" end="00:23:18:20"><span ry:kind="ruby"><span ry:kind="rb">傍</span><span ry:kind="rt">・</span></span><span ry:kind="ruby"><span ry:kind="rb">点</span><span ry:kind="rt">・</span></span></p>Note: When using bouten, do not group a series of bouten together within a single "ruby" span. Place one bouten per character as shown in the example above.
Middle Dot:
A full-width KATAKANA MIDDLE DOT: 30FB (・) should be used when delimiting parts of foreign words or nouns.
Example:
エンターテインメント・センター (Translation: entertainment center)
<p begin="01:00:48:14" end="01:00:50:04" >エンターテインメント･センター</p>
Dashes:
U+2E3A TWO-EM DASH (U+2E3A will be displayed as two consecutive em-dash characters for both horizontal and vertical subtitles.)
U+2E3B THREE-EM DASH (U+2E3B will be displayed as three em-dash characters for both horizontal and vertical subtitles.)
U+2013 EN DASH
U+2014 EM DASH
Note: Unicode representing two and three em-dash may change in the future.
No-Break Space:
Chidori-style Placement: Use (U+3000 IDEOGRAPHIC SPACE) and (U+00A0) NO-BREAK SPACE for Chidori-style Placement.
Subtitle Spacing: Use No-Break Space (U+00A0) when preserving half-width space at the beginning of the subtitle. Use U+00A0 when preserving full-width space at the beginning of the subtitle.
Tate Chu Yoko (TC):
This is limited up to two half-width alphanumeric characters and up to four half-width numerical characters.
Numerical text within the Tate Chu Yoko (TC) should be in halfwidth and will be displayed in halfwidth.
Below is an example XML document in iTT format for delivering Japanese subtitles and ruby text.
<?xml version="1.0" encoding="UTF-8"?> <tt xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.w3.org/ns/ttml" xmlns:tt="http://www.w3.org/ns/ttml" xmlns:tts="http://www.w3.org/ns/ttml#styling" xmlns:ttp="http://www.w3.org/ns/ttml#parameter" xmlns:ry="http://namespace.itunes.apple.com/itt/ttml-extension#ruby" xmlns:vt="http://namespace.itunes.apple.com/itt/ttml-extension#vertical" xml:lang="ja" ttp:timeBase="smpte" ttp:frameRate="24" ttp:frameRateMultiplier="999 1000" ttp:dropMode="nonDrop"> <head> <ttp:profile> <ttp:extensions xml:base="http://namespace.itunes.apple.com/itt/ttml-extension/"> <ttp:extension>#ruby</ttp:extension> <ttp:extension>#vertical</ttp:extension> </ttp:extensions> </ttp:profile><!-- NOTE: Tags not related to Tate Chu Yoko (TC), ruby, and vertical support have been omitted in this example (as indicated by the three dots) for brevity and focus. --> <styling>. . . <style xml:id="ruby-before" tts:fontFamily="sansSerif" tts:color="white" tts:fontStyle="normal" tts:fontSize="100%" tts:fontWeight="normal" ry:position="before"/> <style xml:id="ruby-after" tts:fontFamily="sansSerif" tts:color="white" tts:fontStyle="normal" tts:fontSize="100%" tts:fontWeight="normal" ry:position="after"/> <style xml:id="ruby03" tts:fontFamily="sansSerif" tts:color="white" tts:fontStyle="normal" tts:fontSize="100%" tts:fontWeight="normal" ry:align="start"/> <style xml:id="ruby04" tts:fontFamily="sansSerif" tts:color="white" tts:fontStyle="normal" tts:fontSize="100%" tts:fontWeight="normal" ry:align="center"/> <style xml:id="ruby05" tts:fontFamily="sansSerif" tts:color="white" tts:fontStyle="normal" tts:fontSize="100%" tts:fontWeight="normal" ry:align="spaceBetween"/> <style xml:id="ruby06" tts:fontFamily="sansSerif" tts:color="white" tts:fontStyle="normal" tts:fontSize="100%" tts:fontWeight="normal" ry:align="spaceAround"/> <style xml:id="ruby07" tts:fontFamily="sansSerif" tts:color="white" tts:fontStyle="normal" tts:fontSize="100%" tts:fontWeight="normal" ry:position="after" ry:align="spaceBetween"/> <style xml:id="tc" tts:fontFamily="sansSerif" tts:color="white" tts:fontStyle="normal" tts:fontSize="100%" tts:fontWeight="normal" vt:combine="all"/> <style xml:id="yellow" tts:fontFamily="sansSerif" tts:color="yellow" tts:fontStyle="normal" tts:fontSize="100%" tts:fontWeight="normal"/> <style xml:id="italic" tts:fontFamily="sansSerif" tts:color="rgb(255,255,255)" tts:fontStyle="italic" tts:fontSize="100%" tts:fontWeight="normal"/> <style xml:id="yellowitalic" tts:fontFamily="sansSerif" tts:color="yellow" tts:fontStyle="italic" tts:fontSize="100%" tts:fontWeight="normal"/> </styling> <layout> <region xml:id="right" tts:origin="85% 0%" tts:extent="15% 100%" tts:textAlign="start" tts:writingMode="tbrl"/> <region xml:id="left" tts:origin="15% 0%" tts:extent="15% 100%" tts:textAlign="start" tts:writingMode="tbrl"/> <region xml:id="top" tts:origin="0% 0%" tts:extent="100% 15%" tts:textAlign="center"/><!-- Two regions have been set up to accommodate horizontal subtitle display. One region centers the subtitle and the other region aligns the subtitle on the left. --> <region xml:id="bottomcenter" tts:origin="0% 85%" tts:extent="100% 15%" tts:textAlign="center"/> <region xml:id="bottomleft" tts:origin="0% 85%" tts:extent="100% 15%" tts:textAlign="start"/>. . . </layout> </head> <body region="bottomcenter" style="normal"> <div begin="00:00:00:00"> <p region="bottomleft" begin="00:00:15:01" end="00:00:18:05"> <span ry:kind="ruby"> <span ry:kind="rb">漢字</span> <span ry:kind="rt">かんじ</span> </span> </p><!-- The following <p> block overrides the bottomcenter region by using bottomleft --> <p region="bottomleft" begin="00:00:20:07" end="00:00:24:02"> <span ry:kind="ruby" style="ruby-before"> <span ry:kind="rb">漢字</span> <span ry:kind="rt">かんじ</span> </span> </p><!-- The time period in this <p> block (region="right") overlaps the <p> block (region="bottomcenter") above. Time periods can overlap as long as they are in different regions --> <p region="right" begin="00:00:22:12" end="00:00:27:10"> <span ry:kind="ruby" style="ruby-before"> <span ry:kind="rb">平成</span> <span ry:kind="rt">へいせい</span> </span>二十年 </p><!-- Example of Tate Chu Yoko (TC) --> <p region="right" begin="00:00:30:09" end="00:00:35:13">最初に事件が起きたのは <br/>4月 <span style="tc">14</span>日だった </p> <p region="left" begin="00:00:33:00" end="00:00:36:00">最初に事件が起きたのは <br/>4月 <span style="tc">14</span>日だった </p> <p begin="00:00:37:12" end="00:00:40:20"> <span style="yellow">家に入るなり札束 を投げ出して</span> </p><!-- Additional <p> tags here -->. . . </div> </body> </tt>
XML Declaration (required) The character encoding of your document must be defined. Apple only accepts UTF-8 encoding as it efficiently encodes non-Roman characters. Important: The iTT file must not contain a byte-order mark (BOM). |
Ruby Namespace (required) Within the tt block, the ruby namespace (and associated schema) to which the tags in the XML are expected to conform must be declared. The namespace must be |
Vertical Text Namespace (required) Within the tt block, the vertical text namespace (and associated schema) to which the tags in the XML are expected to conform must be declared. The namespace must be |
Language (required) Indicates the language and optional dialect used in the ruby base and ruby text. |
Head Element |
Head (required) Begins the head element, which defines attributes to be used in the |
Timed Text Profile Extensions (required) The Two extensions can be specified: |
Styling (required) Defines the common color, weight, family and styles of the timed text. This section defines all styles to be used in the body of your document. This annotation covers only the styling related to ruby text and Tate Chu Yoko (TC); see iTunes Timed Text Annotated for information on sending style tags. |
Style for Ruby Text (required) Defines the positioning and alignment of the ruby text. In the example, seven styles are defined to set the appearance of the ruby text which will be used in the body section of the document (the body section is where you put the actual text of the timed text). At least one style must be defined (to be used as the default) and more can be created to stylize as needed. The default style of the document is assigned in the Position Use
Alignment Use
|
Style for Tate Chu Yoko (TC) (required when using Text Combine) TC (Text Combine) refers to numerical text that is rendered horizontally in a vertical subtitles. By creating and using a style, you can prevent, for example, the number 14 from being rendered as two characters each one below the other vertically. Instead, the number when using the style takes the space of one character, rendered horizontally and condensed. Using this feature requires that you specify the namespace Use the |
Layout (required ) Defines the location of the timed text within the frame. |
Region (required ) To accommodate vertical text, iTT now supports text on the left or right side of the screen. Use the Use Use The following image shows how text is displayed on the bottom region within a video frame:  The following image shows how text is displayed on the right region within a video frame:  Use Use the
Note: For Japanese subtitles, the writing mode must be |
Body Element |
Body (required ) Begins the body element, used to determine the titles and their timings. Attributes defined in the The attribute The attribute |
Div (required ) Begins the section within the document where you enter the actual text of the timed titles and the timing. Note: Subtitles can be displayed during the same time period. That is, the time periods in the
|
Ruby Text Container Each The To specify the ruby base text, use the Note: Span elements enclose the text that should be displayed as ruby text, overriding the default style. |
Tate Chu Yoko (Text Combine) Container The Note: Tate Chu Yoko (Text Combine) is limited up to 2 single byte alphabet characters and up to 4 numerical characters. |
|
The following example shows the recommended, basic set of styles and layouts for Japanese subtitles with ruby text, vertical text, and Tate Chu Yoko (Text Combine). It’s recommended that the top and bottom subtitles be set as “center" justified and vertical left and right subtitles be set as “start" justified. (See iTunes Timed Text Example for Ruby for an example that includes a more comprehensive set of styles and layout options.)
<styling> <style xml:id="normal" tts:fontFamily="sansSerif" tts:fontSize="100%" tts:fontWeight="normal" tts:color="rgb(255,255,255)" tts:fontStyle="normal"/> <style xml:id="italic" tts:fontFamily="sansSerif" tts:fontSize="100%" tts:fontWeight="normal" tts:color="rgb(255,255,255)" tts:fontStyle="italic"/> <style xml:id="yellow" tts:fontFamily="sansSerif" tts:fontSize="100%" tts:fontWeight="normal" tts:color="yellow" tts:fontStyle="normal"/> <style xml:id="yellowitalic" tts:fontFamily="sansSerif" tts:fontSize="100%" tts:fontWeight="normal" tts:color="yellow" tts:fontStyle="italic"/> <style xml:id="ruby-before" tts:fontFamily="sansSerif" tts:fontSize="100%" tts:fontWeight="normal" tts:color="white" tts:fontStyle="normal" ry:position="before"/> <style xml:id="ruby-after" tts:fontFamily="sansSerif" tts:fontSize="100%" tts:fontWeight="normal" tts:color="white" tts:fontStyle="normal" ry:position="after"/> <style xml:id="tc" tts:fontFamily="sansSerif" tts:fontSize="100%" tts:fontWeight="normal" tts:color="white" tts:fontStyle="normal" vt:combine="all"/> </styling> <layout> <region xml:id="top" tts:origin="0% 0%" tts:extent="100% 15%" tts:textAlign="start" tts:displayAlign="before"/> <region xml:id="bottom" tts:origin="0% 85%" tts:extent="15% 100%" tts:textAlign="start" tts:displayAlign="after"/> <region xml:id="right" tts:origin="85% 0%" tts:extent="15% 100%" tts:textAlign="start" tts:displayAlign="after" tts:writingMode="tbrl"/> <region xml:id="left" tts:origin="15% 0%" tts:extent="15% 100%" tts:textAlign="start" tts:displayAlign="after" tts:writingMode="tbrl"/> </layout>Note: The following product is neither endorsed nor supported by Apple.
CANVASs SSTG1 is a software application for creating and editing Japanese subtitle data. CANVASs SSTG1 can handle all aspects of Japanese subtitle authoring, including ruby and vertical text layout. CANVASs SSTG1 can ingest data DCP (XML), Advanced Authoring Format (.aaf), and Lambda CAP to create an iTunes Timed Text (.itt) file. See https://canvass.co.jp/#link-products for more information.
To preview and check the Japanese subtitles of your movie, you can download a proxy encode. To obtain the proxy encode, perform a metadata lookup using Transporter (see Use Lookup Metadata Mode) on the movie you have delivered with the Japanese subtitles. This encode is a small, low bit-rate-encoded version of the movie. The proxy encode contains the Japanese subtitles, which can be played back by using the latest macOS Sierra v10.12 (or later). Note that it can take several hours for a film with subtitles to go through the video workflow process to include the delivered subtitle file within the proxy encode.
To validate the iTT document, you need the iTunes Timed Text Schema Validation document (itunes-timed-text.ruby.rnc). Contact your Technical Representative for a copy. Available tools that support RelaxNG Condensed Schema validation can be used to validate the timed text iTT document.
The TTML schemas published by the W3C (http://www.w3.org/TR/ttaf1-dfxp/#ttml-schema-rnc) can be used to validate that an iTT document meets base line conformance, but the iTT schema must be used to verify that a document conforms to the more stringent requirements required by Tunes Store.
The following shows an example of using the open source utility Jing (http://www.thaiopensource.com/relaxng/jing.html) to validate a document against the DXFP schema, and then against the iTT schema. The following example shows how to validate the ruby iTT document.
> java -cp isorelax.jar:saxon.jar:xercesImpl.jar:xml-apis.jar \ -jar jing.jar -c schemas/ttaf1-dfxp.rnc myfile.itt > java -cp isorelax.jar:saxon.jar:xercesImpl.jar:xml-apis.jar \ -jar jing.jar -c itunes-timed-text.ruby.rnc myfile.ittTwo versions of ruby vertical subtitles have been released so far. The features available in each version are listed below.
Vertical subtitle support
Ruby annotations support
Overlapping subtitles in different regions
Special character display: Side Marks (Ellipsis / bouten), Vertical Double Quotation, Vertical Single and Double Angle Bracket, Middle Dot, Dashes
Vertical character mapping
Ruby annotations styles: position and align added
Tate Chu Yoko (TC) (horizontal text in vertical text)
Special character display: Side Marks (Ellipsis / bouten), Middle Dot, Dashes, Tate Chu Yoko (Vertical Double Quotation and Vertical Single and Double Angle Bracket removed)
Since the release of version 2, the following changes have been made:
Incorporated the addendum for Japanese timed text into this specification in March 2017
Added character mapping tables for Japanese timed text in May 2017
Added characters to preserve whitespace in Japanese subtitles, such as Chidori-style placement for song lyrics and whitespace after the break for half-width quotation marks and brackets
This chapter specifies the package format for delivering pricing in an interval format. Using interval pricing, you can set prices over an unlimited number of specific time periods. Interval pricing, if used, replaces the previous pricing model. Using interval pricing is not required; use intervals only if you need to schedule price changes in advance.
This chapter describes the metadata.xml for delivering interval pricing only. To see the complete annotations, see Basic Film Metadata Annotated. For questions, contact your Technical Representative.
If you provide interval pricing, you must follow these requirements or delivery will fail:
Gaps between intervals are not allowed.
For the first interval, the <start_date> tag must either be omitted (meaning that the interval implicitly starts immediately), or it must contain a value that is no later than the current date. For subsequent intervals, the <start_date> may be any point in the future.
The end date of the first interval must not be earlier than the <sales_start_date>.
The last interval must have no end date.
Interval pricing allows a film's wholesale pricing to automatically change during specific periods of time. This is especially useful for sales and other promotions that require temporary or permanent pricing changes on pre-determined dates.
Note: You are not required to use interval pricing. Use intervals only when you want the price to change automatically.
Intervals may be delivered at any time for up to one year into the future.
An unlimited number of intervals are allowed; however, for each interval, there is a period of several hours where the product will be unavailable for sale while the price is changed.
Once intervals are delivered for a given product, the classic pricing model (as outlined in the Basic Film Metadata Example) may no longer be used. This provides a transition platform for moving to the new specification for older deliveries.
When an interval concludes and no new interval is specified, the product may become unavailable in the associated territory if no "base price" is specified. Base prices are specified by delivering an interval with a beginning but no end date.
Intervals are date-specific and not time-specific. Your content will be available based on the time zone used for each territory. For example, in the US, the content will be available no later than midnight Pacific time (PT) on the date specified in the <sales_start_date> tag.
The minimum interval duration is one day, and each change will take several hours to appear in the Apple TV app while the cache is updated.
In order to transition between two intervals, a new interval must always begin on the same date as the end of the previous one. In the case of intervals that have no end date, the interval with the later start date will take precedence (see below example).
If two intervals overlap, the last interval specified in a given metadata update will take precedence.
You can leave out the <end_date> and the price will not change again. If no <end_date> is supplied, the interval does not end and remains in effect indefinitely.
When all pricing intervals end, the content is no longer available in the Apple TV app.
Product updates should contain all known pricing intervals from date of delivery forward.
Intervals may start and end on any date; the intervals below start and end on the first day of the month for ease of explanation.
Two intervals are provided, both without end dates:
Interval | Start Date | End Date | Wholesale Price Tier |
|---|---|---|---|
1 | 2008-05-01 | Unspecified | 3 |
2 | 2008-10-01 | Unspecified | 2 |
These two intervals as supplied, in a timeline-like format:
May | June | July | Aug | Sept | Oct | Nov | Dec | Jan |
Tier 3 |
|
|
|
|
|
|
|
|
|
|
|
|
| Tier 2 |
|
|
|
All intervals are collapsed into a single timeline when processed. The above two intervals will therefore collapse into the following:
May | June | July | Aug | Sept | Oct | Nov | Dec | Jan |
Tier 3 |
|
|
|
| Tier 3 Tier 2 |
|
|
|
Two intervals are provided, the second specified in the metadata has an end date, while the first has none.
Interval | Start Date | End Date | Wholesale Price Tier |
|---|---|---|---|
1 | 2008-05-01 | Unspecified | 3 |
2 | 2008-10-01 | 2008-11-01 | 2 |
The intervals as supplied:
May | June | July | Aug | Sept | Oct | Nov | Dec | Jan |
Tier 3 |
|
|
|
|
|
|
|
|
|
|
|
|
| Tier 2 | Tier 2 |
|
|
In this case, a smaller interval overlaps an unending one, therefore, this happens:
May | June | July | Aug | Sept | Oct | Nov | Dec | Jan |
Tier 3 | Tier 3 | Tier 3 | Tier 3 | Tier 3 | Tier 3 Tier 2 | Tier 3 Tier 2 | Tier 3 | Tier 3 |
Two price intervals are specified. One with a start and end date and one is open-ended:
Interval | Start Date | End Date | Wholesale Price Tier |
|---|---|---|---|
1 | 2008-10-01 | 2008-12-01 | 2 |
2 | 2008-05-01 | Unspecified | 3 |
These are the intervals as supplied:
May | June | July | Aug | Sept | Oct | Nov | Dec | Jan |
|
|
|
|
| Tier 2 | Tier 2 |
|
|
Tier 3 |
|
|
|
|
|
|
|
|
Since the intervals are read in order, if they send the smaller one first, the pricing intervals function as follows:
May | June | July | Aug | Sept | Oct | Nov | Dec | Jan |
Tier 3 |
Three tiers are specified. Two with a start and end date and one is open-ended. This is the safest way to deliver intervals, as it ensures that pricing changes as expected.
Interval | Start Date | End Date | Wholesale Price Tier |
|---|---|---|---|
1 | 2008-05-01 | 2008-10-01 | 3 |
2 | 2008-10-01 | 2008-11-01 | 2 |
3 | 2008-11-01 | Unspecified | 3 |
The intervals as supplied:
May | June | July | Aug | Sept | Oct | Nov | Dec | Jan |
Tier 3 |
|
|
|
|
|
|
|
|
|
|
|
|
| Tier 2 |
|
|
|
|
|
|
|
|
| Tier 3 |
|
|
The intervals as implemented:
May | June | July | Aug | Sept | Oct | Nov | Dec | Jan |
Tier 3 |
|
|
|
| Tier 2 | Tier 3 |
|
|
All intervals supplied in metadata updates will be applied in the same manner as above.
Three intervals currently exist in the Apple database (as created by previous deliveries):
May | June | July | Aug | Sept | Oct | Nov | Dec | Jan |
Tier 3 |
|
|
|
| Tier 2 | Tier 3 |
|
|
Two intervals are provided in a metadata update:
Interval | Start Date | End Date | Wholesale Price Tier |
|---|---|---|---|
1 | 2008-05-01 | 2008-11-01 | 3 |
2 | 2008-11-01 | Unspecified | 2 |
These two intervals as supplied, in a timeline-like format:
May | June | July | Aug | Sept | Oct | Nov | Dec | Jan |
Tier 3 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| Tier 2 |
|
|
The collapsed interval combines the new intervals into the currently active interval timeline. Due to date overlap, the new update completely overwrites all current intervals. The new active timeline will be as follows after this update:
May | June | July | Aug | Sept | Oct | Nov | Dec | Jan |
Tier 3 |
|
|
|
|
| Tier 2 |
|
|
Changes made for interval pricing are in bold. The US territory includes intervals for both EST and VOD products. The GB territory product is VOD only and the CA territory product is EST only.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <provider>Paramount</provider> <language>en-US</language> <video> <type>film</type> <subtype>feature</subtype> <vendor_id>09736156444</vendor_id> <isan>0000-0000-03B6-0000-O-0000-0000-2</isan> <upc>09736156444</upc> <countries_of_origin> <country primary="true">US</country> <country>CA</country> </countries_of_origin> <production_countries> <country primary="true">US</country> </production_countries> <title>Forrest Gump</title> <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> <production_company>Paramount Pictures</production_company> <copyright_cline>1994 Paramount Pictures</copyright_cline> <theatrical_release_date>2007-05-04</theatrical_release_date> <genres> <genre code="COMEDY-00"/> <genre code="DRAMA-00"/> </genres> <ratings> <rating system="mpaa" reason="for drug content, some sensuality and war violence" code="PG-13"/> </ratings> <cast> <cast_member billing="top"> <display_name>Tom Hanks</display_name> <apple_id>2672649</apple_id> <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> <characters> <character> <reference_id>FORREST</reference_id> <character_name>Forrest Gump</character_name> <character_note>Protagonist</character_note> <character_image> <data_file> <file_name>hanks_as_forrest_gump.png</file_name> <size>2813243</size> <checksum type="md5">4ec1addb1f4d3617718b3ebd1ae9ec96</checksum> </data_file> </character_image> </character> <!-- Additional character blocks here if needed for this cast member to handle cases where a cast member plays multiple characters in the film. --> </characters> </cast_member> <!-- Additional cast members here --> </cast> <crew> <crew_member billing="top"> <display_name>Robert Zemeckis</display_name> <apple_id>274059420</apple_id> <roles> <role>Director</role> </roles> </crew_member> <crew_member billing="top"> <display_name>Steve Starkey</display_name> <apple_id>274059432</apple_id> <roles> <role>Producer</role> </roles> </crew_member> <!-- Additional crew members here --> </crew> <chapters> <timecode_format>24/999 1000/nonDrop</timecode_format> <chapter> <start_time>00:00:00:00</start_time> <title locale="en-US">Forrest's Story Begins</title> <artwork_file> <file_name>chapter01.jpg</file_name> <checksum type="md5">ed93d0f3224a353a4cc8d4175d645130</checksum> <size>6591649</size> </artwork_file> </chapter> <chapter> <start_time>00:07:45:23</start_time> <title locale="en-US">Football at Alabama</title> <artwork_file> <file_name>chapter02.jpg</file_name> <checksum type="md5">86bed7ef05c34c1e85345f40d11137a9</checksum> <size>6591649</size> </artwork_file> </chapter> <!-- Additional chapters here. --> </chapters> <accessibility_info> <accessibility role="captions" available="true"/> </accessibility_info> <assets> <asset type="full"> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-source.mov</file_name> <size>2595225600</size> <checksum type="md5">2a793a8b46037fe8aa29dd739b49911a</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> <data_file role="captions"> <file_name>09736156444-english.scc</file_name> <size>9511</size> <checksum type="md5">5a793a8b46037fe8aa2bdd739b49911a</checksum> <locale name="en-US"/> </data_file> </asset> <!-- World Trailer. Will be used where territory-specific trailer has not been provided --> <asset type="preview"> <territories> <territory>WW</territory> </territories> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-US-preview.mov</file_name> <size>9987212</size> <checksum type="md5">739b43b793a8b46037fe8aa29dd9911e</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> </asset> <!-- World Poster Art. Will be used where territory-specific poster art has not been provided --> <asset type="artwork"> <territories> <territory>WW</territory> </territories> <data_file> <locale name="en-US"/> <file_name>09736156444.jpg</file_name> <size>6591649</size> <checksum type="md5">43e7dddfe4b8ab433ede429df86cabb2</checksum> </data_file> </asset> </assets> <products> <product> <territory>US</territory> <!-- The US territory includes both EST and VOD products. --> <intervals> <interval> <start_date>2011-07-01</start_date> <end_date>2011-09-01</end_date> <wholesale_price_tier>3</wholesale_price_tier> <hd_wholesale_price_tier>1</hd_wholesale_price_tier> <vod_type>New Release</vod_type> </interval> <interval> <start_date>2011-09-01</start_date> <end_date>2011-10-01</end_date> <wholesale_price_tier>5</wholesale_price_tier> <hd_wholesale_price_tier>3</hd_wholesale_price_tier> <vod_type>Library</vod_type> </interval> <interval> <start_date>2011-10-01</start_date> <wholesale_price_tier>3</wholesale_price_tier> <hd_wholesale_price_tier>1</hd_wholesale_price_tier> <vod_type>Library</vod_type> </interval> </intervals> <cleared_for_sale>true</cleared_for_sale> <cleared_for_hd_sale>true</cleared_for_hd_sale> <cleared_for_vod>true</cleared_for_vod> <cleared_for_hd_vod>false</cleared_for_hd_vod> <preorder_sales_start_date>2011-02-10</preorder_sales_start_date> <sales_start_date>2011-03-12</sales_start_date> <sales_end_date>2011-12-12</sales_end_date> <available_for_vod_date>2011-09-01</available_for_vod_date> <unavailable_for_vod_date>2012-11-12</unavailable_for_vod_date> <physical_release_date>2007-08-01</physical_release_date> </product> <product> <territory>GB</territory> <!-- The GB territory includes a VOD product only. --> <intervals> <interval> <start_date>2011-07-01</start_date> <end_date>2011-09-01</end_date> <vod_type>New Release</vod_type> </interval> <interval> <start_date>2011-09-01</start_date> <vod_type>Library</vod_type> </interval> </intervals> <cleared_for_sale>false</cleared_for_sale> <cleared_for_vod>true</cleared_for_vod> <cleared_for_hd_vod>true</cleared_for_hd_vod> <available_for_vod_date>2011-11-12</available_for_vod_date> <unavailable_for_vod_date>2012-11-12</unavailable_for_vod_date> <physical_release_date>2007-08-01</physical_release_date> </product> <product> <territory>CA</territory> <!-- The CA territory includes an EST product only. --> <intervals> <interval> <start_date>2011-07-01</start_date> <end_date>2011-09-01</end_date> <wholesale_price_tier>5</wholesale_price_tier> </interval> <interval> <start_date>2011-09-01</start_date> <end_date>2011-10-01</end_date> <wholesale_price_tier>5</wholesale_price_tier> </interval> <interval> <start_date>2011-10-01</start_date> <wholesale_price_tier>5</wholesale_price_tier> </interval> </intervals> <cleared_for_sale>true</cleared_for_sale> <cleared_for_hd_sale>true</cleared_for_hd_sale> <preorder_sales_start_date>2011-02-10</preorder_sales_start_date> <sales_start_date>2011-03-12</sales_start_date> <sales_end_date>2011-12-12</sales_end_date> <physical_release_date>2007-08-01</physical_release_date> </product> </products> </video></package>Interval Pricing Metadata Fields |
Product (required) Begin the product in the same manner of the basic film. The territory specified here is the only one affected by the intervals defined within this product tag. |
Interval Declaration (required if using intervals) The beginning of a group of intervals for a specific territory. |
Interval (required if using intervals) The beginning of an individual interval for a specific territory. This interval will only be applied to the territory specified in the parent's (product) territory tag. Any number of intervals may be provided in any initial product delivery or subsequent update. |
Interval Start Date (required except for the first interval) The start date for the given interval in If you leave out the |
Interval End Date (optional) The end date for the given interval. This may be any point at least 24 hours after the interval's start date and must follow the |
Interval Wholesale Price Tier (required for EST; otherwise optional) The wholesale price tier for the film for the given interval. Must be a wholesale price tier number as specified in your contract with Apple. See Table 1: Wholesale Price Tiers for a list of available price tiers. Review your contract to verify the tiers available to you. If an invalid price tier is provided, Apple reserves the right to reject the package or to use default pricing. Contact your Technical Representative for more details. |
HD Wholesale Price Tier (optional) The wholesale price tier for an HD film for the given interval. Must be a wholesale price tier number as specified in the contract with Apple. Note: This tag is not available to all providers or in all countries/regions. Refer to your contract to see if you may send this tag. |
Video on Demand Type (required if using intervals for VOD) To supply interval pricing for VOD products, use the Important: If you deliver the |
|
Product (required) Note: When sending price intervals for Electronic sell-through (EST) products, the tag The rest of the product block remains the same as the Basic Film, except for pricing. When interval pricing is used, pricing may not be located outside of the |
After you submit a package to Apple, you can “look up” the metadata (see Use Lookup Metadata Mode in the Transporter User Guide for information on how to do a metadata lookup). This is useful when you need to resend the package with updated metadata, not only to save time, but if Apple has made any changes to the metadata during quality control, those changes will be reflected in the metadata returned from lookup. It is also useful for the “read-only” information it returns. This appendix explains read-only information in detail.
Read-only tags are returned in the metadata lookup and are supplied by Apple to provide information about the package, such as the status of the content review and Apple identifiers for cast and crew. In addition, metadata lookup also provides the URLs to the scratch encode for your asset so you can confirm the synchronization for your asset before uploading your package again.
Note: If you submit a metadata delivery and you include the read-only tags, those tags will be ignored.
When you retrieve the metadata, you will see two “read-only” tags: <read_only_info> and <read_only_value>. These tags may appear throughout the XML. The <read_only_info> block identifies one or more <read_only_value>(s). The <read_only_value> tag uses the key="XXX" attribute to describe what the information provided represents and the actual value supplied with the tag.
The following partial example shows where read-only information appears in the returned metadata for a film.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="film5.3"> <metadata_token>1405704088101-ae534236053dbb0b082dd6319857a403bce91396e5753fa6ff70f8b3047609fc</metadata_token> <provider>Paramount</provider> <language>en-US</language> <video> <read_only_info> <read_only_value key="content-review-status">Live-Reviewed</read_only_value> </read_only_info> <type>film</type> <subtype>feature</subtype> <vendor_offer_code>408CH98720X103</vendor_offer_code> <vendor_id>09736156444</vendor_id> <isan>0000-0000-03B6-0000-O-0000-0000-2</isan> <upc>09736156444</upc> <countries_of_origin> <country primary="true">US</country> <country>CA</country> </countries_of_origin> <production_countries> <country primary="true">US</country> </production_countries> <original_spoken_locale>en-US</original_spoken_locale> <title>Forrest Gump</title> <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> <production_company>Paramount Pictures</production_company> <copyright_cline>1994 Paramount Pictures</copyright_cline> <theatrical_release_date>2007-05-04</theatrical_release_date> <genres> <genre code="COMEDY-00"/> <genre code="DRAMA-00"/> </genres> <ratings> <rating system="mpaa" reason="for drug content, some sensuality and war violence" code="PG-13"/> </ratings> <cast> <cast_member billing="top"> <read_only_info> <read_only_value key="apple-id">2672649</read_only_value> <read_only_value key="character-reference-id">REF_247828</read_only_value> </read_only_info> <display_name>Tom Hanks</display_name> <apple_id>2672649</apple_id> <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> <characters> <character> <reference_id>REF_247828</reference_id> <character_name>Forrest Gump</character_name> <character_note>Protagonist</character_note> <character_image> <data_file> <file_name>hanks_as_forrest_gump.png</file_name> <size>2813243</size> <checksum type="md5">4ec1addb1f4d3617718b3ebd1ae9ec96</checksum> </data_file> </character_image> </character> <!-- Additional character blocks here if needed for this cast member to handle cases where a cast member plays multiple characters in the film. --> </characters> </cast_member> <!-- Additional cast members here --> </cast> <crew> <crew_member billing="top"> <read_only_info> <read_only_value key="apple-id">274059420</read_only_value> </read_only_info> <display_name>Robert Zemeckis</display_name> <apple_id>274059420</apple_id> <roles> <role>Director</role> </roles> </crew_member> <crew_member billing="top"> <read_only_info> <read_only_value key="apple-id">274059432</read_only_value> </read_only_info> <display_name>Steve Starkey</display_name> <apple_id>274059432</apple_id> <roles> <role>Producer</role> </roles> </crew_member> <!-- Additional crew members here --> </crew> <chapters> <timecode_format>24/999 1000/nonDrop</timecode_format> <chapter> <start_time>00:00:00:00</start_time> <title locale="en-US">Forrest's Story Begins</title> <artwork_file> <file_name>chapter01.jpg</file_name> <checksum type="md5">ed93d0f3224a353a4cc8d4175d645130</checksum> <size>6591649</size> <read_only_info> <read_only_value key="chapter-thumbnail-url-expires">2014-08-16T18:32:06-07:00</read_only_value> <read_only_value key="chapter-thumbnail-url">http://a1814.phobos.apple.com/us/r30/Music/94/a2/1e/mzi.eknxukgk.jpg?downloadKey=1408649526_d8b1ac3332a20644d817014257bbddda</read_only_value> </read_only_info> </artwork_file> </chapter> <chapter> <start_time>00:07:45:23</start_time> <title locale="en-US">Football at Alabama</title> <artwork_file> <file_name>chapter02.jpg</file_name> <checksum type="md5">86bed7ef05c34c1e85345f40d11137a9</checksum> <size>6591649</size> <read_only_info> <read_only_value key="chapter-thumbnail-url-expires">2014-08-16T18:32:06-07:00</read_only_value> <read_only_value key="chapter-thumbnail-url">http://a1.phobos.apple.com/us/r30/Music/8d/81/d2/mzi.mgbjrghi.jpg?downloadKey=1408649526_0ae93ed7c39469ddf25d9b4f10c510fa</read_only_value> </read_only_info> </artwork_file> </chapter><!-- Additional chapters here. --> </chapters> <accessibility_info> <accessibility role="captions" available="true"/> </accessibility_info> <assets> <asset type="full"> <read_only_info> <read_only_value key="proxy-encode-url">http://a1484.phobos.apple.com/us/r30/Video4/v4/6e/a7/80/6ea78074-f002-5373-1eec-623cfa19984c/temp..ujzcqupe.s.m4v?downloadKey=1408239124_eab4b6c25453c355cc0ca36e0fb81e1c</read_only_value> <read_only_value key="proxy-encode-url-expires">2014-08-16T18:32:04-07:00</read_only_value> </read_only_info> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-source.mov</file_name> <size>2595225600</size> <checksum type="md5">2a793a8b46037fe8aa29dd739b49911a</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> <data_file role="captions"> <file_name>09736156444-english.scc</file_name> <size>9511</size> <checksum type="md5">5a793a8b46037fe8aa2bdd739b49911a</checksum> <locale name="en-US"/> <attribute name="program.start.timecode">-01:00:00:00</attribute> </data_file> <data_file role="audio.visually_impaired"> <file_name>09736156444-ad.mov</file_name> <size>34866696</size> <checksum type="md5">a2db7f2f30c9744e98fa393e51cf6a93</checksum> <locale name="en-US"/> </data_file> </asset><!-- Required. World Trailer. Will be used where territory-specific trailer has not been provided --> <asset type="preview"> <read_only_info> <read_only_value key="proxy-encode-url">http://a1965.phobos.apple.com/us/r30/Video/v4/07/6f/b4/076fb404-2ac8-0c98-4e89-8e93b9a32321/temp..ulcrmwxn.s.m4v?downloadKey=1408239124_a6d7fb340e287494d92cbcadc3c59582</read_only_value> <read_only_value key="proxy-encode-url-expires">2014-08-16T18:32:04-07:00</read_only_value> </read_only_info> <territories> <territory>WW</territory> </territories> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-US-preview.mov</file_name> <size>9987212</size> <checksum type="md5">739b43b793a8b46037fe8aa29dd9911e</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> </asset><!-- Required. World Poster Art. Will be used where territory-specific poster art has not been provided --> <asset type="artwork"> <territories> <territory>WW</territory> </territories> <data_file> <locale name="en-US"/> <file_name>09736156444.jpg</file_name> <size>6591649</size> <checksum type="md5">43e7dddfe4b8ab433ede429df86cabb2</checksum> </data_file> </asset> </assets> <products> <product> <territory>US</territory> <cleared_for_sale>true</cleared_for_sale> <cleared_for_hd_sale>true</cleared_for_hd_sale> <wholesale_price_tier>3</wholesale_price_tier> <hd_wholesale_price_tier>1</hd_wholesale_price_tier> <preorder_sales_start_date>2011-02-10</preorder_sales_start_date> <sales_start_date>2011-03-12</sales_start_date> <cleared_for_vod>true</cleared_for_vod> <vod_type>New Release</vod_type> <available_for_vod_date>2012-11-12</available_for_vod_date> <unavailable_for_vod_date>2013-11-12</unavailable_for_vod_date> <physical_release_date>2007-08-01</physical_release_date> <cleared_for_hd_vod>false</cleared_for_hd_vod> <read_only_info> <read_only_value key="apple-id">314029341</read_only_value> <read_only_value key="storeURL-US">https://itunes.apple.com/us/movie/forrest-gump/id314029341?ls=1</read_only_value> </read_only_info> </product> </products> </video></package>Package Metadata Fields |
Metadata Token Apple returns a value token that you should include when doing a metadata update for content that has been reviewed. This ensures you are using the most recent, edited version of the metadata. |
Read-Only Metadata Fields |
Review Status Read-Only Value This key attribute ( Before content can go live in the Apple TV app, Apple may review and confirm the quality of the metadata and the assets, and as a result, Apple may choose to ignore updates to fields that have been edited. You can check the review status to see if the content has been reviewed; if the status indicates “Reviewed,” some tag updates may be ignored. Below are the possible review statuses:
|
Apple ID Read-Only Value A read-only info block appears in the The Note: The Apple identifier is also returned in a “comment” field Store URL Read-Only Value The |
Cast Apple ID and Character ID Read-Only Value A read-only info block appears in the
|
Crew Apple ID Read-Only Value A read-only info block appears in the
|
Content URL A read-only info block appears in the
|
Chapter Artwork A read-only info block appears in the
|
Language codes should be 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/. When specifying languages, you can use any language as long as it is a valid BCP 47 code that consists of the language subtag, optional region subtag, and optional script subtag as appropriate.
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.
Although script subtags are valid (for example, Chinese can be written in either Traditional or Simplified characters, and you may need to indicate that localizations appear in a specific script), keep in mind that script subtags are for describing text and should not be used for describing audio. For example, you would deliver cmn to describe audio in Mandarin, not cmn-Hant or cmn-Hans.
Note: Although BCP 47 also includes support for UN M.49 region codes in addition to commonly-used alphabetic country codes, the only UN M.49 region code supported by Apple at present is 419 (representing Latin America and the Caribbean). This is useful in forming the language tag es-419 to represent Spanish as used in Latin America (as distinct from Spanish as used in Spain).
Note that while any language code complying with the guidelines above will be accepted, the Apple TV app displays content only in a limited set of languages as shown in the table below. The fourth column of the table is provided for reference only, and may be useful for cross-reference if you have existing data from other sources that uses 3-character ISO 639-3 language codes.
Description | RFC 5646 Language Code | The Apple TV app displays these languages | ISO 639-3 3 char Language (for reference only) |
|---|---|---|---|
Afrikaans | af | ✓ | afr |
Arabic | ar | ✓ | ara |
Bengali | bn | ✓ | ben |
Bulgarian | bg | ✓ | bul |
Cantonese (Spoken) | yue | yue | |
Cantonese (Script) | yue-Hant | ✓ | yue |
Catalan | ca | ✓ | cat |
Croatian | hr | ✓ | hrv |
Czech | cs | ✓ | ces |
Danish | da | ✓ | dan |
Dutch | nl | ✓ | nld |
English | en | ✓ | eng |
English (Australia) | en-AU | ✓ | eng |
English (Canada) | en-CA | ✓ | eng |
English (France) | en-FR | eng | |
English (Germany) | en-DE | eng | |
English (Ireland) | en-IE | eng | |
English (New Zealand) | en-NZ | eng | |
English (United Kingdom) | en-GB | ✓ | eng |
English (United States) | en-US | ✓ | eng |
Estonian | et | ✓ | est |
Finnish | fi | ✓ | fin |
Flemish | nl-BE | nld | |
French | fr | ✓ | fra |
French (Belgium) | fr-BE | fra | |
French (Canada) | fr-CA | ✓ | fra |
French (France) | fr-FR | ✓ | fra |
French (Switzerland) | fr-CH | fra | |
German | de | ✓ | deu |
German (Austria) | de-AT | deu | |
German (Germany) | de-DE | ✓ | deu |
German (Switzerland) | de-CH | deu | |
Greek | el | ✓ | ell |
Greek (Cyprus) | el-CY | ell | |
Hebrew | he | ✓ | heb |
Hindi | hi | ✓ | hin |
Hungarian | hu | ✓ | hun |
Icelandic | is | ✓ | isl |
Indonesian | id | ✓ | ind |
Italian | it | ✓ | ita |
Japanese | ja | ✓ | jpn |
Kannada | kn | ✓ | kan |
Kazakh | kk | ✓ | kaz |
Korean | ko | ✓ | kor |
Lao | lo | ✓ | lao |
Latvian | lv | ✓ | lav |
Lithuanian | lt | ✓ | lit |
Luxembourgish | lb | ltz | |
Malay | ms | ✓ | msa |
Malayalam | ml | ✓ | mal |
Maltese | mt | mlt | |
Mandarin (Simplified Script) | cmn-Hans | ✓ | cmn |
Mandarin (Spoken) | cmn | cmn | |
Mandarin (Traditional Script) | cmn-Hant | ✓ | cmn |
Marathi | mr | ✓ | mar |
Norwegian | no | ✓ | nor |
Polish | pl | ✓ | pol |
Portuguese | pt | ✓ | por |
Portuguese (Brazil) | pt-BR | ✓ | por |
Portuguese (Portugal) | pt-PT | ✓ | por |
Punjabi | pa | ✓ | pan |
Romanian | ro | ✓ | ron |
Russian | ru | ✓ | rus |
Slovak | sk | ✓ | slk |
Slovenian | sl | ✓ | slv |
Spanish | es | ✓ | spa |
Spanish (Latin America)* | es-419 | ✓ | spa |
Spanish (Mexico) | es-MX | ✓ | spa |
Spanish (Spain) | es-ES | ✓ | spa |
Swedish | sv | ✓ | swe |
Tagalog | tl | ✓ | tgl |
Tamil | ta | ✓ | tam |
Telugu | te | ✓ | tel |
Thai | th | ✓ | tha |
Turkish | tr | ✓ | tur |
Ukrainian | uk | ✓ | ukr |
Urdu | ur | ✓ | urd |
Vietnamese | vi | ✓ | vie |
Zulu | zu | ✓ | zul |
* 419 is a UN M.49 region code. https://unstats.un.org/unsd/methodology/m49/
The SMPTE timecode format is expressed as: framerate/framerate multiplier/mode. The W3C standard for expressing the framerate multiplier has changed: the colon (:) used to separate the framerate from the multiplier has been replaced by a space. For example, 999:1000 is now expressed as 999 1000. For a further explanation of timecodes, review the Final Cut Pro X User’s Guide.
The following table shows the supported timecode formats and what the <start_time> would be for each of the timecode formats (note that the timecodes represent the 99,290th frame of the movie):
Description | Effective FPS | Timecode format (<timecode_format>) | <start_time> example (HH:MM:SS:FF) |
|---|---|---|---|
Default (legacy) | N/A (Note: |
| 00:55:13.124 (Note: |
NTSC Video |
|
| 00:55:09:20 |
NTSC Video |
|
| 00:55:13;00 (Note: Drop frame mode requires the use of the semicolon after the seconds.) |
NTSC Film (Imprecise) |
|
| 01:08:57:02 |
NTSC Film |
|
| 01:08:57:02 |
PAL |
|
| 01:06:11:15 |
ATSC Video |
|
| 00:55:09:01 |
1 Imprecise: Many software-based video systems, including those from Apple, use the imprecise value of 29.97 as the frame rate for NTSC video. So although 1000 1001 would be the precise rate for NTSC, 999 1000 is used.
2 Precise: Use the 1000 1001 ratio if your source video is timed accurately to true NTSC standard framerate.
These are the standard wholesale price tiers most providers have. Tiers can vary by provider, so check your contract to find out which apply to you.
Note: You can use any of the film tiers below in the metadata to activate pricing for short films, but be aware that short films have a set price and are not priced by tier.
Tier | Tier Name | |
|---|---|---|
Film Tiers | 1 | Highest wholesale price |
| 2 | |
| 3 | |
| 4 | |
| 5 | Lowest wholesale price |
Concert Tiers* | 201 | Highest wholesale price |
| 202 | |
| 203 | |
| 204 | |
| 205 | |
| 206 | |
| 207 | Lowest wholesale price |
* New contract required |
Accented characters such as é and ü don’t appear correctly in my titles and descriptions.
Make sure you are correctly encoding your metadata in UTF-8. You can use one of the XML Metadata Production tools listed in the Helpful Tools section. There is an XML tool called xmllint that will help identify problems with your XML encodings. You can also try previewing your XML in a browser that renders XML trees such as Firefox.
How do I create a checksum for my files?
Apple accepts file checksums using the industry standard MD5 message digest. There are a variety of tools available to produce an MD5 checksum. See the tools listed in Helpful Tools.
I’m not familiar with XML. Where can I find a general tutorial for XML?
W3Schools | Tizag Tutorials | XML: A Beginner’s Guide by Dave Mercer |
|---|---|---|
Some letters in XML have to be rewritten, what is that about? What’s wrong with my ampersand? My XML isn’t valid!
XML uses a small set of characters to denote structure in the document. If you need to use these characters within content in your XML file, you need to let the XML file know that the characters are not being used as structure by "escaping" them. For example the letters < and > designate an element tag marker, so if you have a value of "9 > 0" in your XML, you need to escape the greater than character with a set of characters called an entity. The entity for greater than ">" is ">", thus making your previous statement "9 > 0". If you cannot rewrite these characters, see the next section regarding using a Character Data (CDATA) block.
Here are the characters that need to be escaped, and their equivalent entities:
Character | Escaped Equivalent |
|---|---|
> | > |
< | < |
& | & |
I cannot rewrite my characters. Is there another option? What is CDATA?
XML does offer another solution when rewriting reserved characters is not possible. Element text may be enclosed in a special structure called a character data block CDATA. In a CDATA block, the <, >, and & characters are allowed; the only thing not allowed is the CDATA block closing sequence “]]>” which is unlikely to occur in your text.
Here’s an example using entity escaping:
<description>If 9 > 0, then take 0 & 9.</description>
And here is an example using a CDATA block:
<description><![CDATA[if 9 > 0, then take 0 & 9. ]]></description>
Both of these examples are correct and acceptable. For further explanation, see http://www.w3schools.com/xml/dom_cdatasection.asp. Note the characters must still be encoded in UTF-8.
I don’t have a value for an element that is shown in the XML.
For elements marked optional for which you have no value, Apple requires that you remove the tag entirely from the XML rather than leaving the element empty. If the element is marked required, you may not omit the element.
These products are neither endorsed nor supported by Apple.
XML Metadata Production | ||
Oxygen XML Editor Mac, Windows, Linux | Exchanger XML Editor Mac, Windows, Linux | Altova XML Spy Windows |
XML Debugging | ||
Firefox Mac, Windows, Linux | xmllint macOS, BSD | |
MD5 Checksum | ||
md5 macOS, BSD | md5sum Windows |
The following table lists the previously-released specifications and the revisions:
Date/Version | Summary |
|---|---|
September 22, 2025 - Version 5.3.21 | Updates for the film profile. Updates for New Zealand ratings requirements. Additional minor updates. |
June 30, 2025 - Version 5.3.20 | Updated information about stereoscopic video delivery. Additional minor updates. |
March 17, 2025 - Version 5.3.19 | Updated the Film Ratings, Advisories, and Genres. Additional corrections and clarifications. |
October 14, 2024 - Version 5.3.18 | Updated information about HDR delivery. Updated the ratings requirements for Brazil and South Africa. Additional corrections and clarifications. |
May 1, 2024 - Version 5.3.17 | Updated ratings and advisories for Korea. Added a brightness control attribute for stereoscopic video delivery. |
April 8, 2024 - Version 5.3.16 | Renamed this document; added information about stereoscopic source files; updated information about forced subtitles, backdrops, and logos; and made additional minor corrections. |
December 4, 2023 - Version 5.3.15 | Updated references to the TTML spec, updated Turkey to Türkiye, and made additional minor corrections. |
August 14, 2023 - Version 5.3.14 | Added rating requirements for Vietnam. Added support for 30 fps content for film. Additional corrections and clarifications. |
February 8, 2022 - Version 5.3.13 | Updated information on ratings and advisories for India, Korea, and New Zealand. |
November 9, 2022 - Version 5.3.12 | Updated the ratings requirements for Brazil. Added the |
October 17, 2022 - Version 5.3.11 | Added the consumer advice labels for New Zealand. Additional corrections and clarifications. |
June 30, 2022 - Version 5.3.10 | Added the |
February 3, 2022 - Version 5.3.9 | Removed a Brazil ratings requirement. Clarified sending film advisories for India. Clarified dub card video. |
November 29, 2021 - Version 5.3.8 | Added a new chapter for Korean film deliveries. Added Korea to the Minimum Storefront Requirements table. |
July 19, 2021 - Version 5.3.7 | Removed references to CBFC for India. Added advisories for India. Summarized ratings changes. |
April 26, 2021 - Version 5.3.6 | Added new regional requirements. Updated ratings. |
December 21, 2020 - Version 5.3.5 | Apple strongly recommends that you deliver 16:9 poster art. Minor corrections. |
November 30, 2020 - Version 5.3.4 | Corrected the example for delivering HDR and SDR in the same delivery and added annotations. Added |
August 10, 2020 - Version 5.3.3 | Added a new data file role for delivering CBFC Certificates for content sold in India. Removed support for displaying the certificate in the bottom corner of the poster art. Dolby Vision CM 4 metadata files are now supported. Added |
June 29, 2020 - Version 5.3.2 | Expanded delivery of country information. Added example and annotations for 4K availability in HDR and 4K deliveries ( |
September 16, 2019 - Version 5.3.1 | The |
May 13, 2019 - Version 5.3 | Added delivery of video and audio as separate components (the audio is not required to be embedded in the source video). Added delivery of a Dolby Vision video with an option to down-convert to SDR. Added delivery of a Dolby Atmos audio file with an option to downmix to other formats. Added support for 16:9 artwork, content logos, and backdrop art. Added an attribute for use within the |
February 15, 2019 - Version 5.2.23 | VOD pricing can now be specified within the |
January 30, 2019 - Version 5.2.22 | Added a new tag to specify digital release date. Minor corrections. |
September 10, 2018 - Version 5.2.21 | Added Dolby Atmos audio. Added languages and locales to the Minimum Storefront Requirements table. |
June 13, 2018 - Version 5.2.20 | The date delivered with the |
April 4, 2018 - Version 5.2.19 | Added a new tag to specify a frame to use for the production still image ( New tags have been added to provide 4K and HDR video information for preorders. |
February 21, 2018 - Version 5.2.18 | 4K HDR is supported for custom previews. New territories have been added to the Minimum Storefront Requirements. Some ratings have changed for film. Added languages to the language code table. Clarified phonetic title and ruby feature support by version. Changes to character mapping tables for Japanese timed text. |
October 18, 2017 - Version 5.2.17 | Added 4K video and HDR (high dynamic range) video in either Dolby® Vision or HDR10 format. Embedded audio on a previously-delivered video source can be re-used. |
September 20, 2017 - Version 5.2.16 | Made changes to artist roles for concert films and cue sheets. Changed ISAN requirements for Switzerland. Changed phonetic title tag to be required. Clarified schema and spec versioning. Made minor corrections. |
July 12, 2017 - Version 5.2.15 | The |
May 24, 2017 - Version 5.2.14 | Cue sheets can be delivered for a feature film to provide a list of music played in the film. Added a link to the iTunes Timed Text Schema Validation document. Added character mapping tables for Japanese timed text. Minor correction to Japanese Timed Text. |
March 29, 2017 - Version 5.2.13 | Added a new chapter for Japanese timed text. |
February 2, 2017 - Version 5.2.12 | Clarified crop dimensions. ISAN is now required for films sold in Switzerland. Audio description and language clarifications. |
June 22, 2016 - Version 5.2.11 | Added a |
May 4, 2016 - Version 5.2.10 | Updated the iTunes Film Rating Codes document. Clarified the restrictions for audio and subtitles that are in the same language. Clarified the handling of burned-in text for metadata-based cropping. Minor corrections. |
March 23, 2016 - Version 5.2.9 | Added a |
December 8, 2015 - Version 5.2.8 | Added a new tag |
September 30, 2015 - Version 5.2.7 | Added new poster art sizes. Added Flemish to the language code table. Minor corrections. |
July 8, 2015 - Version 5.2.6 | Added a |
May 6, 2015 - Version 5.2.5 | Clarified timecode formats and frame separators. Delivering the |
February 11, 2015 - Version 5.2.4 | The |
December 10, 2014 - Version 5.2.3 | Added Audio Description (AD) as a new data file role: |
September 17, 2014 - Version 5.2.2 | Added a new tag ( |
July 9, 2014 - Version 5.2.1 | Changes made in the delivery of cast and crew information. Closed caption files can now be delivered in languages other than English. Added localizations to the concert films metadata example. Clarified short film pricing and timecode. Added an example for delivering chapter updates with an asset-only update. |
April 9, 2014 - Version 5.2 | Added localization examples to the concert films metadata. Added new Japanese price tiers. Changed the version number of this specification from 5.1 to 5.2 to keep the version number in sync with the new schema version. |
March 28, 2014 - Version 5.1.4 | Added new requirements for ratings. |
March 14, 2014 - Version 5.1.3 | Removed existing closed captioning reason codes and added new ones. Clarified the |
November 20, 2013 - Version 5.1.2 | Added a new tag for asset component exclusions by territory. Added support for SDH. Vendor offer codes can be updated. Clarified poster image. Added a new tag to deliver QC notes. Updated closed captioning reason codes. Territory rights and pricing can be delivered in a metadata-only update that includes only the |
June 26, 2013 - Version 5.1.1 | Updated closed captioning reason codes. Cue sheets should be provided (if available) for films with music that are to be sold or rented outside the United States. EST/VOD end dates can be removed through the feed. New validations have been added for interval pricing. Revised the multiple language film metadata example. Added minimum Storefront requirements for some territories. Apple rating codes and Apple genre codes are now required. Added annotations for concert films. Clarified requirements specific to India. Added a section on requirements specific to Russia. |
February 6, 2013 - Version 5.1 | Added a new tag to reference cast and crew members by Apple ID. Added a new attribute on the |
October 18, 2012 - Version 5.0.2 | Added new elements for closed captions to indicate availability. Added Co-Director as a crew member role. The audio for the source video can be updated. Corrected an error in the frame rate table and annotation. Added interval pricing and iTT file requirements. The locale values for any video asset containing Chinese audio should not contain script information. |
July 10, 2012 - Version 5.0.1 | Added film ratings for newly supported countries/regions. Added a new frame rate for timecode formats. Removed some ratings that are no longer supported. |
May 30, 2012 - Version 5.0 | Added a section to explain how the Store handles languages. Additional languages have been added to the Language Codes appendix. Added a best practice for supplying language codes. The XML structure for cast and crew has changed to support localizations. Poster art requirements have changed. Added Dub Card Video as a supported data file on the full source. Reorganized and rewrote the Multiple Language Film Profile chapter. Removed the French film metadata example and annotations. Moved the Japanese metadata example and annotations from the Multiple Language Film Profile chapter to the Basic Example chapter. |
January 31, 2012 - Version 4.9 | Updated the table of language codes to remove the checkmarks for languages not supported for use in the |
September 22, 2011 - Version 4.8 | SD and HD films can now be priced at different price tiers. Added a role for use in the |
July 13, 2011 - Version 4.7.3 | The theatrical release date is required. Additional ratings have been added. Clarified the effect of “top” billing. Added a new tag for reporting purposes. |
June 1, 2011 - Version 4.7.2 | Subtitles and forced subtitles can now be delivered within the iTunes Store package (itmsp) as a |
April 14, 2011 - Version 4.7 | Clarified the use of Not Rated and Unrated film ratings. Added a new attribute for the full source to indicate that the film does not contain any burned-in narrative text. Corrected timecodes that were incorrect. Added a note to the Changed the version number of this specification from 4.5.1 to 4.7 to keep the version number in sync with the schema version. There was no release of this spec for 4.6. |
December 8, 2010 - Version 4.5.1 | Added Japanese genres. Clarified how to remove content from the Store. Changed the ratings table to remove legacy and unsupported US MPAA ratings. Added links to language and country codes. |
November 5, 2010 - Version 4.5 | Ratings for feature and concert films are required. Clarified use of crop dimensions on video source. Made minor corrections to the ratings table. Corrected the timecode formats table in the appendix. Clarified size limits in string fields, for example, |
August 5, 2010 - Version 4.4 | Added more film ratings. Clarified Introduced new page design. Added visual cues in the annotations to show the XPath of the tags. |
May 26, 2010 - Version 4.3.2 | This revision represents changes made to this document; the schema (4.3) has not changed. The tag |
February 3, 2010 - Version 4.3 | Added a chapter to explain interval pricing. Added capability to identify Ireland-specific poster art and trailers. Added an explanation for the |
December 18, 2009 - Version 4.2 | Added new tag for HD EST clearances. Clarified use of the |
November 10, 2009 - Version 4.1 | Clarified package version attribute name requirements. Added a best practice for sending chapters. Removed the restriction of requiring that at least one title for each chapter be in English. Clarified values used when specifying crop dimensions. Removed Co-Director as a crew member role. |
September 11, 2009 - Version 4.0 | Added capability to deliver one or more Quality Control notes with full and preview videos. Clarified how to change the |
August 10, 2009 - Version 3.3.3 | Video |
July 1, 2009 - Version 3.3.2 | Clarified vendor identifier, chapter title, and image requirements. |
May 12, 2009 - Version 3.3.1 | Added capability to remove assets through the feed. Changed requirements for metadata/asset updates. Clarified |
March 15, 2009 - Version 3.3 | Added audio as a type of data file that can be imported. Added support for multiple assets and languages. Added new tags for locale-specific assets. Chaptering is now delivered in the primary metadata file, not as a separate XML file. Added a new attribute to identify videos with burned-in subtitles. Added a table that lists common language/locale codes. Changed the order of tags in the metadata examples. Clarified the |
September 30, 2008 - Version 3.2 | Added ratings for Australia, Canada, France, Germany, New Zealand, United Kingdom and United States, new elements for concert films, Closed Captioning information, added examples for metadata-only deliveries and updates, and examples for asset-only updates. Vendor identifier format restrictions are now enforced. |
March 6, 2008 - Version 3.1 | Reorganized document and added new elements. |
April 2, 2007 - Version 2.3 | General document updates, added element details, deprecated and updated element tags, asset details moved to the iTunes Video and Audio Asset Guide. |
November 30, 2006 - Version 2.2.1 | Minor edits and updates. |
October 24, 2006 - Version 2.2 | Introduction of Film Profile Specification: feature film content for the iTunes Store, including new profiles for short film and feature film. |
Film Profile
Added information about the <video_has_varying_active_region> attribute. See Basic Film Metadata Annotated.
Film Advisories
Updated the ratings requirements for New Zealand. See New Zealand.
Correction/Clarifications
Made additional minor updates and clarifications.
Stereoscopic Video Delivery
Added the data_file roles for 3D HDR mapping and parallax metadata files. See Assets and Data Files and Stereoscopic Video Overview.
Correction/Clarifications
Made additional minor updates and clarifications.
Film Ratings, Advisories, and Genres
Revised the sections on ratings, advisories, and genres. See Overview in the “Film Ratings, Advisories, and Genres” section.
Correction/Clarifications
Updated references to the Multiple Language Support section of the Apple Transactional Movies User Guide.
Made additional minor updates and clarifications.
HDR Delivery
Updated the information about HDR delivery. See HDR Delivery.
Brazil Ratings Requirements
Updated the information about delivering ratings for Brazil. See Brazil.
South Africa Ratings Requirements
Updated the information about delivering ratings for South Africa. See South Africa.
Correction/Clarifications
Minor updates and clarifications.
Film Ratings
Updated ratings and advisories for Korea. See Korea.
Film Profile: Tags
Added <attribute name=”hdr.max.display.luminance”> for use with stereoscopic video delivery. See Stereoscopic Video Overview.
Title
Renamed this document to Apple Transactional Film Specification.
Stereoscopic video source files
Added instructions on delivering stereoscopic video source files. See Stereoscopic Video Overview.
Forced subtitles
Updated instructions on delivering forced subtitles. See Assets and Data Files and Delivering Forced Subtitles.
Backdrops and logos
Updated requirements for backdrops and logos. See Basic Film Metadata Annotated.
Correction/Clarifications
Minor updates and clarifications.
iTunes Timed Text Profile
Updated cross references to the Timed Text Markup Language, Version 1.0 specification. See Overview.
Minimum Storefront Requirements
Updated Turkey to Türkiye. See Minimum Storefront Requirements.
Correction/Clarifications
Minor updates and clarifications.
Film Ratings
Added rating requirements for Vietnam. See Vietnam.
ATSC Video: Timecode Format
Added support for 30 fps content for film. See Timecode Formats.
Film Profile: Tags
The suppression lift date (<release_date_suppression_lift_date>) can be the same date as the sales start date (<sales_start_date>). See and Basic Film Metadata Annotated.
Correction/Clarifications
Minor updates and clarifications.
Film Ratings
Updated rating requirements for India. See India.
Updated rating requirements for New Zealand. See New Zealand.
Updated rating requirements for South Africa. See South Africa.
Updated ratings and advisories for Korea. See Korea.
Film Profile: Ratings
Updated the ratings requirements for Brazil. See Brazil.
Film Profile: Tags
Added <release_date_suppression_lift_date>. See Basic Film Metadata Example and Basic Film Metadata Annotated.
Correction/Clarifications
Updates to the Visual and Textual Restrictions and HDR Delivery sections.
Film Profile: Ratings
Added the consumer advice labels for New Zealand. See New Zealand.
Correction/Clarifications
Clarified information about when the <sales_start_date> and <available_for_vod_date> elements are required. See the Basic Film Metadata Annotated and Multiple-Language Film Metadata Annotated sections.
Clarified information about the crop dimension attributes for dub cards in the Multiple-Language Film Metadata Annotated section.
Clarified the descriptions for forced subtitles. See Assets Delivered in a Multiple Language Package.
Updated the link to the Movies Style Guide.
Film Profile: Provider Review Start Date
Added the optional <provider_review_start_date> tag to specify the date when a film is available to be reviewed in Extras Previewer and Apple Partner Media Review. See Basic Film Metadata Annotated.
Correction/Clarifications
Clarified the 4K availability date information. See HDR Preorder Metadata-Only Annotations.
Clarified that for Multiple Audio Language Worldwide film previews, a preview can have either a subtitles data file or an audio data file, but not both. See Defined Previews.
Included 24fps in the Timecode Formats table. (Support for 24fps was added in 5.0.1.)
Film Ratings: Brazil
Removed the requirement to include the following descriptor: Não há inadequações (No inadequacies). See the ratings requirements section for Brazil.
Film Advisories: India
Film advisories for India must be delivered in <advisory> tags within the <ratings> block. The <rating> tag is used to deliver the rating code and reason. Here is a sample XML:
<ratings> <rating system=“in-movies” reason=“for alcohol consumption, imitable behavior, and smoking or tobacco use” code=“UA16+“/> <advisory system=“in-movies” code=“AC”/> <advisory system=“in-movies” code=“B”/> <advisory system=“in-movies” code=“T”/> </ratings>Film Profile: Dub Card Video Clarification
Clarified in the Assets and Data Files and the Assets Delivered in a Multiple Language Package sections that the locale value for the dubbed audio asset and the dubbing cards must match, with the exception of Chinese language dub cards, which use the script subtag.
Film Profile: Korean Film Delivery
A new chapter introduces features related to the delivery of film content for Korea. It covers film ratings and advisories, style guidelines, minimum storefront requirements, and XML tags specific to Korea, including: <watermark_end_date>, <burned_in_subtitles_end_date>, and <premium_end_date>. See Overview of Korean Deliveries.
Film Profile: Minimum Storefront Requirements
Korea has been added to the Minimum Storefront Requirements table. See Minimum Storefront Requirements.
Correction
Updated the link to Multiple Language Support in the Apple Transactional Movies User Guide.
Film Profile: Regional Requirements
References to CBFC requirements have been removed as part of the overall changes to India ratings. See Regional Requirements.
Film Profile: India Advisories
Film advisories have been added for India. An advisory is required for all ratings for India, except for the U rating. See India.
Film Profile: Ratings
Several ratings have changed for film. The ratings document can be downloaded from Film Ratings, but the changes are summarized in the table below.
Country/Region | Changes |
|---|---|
Australia |
|
Belgium |
|
Bulgaria |
|
Germany |
|
Greece |
|
India |
|
Indonesia |
|
Italy |
|
Kazakhstan |
|
Latvia |
|
Netherlands |
|
Poland |
|
Qatar |
|
Saudi Arabia |
|
Singapore |
|
South Africa |
|
Spain |
|
Switzerland |
|
Ukraine |
|
United Kingdom/Great Britain |
|
United States |
|
Vietnam |
|
* These ratings will be deprecated and at some point in the future, delivery will be blocked if you send them.
Film Profile: Regional Requirements
New regional requirements have been added for the United States, Europe, and Colombia. In addition, the regional requirements section has been reorganized. See Regional Requirements.
Film Profile: Ratings
A T rating (Suitable without age restriction) for Portugal has been added. The country name for Swaziland has been updated to eSwatini. You can download the ratings document from Film Ratings.
Film Profile: Poster Art
Apple strongly recommends that you deliver 16:9 poster art. Currently, delivering 16:9 artwork is optional and may be required at a later date. Note that 16:9 artwork is required for promotion on the Store.
Film Profile: Corrections
The introductory paragraph in the Dolby® Atmos Audio Downmixing section listed incorrect attribute names, which have now been corrected (for example, audio.transform_to.2.0 was changed to audio.transform_to.2_0. The names in the XML examples were correct.
Film Profile: Corrections
The example XML for delivering HDR and SDR in the same delivery has been corrected and annotations have been added. See HDR and SDR Delivery Example and HDR and SDR Delivery Annotations.
Film Profile: Metadata Lookup
When you perform a metadata lookup on a package, the lookup returns a <metadata_token> tag, which you need to deliver when doing a metadata update for content that has been reviewed. The <metadata_token> tag was omitted in previous versions of the specification. See Read-Only Metadata Example for an example.
Film Profile: New Data File Role
A new data file role has been added for use with the <asset> block: card (<data_file role="card">). Currently, this data file is used for films for sale inside India to deliver the required authority (CBFC) Certificate. This data file is an image with the following requirements: JPG extension (.jpg) or PNG extension (.png) with a minimum size of 640 x 480 pixels. The card data file will have subtypes to distinguish the type of card that is delivered. Currently, there is only one subtype (certificate), but more subtypes may be added in the future. See the partial XML example below:
<data_file role="card"> <territories> <territory>IN</territory> </territories> <file_name>BN_Certificate.jpg</file_name> <checksum type="md5">bc5b28a6200e5273202b7609f626fec0</checksum> <size>1142644642</size> <locale name="bn”/> <attribute name=“subtype”>certificate</attribute> </data_file>Film Profile: CBFC Certificate
The method for delivering a CBFC Certificate for films that will be for sale inside of India has changed. You can use the existing method of stitching the certificate into the video source and deliver an attribute for use within the <asset> tag on the full video source. Or, you can deliver an image file of the certificate. Apple will create a video using the image for playback on the Store. To deliver the image file, use the new data file role card (<data_file role="card">) described above. Displaying the certificate on the poster art is no longer supported. See Regional Requirements for examples.
Film Profile: Dolby Vision
Dolby Vision CM 4 sidecar metadata files are now supported. Dolby Vision CM version 4.0 provides an improved tone curve, updated trims, additional 6-vector trims for saturation and hue, and new adjustments for mid tones.
Music Profile: Metadata Lookup
When you perform a metadata lookup on a package, the lookup returns a <metadata_token> tag, which you need to deliver when doing a metadata update for content that has been reviewed. The <metadata_token> tag was omitted in previous versions of the specification. See Read-Only Metadata Example for an example.
Film Profile: Element Changes
Added
"card" as a role on a data file
Film Profile: Countries
The ability to designate countries associated with a video has been expanded. Two new tags have been added to clarify the role of the country (<production_countries>) and to list all the countries involved (<countries_of_origin>).
Production Countries
The countries to deliver with the <production_countries> tag are the 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. Below is an example of using the tag:
<production_countries> <country primary="true">US</country> <country>CA</country></production_countries>Countries of Origin
The country (or countries) to deliver with the <countries_of_origin> tag indicates 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. Below is an example of using the tag:
<countries_of_origin> <country primary="true">US</country> <country>CA</country> <country>MX</country></countries_of_origin>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.
Film Profile: 4K Video Availability Date
You can use the <available_for_4k_date> tag to indicate when a 4K video will be available for sale on the iTunes Store in a specified territory. (Previously, the <available_for_4k_date> tag was used for preorders only.) You deliver the optional tag in the <product> block for a territory. Supplying the date ensures that the film will be labeled as 4K video on the Store. See the annotations in 4K Metadata Example Annotations for tag details.
Corrections
Chapter tags have been removed from the “Film Metadata-Only New Delivery Package” section. You can only add chapters to a delivery that includes the full asset, or if the full asset has been delivered previously. A metadata-only package for a new delivery that includes chapters will be blocked.
Film Profile: Element Changes
Added
<countries_of_origin>
<production_countries>
Changed
<country> can now be used within the <countries_of_origin> block and the <production_countries> block
<available_for_4k_date> can now be used for 4K deliveries (not just for preorders)
Film Profile: Textless Master
The textless master attribute (<attribute name="image.textless_master">) is required for all videos; previously it was required only for videos that were textless.
Film Profile: Japanese iTunes Timed Text Profile
Tate Chu Yoko (TC) can be up to four half-width numerical characters, in addition to up to two half-width alphanumeric characters.
When using bouten, do not group a series of bouten together within a single "ruby" span. Place one bouten per character as shown in the example in Special Character Display.
Corrections
The locales for an example showing how to deliver 16:9 artwork have been corrected.
Tag Changes
Changed
"image.textless_master" attribute on the source is now required for all videos
Film Profile: Audio and Video Delivery
Previously, film delivery included an SDR source with embedded audio as the primary audio of the package and an optional delivery of a Dolby® Vision video that could use the embedded audio on the SDR source. You can now deliver video and audio as separate components (the audio is not required to be embedded in the source video) and you can deliver a Dolby Vision video and specify that it be down-converted to SDR. See the subsections below for example deliveries of components.
All deliveries must conform to the following rules:
A new package delivery must include both video and audio components.
Every package must have a primary audio source. This primary audio source must include the stereo mix as it is the base requirement.
The audio to use as the primary audio must be indicated if you’re not using the embedded SDR source audio.
Every package must include stereo audio file mix.
A package can have only one primary audio (default embedded SDR audio or another audio source specified in the XML delivery). This primary audio aligns with the primary audio locale you want for the package. For example, if the movie has dubbed Russian and is sold only in Russia, the primary audio would be "ru" even though the video source is "en-US".
SDR Delivery
You can now deliver an SDR source without embedded audio. In this case, you deliver an alternate audio as a separate file and it will be used as the primary audio. If you deliver more than one alternate audio file, the audio file with the locale that matches the source video will be used as the primary audio, unless you specify a different locale as primary using <attribute name="primary_audio">true</attribute>. Note that there can only be one primary audio per package.
If you deliver an SDR video source that has embedded audio and you deliver alternate audio files, you can use the "ignore_audio" attribute to indicate you do not want to use the embedded audio. Then you specify that the separate audio component should be considered the primary audio.
Below are two examples of the existing and new SDR delivery methods (see the subsection below for HDR deliveries):
Current delivery method (will still be supported):
SDR source with embedded audio
Optional HDR source with embedded audio
Audio on the HDR source is ignored and the SDR audio is used
New delivery method with SDR source with no audio:
SDR source with no audio
Alternate audio is used as the primary audio and delivered with the <attribute name="primary_audio">true</attribute>
Dolby® Vision HDR-Only Delivery
You can now deliver Dolby Vision HDR video without a corresponding SDR video delivery and specify a tag to down-convert to SDR. Apple will create the SDR video using the Dolby Vision SDR trim metadata. Using this method is optional, but it could streamline the delivery process for you. When you deliver a Dolby Vision-only package, you can choose to include embedded audio or you can deliver the audio in a separate file. Note that this delivery method is not available for HDR 10 videos.
To deliver a Dolby Vision-only package, you must use the attribute that indicates you want the HDR video to be down-converted to SDR: <attribute name="video.hdr.force_sdr_downconvert">true</attribute>. In addition, if the HDR video has embedded audio, include both 5.1 and stereo audio. It is also recommended that you use the <attribute name="primary_audio">true</attribute> tag to indicate which audio to use as the primary audio.
If you deliver an HDR video source that has embedded audio and you deliver alternate audio files, you can use the "ignore_audio" attribute to indicate you do not want to use the embedded audio. Then you specify that the separate audio component should be considered the primary audio.
Below are two examples of an HDR-only package:
For HDR with embedded audio:
HDR source with embedded audio (5.1 and 2.0)
Audio on the HDR source is used
HDR source can be down-converted to SDR by specifying the attribute: <attribute name="video.hdr.force_sdr_downconvert">true</attribute>
Optional: Use the <attribute name="primary_audio">true</attribute> tag on the source HDR video
For HDR with no audio:
HDR source with no audio
Alternate Audio 1 is delivered and designated as the primary audio: <attribute name="primary_audio">true</attribute>
Alternate Audio 2 is delivered but not used as the primary audio
HDR source can be down-converted to SDR by specifying the attribute: <attribute name="video.hdr.force_sdr_downconvert">true</attribute>
Note that there can only be one primary audio per package. It is recommended that you always specify which audio to use as primary using the primary_audio attribute.
Film Profile: Dolby Atmos Delivery
If you deliver a Dolby Atmos audio file, you can specify that you want Apple to downmix to other formats. This allows you to deliver a single Atmos audio file and derive all of the other formats (7.1, 5.1, and stereo). You use the following attributes on the Dolby Atmos source audio:
audio.transform_to.2_0
audio.transform_to.5_1
audio.transform_to.7_1
If you downmix Atmos audio to stereo (2.0) for the main locale, you must specify it as the primary audio using <attribute name="primary_audio">true</attribute> and you must also use ignore_audio on any video sources with embedded audio (HDR or SDR):
<asset type="full"> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-source.mov</file_name> <size>2595225600</size> <checksum type="md5">2a793a8b46037fe8aa29dd739b49911a</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="ignore_audio">true</attribute> </data_file> <data_file role="audio.object_based"> <locale name="en-US"/> <file_name>audio_atmos.wav</file_name> <size>1142644642</size> <checksum type="md5">bc5b28a6200e5273202b7609f626fec0</checksum> <attribute name="audio.transform_to.2_0">true</attribute> <attribute name="audio.transform_to.5_1">true</attribute> <attribute name="audio.transform_to.7_1">true</attribute> <attribute name="primary_audio">true</attribute> </data_file></asset>Film Profile: Artwork
New values for the <asset> tag type attribute have been added to support 16:9 artwork, content logos, and backdrop art. In addition to 16:9 poster art, you can deliver tall or wide backdrop art and single- or full-color logos. The artwork is delivered in an <asset> block with the following types available:
Artwork Type | Allowed Formats | Tag Specifications |
|---|---|---|
artwork_16:9 | LSR (.lsr) PNG (.png) | Requires |
backdrop_tall | PNG (.png) | Requires Specifying locales is not supported |
backdrop_wide | PNG (.png) | Requires Specifying locales is not supported |
single_color_content_logo | PNG (.png) | Requires
|
full_color_content_logo | PNG (.png) | Requires
|
See iTunes Video and Audio Asset Guide for specifications.
Film Profile: CBFC Certificate
For each film that will be for sale inside of India, you must provide the authority (CBFC) Certificate. You can display the certificate in the bottom corner (preferably left) of the poster art, or you can stitch the certificate into the video source. A new attribute for use within the <asset> tag for the video has been added to indicate that you included the certificate in the video source instead of on the poster art: <attribute name="image.inline_regulatory_certification.cbfc">true</attribute> . This attribute applies to both SDR and HDR videos.
<asset type="full"> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-source.mov</file_name> <size>2595225600</size> <checksum type="md5">2a793a8b46037fe8aa29dd739b49911a</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> <attribute name="image.inline_regulatory_certification.cbfc">true</attribute> </data_file></asset>Timed Text Profile
To indicate the direction of bi-directional text (such as Arabic and Hebrew), you can use the escape character:
U+200E LEFT-TO-RIGHT MARK or U+200F RIGHT-TO-LEFT MARK [1]
Using the escape character can be used instead of tts:direction to signal writing direction.
Correction: Removed the phrase “of a region” from: If specified, the tts:backgroundColor must be set to "transparent".
Film Profile: Japanese Timed Text Character Mapping
Changes have been made to the character mapping tables (see Character Mapping).
Character | Unicode | New Mapping Unicode | Old Mapping Unicode |
|---|---|---|---|
< | 003C | FE3F | FF1C |
> | 003E | FE40 | FF1E |
Film Profile: Schema Version
The version number of this specification has changed from 5.2 to 5.3 to keep the version number in sync with the new schema version. In addition, the <package> tag version attribute has been updated in all examples to 5.3:
<package xmlns="http://apple.com/itunes/importer/" version="film5.3">
Film Profile: Pricing Intervals Updates
When updating price intervals for Electronic sell-through (EST) products, the tag <cleared_for_sale> is required. When updating price intervals for video-on-demand (VOD) products, the tag <cleared_for_vod> is required.
Tag Changes
Added
video.hdr.force_sdr_downconvert as an attribute in a Dolby Vision-only package
audio.transform_to.2_0 as an attribute for Dolby Atmos audio
audio.transform_to.5_1 as an attribute for Dolby Atmos audio
audio.transform_to.7_1 as an attribute for Dolby Atmos audio
artwork_16:9 as a type value within an <asset> block
backdrop_tall as a type value within an <asset> block
backdrop_wide as a type value within an <asset> block
single_color_content_logo as a type value within an <asset> block
full_color_content_logo as a type value within an <asset> block
image.inline_regulatory_certification.cbfc as an attribute on an SDR or HDR video asset
Changed
primary_audio as an attribute can be used for alternate audio files
Video On Demand: Pricing Intervals
You can change the price for video-on-demand (VOD) products automatically for specific time periods using interval pricing. Use the <vod_type> tag within an <interval> block along with specific time periods to change pricing levels. To change the pricing, change the VOD type.
The example below shows how to use the <vod_type> tag within an <intervals> block:
<product> <territory>GB</territory> <intervals> <interval> <vod_type>New Release</vod_type> <start_date>2011-07-01</start_date> <end_date>2011-09-01</end_date> </interval> <interval> <vod_type>Library</vod_type> <start_date>2011-09-01</start_date> </interval> </intervals>Using intervals for VOD pricing is not required; use only when you want the price to change automatically for specific time periods. See Interval Pricing Metadata Example for details.
Multiple Language Assets: Clarification
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.
Tag Changes
Changed
<vod_type> can be used within the <interval> block
Digital Release Date
Use the new <digital_only_release_date> tag instead of the <theatrical_release_date> tag to specify the release date of a film that was never released in theaters. The <digital_only_release_date> tag can be used under <video> or in the <regions><region> block. The <digital_only_release_date> tag is optional. You can supply either the <digital_only_release_date> tag or the <theatrical_release_date> tag, but not both.
Tag Changes
Added
<digital_only_release_date>
Dolby® Atmos Audio Source
You can deliver Dolby Atmos audio source for a film. To deliver Atmos audio, a new role has been added for use with the <asset> block: audio.object_based. See the partial XML example below and see Basic Film Metadata Example and Multiple-Language Film Metadata Example for complete examples of how to provide Dolby Atmos audio in the metadata. See Dolby Atmos Audio Source Profile in the iTunes Video and Audio Asset Guide for the audio file requirements.
<data_file role="audio.object_based"> <locale name="en-US"/> <file_name>09736156444_ATMOS.wav</file_name> <checksum type="md5">bc5b28a6200e5273202b7609f626fec0</checksum> <size>1142644642</size> </data_file>Minimum Storefront Requirements
Additional languages and locales have been added to the Minimum Storefront Requirements table. See Minimum Storefront Requirements. Below is a summary of the changes:
Added Austria with the locales: de, de-DE, de-LU, de-AT, de-LI, de-BE, and de-IT
Added locales to Germany: de, de-DE, de-LU, de-AT, de-LI, de-BE, and de-IT
Added original spoken language locale to Latin America and Mexico: OSL Spanish (es-**)
Added original spoken language locale to Spain: OSL Spanish (es-**)
Added original spoken language locale to France: OSL Canadian French (fr-CA)
Tag Changes
Added
"audio.object_based" as a role on a data file
Film Profile: HDR Delivery Clarifications and Corrections
To ensure that the film will be labeled as 4K video on the Store during the preorder period, the date delivered with the <available_for_4k_date> tag should match the preorder date delivered with the <preorder_sales_start_date> tag.
The HDR sidecar mapping file (for the source and preview assets) does not require a locale, so the <locale> tags have been removed from the annotations. Added missing <size> and <checksum> tags to the HDR and SDR Delivery XML example.
Film Profile: Subtitles
Right-to-left subtitles are now supported for Arabic and Hebrew. Previously, the only value allowed for the tts:direction attribute was ltr. You can now additionally use the rtl attribute for Arabic and Hebrew. See Text Direction.
Film Profile: Minimum Storefront Requirements
Language codes have been added to the Minimum Storefront Requirements table for languages that were missing them. See Minimum Storefront Requirements.
Film Profile: HDR and 4K Video Preorders
New tags have been added to provide 4K and HDR video information for preorders. You can use the new tag <available_for_4k_date> to indicate when an HDR or 4K video will be available for sale on the iTunes Store in a specified territory. You deliver the optional tag in the <product> block for a territory. Supplying the date ensures that the film will be labeled as 4K video on the Store during the preorder period. See the annotations in HDR Preorder Metadata-Only Annotations for tag details.
If you want to allow preorders on a 4K video before delivering the asset, send a metadata-only package to supply the format of the video so that the format can be displayed on the Store during the preorder period. The value can be "hdr10" or "dolby_vision". Only one HDR format can be specified and once delivered, it cannot be updated. This setting is for all territories.
Corrected the version number for the document “Dolby Content Mapping (CM) Metadata Format Specification” to Version 2.0.5.1.
Film Profile: Production Still Image
You can specify a frame to use for the production still image that will be displayed on the product page for a full source 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 and that frame will be used for all territories. Note that this is not the same as the image cut using 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.
The following example shows how to use the <production_still_image_time> tag on the full asset:
<asset type="full"> <. . .> <production_still_image_time format="24/999 1000/nonDrop">00:00:57:02</production_still_image_time> <. . .> </asset>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:
<asset type="full"> <. . .> <data_file role="production_still_image"> <file_name>fearless.png</file_name> <size>111037</size> <checksum type="md5">96a2c3979611ea3966f19ff1ac4f28b0</checksum> </data_file> <. . .> </asset>Film Profile: Element Changes
Added
<available_for_4k_date>
<expected_hdr_formats>
<hdr_format>
<production_still_image_time> for use within the <asset type="full"> block
"production_still_image" as an attribute of <data_file> within the <asset type="full"> block
Film Profile: HDR and 4K Video Previews
4K HDR is supported for custom previews. Examples and annotations have been added to Metadata Example for HDR Dolby® Vision, Metadata Annotations for HDR Dolby® Vision, Metadata Example for HDR10, and Metadata Annotations for HDR10.
Film Profile: Minimum Storefront Requirements
New territories have been added to the Minimum Storefront Requirements table: Bahrain, Egypt, Japan, Jordan, Lebanon, Oman, Qatar, Saudi Arabia, Thailand, and United Arab Emirates. For more information, see Minimum Storefront Requirements.
Film Profile: Languages
Added the following languages to the language code table: Bengali, Kannada, Malayalam, Marathi, and Punjabi. See Language Codes.
Film Profile: Ratings
Some ratings have changed for film. The ratings document can be downloaded from Film Ratings, but the changes are summarized in the table below.
Country/Region | Changes |
|---|---|
Ukraine |
|
Taiwan |
|
Cambodia |
|
Vietnam |
|
Film Profile: Phonetic Title Clarification
The phonetic title tag is required when a Japanese title is provided. The reading (furigana) of the film title must be provided in full-width katakana or hiragana.
Film Profile: Japanese Timed Text
A new section has been added to clarify support for ruby by release version. See Feature Sets of Ruby Vertical Versions.
Film Profile: Japanese Timed Text Character Mapping
Additions have been made to the character mapping tables (see Character Mapping).
Film Profile: HDR Video
You can now deliver HDR (high dynamic range) video in either Dolby® Vision or HDR10 format. The HDR video is delivered as an asset-only update to an existing SDR video or with a new delivery of both the SDR and HDR videos. When delivering HDR video, you specify values for the ranges of color, shades of darkness, and brightness, which can also vary based on the target display. The Dolby® Vision HDR source video must include an accompanying mapping XML file (referred to as the sidecar metadata) with those values. For HDR10, you supply those values using <attribute> tags in the <asset> block. See HDR Delivery for more information.
For delivery, the assets and files must meet certain requirements, including correlations between the SDR video and the HDR video (for example, the <locale> specified on the HDR video must match the <locale> of the SDR video). See For HDR source with a corresponding SDR source: for the list of requirements. In addition, the HDR source assets must meet the requirements listed in Film HDR Source Profile in the iTunes Video and Audio Asset Guide.
For XML examples, see Metadata Example for HDR Dolby® Vision and Metadata Example for HDR10. For an XML example showing how to deliver HDR and SDR videos in the same delivery, see HDR and SDR Delivery Example.
Film Profile: 4K Video
You can now deliver 4K video. See the requirements listed in 4K Source Profile in the iTunes Video and Audio Asset Guide for more information.
Film Profile: Source Audio
You can re-use a previously-delivered video source as an audio file. This could be useful if you are delivering a new video source with embedded audio, but you want to use the embedded audio from a previously-delivered video source instead of the audio embedded in the new video source. In this case, neither stereo nor surround embedded audio will be used from the new video source. To re-use the previously-delivered video source as an audio file, two new attributes have been added: ignore_audio and reused_old_source. When delivering the new source, you would use the <attribute name="ignore_audio">true</attribute> on the data file. In the same delivery, you would supply the previously-delivered video source, but change the role from source to audio and use the <attribute name="reused_old_source">true</attribute> on the data file.
Below is an example of the XML used in the original delivery and then an example of the updated delivery:
Previously-delivered video source:
<asset type="full"> <data_file role="source"> <locale name="en-US"/> <file_name>full-source-with-good-audio.mov</file_name> <size>343376467</size> <checksum type="md5">301e72262aea7d504aca91abe229cded</checksum> </data_file></asset>Delivering new source and reusing old source audio:
<asset type="full"> <data_file role="source"> <locale name="en-US"/> <file_name>new-full-source-with-bad-audio.mov</file_name> <size>523996467</size> <checksum type="md5">5a793a8b46037fe8aa2bdd739b49911a</checksum> <attribute name="ignore_audio">true</attribute> </data_file> <data_file role="audio"> <locale name="en-US"/> <file_name>full-source-with-good-audio.mov</file_name> <size>343376467</size> <checksum type="md5">301e72262aea7d504aca91abe229cded</checksum> <attribute name="reused_old_source">true</attribute> </data_file> . . .</asset>Film Profile: Element Changes
Added
"ignore_audio" for use in the <attribute> tag on a source data file
"reused_old_source" for use in the <attribute> tag on an audio data file
source.hdr and mapping.hdr for use on the <asset> tag
Film Profile: Artist Roles
Cue sheets provide a list of music played in a film for both concert films (required) and feature films (optional). For a piece of music, you supply the artist information, including the artist <role>. Roles define the part that a particular artist performs. Performer and Songwriter (or Composer) roles are always required and the Featuring or With roles are required when there is a featured artist on the musical piece. All other roles are optional. Apple recommends that you supply as much role data as you have for your content. To help ensure consistency and provide formatting guidelines (for example, use Lead Vocals instead of Singer), use the roles preferred by the iTunes Store listed here: Recommended Contributor Roles.
Film Profile: ISAN for Switzerland
Due to a recent change in policy by the Swiss Federal Office of Culture, ISAN values are now only required for certain movies sold in Switzerland. Because of this change, the previously strict requirements on ISAN have been relaxed.
For movies that meet the requirements listed below, you need to provide an ISAN or V-ISAN:
If the film is over 60 minutes long and meets one of the following:
The film was released on iTunes (EST or VOD) after 1 January 2017
Or the film has been registered with the ISAN organization and assigned an ISAN or V-ISAN
See Regional Requirements for more information.
Film Profile: Dub Artist
Previous revisions of this specification indicated that the dub artist role would be displayed on the Store. Dub artists do not appear on the Store and the appropriate annotations have been corrected.
Film Profile: Phonetic Title
The phonetic title tag is required when a Japanese title is provided.
Film Profile: Japanese Timed Text Correction
When delimiting parts of foreign words, use a full-width KATAKANA MIDDLE DOT: 30FB (・), for example: エンターテインメント・センター (Translation: entertainment center). Previous revisions indicated that a half-width KATAKANA MIDDLE DOT: U+FF65 (･) should be used.
iTunes Timed Text Profile: Clarification
Non-Japanese content must use the standard iTunes Timed Text profile. The information provided in the Japanese iTunes Timed Text Profile chapter relates only to Japanese content.
Versioning Clarification
A schema is used to validate the XML document you send in an iTunes Package. The version of the schema consists of two numbers: a major number for the schema and a minor number to track changes to the that version of the schema. The schema version number is expressed as major.minor, for example 5.2. The revisions of the specifications are based on the schema version. Each time a specification is released for a specific schema version, the release is tracked using an additional number. The specification version number is expressed as major.minor.revision, for example 5.2.16. When specifying the version attribute in the <package> tag, match the schema version, not the specification revision. For example, for this revision of the spec, 5.2 is the schema version and 5.2.16 is the specification revision (so the attribute value is 5.2, not 5.2.16):
<package xmlns="http://apple.com/itunes/importer" version="film5.2">
Note that this information is for clarification purposes; the numbering schemes have not changed and do not affect the delivery process as long as you follow the numbering rules.
Film Profile: Concert Films
You can add metadata to supply information on cast and crew members in a concert film. The cast metadata is supplied in a <cast> block, with a <cast_member> block within the <cast> tag for each cast member; the crew metadata is supplied in a <crew> block, with a <crew_member> block within the <crew> tag for each crew member. Tags have been added to a concert films metadata example (Concert Film with Cast and Crew Metadata Example) and the annotations are in the Basic Film Metadata Annotated section.
You can use any combination of the <artists> block, the <cast> block, and <crew> block as needed to ensure that all contributors involved in the concert film are specified. For concert films, the <artists> block is required, but the <cast> and <crew> blocks are optional.
Film Profile: Dub Card Video
If you deliver a dub card video with a resolution that does not match the resolution of the video source, you must supply different crop dimension attributes for dub cards. See the annotations for dub card video in Multiple-Language Film Metadata Annotated for an XML example.
Film Profile: Previews
A movie preview length should be a maximum of 10 minutes to help prevent accidentally uploading the feature-length film.
If you provide defined previews, the image_time attribute is required. If you deliver a defined preview without the image_time attribute, you will see a warning. At a later date in the future, delivery will fail. The frame must be within the start_time and end_time.
Film Profile: Cue Sheets
The allowed length of cue sheet titles has changed. Previously, there was a 255-byte limit for single-byte characters (such as ASCII characters); for multiple-byte (for example, Japanese) characters, this limit equated to as few as 71 characters. The new limit is 256 characters for single-byte characters and 1024 bytes for multiple-byte characters (which can equate to as many as 256 characters).
Film Profile: Poster Art
Non-layered JPG and PNG (.jpg and .png) files must be at least 2000 x 3000 pixels. See iTunes Video and Audio Asset Guide for specifications.
Film Profile: Audio Description (AD)
You can now deliver Audio Description (AD) files in 5.1 surround audio, in addition to 2.0 stereo.
Film Profile: Japanese Timed Text
Special characters can be used to preserve whitespace in Japanese subtitles, such as Chidori-style placement for song lyrics and whitespace after the break for half-width quotation marks and brackets. See Special Character Display for more information. Other minor corrections.
Film Profile: Cue Sheets
Cue sheets provide a list of music played in a film. Cue sheets have been available for concert films, but are now deliverable for feature films. If a feature film contains music, you can optionally supply cue sheets that list the start time, duration, title, performers, and other details of a musical piece. Note that the information you supply for cue sheets is currently not supported for display on the Store. See Basic Film Metadata with Cue Sheet Example for an XML example and see Concert Film Metadata Annotated for tag annotations. The only difference for feature films is that cue sheets are optional for all countries/regions.
Film Profile: Japanese Timed Text Character Mapping
Several character mapping tables for Japanese timed text have been added (see Character Mapping). The tables show how iTunes maps characters (ASCII, symbols, punctuation, Hangul, and Katakana) in subtitle iTT files to support ruby and vertical subtitles. These characters often rotate incorrectly 90 degrees when displayed in vertical subtitles. The iTunes mapping process ensures that the characters are correctly displayed. In the mapping tables, each row maps the horizontal representation of a character to its vertical counterpart when available.
Film Profile: Japanese Timed Text Correction
Within a div element, subtitles can be displayed during the same time period. That is, the time periods in the <p> elements can overlap and the start timecode for each <p> can be identical. (The previous specification indicated that the start timecodes needed to be different.) This applies to a vertical subtitle and a horizontal subtitle displayed together, as well as two horizontal subtitles and two vertical subtitles.
Film Profile: iTunes Timed Text
To validate an iTunes Timed Text .itt document, you need the iTunes Timed Text Schema Validation document (itunes-timed-text.complete.rnc), which can be found here.
Film Profile: Japanese Timed Text
A new chapter has been added to support Japanese subtitles that includes ruby and vertical subtitle support. See Overview of Japanese Timed Text.
Film Profile: Crop Dimensions
Crop dimensions are required for films that are matted and 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, iTunes will default to 0,0,0,0.
Film Profile: ISAN
ISAN (International Standard Audiovisual Number) is now required for movies sold in Switzerland. See Regional Requirements for more information.
File Profile: Audio Description Clarification
Audio Description (AD) files are accepted for all languages and iTunes 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 will not go live on the Store.
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.
Language Codes Clarification
When specifying languages, you can use any language as long as it is a valid BCP 47 code that consists of the language subtag, optional region subtag, and optional script subtag as appropriate. Although script subtags are valid (for example, Chinese can be written in either Traditional or Simplified characters and you may need to indicate that localizations appear in a specific script), keep in mind that script subtags are for describing text and should not be used for describing audio. Note that while any valid language code is accepted, the iTunes Store only displays content in a limited set of languages. See Language Codes for more information.
Film Profile: Preview Image
You can now specify which frame to use for the preview image using the <preview_image_time> tag (custom previews) and the image_time attribute (defined previews). The frame must be within the preview. If the tag is not supplied, the first frame of the preview is the default image for defined previews. If the tag is not supplied for custom previews, 45 seconds is the default.
You can specify the frame for both custom and defined previews.
For custom previews, specify the frame using the <preview_image_time> tag. For example:
<asset type="preview"> <preview_image_time format="24/999 1000/nonDrop">00:00:57:02</preview_image_time> <territories> <territory>WW</territory> </territories> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-preview.mov</file_name> <size>9987212</size> <checksum type="md5">739b43b793a8b46037fe8aa29dd9911e</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> </data_file> </asset>For defined previews, specify the frame using the image_time attribute. For example:
<previews> <preview territory="US" timecode_format="24/999 1000/nonDrop" start_time="00:55:13.02" end_time="00:58:27.00" image_time="00:55:45.12"/> </previews>See Defined Previews for requirements and considerations when defining a metadata-based preview. See Multiple-Language Film Metadata Example for an XML example of defining a preview.
Film Profile: Chapter Image
Previously, you provided artwork files for each chapter image. Using the <artwork_time> tag, you can now specify which frame to use for each chapter image. The frame must be within the chapter. For example:
<chapter> <start_time>00:07:45:23</start_time> <title locale="en-US">Football at Alabama</title> <artwork_time>00:07:45:23</artwork_time> </chapter>If you create a new chapter, you must provide an artwork image. The image can be either an artwork file or a frame specified by a timecode.
If you specify a <timecode_format> of qt_text under <chapters>, then the frame nearest the timecode is used for the chapter image: you cannot specify a frame for the chapter image using qt_text.
See Chaptering for requirements and considerations when defining chapters. See Basic Film Metadata Example for an XML example of defining a chapter image.
Film Profile: EIDR
An optional tag has been added to support EIDR (Entertainment Identifier Registry). EIDR is a universal, unique identifier system for movie assets. Any level of EIDR is accepted in this field, so long it is in a valid format. See the annotation in Basic Film Metadata Annotated for more information on the format. For more information on EIDR, see https://eidr.org/about-us/.
Timecode Formats: qt_text milliseconds
The qt_text timecode format now supports milliseconds. See Timecode Formats for more information.
Schema Support
Support for 4.x and lower schemas is being discontinued. This means that the tags and requirements included in a delivery must conform to a 5.0 or higher schema (iTunes recommends you use the latest published specification version, currently film5.2). For example, a tag that has been deprecated in a 5.0 or higher schema but was valid in a 4.x schema would no longer be supported. If you deliver a package that does not specify and conform to a 5.0 or higher schema version, you will see a warning when delivered. At some point in the near future, delivery will fail. For example, the following package would receive a warning because the version number is below 5.0:
<package xmlns="http://apple.com/itunes/importer" version="film4.7">
Film Profile: Ratings
Some ratings have changed for film. The ratings document can be downloaded from Film Ratings, but the changes are summarized in the table below.
Country/Region | Changes |
|---|---|
Indonesia | Removed ratings for A, R, and D |
Luxembourg | Added 10 rating: Not suitable for viewers under the age of 10 |
Norway | Removed ratings for 7, 11, and Kun registrert |
Philippines | Changed the description for PG to: "Children under 13 must be accompanied by an adult." |
Film Profile: Audio Descriptions Clarification
The locale of the audio description must match the locale of a corresponding source audio or alternate audio file.
Film Profile: Element Changes
Added
<preview_image_time> for use within the <asset type="preview"> block
image_time="valid_timecode" as an attribute of <preview> within the <previews> block
<artwork_time> for use within the <chapter> block
<eidr>
Film Profile: Ratings
New ratings have been added for film. The ratings document is available in “Resources and Help” in iTunes Connect, but the changes are summarized in the table below.
Country/Region | Rating and Description |
|---|---|
Norway |
|
Film Profile: Subtitle Restrictions Clarification
If audio and forced subtitles in the same language are included in a package, they must both have the same locale value. See Restrictions for more information.
Film Profile: Metadata-Based Cropping Clarification
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. See Basic Film Metadata Annotated for more information.
Film Profile: Corrections
Removed the note that Audio Descriptions will be supported on the sellable movie product at a later date. Audio Descriptions are currently available on all devices.
Film Profile: Localized Synopsis
When localizing film metadata, you must localize the <synopsis> of the film, as well as the <title>. If you do not supply a localized synopsis for a film being localized, you will see a warning that the synopsis is missing. In the future, Apple intends to transition from warning to failing delivery of packages that do not localize the <synopsis>. The XML example for Japanese omitted the <synopsis> tag, which has now been added. See Non-Japanese Language Metadata Example for details.
Film Profile: Component Previews Clarification
When delivering a multiple-language preview, you can include a forced subtitles file along with one subtitles file OR one audio file for each territory. The forced subtitles file does not count toward the limit of one subtitles file or one audio file.
Film Profile: Minimum Storefront Requirements
Added territories (Hong Kong, Macau, and Taiwan) with minimum Storefront requirements, and added to the existing minimum Storefront requirement for Türkiye.
To meet the minimum Storefront requirements, preview files must meet the same minimum requirements as the full asset. See Minimum Storefront Requirements for a list of requirements.
Film Profile: Poster Art
iTunes now supports layered images that are used to achieve a parallax (3D) effect for poster art. The layered image format is a zipped folder with the extension .lsr containing a set of folders, json descriptions, and PNG .png files, one file for each layer. The layered image must have a minimum of 2 layers with a maximum of 5 layers. The folder contains the PNG images along with a manifest describing the order and position of each layer. The LSR .lsr file must have a minimum resolution of 2000 x 3000 pixels. For LSR format details and for additional tools, see Support.
Non-layered poster art (.jpg and .png) should have a recommended resolution of 2000 x 3000 pixels. See the iTunes Video and Audio Asset Guide for specifications.
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.
Film Profile: Territory Exclusion End Dates
Territory exclusions allow you to exclude assets from particular territories. You can now indicate that the exclusion should end on a specific date by adding the end date to the tag: <territory_exclusion end_date="2013-02-02">MX</territory_exclusion>. On the specified date, the asset will be made available for the territory.
When territory exclusions were first introduced in this specification, the <territory> tag was used to list the territories from which the asset should be excluded. With the added end date feature, the <territory> tag has been modified to <territory_exclusion end_date>. The <territory> tag will still be valid as long as you are not specifying an end date. You can also use the <territory_exclusion> without the end date. The following example shows a <territory_exclusions> block with all variations of the tags:
<territory_exclusions> <territory_exclusion end_date="2013-02-02">FR</territory_exclusion> <territory_exclusion>CA</territory_exclusion> <territory>BR</territory></territory_exclusions>Note that if you use the <territory> tag and then later do a metadata lookup, the tag will be returned as <territory_exclusion>.
See About Territory Exclusions for more details on territory exclusions in general and see Multiple-Language Film Metadata Example for an XML example that includes a <territory_exclusion end_date> tag for Brazil subtitles.
Film Profile: Preview Clipping
The preview contains the movie trailer or pre-sale merchandising asset. The preview can be a custom asset file, or it can be a defined preview clipped from the source video and specified in the metadata using the <preview> tag. You can specify more than one preview, one per territory.
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 new <preview> tag and specify the territory for the preview, the timecode format, and the start and end times of the clip.
See Defined Previews for requirements and considerations when defining a metadata-based preview. See Multiple-Language Film Metadata Example for an XML example of defining a preview.
Film Profile: Component Previews
You can deliver previews with a data file to accommodate an additional language. For each territory, the preview can have only one alternative audio OR one subtitles file, but not both. If you are delivering alternate audio, you can optionally deliver both a data file with the role of audio and a data file with the role of audio.7_1 if both data files have the same locale.
The following XML example shows how to deliver the components:
<asset type="preview"> <territories> <territory>FR</territory> </territories> <data_file role="source"> <locale name="fr-FR"/> <file_name>09736156444-FR-preview.mov</file_name> <size>9787655</size> <checksum type="md5">603b43b7fe739798aed991a3a8b429d1</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> </data_file>PLUS EITHER . . . <data_file role="audio"> <locale name="en-CA"/> <file_name>audio_EN_CA.mov</file_name> <checksum type="md5">bdeea426ac79543b691a45507e9956c8</checksum> <size>5820197005</size> </data_file>OR . . . <data_file role="subtitles"> <locale name="en-CA"/> <file_name>Subtitles_EN_CA.itt</file_name> <size>88634</size> <checksum type="md5">54f16038469c9af0cbc123e8b8b9e4df</checksum> </data_file>Film Profile: Element Changes
Added
<previews> and <preview>
<territory_exclusion end_date> for use within the <territory_exclusions> block
Film Profile: Minimum Storefront Requirements
To improve the quality of the content offered on the iTunes Store, certain territories must meet a set of minimum requirements for movies. These requirements apply to feature films only; concert films and short films are excluded. To see which territories are affected and view the requirements, see Minimum Storefront Requirements.
Film Profile: Poster Art
Poster art (.jpg and .png) should have a recommended resolution of 2000 x 3000 pixels. See the iTunes Video and Audio Asset Guide for specifications.
Film Profile: Languages
The code (nl-BE) for Flemish (Dutch as spoken in Belgium) has been added to the language codes table for use with dub card videos.
Film Profile: Corrections
Removed the phrase “or {+|-}HH:MM:SS;FF for drop frame timecodes (for example, begin="-01:00:00;00")” from the annotation on Div in the “iTunes Timed Text Profile” chapter. The TTML-compliant iTT spec does not support the use of the semi-colon as a frame separator.
Film Profile: 7.1 Surround Audio
To support the import of Dolby Digital Plus audio, a new role has been added for the <data_file> block. The optional 7.1 surround audio is delivered as a role for the full asset using role="audio.7_1". One 7.1 surround audio file can be provided for each desired language (and region). Use the required <locale> tag to indicate the language (and optional region) of the audio. In addition, you can indicate how to handle existing 5.1 surround audio using the new "audio.surround.force_5_1_downmix" attribute. See the partial XML example below and see Multiple-Language Film Metadata Example for a complete example of how to provide 7.1 surround audio in the metadata.
<data_file role="audio.7_1"> <locale name="fr-FR"/> <file_name>09736156444-71-audio_FR.mov</file_name> <checksum type="md5">a765a9fc88ac893ead51366fbeb04d82</checksum> <size>8730177839</size> <attribute name="audio.surround.force_5_1_downmix">true</attribute></data_file>For details and delivery considerations, see 7.1 Surround Audio Delivery.
In addition, two new channels have been added to tag audio tracks. See the “Film Audio/Video and Alt-Audio Container” section in the iTunes Video and Audio Asset Guide for information on tagging the audio tracks for 7.1 surround audio.
Film Profile: Closed Captioning Reason Codes
As of June 30, 2015, all promotional content must be captioned and the closed captioning reason code "PROMOTIONAL_TV_CONTENT_PRE_JUNE_2015" is no longer applicable. Deliveries sent with this code will be blocked. The reason code "PROMOTIONAL_TV_CONTENT_PRE_JUNE_2015" has been removed from the examples and annotations.
Film Profile: Element Changes
Added
"audio.7_1" as a role on a data file
"audio.surround.force_5_1_downmix" as a name attribute with the <attribute> tag
Film Profile: Poster Art
Delivering the <locale> for poster art is now 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, the delivery will fail.
Film Profile: Closed Captions Reason Codes
Two accessibility information reason codes ("NEVER_IN_US" and "IN_US_NO_CAPTIONS") that were previously deprecated have been reinstated.
Movies that are in English can be delivered with subtitles for the deaf or hard-of-hearing (SDH) if closed captions are not available and one of the following reason codes is applicable:
"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.
Movies that are not in English and have never been broadcast in the United States don’t need captions. These movies will need either English subtitles or SDH. Use the reason code NO_CC_SDH_FOREIGN_LANGUAGE_ENGLISH_SUBS for these movies.
See Basic Film Metadata Example without Closed Captions for information on sending accessibility information reason codes.
Film Profile: Texted Previews
An example and annotations for delivering a preview that includes forced narrative and burned-in subtitles has been added to the multiple languages chapter. See Multiple-Language Film Metadata Example.
Film Profile: Requirements for Content from India
Movies sold in India that contain a smoking and/or drinking alcohol health warning, as per CBFC guidelines, should be tagged with a textless master reason code. To indicate that the film contains this burned-in text, a new attribute has been added for the source video. The tag is <attribute name="image.textless_master.reason_code"> and the allowed value is india_health_warning. This attribute is only allowed on data files with a "source" role. See Regional Requirements for a sample XML showing how to deliver the tag.
NTSC Video: Timecode Format and Frame Separator
Many software-based video systems use the imprecise value of 29.97 as the frame rate for NTSC video. If your source video is timed accurately to true NTSC standard framerate, use the 1000 1001 ratio. See Timecode Formats for more information.
Previous versions of the specification indicated that using a semicolon (;) separator for frames is insufficient to indicate drop frame. However, using the semicolon is not allowed and the "dropNTSC" value must be used.
Film Profile: Element Changes
Added
<attribute name="image.textless_master.reason_code"> as an attribute of the full source asset
india_health_warning as the value for the <attribute name="image.textless_master.reason_code"> tag
Film Profile: Role
When you deliver a film, you specify and deliver the assets, such as the film video and its closed captions. The full video asset is made up of one or more data files (delivered in a <data_file> block) and each data file plays a specific role for the asset. For film, several roles can be specified (including the role called “source” for the full asset and other roles such as “captions” for a closed captions file, “audio” for alternate audio files, among others). Specifying the roles of the data files is required. In previous revisions of this specification, the full asset did not require the “source” role to be specified, but it is now 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.
Film Profile: Previews
Previews for Russian films must be localized and follow the guidelines in the iTunes Store Movies Style Guide (Trailers and Clips). For more details, see Regional Requirements.
Film Profile: Poster Art
Specifying the <locale> for poster art is now supported and it is used to indicate the language in which the text on the poster art appears. In some cases, poster art could display more than one language, for example, poster art for Canada that shows both English and French (see the example below). At a date in the future, if you do not specify the locale, you will see a warning message that the <locale> tag is required.
Poster art displaying both English and French:
<asset type="artwork"> <territories> <territory>CA</territory </territories> <data_file> <locales> <locale name="en"/> <locale name="fr"/> </locales> <file_name>09736156444_CA.jpg</file_name <checksum type="md5">b433e43e7ddeddfe4b8a429df86cabb2</checksum> <size>6491589</size> </data_file></asset>Film Profile: Ratings
New ratings have been added for film. The ratings document is available in “Resources and Help” in iTunes Connect, but the changes are summarized in the table below.
Country/Region | Rating and Description |
|---|---|
Portugal |
|
Hungary |
|
Film Profile: Video Source Asset Clarification
When delivering the video source asset, the <locale> tag is required. The previous revision of this specification indicated that an audio track could be delivered as a separate component, however the video source cannot be delivered without embedded audio.
Film Profile: Timed Text
When specifying a <div> block, you can use the optional begin attribute to set an offset for all the timecodes expressed for the <p> tags within the <div> block. The format of the value used must be:
{+|-}HH:MM:SS:FF for non-drop timecodes (for example, begin="-01:00:00:00")
{+|-}HH:MM:SS;FF for drop frame timecodes (for example, begin="-01:00:00;00")
Use the negative (-) sign for negative offsets; the positive (+) sign is assumed and can be omitted from the timecode value. See the annotation for <div> in iTunes Timed Text Annotated.
Film Profile: Metadata-Based Cropping
A metadata example showing how to update crop dimensions has been added. See Crop Dimensions Update Example.
Film Profile: Corrections/Clarifications
The locale in the XML example showing how to remove German audio was changed from "en-US" to "de-DE".
Clarified the descriptions for full subtitles and forced subtitles. See Assets Delivered in a Multiple Language Package.
Film Profile: Element Changes
Changed
"source" value in the role attribute is now required on the full video asset
Film Profile: Audio Description (AD)
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. A new role for a data file on the full source has been added for Audio Description (AD). The AD file is an optional data file containing an alternative audio track. The AD file is delivered as a role for the full asset using role="audio.visually_impaired". The file must be in pre-mixed format and in stereo (no 5.1). See Assets and Data Files for more information.
If you deliver an AD file, you must specify the language using the <locale> tag (for example, <locale name="en-US/>) in the <data_file> block. See Basic Film Metadata Example for an example of how to provide AD in the metadata. Audio Descriptions will be supported on the sellable movie product at a later date, but you can start sending AD files for your content now to prepare for the time in the future when AD will be supported.
Film Profile: Ratings
Due to a legal clarification in Brazil, iTunes can now accept ratings and consumer advice labels that have been designated by our providers, as well as those issued by the Brazilian National Secretariat of Justice (NSJ). If you have withdrawn your content from Brazil because it has not been officially reviewed/rated, you can offer it again as long as you are comfortable designating the rating and consumer advice yourself. Note that you must comply with the "Practical Guide to Content Rating" issued by the NSJ (see Brazil for more information and a link to the guide) in designating your rating/advice.
In addition, note that if a film already has an official NSJ classification for Brazil, you cannot designate the rating and consumer advice yourself. The officially issued classification must be submitted to iTunes.
Film Profile: Cast and Crew
The <description> tag, if supplied for a cast member, requires the format attribute that identifies the format of the text delivered in the <description> tag. Currently, the format can be unformatted plain text ("plain"). The <description> tags in all examples and annotations have been updated to include the format attribute.
In the Multiple Languages chapter, the example and annotation for the <crew_member> tag included an <apple_id> tag for each locale. The Apple ID does not need to be supplied at the <locale> level and those tags have been removed.
Film Profile: Asset Updates Clarification
When you need to update or change assets for an existing product, you can simply send an asset-only update and deliver a new asset with the same locale; you do not need to remove the asset using the remove="true" attribute. See the first XML example in Film Asset-Only Update Example which shows that a German audio file is being replaced. Keep in mind that the use of the remove="true" attribute is intended only for removing audio files permanently, changing the locale of a previously delivered asset, and removing QC notes. Using remove="true" for any other purpose can result in unintended changes to the language bundling of the final product.
Film Profile: Video Source Asset Clarification
When delivering the video source asset, the <locale> tag is required.
Film Profile: Provider Clarification
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.
Film Profile: Tag Updating
The <studio_release_title> tag introduced in the previous revision of this specification has been added to the list of tags that can be updated. See Metadata and Asset Updates.
Film Profile: Element Changes
Added
role="audio.visually_impaired" as an attribute of <data_file> for the full asset
Film Profile: Studio Release Title
A new tag has been added to provide 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>. Beginning November 2014, if you deliver a package and do not include the <studio_release_title> tag, you will see a warning.
Read-Only Information
A new appendix describes read-only information that appears when you do a metadata lookup on an existing package. Read-only tags are shown in the returned metadata and are supplied by Apple to provide information about the package, such as the status of the content review and Apple IDs for cast and crew members, among others. See About Metadata Lookup for a description of metadata lookup and the read-only tags returned.
Multiple-Language Film Profile
A film package can now include more than one dialect for the audio and subtitle languages and the following paragraph has been removed as a restriction:
In a film package delivered to iTunes, only one dialect of the audio and subtitle languages is supported. If two or more dialects of the same language are included in the package, only one will be included in the product provided to the customer. For example, do not include both Castilian Spanish (es-ES) and Latin American Spanish (es-419) in the same package; Parisian French (fr-FR) and Canadian French (fr-CA) should also not be delivered in the same package.
Film Profile: Asset-Only Updates Clarification
When delivering updated source video, keep in mind that the duration of the source video must match the durations of related components (such as subtitles, forced subtitles, alternate audio, and so on). If the duration of the source video has changed, you must also deliver updates of any related components intended to track to the same timeline as the source video.
iTunes Connect Section Names
Changed the iTunes Connect module names throughout the specification to match the new section names (for example, “Deliver Your Content” has been changed to “Resources and Help.”
Film Profile: Element Changes
Added
<studio_release_title>
Film Profile: Cast and Crew
The structure for delivering cast and crew metadata has changed. New tags have been added for delivering more detail on the characters cast members play in the film, including the character name, character description, a note on the character type (protagonist, antagonist, and so on), and an image of the character.
New attributes for use with the Dub Artist role have been added. You can use the locale attribute to specify the language of the voiceover. You must also specify the character being dubbed using the character_reference attribute and the value specified in the <reference_id> tag (which is in 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. See the annotation for Dub Artist Crew in Multiple-Language Film Metadata Annotated for more information.
Film Profile: Closed Captions
Closed caption files can now be delivered in languages other than English. When you deliver a closed captions asset file, you must specify the language of the captions using the <locale> tag. For example, if a Canadian film is in French and you are supplying French closed captions, you need to specify the locale in the <data_file> block for the closed captions:
<data_file role="captions"> <file_name>09736156444-french.scc</file_name> <size>9511</size> <checksum type="md5">5a793a8b46037fe8aa2bdd739b49911a</checksum> <locale name="fr-CA"/> <attribute name="program.start.timecode">-01:00:00:00</attribute></data_file>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. If you deliver a package and do not include the locale for the captions, you will see a warning that the locale is missing and that English ("en") will be used by default.
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.
Film Profile: Timecode Offset
The timecode offset attribute ("program.start.timecode") used to keep closed captions in sync with the encoded film is now supported for both non-drop and drop frame timecodes.
Film Profile: Concert Films
Locale tags have been added to the concert film metadata example to show how to deliver localizations for the title, synopsis, and artist name.
Film Profile: Price Tiers
Short films must be identified as short with the <subtype> tag: <subtype>short</subtype>. This sets up the correct pricing. See Table 1: Wholesale Price Tiers for further information.
Film Profile: Asset-Only Updates
If you are delivering an asset-only update for the full asset, you can now update the chapter metadata with the asset; you can send the <chapters> block inside the <asset> block for the full source video in an asset-only update. See Film Asset-Only Update with Chapters for more information.
Film Profile: Element Changes
Added
<characters>
<character>
<character_name>
<character_note>
<character_image>
<description>
<reference_id>
character_reference as an attribute of <role>
locale as an attribute of <role>
Film Profile: Concert Films
Locale tags have been added to the concert films metadata example to show how to deliver localizations for the title, synopsis, and artist name.
Film Profile: Price Tiers
New price tiers for Japanese concert films have been added.
Film Profile: Schema Version
The version number of this specification has changed from 5.1 to 5.2 to keep the version number in sync with the new schema version. In addition, the <package> tag version attribute has been updated in all examples to 5.2:
<package xmlns="http://apple.com/itunes/importer/" version="film5.2">
Film Profile: Ratings
New legal requirements covering rating reasons have been added for films delivered to iTunes for distribution in South Africa, New Zealand, and Brazil. See South Africa, New Zealand, and Brazil for full details.
Film Profile: Closed Captioning Reason Codes
After March 31, 2014, the closed captioning reason codes "NEVER_IN_US" and "IN_US_NO_CAPTIONS" are no longer applicable. Deliveries sent with these codes will be blocked. The reason codes "NEVER_IN_US" and "IN_US_NO_CAPTIONS" have been removed from the examples and annotations.
New U.S. closed captioning reason codes have been released. For U.S. deliveries, when a video does not include closed captions, you must indicate the reason why they have not been included using the <accessibility_info> tag. The reason codes are:
"PROMOTIONAL_TV_CONTENT_PRE_JUNE_2015": Video used for promotional content only are exempt from the closed captioning mandate.
"NO_CC_SDH_FOREIGN_LANGUAGE_ENGLISH_SUBS": If closed captions do not exist and the original film is in a language other than English and the target audience is en-US, English subtitles may be used in place of closed captioning.
See Basic Film Metadata Example without Closed Captions for a metadata example with annotations.
Film Profile: Theatrical Release Date
The <theatrical_release_date> tag cannot be updated. This date specifies when 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 or digitally.
Film Package Summary Appendix
The “Film Package Summary” appendix has been removed from this spec. The content of the appendix repeated information that is in the iTunes Video and Audio Asset Guide.
Film Profile: Territory Exclusions
The <territory_exclusions> tag can be used to exclude assets from particular territories. For example, you can exclude French audio from your film offering from the Canadian Store if you do not have distribution rights in Canada, and leave the rest of your worldwide storefront offerings untouched. See About Territory Exclusions for more details and an example. See Multiple-Language Film Metadata Example for an XML example that includes the <territory_exclusions> tags.
Film Profile: Subtitles for the Deaf and Hard-of-Hearing
A new role for a data file on the full source has been added for Subtitles for the Deaf and Hard-of-Hearing (SDH). The SDH file is an optional data file containing subtitles that provide textual versions of the dialogue, as well as song lyrics and sound effects (owl hooting, scream in distance, crunch of footsteps in forest, for example). SDH subtitles are delivered as a role for the full asset using role="subtitles.hearing_impaired". The file must be in the iTT file format with the extension .itt. For a list of supported languages, see Multiple Language Support in the Apple Transactional Movies User Guide. The language of the SDH is specified using the <locale> tag (for example, <locale name="es-419"/>) in the <data_file> block. See Multiple-Language Film Metadata Example for an example of how to provide SDH in the metadata and see iTunes Timed Text Example for more information on the iTT file format.
Film Profile: Poster Image
You can add a new poster image if the poster art has not yet been delivered or if it is for a new territory. After a film has gone live on the Store, existing poster art may be updated, but these updates are subject to review by Apple and may not take effect immediately.
Film Profile: QC Notes
Notes to the Quality Control team can now be sent using a standalone tag instead of sending a PDF within an <asset> block. See Deliver QC Notes Using a Tag for an XML example.
Film Profile: Closed Captioning Reason Codes
Closed captioning reason code "EDITED_FOR_INTERNET" is no longer applicable. Deliveries sent with that code will be blocked. As of September 30, 2013, all content edited for Internet distribution must be captioned.
Film Profile: Product-Only Updates
After an initial import of the package, you can send a metadata update to add or modify territory rights and pricing. This update includes only the <products> block and the content identifier used in the initial import (for example, <vendor_id>) within the <video> block; you do not need to include other metadata tags or any assets. You can deliver only those territories you are adding or modifying; you do not need to deliver all territories. If you are removing a product from sale, you can set <cleared_for_sale> to false for the territory without any other pricing or sales tags for that territory. See Product-Only Update Example for an example.
Film Profile: Metadata Updates
Previous versions of this specification indicated that if the <assets> block was included in a metadata-only update without also providing the asset files, the delivery would be rejected. However, you can include the <assets> block with or without providing the asset files in a metadata-only update.
If asset files are provided and properly referenced in the metadata, then the corresponding checksums will be compared to the checksums of the assets currently on file, and if any checksums are different, the assets will be updated as necessary. If the checksums are unchanged, then the import package (.itmsp) does not need to contain the asset files, even if they are listed in the metadata, because those asset files will be ignored.
Film Profile: Element Changes
Added
<territory_exclusions>
role="subtitles.hearing_impaired" as an attribute of <data_file> for the full asset
role="audio" as an attribute for <territory_exclusions> on the source video
<comments> for delivering QC notes
Changed
<territory> can be used within a <territory_exclusions> block
<vendor_offer_code> can be updated
Film Profile: Closed Captioning Reason Codes
Closed captioning reason codes "ARCHIVAL_CONTENT" and "LIVE_OR_NEAR_LIVE_CONTENT" are no longer applicable. Deliveries sent with either code will be blocked.
The "EDITED_FOR_INTERNET" code will no longer be valid as of September 30, 2013. All content edited for Internet distribution must be captioned by this time.
Film Profile: Cue Sheets
Cue sheets provide a list of music played in a concert film, short film, or feature film. If a film contains music, cue sheets should be supplied (if available) for the film to be sold or rented outside of the United States. The multiple language film example in this spec is sold in three territories: United States, Brazil, and France. Because the film is sold outside the United States, cue sheets have been added to the example. See Multiple-Language Film Metadata Example.
Film Profile: EST/VOD End Dates
If you deliver end dates using the <sales_end_date> or <unavailable_for_vod_date> tags, the video will be removed from sale on the Store on that date. If providing an end date was not your intention, you can remove the date through the feed. 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/>
<unavailable_for_vod_date></unavailable_for_vod_date>
<unavailable_for_vod_date/>
Note that simply omitting the tag does not remove the end date; you must submit the tag without a value.
Important: Sending empty tags is only allowed for certain tags as noted in the annotated examples.
Film Profile: Interval Pricing
New validations have been added for interval pricing. Packages that do not adhere to the requirements will be blocked. See Interval Pricing for a list of the requirements. In addition to the validations, the <start_date> of the first interval within the <intervals> block is optional for the first interval. See Interval Pricing Metadata Annotations for more information.
Film Profile: Multiple Languages
When the chapter on multiple languages was reorganized and the examples consolidated in the 5.1 version of the spec, the metadata showing how to deliver multiple trailers and poster art was inadvertently removed. The multiple language example in this revision of the spec now includes the XML showing how to deliver multiple localized trailers and poster art (see Multiple-Language Film Metadata Example).
The following restriction has been removed: “When a forced subtitles file and a full subtitles file are delivered in the same language, the <body> element in the forced subtitles file must be an exact subset of the <body> element in the full subtitles file. To be an exact subset, every <p> element must have the same time codes, grammar, spelling, styling, spacing, etc as the corresponding <p> element in the full subtitles file.”
Film Profile: Minimum Storefront Requirements
To improve the quality of the content offered on the iTunes Store, certain territories must meet a set of minimum requirements for movies. These requirements apply to feature films only; concert films and short films are excluded. These minimum requirements apply to new deliveries only and older content is unaffected. To see which territories are affected and view the requirements, see Minimum Storefront Requirements.
A new section has been added to describe specific requirements for films sold in Russia. See Regional Requirements.
Film Profile: Ratings
When specifying the rating for a film, you must supply the Apple rating code, for example: <rating code="PG-13"/>. Currently, you can supply both the code and the rating label as follows: <rating code="PG-13">PG-13</rating>, however, supplying only the rating label (<rating>PG-13</rating>) is not allowed.
Film Profile: Genres
When specifying the genre for a film, you must supply the Apple genre code, for example: <genre code="DRAMA-00"/>. Currently, you can supply both the code and the genre label as follows: <genre code="DRAMA-00">Drama</genre>, however, supplying only the genre label (<genre>Drama</genre>) is not allowed.
Film Profile: Concert Films
Annotations for <production_company> and <theatrical_release_date> have been added for concert films.
Clarification: Requirements for Content Sold in India
The previous version of the spec indicated that the rules below applied only to films from India, but the rules apply to all films (regardless of where they are "from") that are sold in the iTunes Store in India.
For each film for sale inside of India, you must provide the authority (CBFC) Certificate with applicable ratings on the theatrical poster art available in India. The poster art could be the India-specific art or the Worldwide poster art. The certificate must be located on the bottom corner (preferably left) of the poster art and must not be smaller in size than that on the physical release. If there is no physical release, the certificate must be a size that is readable when zoomed.
Copyright information delivered using the <copyright_cline> tag in the metadata must use the following wording: “Statutory declaration under section 52A of the Copyright Act, 1957 (as amended): We, [name of copyright holder] located at [insert address] hereby declare that we are the owners of the copyright for distributing this cinematography film, having secured necessary consent and license from the producer of the film.”
See Regional Requirements for examples of copyright information.
Film Profile: Element Changes
Changed
<start_date> of the first interval within the <intervals> block is now optional
<cue_sheet> and <cue> element blocks can now be used for short films and feature films, in addition to concert films
Film Profile: Closed Captioning Availability
Closed caption availability information can now be delivered within the <assets> block, as an alternative to supplying the information within the <video> block. This allows the option of delivering closed-caption availability information in delivered an asset-only update. See Film Asset-Only Update Example for more information.
Film Profile: Crew Member Role
Added Composer as a crew member role. See the annotations for the <crew> block in Basic Film Metadata Annotated or in Multiple-Language Film Metadata Annotated.
Film Profile: Cast and Crew Reference
You can refer to a film’s cast and crew members by name (using the <display_name> tag) or by Apple ID (using the <apple_id> tag). iTunes assigns every cast and crew member a unique Apple ID; Apple recommends using the Apple ID 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 ID. If you do not know the cast or crew member's Apple ID, 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. Note that if you are supplying localizations for cast and 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.
Film Profile: Genres
All film genres now have a genre code. A new attribute named code can be used with the <genre> tag to supply the Apple genre code. Standardizing on the Apple genre codes reduces errors resulting from typos. Currently, if you have a typo in the label of the genre you send, the delivery will be accepted but the content will not be categorized by genre on the Store. If you have a typo when using the code, the package will fail and you can correct the code and re-deliver.
The code attribute is currently optional, however Apple recommends that you start supplying the codes to prepare for the time in the future when the codes become required and the current method deprecated. All of the following are currently supported for delivering genre information:
Preferred Method Using the Genre Code |
|
Previous Method Using the Genre Label |
|
Acceptable Method Using Both the Genre Code and the Genre Label |
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, |
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.
New genres have been added for newly supported countries/regions.
See Table 1: Film Genres and Table 2: Japanese Film Genres for a list of the codes.
Film Profile: Ratings
All film ratings now have a short, plain-ASCII Apple rating code. A new attribute named code can be used with the <rating> tag to supply the Apple rating code. Standardizing on the Apple rating codes reduces errors resulting from typos and removes the need to enter escape codes for certain ratings.
The code attribute is currently optional, however Apple recommends that you start supplying the codes to prepare for the time in the future when the codes become required and the current method deprecated. All of the following are currently supported for delivering rating information:
Preferred Method Using the Rating Code |
|
Previous Method Using the Rating Label |
|
Acceptable Method Using Both the Rating Code and the Rating Label |
If you use this method, the rating identified by code and the rating identified by rating label must resolve to the same rating, for example, |
In addition to the rating codes, iTunes has expanded worldwide, and as a result, new film ratings have been added for 58 new countries/regions. Because of the increased number of countries/regions, the ratings have been moved from this spec to a PDF titled “Film Rating Codes,” which can be downloaded from the Resources and Help section on iTunes Connect.
Film Profile: Multiple Language Film Profile
The German-specific XML examples and annotations, and film bundle information have been removed from this spec. See Multiple Language Support in the Apple Transactional Movies User Guide.
Film Profile: Languages
Several languages have been added that are supported for <language> and metadata level <locale> tags. See Language Codes for details.
Film Profile: Requirements for Content from India
The following rules apply to all films (regardless of where they are "from") that are sold in the iTunes Store in India.
For each film for sale inside of India, you must provide the authority (CBFC) Certificate with applicable ratings on the theatrical poster art available in India. The poster art could be the India-specific art or the Worldwide poster art. The certificate must be located on the bottom left corner of the art and have a width of 500 pixels.
Copyright information delivered using the <copyright_cline> tag in the metadata must use the following wording: “Statutory declaration under section 52A of the Copyright Act, 1957 (as amended): We, [name of copyright holder] located at [insert address] hereby declare that we are the owners of the copyright for distributing this cinematography film, having secured necessary consent and license from the producer of the film.”
The copyright information can be set under the <video> level or within a <region> block delivered specifically for India. For example:
<video> . . . <copyright_cline>Statutory declaration under section 52A of the Copyright Act, 1957 (as amended): We, [name of copyright holder] located at [insert address] hereby declare that we are the owners of the copyright for distributing this cinematography film, having secured necessary consent and license from the producer of the film.</copyright_cline> . . .Or,
. . . <region> <territory>IN</territory> <copyright_cline>Statutory declaration under section 52A of the Copyright Act, 1957 (as amended): We, [name of copyright holder] located at [insert address] hereby declare that we are the owners of the copyright for distributing this cinematography film, having secured necessary consent and license from the producer of the film.</copyright_cline> <theatrical_release_date>2013-06-04</theatrical_release_date> </region> . . .Corrections
Added the missing closing </description> tag in the example showing how to use CDATA.
Film Profile: Element Changes
Added
<apple_id> for use within the <cast_member> and <crew_member> tags
code as an attribute of the <genre> and <rating> tags
Changed
<accessibility_info> can be used within the <assets> block
Film Profile: Closed Captioning Availability
New U.S. closed captioning requirements have been released and video content may be subject to the rules as of September 30, 2012. To support these requirements, new tags have been added to indicate if a film includes closed captions. These tags are required for U.S. deliveries. If the content does not include closed captions, you must explain why they are not included. See Basic Film Metadata Example without Closed Captions.
Film Profile: Closed Captioning Start Timecode
Apple requires that timecodes start at a program start of 00:00:00:00, which may require that captions be offset if they have been mastered to tape timecode. To keep closed captions in sync on the encoded file, a new attribute for use with closed captions data files has been added to offset captions: "program.start.timecode". The value is a SMPTE HH:MM:SS:FF timecode in non-drop frame with an optional negative (-) sign for negative offsets. This feature is currently supported for non-drop frame timecodes.
Film Profile: Source Audio Replacement
A new audio data file for a film can be delivered without redelivering the video source. For example, a film with stereo audio can be updated to 5.1 by providing an audio-only update. The replacement audio file must have the same vendor ID and locale code as the full source video. See Source Audio Asset-Only Update Example for an example.
Film Profile: Crew Member Role
Added Co-Director as a crew member role. See the annotations for the <crew> block in Basic Film Metadata Annotated or in Multiple-Language Film Metadata Annotated.
Film Profile: Video Assets with Chinese 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. This requirement applies to the following tags:
<original_spoken_locale>
<data_file role="source"> in the <assets> block
<data_file role="audio"> in the <assets> block
Dub cards do not contain audio tracks, so the script portion of the locale value is allowed.
Film Profile: Ratings
Corrected the escape codes for the Sri Lanka “unrated” rating. See Table 1: Film Genres.
Film Profile: Validations
New validations have been added for interval pricing. Packages that do not adhere to the requirements will be blocked. See Interval Pricing for a list of the requirements.
In .itt files (iTunes Timed Text), only one <p> element can be displayed at a time. The time periods must not overlap. The begin time of a <p> element must not come before or be the same as the end of another. Metadata with overlapping <p> elements will be blocked.
Film Profile: Element Changes
Added
<accessibility_info>
<accessibility>
"program.start.timecode" for use in the <attribute> tag on a closed captions data file
Film Profile: Ratings
Removed the following ratings for Finland: K-3, K-11, K-13, and K-15. Added film ratings for 13 newly supported Asian countries/regions. In some cases, the rating value in the Ratings table is actually an image of the rating. For your convenience, the escape codes for those ratings are provided below the table. You can copy and paste the escape codes into the XML. See Overview in the “Film Ratings, Advisories, and Genres” section.
Film Profile: Timed Text Profile
Added a new frame rate for timecode formats. 24fps 1 1 frame rate is now accepted.
iTunes Store: Languages
A new section has been added to explain how languages display on the iTunes Store. See How Localized Content Displays in the Apple TV App.
Film Profile: Cast and Crew
To support localizations of cast and crew members, the XML structure for cast and crew has changed. You can now supply localizations for cast and crew members using <locale> tags. Four new tags have been added to support localization: <cast_member>, <crew_member>, <display_name>, and <character_name>. In addition, the <role> tag (previously used only for concert films) can be used within a <crew_member> tag.
Film Profile: Dub Card Video
Added a new role for a data file on the full source for dub card video. Dub card video is an optional data file containing one or more still credits specific to the locale-matched audio. 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 asset and the dubbing cards must match. See Multiple-Language Film Metadata Example for an example of how it is provided in the metadata.
Film Profile: Languages and Codes Best Practices
As a best practice when specifying a language, use the region subtag (for example, the US of en-US) only when it supplies useful information, such as spelling variations between countries; otherwise provide only the language subtag. For example, for Japanese, use <language>ja</language> instead of <language>ja-JP</language> because there is generally not a need to distinguish between Japanese as used in one country versus another. See Language Codes for more information.
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/.
The checkmarks in the “Supported for <language> and <locale>” column that had been incorrectly removed for Danish, Finnish, Norwegian, and Swedish have been added.
Added the following languages to the language code table: Arabic, Cantonese, Catalan, Chinese (Simplified), Chinese (Traditional), Croatian, Hebrew, Icelandic, Indonesian, Lao, Malay, Russian, Tagalog, Thai, Turkish, Ukrainian, and Vietnamese.
Film Profile: Poster Art
Poster art size must be at least 1400 x 2100 pixels with a 2:3 aspect ratio. See the iTunes Video and Audio Asset Guide for specifications.
Film Profile: Changed/Deprecated Tags
When a tag is deprecated or changed, providers must implement the change within a year. After a year, iTunes reserves the right to stop supporting the old version. XML deliveries that contain the old tags may fail delivery. Review Previous Spec Revisions for tags that have been changed or deprecated.
Multiple Language Film Profile
The XML example in the Multiple Language Film Profile chapter has been changed to reflect the new component delivery. iTunes accepts films with multiple language audio, subtitles, forced subtitles, and dub card video. The iTunes video processing workflow arranges the components into bundles—each bundle is a sellable product, which means that there could be multiple bundles produced for the same vendor ID. Each bundle is composed of various combinations of the assets included in the package and is similar to a physical product SKU.
Film Profile: Element Changes
Added
<locales><locale>
<cast_member>
<crew_member>
<roles><role> for use within the <crew_member> block
<character_name>
<display_name>
Changed
<name> (under <artist> used in concert films has changed to <artist_name>
Deprecated
<actor> (used in the <cast> block
<member> (used in the <crew> block
Film Profile: Corrections and Additions to Language Table
The checkmark in the “Supported for <language> and <locale>” column has been removed for Danish, Greek, Spanish for Mexico, Finnish, Norwegian, and Swedish. Added Korean (which is supported in the <language> and <locale> tags). Added languages for the following countries: Bulgaria, Cyprus, Czech Republic, Estonia, Hungary, Latvia, Lithuania, Malta, Poland, Romania, Slovakia, and Slovenia. See Language Codes.
Film Profile: Theatrical Release Date
The <theatrical_release_date> tag is required for film delivery. If a film was not released theatrically, use the date it was first released physically.
Film Profile: Chapter Updates
Added a new section to show examples of updating chapters. When updating or adding chapters or locales, all chapters must be sent, not just the chapter with the changes. See Chapter Update Examples.
Film Profile: Ratings
The rating Unrated has been removed from the UK ratings. See Overview in the “Film Ratings, Advisories, and Genres” section. Added the 18 rating for Ecuador.
Film Profile: Correction
A <territory> tag in the metadata example for interval pricing contained an incorrect value: <territory>UK</territory>. It has been changed to: <territory>GB</territory>. Corrected the example for the Musicals genre (changed Musical to Musicals).
Film Profile: HD Price Tiers
SD and HD films can now be priced at different price tiers using the new tag: <hd_wholesale_price_tier>. This tag can be used in the <product> block and the <interval> block. Use the existing <wholesale_price_tier> tag to price SD films and use the new <hd_wholesale_price_tier> tag to price HD films if you want separate pricing. Note that this tag is not available to all providers and countries/regions. Refer to your contract to see if you may send this tag.
Film Profile: Crew
A new role has been added to indicate the actor who performed the dubbing in a dubbed film. See the annotations for the <crew> block in Multiple-Language Film Metadata Annotated.
Film Profile: Language Codes
The language code for Brazilian Portuguese (pt-BR) is a supported value for the <language> and <locale> tags. Removed the code for US Spanish (es-US) and added the code for Mexican Spanish (es-MX).
Film Profile: Updates
The tag <production_company> can be updated through the feed. The following tags can be updated unless Apple has reviewed and confirmed the quality of the metadata: <title>, <synopsis>, <genre>, <cast>, and <crew>. When updating cast or crew members, you must send all cast and crew members in the metadata update, not just the ones being updated.
Film Profile: Ratings
Removed the 'Ikke vurderet' rating for Denmark.
Film Profile: Element Changes
Added
<hd_wholesale_price_tier>
Deprecated
<amg_video_id>
amg_artist_id (attribute of <member> tag)
Film Profile: Ratings
Added ratings for 32 more countries/regions. See Overview in the “Film Ratings, Advisories, and Genres” section.
Film Profile: Vendor Offer Code
A new optional tag has been added that can be reported back through sales reporting channels.
Film Profile: Cast and Crew
To be displayed on the iTunes Store, cast and crew members must be specified with billing="top".
Film Profile: Theatrical Release Date
The tag <theatrical_release_date> is now required.
Film Profile: Element Changes
Added
<vendor_offer_code>
Film Profile: Subtitles Delivery
Subtitles and forced subtitles can now be delivered within the iTunes Store package (itmsp). Subtitles and forced subtitles are delivered as a role for the full asset. The files must be in the iTT file format with the extension .itt.
For specifications on creating the iTT file format, see the new chapter in this spec: iTunes Timed Text Example. This chapter also includes XML examples of delivering subtitles and forced subtitles as separate files.
Film Profile: Poster Art and Preview Trailer
A trailer and poster art are required for a film to appear in the iTunes Store. Each must be delivered with <territory> set to WW. Other territories are optional.
Film Profile: Language Codes
Added the language code for Latin American Spanish (es-419).
Film Profile: Element Changes
Added
role="subtitles" as an attribute of <data_file> for the full asset
role="forced_subtitles" as an attribute of <data_file> for the full asset
Film Ratings
The Unrated film rating indicates that the film contains explicit content. When browsed by customers, films marked Unrated will be restricted by the iTunes Parental Control feature, so Apple suggests providing ratings when available. See Overview in the “Film Ratings, Advisories, and Genres” section for a complete explanation.
Film: Full Source
A new attribute on the full source specifies that the film is free of 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. The attribute is required for films that do not have any burned-in narrative text or burned-in subtitles. The tag is <attribute name="image.textless_master"> and allowed values are true or false.
Film: Poster Art
Poster art assets (<asset type="artwork">) can be updated through the feed.
Film: Interval Pricing Clarification
You are not required to use interval pricing. Use intervals only when you want the price to change automatically for specific time periods. When supplying intervals, you can leave out the <end_date> and the price will not change again; the interval does not end and remains in effect indefinitely.
Film Profile: Clarifications/Corrections
Clarified that if you omit the <available_for_vod_date> tag (in the <product> block) for a Video on Demand film, the film will be made available for rental immediately.
Corrected the timecode format that was shown incorrectly in the examples. The timecode 24/1 1/nonDrop has been changed to 24/999 1000/nonDrop.
Film Profile: Element Changes
Added
<attribute name="image.textless_master"> as an attribute of the full source asset
Film Genres
Added four genres for use in the Japanese Store only: Japanese Cinema, Jidaigeki, Tokusatsu, and Korean Cinema.
Film Profile: Takedowns
Clarified how to remove content from the Store. 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.
Film Ratings
Removed legacy and unsupported MPAA ratings from the ratings table and created a new table listing unsupported ratings.
Language Codes
Added two links to the appendix Language Codes that point to lists of language and country codes.
Film Profile: Crop Dimensions Clarification
Crop dimensions for video source are required. If the video’s source file is delivered matted (letterbox, pillarbox, or windowbox), specify the crop rectangle to crop the inactive pixels. If the source file is not delivered matted or if there are no inactive pixels, we recommend setting all the crop dimensions to 0 (zero).
Film Profile: Chaptering Start Time and Timecode Formats
The timecode format table in Timecode Formats has been replaced with a more accurate table. In the previous version of the specification, two of the <start_time> examples incorrectly used colons and semicolons to separate the seconds from the frames. Drop frame mode requires the use of the semicolon after the seconds, for example: 00:55:13;00. Non-drop frame mode uses a colon, for example: 00:55:09:20.
In addition, the W3C standard for expressing the framerate multiplier has changed: the colon (:) used to separate the framerate from the multiplier has been replaced by a space. For example, 999:1000 is now expressed as 999 1000. Apple recommends changing the timecode in the <timecode_format> tag so that it complies with the new standard, as in this example:
<timecode_format>24/999 1000/nonDrop</timecode_format>
instead of:
<timecode_format>24/999:1000/nonDrop</timecode_format>
The use of the colon will be deprecated in a future version of this spec.
Film Profile: Ratings
Ratings for feature and concert films are required. If the film is not rated, choose the appropriate rating for Unrated or Not Rated. For countries/regions that do not have an Unrated or Not Rated classification, you must choose another rating.
Film Profile: String Field Size Clarification
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.
Multiple Language Film Profile: Burned-in Subtitles and Narratives
If a film contains burned-in subtitles or burned-in narratives, the data file attribute "image.burned_subtitles.locale" is required for burned-in subtitles; the data file attribute "image.burned_forced_narrative.locale" is required for burned-narratives.
Film Ratings Table
Corrected Japanese ratings: changed PG-12 to PG12, R-15 to R15+, and R-18 to R18+. Changed the ratings system name for Quebec from frca-movies to ca-rcq. Removed the E (Exempt) rating from Canada and the Uc (Universal Children) rating from the UK. See Overview in the “Film Ratings, Advisories, and Genres” section.
Film Profile: Locales Corrections/Clarifications
The <locale> tag is required for assets (full source, preview source, and audio) and within a <locales> tag (if used). locale when used as an attribute for chapter titles is also required. The value used for locale is case-insensitive, even though the examples show the value in the format xx-XX, such as en-US.
Film Profile: Forced Narrative
Added a new attribute to identify videos with burned-in forced narrative (for example, text that describes the setting, such as—Cairo, 1910).
Film Ratings
Added ratings for more countries/regions; added “Unrated” ratings to all countries/regions where available. See Overview in the “Film Ratings, Advisories, and Genres” section.
Language Codes
Corrected the RFC 4646 language codes for Danish to da-DK, Greek to el-GR, and Swedish to sv-SE. See Language Codes.
Film Profile: Element Changes
Added
<attribute name="image.burned_forced_narrative.locale"> as an attribute of the source asset
Film Profile: Corrections/Clarifications
Made a correction to all of the annotations for <original_spoken_locale>; the tag is required, not optional. Added the <original_spoken_locale> tag to the examples where it was omitted.
In the section Film Metadata-Only New Delivery Package, the sentence that described how to replace QC notes incorrectly stated that the QC notes file could be redelivered with the same filename. The correct procedure is to first remove the existing QC notes file and then deliver it again.
Concert Films: Artist Roles
The roles accepted for artists in concert films include Composer, DJ, Featuring, Narrator, Performer, Producer, Remixer, Songwriter, and With. Artists with the roles listed have their own artist page.
Film Ratings
Added the film rating Tout Public for France. Tout Public indicates the film is suitable for all ages.
Film Profile: Interval Pricing
Interval pricing allows a film's wholesale pricing to automatically change during specific periods of time. This is especially useful for sales and other promotions that require temporary or permanent pricing changes on pre-determined dates. Interval pricing, if used, replaces the previous pricing model.
Film Profile: Locales
Ireland is now supported for use with Ireland-specific poster art and trailers. en-IE can now be used as a locale for trailers and IE can be used as a territory for poster art. Note that en-IE cannot be used in the <language> tag, or in the <locale> tag for the main video source, audio, title, synopsis, or chapter titles.
Film Profile: Poster Art
Poster art must not display any film ratings.
Film Profile: Corrections/Clarifications
The <package> tag annotations omitted the description of the xmlns attribute. It serves as a declaration that the elements in the XML are expected to conform to the schema associated with the specified namespace, which is http://apple.com/itunes/importer. An example showing how to update an alternate audio asset has been added (see Alternate Audio Asset-Only Update Example.
Made a correction to the annotation for <original_spoken_locale>.
Film Profile: Element Changes
Added
<intervals>
<interval>
Film Profile: Cleared for HD EST Sale
A new tag specifies whether a film in HD EST is cleared for sale in the territory for the product. Must be "true" or "false."
Film Profile: WW Territory Clarification
The <territory> tag can be specified in both the <assets> block and the <products> block, but the use of the WW territory needs to be clarified.
For artwork and trailer assets, it is recommended that each asset should have a WW territory, in addition to any territory-specific assets that are to be delivered. Using WW ensures that all territories will have the asset. For example, suppose a film is to be distributed in the US and Canada. If you specify only US as the territory for a trailer, and you don’t also specify WW, the Canada territory will not have the trailer. We encourage you to use WW for all assets, and only specify a territory-specific asset where needed. If you do not specify any territory, WW is the default territory.
When using the <territory> tag within the <products> block, do not use WW as a territory. The <product> block is where pricing is set. 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.
Film Profile: Corrections
In the Multiple Language XML annotations, Poster Image Territory was incorrectly marked as required. Using the territory tag for poster images is optional.
Changed the genre in the Concert Films example from Concert Film to Concert Films.
Assets: Quality Standards
Quality is important to us at iTunes. We expect to receive the highest-quality assets available.
Film Profile: Element Changes
Added
<cleared_for_hd_sale>
Film Profile: Chapters
For multiple-language films, the requirement for delivering chapter titles in English has been removed.
When sending chapters, we recommend that the chapters provided match what is on the DVD. In addition, include a chapter for film credits as the last chapter.
Film Profile: Clarifications
When specifying the version attribute of the package (<package xmlns="http://apple.com/itunes/importer" version="film4.1">), the “film” portion of the version attribute must be in lowercase letters.
When specifying crop dimensions, the values must be integers that represent the number of whole pixels. Do not use negative numbers, decimal numbers, or words, which will cause the import to fail.
Film Profile: Crew Member Roles
Co-Director has been removed as an option for crew member roles.
iTunes Store: Package Delivery
One or more QC (Quality Control) Notes can now be delivered within the iTunes Store package (itmsp). These Notes can inform the iTunes QC team about known issues or characteristics of a video (full and preview source). The iTunes QC team can read the notes as part of their review process to help identify whether or not some of the issues they see in the video source are known issues.
The notes must be in PDF format and multiple note files can be delivered.
Film Profile: Chapters
Each chapter must have an image and each chapter image must have a unique file name.
Film Profile: Clarifications
Added an XML example to show how to correct a locale on a delivered source video. Clarified that a library title is a feature length film that is not a new release. Role names for artists and crew members (for example, Director or Producer) must be in English to be imported correctly into the iTunes Store. Clarified package naming conventions.
Film Profile: Element Changes
Added
role="notes" as an attribute of <data_file>
Film Profile: Metadata Updates
The <subtype> tag can now be updated through metadata updates.
Film Profile: Genres
Film genres have been updated. The Music genre has been replaced by Musicals, Concert Films, Music Documentaries, and Music Feature Film.
Film Profile: Metadata Updates
The <theatrical_release_date> tag can now be updated through metadata updates.
Film Profile: Clarifications
The <vendor_id> must not start with an underscore character. Images must be at least 72 dpi. Chapter titles have a 255-byte limit.
If a crew member has more than one role in a film, each role must be listed in its own <member> tag.
iTunes Store Package: Updates to Assets and Data Files
Referencing all the assets in the <asset> block for an update is no longer required. If an asset is not referenced in the <asset> block, the asset will not be removed. Instead, assets can now be removed using remove="true" as an attribute of the <data_file> tag:
<data_file role="source" remove="true">
Film Profile: Cleared for HD VOD
A new tag specifies whether a film in HD is cleared for Video On Demand in the territory for the product. Must be "true" or "false."
Film Profile: Element Changes
Added
remove="true" as an attribute of <data_file>
<cleared_for_hd_vod>
iTunes Store Package: Assets and Data Files
Added audio as data file that can be imported. Added a locale tag to full source and preview source assets to specify the language of the audio on the source.
iTunes Store Package: Inline Chaptering
Added ability to deliver chaptering information within the primary metadata file (referred to as “inline chaptering”). Separate delivery in a chapter.xml file is no longer required.
Film Profile: Multiple-Language Films
Multiple assets and languages are now supported for film. A new metadata example is included to showcase these changes. Added a new attribute to identify videos with burned-in subtitles. Added a tag to specify the language spoken by the actors in a film. Added a tag to specify the phonetic title for Japanese films to aid in searching. Changed the German rating for “ohne Altersbeschränkung” to “ab 0 Jahren.” Territory-specific assets are now supported, for example, a trailer for Germany, a trailer for France, and so on.
Film Profile: Element Changes
Added
<regions><region>
<locales><locale>
<phonetic_title> for Japanese films
<original_spoken_locale> for multiple-language films
<attribute name="image.burned_subtitles.locale"> as an attribute of the source asset
<chapters><chapter> now used within the <video> tag (as opposed to a separate file referenced from within the <assets> block)
Changed
<start_timecode> is now optional for cue sheets
<isrc> is now optional for cue sheets
Deprecated
chapter.xml
iTunes Store Package: Package
The <package> element has changed to include the namespace in preparation for schema validation.
iTunes Store Package: Vendor Identifiers
Vendor identifiers can only contain alphanumeric characters and underscores ("_"). Packages delivered with identifiers containing other characters will be rejected.
Film Profile: Metadata-only & Asset-only Deliveries
Complete examples of Metadata-only and Asset-only deliveries are now provided.
Film Profile: Metadata-only & Asset-only Updates
Ratings can now be updated through the feed, but not removed. For a complete list of fields that can be updated through the feed, refer to the section Metadata and Asset Updates.
Film Profile: Concert Films
Concert films can now be delivered using additions outlined in the Concert Films Overview section.
Film Profile: Element Changes
Changed (new tag = old tag)
<package xmlns="http://apple.com/itunes/importer" version="film3.2"> = <package version="film3.2">
Film Profile: Available for Video on Demand Date
Video on demand (VOD) sale date can now be specified to indicate when the film will be available for rent in the iTunes Store to customers in the specified territory. This element is required for new releases.
Film Profile: Cleared for Video on Demand Sale
Availability for VOD sale can now be specified at the territory level. The film will not be available for rent unless this property is explicitly set to “true.” This tag is required for VOD.
Film Profile: Metadata-Based Cropping
Captures no longer need be delivered in a cropped format, but can instead be delivered in their full-frame state with metadata included to specify the crop rectangle. The delivered package is automatically cropped.
Film Profile: Physical Release Date
Physical release date is used to indicate when the film’s first physical product (i.e., VHS, Beta, laserdisc, and DVD) was released for customers to purchase. This element is required for new releases.
Film Profile: Poster Art
Poster art metadata structure is now simplified and resembles other asset declarations.
Film Profile: Theatrical Release Date
Theatrical release date can now be optionally specified for film.
Film Profile: Unavailable for Video on Demand Date
Unavailable for VOD sale can be specified to indicate when the film is no longer available for rent in the iTunes Store to customers in the specified territory.
Film Profile: Video on Demand Type
VOD type is used to specify the film is a new release or is a library title. Provide this value as specified by your contract. This tag is required for all VOD.
Film Profile: Element Changes
Added
<attribute name=””>
<available_for_vod_date>
<cleared_for_vod>
<physical_release_date>
<theatrical_release_date>
<unavailable_for_vod_date>
<vod_type>
Changed (new tag = old tag)
<asset type="artwork"> = <artwork_files>
iTunes Store Package: Empty XML Elements
Empty XML elements are no longer accepted in metadata. If not used, the elements should be removed; otherwise, unintended results may occur, such as not providing a rating, but including an empty rating tag may cause the film to be marked unrated when browsed by customers. Also unrated content may be restricted by the iTunes Parental Control feature.
iTunes Store Package: World Territory
The “world” territory, used to define clearances for every territory in which an active contract is present, has changed to be in line with ISO standards and can be specified using “ww” only.
Film Profile: Element Changes
Deprecated
short is no longer an accepted value for the <type> element
Changed (new tag = old tag)
<title> and <picture> are now required elements for chaptering
system is now a required attribute for the rating element
<sales_start_date> is now a required element
<vendor_id> is now a required element