This document specifies the iTunes Package format for delivering music content to Apple.
An iTunes Package is a directory that contains the data necessary to describe a product: individual audio files, album artwork, and the metadata describing how to put it all together. Each package represents a single audio or music video product within Apple Music and the iTunes Store.
For questions regarding other kinds of content, such as television or film, contact your Apple Technical Representative.
Changes Made in This Release
Date/Version
Changes Made
October 2023 - Version 5.3.19
Updated the list of categories that can be specified for album and track flags. Added information on removing immersive audio source assets. Additional updates and clarifications.
Audio, video, and image files must be provided in very specific sizes and formats. For complete details and all requirements, see the iTunes Video and Audio Asset Guide.
Package Format
All delivered metadata and asset files must be delivered in the iTunes package format.
An iTunes Package is a directory named vendor_identifier.itmsp containing:
an XML file named metadata.xml that describes the delivered content using the structure documented in this specification
digitally encoded source materials (music, videos, digital booklets, and so on), up to a maximum of 500 tracks per album
associated image files
For example, a package for a two-track single with a UPC of 0011223311223 would be sent in a package named "0011223311223.itmsp" and contain the following files:
metadata.xml
0011223311223_01.wav
0011223311223_02.wav
0011223311223_cover.jpg
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 may only contain alphanumeric characters and the underscore mark ("_"); they may not contain spaces, other punctuation or symbols, and must not start with an underscore. The vendor identifier is case-sensitive. Packages delivered with identifiers containing other characters will be rejected.
Note: For music videos, the artwork is a screen capture from the video itself. The screen capture can be sent as a separate asset file or it can be cut from a frame in the video using an XML attribute. Apple strongly recommends that you submit a frame cut directly from the video. See Music Video Single Metadata Example for an example of how to use the attribute.
Schema Versioning
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.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, for this revision of the spec, 5.3 is the schema version and 5.3.1 is the specification revision (so the attribute value is 5.3, not 5.3.1):
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.
Metadata Details
Character Encoding
All metadata files must use UTF-8 Unicode character encoding. UTF-8 efficiently encodes non-Roman characters and helps to ensure that metadata displayed on Apple Music and the iTunes Store is the same as was intended by the repertoire owner. 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.
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 on Apple Music and the iTunes Store.
Checksums
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.
XML Formatting
There should be no null data or empty tags in the XML (except where specifically mentioned in the annotations). 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 iTunes Schema Validation Guide for more information.
Sidecar metadata Refers to the accompanying mapping metadata XML file for Dolby® Vision or HDR asset metadata for HDR10
Overview
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.4”. (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.
Video Source Delivery Requirements
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 Music Video HDR Source Profile in the 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 secondary 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 HDR Dolby® Vision Metadata Example and HDR10 Metadata Example.
The SDR and HDR source videos must have the same start points, and have the same number of black frames.
The HDR source can contain audio, however it will be ignored. The audio from the SDR source will be used for bundling.
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 secondary 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 secondary video must be the same as the primary video.
For Dolby® Vision video source, this secondary 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 Dolby® Vision video source, the secondary video file can be removed at any time using the remove="true" attribute, but you must also remove the corresponding mapping.xml file, unless you plan to update the secondary video using the same mapping.xml file.
For HDR10 video source, this secondary 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 secondary video source.
For HDR10 video source, the secondary video file can be removed at any time using the remove="true" attribute. The sidecar metadata attributes are also removed with the secondary video file.
Note: Currently, you will not see any HDR validation errors. If you see any HDR warning messages, you can ignore them until that feature is available at a later date.
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.
How Localized Content Displays on Apple Music and the iTunes Store
In general, users can configure their OS 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, Apple Music and the iTunes Store have a default language configured for each storefront, based on the country or region of that storefront. Each storefront also has a list of additional languages it supports. For example, the US store has English as its default language, but also supports Spanish. A user who signs into the US iTunes Store with their OS language set to English will see the store's UI in English; a user who signs into the US iTunes Store with their OS language set to Spanish will see the store's UI in Spanish. Whichever language is chosen to display the store's UI for a given user is called the user's storefront language.
When content such as an album or song title is displayed, Apple first looks to see if the title of the album 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 an album 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/Country/Region
Default Language
Other Supported Language
Brazil
Portuguese
Brunei
English
Cambodia
English
Canada
English
French
France
French
Germany
German
Hong Kong
English
Traditional Chinese
India
English
Indonesia
English
Indonesian
Japan
Japanese
English
Korea
Korean
Laos
English
Macau
English
Traditional Chinese
Malaysia
English
Malay
Mexico
Spanish
Philippines
English
Russia
Russian
Singapore
English
Simplified Chinese
Sri Lanka
English
Taiwan
English
Traditional Chinese
Thailand
English
Thai
United Kingdom
English
United States
English
Spanish
Vietnam
English
Vietnamese
Music Profile
Overview
The Music profile is used for the delivery of all types of Music content, including albums, singles, mixed media albums, and video singles.
Each package represents a single downloadable album or single on Apple Music or the iTunes Store. It is not possible to combine content from different packages or to deliver source assets in segments.
For questions regarding this document, contact your Apple Technical Representative.
Basic Music Album Metadata Example
The basic music album is used to deliver all audio: singles, EPs, single albums, and multi-volume albums.
For the sake of brevity, only three audio tracks are shown. Album metadata may contain any number of <track> sections, one per audio track.
In the example below, the first track includes delivery of immersive audio using the track <assets> block to deliver both stereo audio and 7.1 audio. The second track also delivers immersive audio, but the Dolby Atmos audio will be down-mixed to stereo, so a stereo audio file is not included in the track <assets> block. The third track uses the standard <audio_file> block to deliver the audio.
The xmlns (for XML namespace) attribute is required and is needed for schema validation. It is used to declare the namespace (and associated schema) to which the tags in the XML are expected to conform. The namespace must be:
http://apple.com/itunes/importer
The version attribute is required. Packages created to this specification must indicate version="music5.3". The “music” portion of the attribute must be in lowercase letters.
<language>en</language>
Language (required)
The primary language of the metadata for this package. Fields such as title are expected to appear in this language.
As a best practice when specifying a language, use the region subtag (for example, the US of en-US) only when it conveys helpful information, such as spelling variations between countries or regions. See Language Codes for more information. For information on how languages are displayed, see How Localized Content Displays on Apple Music and the iTunes Store.
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 (http://tools.ietf.org/html/rfc5646), which is part of BCP 47. An overview of these best practices is provided here: http://www.w3.org/International/articles/language-tags/.
Provider Metadata Fields
<provider>OneIndependent</provider>
Provider (required, Apple-supplied)
This value should be the Apple-defined provider name used for partner identification. The value must match the provider shortname used in Transporter (the value that is after -s in the Transporter command). Note that it is the value you pass as an argument to Transporter, not the value in the XML, that determines the account you are delivering to. Contact your Apple Technical Representative for this value.
Album Metadata Fields
<album>
Album (required)
Begins the <album> block.
<vendor_id>5099749642829</vendor_id>
Album Vendor ID (optional; cannot be updated)
Uniquely identifies the album for sales that will be reported back through the Financial Report. 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. Although a vendor identifier may contain digits, it is treated as a string, not numbers, which means a vendor identifier of '00000000012345' is not the same as '12345'. Vendor identifiers have a limit of 100 bytes.
Apple recommends using the UPC of your album as the vendor ID.
Albums delivered with identifiers containing other characters will be rejected.
<upc>5099749642829</upc>
Album UPC (required; cannot be updated)
Identifier for the album. This may be UPC (Universal Product Code), EAN (European Article Number) or JAN (Japanese Article Number). UPC is 12-digit code mainly used for US market. Both the EAN and JAN have 13 digits. All of these identifiers require a check digit, generated mathematically from the rest of the number for consistency checking purposes.
These identifiers are usually printed on the barcode of music CDs.
<grid>A10302B0000114391R</grid>
Album GRid (optional; can be updated if not previously provided)
The GRid (Global Release Identifier) for the album. GRids must be unique across all products (the combined set of both albums, tracks, and videos). If your company doesn’t use this identifier, you should remove this tag.
Important: The GRid must not be more than 18 alphanumeric characters. The GRid cannot contain dashes, spaces, underscores, other punctuation, or symbols.
Vendor Offer Code (optional, 1-100 bytes, see restrictions; can be updated)
An additional identifier for the album that can be used for provider-specific purposes.
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'.
<title>Medúlla</title>
Album Title (required; can be updated, but may require a ticket; see Content Update Behavior)
The title of the album in the primary language of the package (see <language> above); in this example, the primary language is English. If the album’s native language is not an ISO Latin-1 or Latin-2 language (for example, Japanese or Greek), refer to the Multiple Language Support chapter for further details on how to supply album title data.
If an album has a title version, use the <title_version> tag (see the annotation below).
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for album titles. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
<title_version>Remastered</title_version>
Album Title Version (optional; can be updated, but may require a ticket; see Content Update Behavior)
The version title of the album in the primary language of the package (see <language> above); in this example, the primary language is English. The <title_version> tag is used to distinguish different versions of the same album by the same artist (for example, "Live from San Francisco", "Remastered"). If not specified, remove the tag from the metadata. If the album’s native language is not an ISO Latin-1 or Latin-2 language (for example, Japanese or Greek), refer to the Multiple Language Support chapter for further details on how to supply album title version.
Note that when imported, Apple takes the information in the tag and appends it to the album title in parentheses for display. If you later do a metadata lookup, the <title_version> tag will not be returned in the metadata; instead you will see the value in the title version tag appended to the album title, for example: <title>Medúlla (Remastered)</title>.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for album titles. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
To remove an existing title version, send an empty tag: <title_version/> or <title_version></title_version>.
Original Album Release Date (required; can be updated)
The original date of the first consumer-available physical album release (LP, cassette, 8-track, CD, or other physical media). This is not the digital release date, unless this album has not previously been released on any format. This is the field presented to the user in the Apple Music and the iTunes Store interface.
This field is cosmetic only and does not impact "available date" or "street date" on Apple Music or the iTunes Store.
For albums that are re-releases (for example, re-mastered, or releases on new media types such as CD, digital, and so on), do not use the date of re-release.
This field must be in YYYY-MM-DD format. If the <original_release_date> is more than 90 days later than the earliest <sales_start_date>, the package will be rejected.
<label_name>One Independent</label_name>
Album Label Name (required; can be updated)
The name of the label that released the album.
<genres>
<genre code="ALTERNATIVE-00"/>
<genre code="WORLD-00"/>
</genres>
Album Genres (required; can be updated, but may require a ticket; see Content Update Behavior)
Genres to associate with the album. Apple recommends defining at least one, but no more than two genres.
All music genres have an Apple genre code, which is supplied using the attribute named code used with the <genre> tag. The code attribute is required. The following are currently supported for delivering genre information:
Required method using the genre code:
<genre code="ELECTRONIC-01"/>
Acceptable method using both the genre code and the genre label:
<genre code="ELECTRONIC-01">Electronic</genre>
If you use this method, the genre identified by code and the genre identified by genre label must resolve to the same genre, for example, <genre code="POLKA-00">Ragtime</genre> would be rejected.
For a complete list of genres, click Resources and Help on iTunes Connect to download the spreadsheet titled “Music, Music Video, and Ringtone Genre Codes.”
Important: Genre information may be reassigned at the discretion of Apple.
<flags>
<flag>DJ Mix</flag>
<flag>Remix</flag>
<flag>Compilation</flag>
<flag>Live</flag>
</flags>
Album Flags (optional; can be updated, but may require a ticket; see Content Update Behavior)
Album flags specify categories that are used to place album content appropriately on artist pages.
The <flags> block is optional. If you omit the <flags> block, there is no change to any existing flags.
You can add or change flags when updating content, but updates must include all flags, not just the ones being updated.
To remove all flags, deliver an empty tag: <flags/>
You can use the following flags for album categories:
Compilation
DJ Mix
Karaoke
Live
Remix
Self Titled
Soundtrack
Note: If you use the DJ Mix flag for a track, you must also use the DJ Mix flag for the album.
<copyright_pline>2004 One Independent</copyright_pline>
Album Copyright P-Line (optional; can be updated)
Performance copyright line for the album. Must follow the format YYYY copyright info as in the example. Do not add the ℗ symbol or “p”; it will be added automatically. Some CDs don't have this P-line printed. Remove this tag if this is the case.
<copyright_cline>2004 One Independent</copyright_cline>
Album artwork is required, and you must provide the <file_name>, <size>, and <checksum>. The artwork file should have a recommended minimum resolution of 3000 by 3000 pixels. See iTunes Video and Audio Asset Guide for complete file requirements.
Important: If providing a metadata-only update, the <artwork_files> block should be omitted.
The <assets> block specifies the assets being delivered.
The <type>value must match the profile of the album motion art being delivered:
"motion_art_3:4"
"motion_art_1:1"
The <data_file> block specifies the source video for the album motion art. The role must be "source". See iTunes Video and Audio Asset Guide for complete file requirements.
In this block, the <file_name>, <size>, and <checksum> tags are required.
<track_count>3</track_count>
Album Track Count (optional)
Defines the total number of tracks within the album. Although it is optional, it provides a way to communicate the completeness of an album. If specified, the <track_count> is compared to the total number of tracks received and the associated album is automatically marked complete at time of import (pending Apple approval).
Note: An album can include up to a maximum of 500 tracks.
Album Products Metadata Fields
<products>
<product>
Product (required; can be updated)
For each territory in which an album is to be sold there must be a defined product.
Important: Omitting this tag indicates you would like the album available in all territories where you have an active contract. The clearances below will be added automatically for you:
If you have a contract in a single territory, a clearance will be added for this contracted territory only.
If you have a contract for more than one territory, world clearances will be added. This means that in the future if more contracts are signed, this product will appear in all new territories.
If you leave out the <products> block for tracks (including videos and booklets) on initial import, those tracks will inherit the product information from the album playlist level. When delivering an update, this rule does not apply.
<territory>GB</territory>
Album Territory (required; can be updated)
The territory in which this album is cleared for sale. Must be specified as an ISO 3166-1 alpha 2 country/region code. If an album is cleared for every country/region, use WW as the country/region code. Some countries or regions in the ISO 3166-1 alpha 2 country/region list contain other countries/regions (for example, United States includes Puerto Rico), and WW contains all territories.
The wholesale price tier for the album. Must be a wholesale price tier number as specified in your contract with Apple.
See 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 Apple Technical Representative for more details.
Important: Omitting this tag will prevent this album from being offered for sale as a complete album and will instead be available only as individual tracks.
<sales_start_date>2019-10-22</sales_start_date>
Sales Start Date (optional; can be updated)
The date that this album is made available for sale to customers in the specified territory only. This is also known as the "street date" of the album and is written in the format YYYY-MM-DD. The <sales_start_date> should be the same as or later than the <original_release_date> (except for exclusive pre-release content).
In this example, "2019-10-22" is the sales start date and the album was made available for sale starting October 22, 2019.
Important: Omitting this tag on an initial upload will make the album available for sale immediately after normal quality assurance processing.
<cleared_for_sale>true</cleared_for_sale>
Cleared for Sale (optional; can be updated)
Specifies whether the album is cleared for sale in the territory for the product. Must be true or false. If not specified, the default is true.
Whenever possible, use the WW (world) territory so that the fewest number of territories need to be included in the delivered metadata.
Because the product for the most specific territory is used, this can be used as an exclusion mechanism for a regional clearance. For example, if you have rights for the world except for the UK (GB), then you would have two products: one for the world with <cleared_for_sale> set to true, and one for the UK with <cleared_for_sale> set to false. The resulting album will be sold everywhere that you have a current contract with the exception of the UK.
As a further example, to indicate album clearance for world less France and US, add only three album products: one for world with <cleared_for_sale> set to true, and one each for France and US with <cleared_for_sale> set to false.
<cleared_for_stream>true</cleared_for_stream>
Album Cleared for Streaming (optional; can be updated)
Indicates if the album can be streamed on demand. Allowed values are true and false.
Set the value to true if you have the rights to distribute the album for streaming; set the value to false to if you do not have the rights to streaming. (If you have rights to stream individual tracks, see the annotation below for track-level <cleared_for_stream>.)
Tip: If you have the rights to stream most tracks on an album, you could use <cleared_for_stream> at the album <product> level set to true, and use <cleared_for_stream> at the track <product> level set to false for each track that cannot be streamed.
In some cases, a provider might only have streaming rights; in that situation, <cleared_for_sale> would be set to false and <cleared_for_stream> set to true.
If you omit the tag, the previously delivered value remains the same. If you have never delivered the tag, the default value is null for streaming. The result is false if the content is not available for sale and true if the content is available for sale.
<stream_start_date>2019-10-22</stream_start_date>
Album Stream Start Date (optional; can be updated)
Indicates the date that the album should be available for streaming. The date must be in the format YYYY-MM-DD. If you do not specify a date, the content is made available for streaming immediately after normal quality assurance processing.
The specified date applies to all tracks on the album. If a specific track should be released for streaming on a date different from that of the album release, use the <stream_start_date> tag at the track level.
</product>
</products>
<artists>
<artist>
<artist_name>Björk</artist_name>
<apple_id>295015</apple_id>
<isni>0000000110013823</isni>
<roles>
<role>Performer</role>
</roles>
<primary>true</primary>
</artist>
<artist>
<apple_id>458966378</apple_id>
<roles>
<role>Producer</role>
</roles>
<primary>false</primary>
</artist>
<artist>
<artist_name>Ewan Pearson</artist_name>
<apple_id>3868597</apple_id>
<isni>0000000076925553</isni>
<roles>
<role>Producer</role>
</roles>
<primary>false</primary>
</artist>
</artists>
Album Artists (required; can be updated, but may require a ticket; see Content Update Behavior)
Name, Apple ID, or International Standard Name Identifier (ISNI), plus primary status and roles for each artist. In this context, "artist" may be any contributor including non-performing persons (for example, producer), groups (for example, a band name), 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"), 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 an album). Note that you should always include composition-related contributor information to the extent you have it.
Artist
You can refer to the artist by Apple ID using the <apple_id> tag, by name using the <artist_name> tag, or by the ISNI using the <isni> tag.
Apple assigns every artist a unique Apple ID; Apple recommends that performing artists be delivered with the Apple ID to avoid the ambiguity in cases where artists share the same name as other music artists, or film actors or crew members. You can supply the <apple_id>, the <artist_name>, or both the <apple_id> and <artist_name>. If you supply both tags, the <artist_name> tag is ignored in favor of the Apple ID.
If you do not know the artist's Apple ID, you can do an artist lookup and look for the <apple_id> tag. See Use Lookup Artist Mode in the Transporter User Guide.
To create an artist, generate the artist and Apple ID using the artist feed. See Creating a New Artist. For subsequent updates, use the <apple_id> tag instead of or in addition to the name, to avoid ambiguity.
For single-byte characters (such as those drawn from the ASCII character set), an artist name is limited to 256 characters. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
ISNI
Use the <isni> tag to provide the ISNI for the artist delivered in this <artist> block. The ISNI is a 16-digit alphanumeric value. (The last character is a check character, either a decimal digit or an X to represent the number 10 as a single character.)
The ISNI provides a persistent, unique identifying number to the public name of a contributor to a creative work. The ISNI helps resolve the problem of name ambiguity so that every published work can be unambiguously attributed to its creator.
When you use the <isni> tag, you must also deliver the <artist_name> tag. The <artist_name> tag is optional when you deliver the <apple_id> tag instead.
Role
Use the <role> tag to define the part that a particular artist performs on an album or track. Some roles are required (as shown in the list below) and other roles are optional (the chapter Recommended Contributor Roles lists all the roles recognized by Apple Music and the iTunes Store.)
Performer: always required for albums and tracks.
Songwriter (or Composer): always required for albums and tracks. Note that songwriter and composer are often used to refer to the same contributor; you can specify either songwriter or composer to refer to an artist, but at least one of those roles is required.
Featuring (or With): required if there is a featured artist on the album or track. Adding the artist with the Featuring or With role ensures that the album will show up on the featured artist’s page.
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: <role>Composer</role>, <role>Lyricist</role>, or <role>Songwriter</role>. You can add as many songwriters/composers as needed for the track. Failure to add full and accurate songwriter metadata in a timely manner may delay payment of royalties to publishers and songwriters.
Primary Status
Primary status indicates whether or not the album appears on the artist’s page on Apple Music and the iTunes Store. 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.
Only primary artists are presently displayed with the album. Artist names will appear in the order in which they are specified in the provided metadata.
Note: You can use the <language> tag under <artist> on the album to indicate the language in which the artist’s name appears. If you omit the <language> tag under <artist>, the <artist_name> is assumed to be in the language of the package (the <language> tag under <package>). Using <language> under <artist> is optional and would only be used in specific circumstances, for example, when a Japanese artist appears on a track on an English album.
Track Metadata Fields
<tracks>
Tracks (required)
Begins the <tracks> block.
<track>
Track (required)
Begins the <track> block.
<vendor_id>GBBFT0501345_9083</vendor_id>
Track Vendor Identifier (optional; cannot be updated)
Uniquely identifies the track for sales that will be reported back through the Financial Report. 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. Although a vendor identifier may contain digits, it is treated as a string, not numbers, which means a vendor identifier of '00000000012345' is not the same as '12345'. Vendor identifiers have a limit of 100 bytes.
Note: Apple recommends relying on GRid and/or ISRC for identifying tracks and omitting the <vendor_id> tag except in cases where an ISRC for a track is not unique on an album.
<isrc>GBBFT0501345</isrc>
Track ISRC (required; cannot be updated)
The ISRC (International Standard Recording Code) for the track. ISRCs must be unique across all recordings. It is normal for an ISRC to appear on Apple Music or the iTunes Store more than once if the same recording is included in more than one album (for example, "greatest hits" albums tend to feature songs from other albums). In this case, the two tracks must have exactly the same audio. A re-recorded, remixed or otherwise different (no matter how similar) track must have a unique ISRC.
Important: ISRCs must not include dashes and should contain only letters and numbers as in the example, GBBFT0501345.
<iswc>T1235996341</iswc>
Track ISWC (optional; can be updated)
The ISWC (International Standard Work Code) for the track. The ISWC is a unique identifier for a particular piece, which helps distinguish a song from other songs with similar or identical titles. The <iswc> tag can be used more than once on the same album, for example a piece could appear twice on an album: one track performed with vocals and another track could be instrumental only. This tag is currently optional; at some point in the future, you may see a warning if the tag is not delivered.
ISWCs begin with the letter “T”, followed by a nine-digit unique number (from 000000001 to 999999999), and an additional check digit at the end. The letter “T” is currently the only prefix element defined and indicates a musical work.
Important: ISWC identifiers are commonly written in the form T-123.456.789-1 with punctuation to help with readability. For the <iswc> tag, the value delivered must not include dashes or punctuation marks and should contain only letters and numbers as in the example, T1235996341.
<grid>A10302B00002427998</grid>
Track GRid (optional; can be updated if not previously provided)
The GRid (Global Release Identifier) for the track. GRids must be unique across all products (the combined set of both albums, tracks, and videos). If your company doesn’t use this identifier, you should remove this tag.
Important: The GRid must not be more than 18 alphanumeric characters. The GRid cannot contain dashes, spaces, underscores, other punctuation, or symbols.
Vendor Offer Code (optional, 1-100 bytes, see restrictions; can be updated)
An additional identifier for the track that can be used for provider-specific tracking purposes.
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'.
<title>The Pleasure Is All Mine</title>
Track Title (required; can be updated, but may require a ticket; see Content Update Behavior)
The title of the track. This tag should be used for titles based on ISO Latin-1 and Latin-2 language (for example, English, French). For details on other languages including double-byte languages (for example, Japanese, Chinese), refer to Multiple Language Support.
If the song track features one or more artists, you can add the artist name(s) as follows: <title>If I Get Locked Up (feat. Eminem & Dr. Dre)</title>. This way the song track will show up in the results when a customer searches for the artist.
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.
Important: If you use parentheses in the title field, the title version field will not appear on Apple Music or the iTunes Store.
<title_version>Dub Remix</title_version>
Track Title Version (optional; can be updated, but may require a ticket; see Content Update Behavior)
The version title of the track. Generally used to distinguish different versions of the same song by the same artist (for example, "Live from San Francisco", "Pump You Up Remix"). If not specified, it is left empty. This tag should be used for title versions based on ISO Latin-1 and Latin-2 language (for example, English, French). For details on other languages including double-byte languages (for example, Japanese, Chinese), refer to Multiple Language Support.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for track title versions. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
To remove an existing title version, send an empty tag: <title_version/> or <title_version></title_version>.
Important: As parentheses will automatically added to the title version, do not supply them when using this field.
Track Original Release Date (optional; can be updated)
The original date of the first consumer-available physical release of the track (LP, cassette, 8-track, CD, or other physical media). This is not the digital release date, unless this track has not previously been released on any format.
This field is cosmetic only and does not impact "available date" or "street date" on Apple Music or the iTunes Store.
For tracks that are re-releases (for example, re-mastered, or releases on new media types such as CD, digital, and so on), do not use the date of re-release.
This field must be in YYYY-MM-DD format. If the <original_release_date> is more than 90 days later than the earliest <sales_start_date>, the package will be rejected.
<gapless_play>true</gapless_play>
Track Gapless Play (optional; can be updated)
Used to specify whether or not there is a gap in the audio separating the track delivered with <gapless_play>true</gapless_play> from the next track on the album. In normal playback, Apple Music and iTunes always play songs without a gap, regardless of the value sent with the tag. The <gapless_play> tag applies if the user has turned on the cross-fade feature in Preferences. When cross-fade is turned on, Apple cross-fades each track with the following track, except for those tracks marked <gapless_play>true</gapless_play>. In other words, when <gapless_play> is set to true, the song will play to completion and then immediately and seamlessly continue playing to the next song with no overlap, even if cross-fade is enabled. This allows the cross-fade feature to preserve the artistic intent of songs that are meant to play back with no audible gap or overlap between tracks.
Accepted values are true or false.
<label_name>One Independent</label_name>
Track Label Name (optional; can be updated)
The name of the label which released the album. If not specified, the <label_name> from the album is used.
<publishers>
<publisher>Kobalt Music Publishing</publisher>
<publisher>Universal Music Publishing</publisher>
</publishers>
Track Publisher (optional; can be updated)
Indicates who controls the underlying work. You can add as many publishers as needed for the piece using a <publisher> tag within the <publishers> block. The publisher name provided with a <publisher> tag is limited to 256 bytes. Within the <publisher> tag, you deliver only one publisher name; individual publishers should be listed separately and not grouped together in one <publisher> tag. This tag is currently optional; at some point in the future, you may see a warning if the tag is not delivered.
<genres>
<genre code="ELECTRONIC-00"/>
<genre code="WORLD-00"/>
</genres>
Track Genres (required; can be updated, but may require a ticket; see Content Update Behavior)
Genres to associate with the track.
All music genres have an Apple genre code, which is supplied using the attribute named code.The code attribute is required. The following are currently supported for delivering genre information:
Required method using the genre code:
<genre code="ELECTRONIC-01"/>
Acceptable method using both the genre code and the genre label:
<genre code="ELECTRONIC-01">Electronic</genre>
If you use this method, the genre identified by code and the genre identified by genre label must resolve to the same genre, for example, <genre code="POLKA-00">Ragtime</genre> would be rejected.
For a complete list of genres, click Resources and Help on iTunes Connect to download the spreadsheet titled “Music, Music Video, and Ringtone Genre Codes.”
Important: Genre information may be reassigned at the discretion of Apple.
<flags>
<flag>Remix</flag>
</flags>
Track Flags (optional; can be updated, but may require a ticket; see Content Update Behavior)
Track flags specify categories used to place track content appropriately on artist pages.
The <flags> block is optional. If you omit the <flags> block, there is no change to any existing flags.
You can add or change flags when updating content, but updates must include all flags, not just the ones being updated.
To remove all flags, deliver an empty tag: <flags/>
You can use the following flags for track categories:
Cover
DJ Mix
Instrumental
Live
Original Recording
Remix
Rerecording
Self Titled
Soundtrack
Tribute
Note: If you use the DJ Mix flag for a track, you must also use the DJ Mix flag for the album.
<products>
<product>
<territory>GB</territory>
<cleared_for_sale>true</cleared_for_sale>
Track Products (optional; can be updated)
For each territory in which a track is to be sold there must be a defined product.
Because the product for the most specific territory is used, this can be used as an exclusion mechanism for a regional clearance. For example, if you have rights for the world except for the UK (GB), then you would have two products: one for the world with <cleared_for_sale> set to true, and one for the UK with <cleared_for_sale> set to false. The resulting track will be sold everywhere that you have a current contract with the exception of the UK.
Note: If you leave out the <products> block for tracks (including videos and booklets) on initial import, those tracks will inherit the product information from the album playlist level. See the annotation for the <products> tag for the album, above.
<wholesale_price_tier>98</wholesale_price_tier>
Track Wholesale Price Tier (optional; can be updated)
The wholesale price tier for the track. Must be a valid track-level wholesale price tier number as specified in your contract with Apple.
See Wholesale Price Tiers for a list of available price tiers. Review your contract to verify the tiers available to you for tracks. If an invalid price tier is provided, Apple reserves the right to reject the package or to use default pricing. Contact your Apple Technical Representative for more details.
Immersive Track Available Date (optional; can be updated)
Indicates the date that the immersive track should be available in the specified territory. The date must be in the format YYYY-MM-DD. If you do not specify a date, the immersive track will be available when the stereo audio goes live for the specified territory (or immediately if the track’s stereo audio is already live). Note that the date delivered in the <available_for_immersive_date> tag must not be before the date delivered in the <stream_start_date> tag; otherwise the immersive track will not go live until the stream start date.
Use this tag on an immersive track if you want the track to be released on a date different from that of the album release or the stereo track’s pre-order release date, if available.
To remove the tag, deliver <available_for_immersive_date/>. Keep the following in mind when updating or removing the tag:
You cannot update (or remove) a track’s available for immersive date if the immersive audio track is already live in the specified territory.
You can remove a track’s available for immersive date if you remove the immersive audio on a track without replacing it.
You can update the <available_for_immersive_date> on the track as long as the date is not in the past, and the existing date has not already passed.
</product>
<product>
<territory>IE</territory>
<cleared_for_sale>true</cleared_for_sale>
<cleared_for_stream>true</cleared_for_stream>
Track Cleared for Streaming (optional; can be updated)
Indicates if the track can be streamed on demand. Allowed values are true and false. In this example, the album for Ireland as a whole is not cleared for streaming, but this track can be streamed in Ireland.
Set the value to true to if you have the rights to distribute the track for streaming.
Set the value to false to if you do not have the rights to streaming.
Tip: If you have the rights to stream an entire album except for one track, you could use <cleared_for_stream> at the album <product> level set to true, and use <cleared_for_stream> at the track <product> level set to false for the track that cannot be streamed.
If you omit the tag, the previously delivered value remains the same. If you have never delivered the tag, the default value is null for streaming. The result is false if the content is not available for sale and true if the content is available for sale.
<stream_start_date>2019-10-22</stream_start_date>
Track Stream Start Date (optional; can be updated)
Indicates the date that the track should be available for streaming. The date must be in the format YYYY-MM-DD. If you do not specify a date, the content is made available for streaming immediately after normal quality assurance processing.
If the album is set to stream on a certain date, a specific track can be released for streaming on a date different from that of the album release using this tag, if necessary.
<cleared_for_fitness>false</cleared_for_fitness>
Track Cleared for Fitness+ (optional; can be updated)
Indicates if the track is available on Fitness+. Allowed values are true and false.
Set the value to false if the track is cleared for streaming on Apple Music and you want to block the track from being available on Fitness+.
Notes:
You must have a fitness music contract in place for your content to be available on Fitness+.
If you omit the tag in an update, the previously delivered value remains the same.
If you’ve never delivered the tag, the default value is null. This means the track will not be available on Fitness+ if it is not available for Apple Music/streaming and the track will be available on Fitness+ if it is available for Apple Music/streaming.
If you set the value to true, the track will be available on Fitness+, even if it is not cleared for Apple Music/streaming.
</product>
</products>
<copyright_pline>2004 One Independent</copyright_pline>
Track Copyright P-Line (optional; can be updated)
Performance copyright line for the track. Must follow the format YYYY copyright info as in the example. Do not add the ℗ symbol or “p”; it will be added automatically. Some CDs don't seem to have this P-line printed. Remove this tag if this is the case.
Important: If not specified, the copyright line from the album is used.
Denotes whether or not a track contains explicit content. May be clean, explicit, or none. If omitted, none (that is, a track for which neither a clean or explicit version exists) is assumed.
Important: A track must only be marked clean if it is an edited version of the original explicit form of the track.
Use <lyrics_set> to deliver lyrics in more than one language. Within the <lyrics_set> block, use one <lyrics_file> tag block for each language. The locale attribute specifies the language of the lyrics file you are delivering and must match the locale in xml:lang in the TTML file of the song.
The lyrics are delivered as a TTML file (.ttml). The song lyrics file is a TTML document using a restricted dialect of TTML and includes some extensions used for Apple-specific properties. To learn how to create the lyrics file in TTML format, see the TTML File Format chapter in the iTunes Video and Audio Asset Guide.
Note for Script Languages: If the locale language you are specifying has a script component, such as Chinese, you must include that information in the locale attribute value to inform users if the script is in simplified or traditional characters. When sending lyrics in Chinese, the locale for Mandarin lyrics in simplified characters must be zh-Hans, not the language code without script information (zh). For traditional characters, it must be zh-Hant. For Cantonese, it must be yue-Hant.
Note:To supply a single lyrics in a file without delivering additional locales, see the annotations for lyrics in Music Video Single Metadata Annotations. If you do not supply the song lyrics in a file, you can use the <lyrics> tag to deliver the lyrics in plain text. See Mixed Media Album Metadata Example.
<volume_number>1</volume_number>
Track Volume Number (optional)
The volume number (that is, disc number) on which the track resides. If specified, it must be a positive integer. If omitted, the track is assumed to be on volume one.
<track_number>1</track_number>
Track Number (required)
The track number, used to order tracks within a volume within an album. Must be a positive integer. The combination of volume number and track number must be unique across all tracks in an album.
Immersive Track 1: Stereo Audio Source Asset (required; may be updated; see Content Update Behavior)
The data file block specifies the audio file for stereo and describes the role of the associated file. In this example delivery of the first track, the file sent is used as the stereo source, so the role must be "audio.2_0". On initial delivery, audio.2_0 is required unless you are downmixing a immersive audio to stereo (see the annotation for the Immersive Track 2).
In this <data_file> block, the <file_name>, <size>, and <checksum> tags are required. Refer to the annotations for <audio_file> below.
Notes:
2.0 stereo is required for each track. You can specify that you want Apple to downmix to stereo from Dolby Atmos, 7.1, or 5.1 audio. This allows you to deliver a single audio file and derive the stereo audio from that file.
For each track, you can deliver only one stereo audio and one immersive audio. For example, you can’t deliver both 5.1 and 7.1 for the same track.
File formats accepted for audio.2_0: .wav, .flac, or .m4a
Only "full" type assets are accepted and only <data_file> tags are allowed within the <asset> block. Delivery will fail if you indicate "type="preview".
Immersive Track 1: Surround Audio Source Asset (optional; may be updated; see Content Update Behavior)
The data file block specifies the audio file for surround audio and describes the role of the associated file. In this example, the file sent is used as the 7.1 source, so the role must be "audio.7_1". For 5.1 source, the role must be "audio.5_1".
In this <data_file> block, the <file_name>, <size>, and <checksum> tags are required. Refer to the annotations for <audio_file> below.
File format accepted for immersive audio.7_1 and audio.5_1:
The ISRC (International Standard Recording Code) for the track’s immersive audio recording. ISRC is used to reflect a specific recording and the immersive audio is considered a new recording. If used, you can supply the ISRC using the attribute "external_identifier.isrc" on the data file for the immersive audio.
ISRCs must be unique across all recordings. A re-recorded, remixed or otherwise different (no matter how similar) track must have a unique ISRC.
Important: ISRCs must not include dashes and should contain only letters and numbers as in the example, GCGHY12345678.
If you want to use an ISRC that is already assigned to another non-immersive track, you can remove that ISRC by sending an empty tag for the track: <isrc/> or <isrc></isrc>. In the same metadata delivery, you can assign the ISRC to the immersive track.
Immersive Track 2: Dolby Atmos Audio Source Asset (optional; may be updated; see Content Update Behavior)
The data file block specifies the audio file for Dolby Atmos audio and describes the role of the associated file: "audio.object.based". In this example delivery of the second track, the Dolby Atmos file will be down-mixed to stereo. In this case, delivering a data file for audio.2_0 is not required. When down-mixing, you must include the attribute audio.transform_to_2.0. See the next annotation for details.
In this <data_file> block, the <file_name>, <size>, and <checksum> tags are required. Refer to the annotations for <audio_file> below.
File format accepted for the Dolby Atmos master file:
.wav file.
Must be provided as a BWF ADM file.
All audio tracks must be 24-bit LPCM audio at 48kHz.
Note: Apple recommends that all tracks should be at same frame rate (Dolby recommends 24).
Immersive Track 2: Downmix to Stereo (optional; may be updated; see Content Update Behavior)
In this example, the Dolby Atmos audio file will be down-mixed to 2.0 stereo. This is specified using the <attribute name="audio.transform_to_2.0"> tag set to true.
Notes:
You can downmix to 2.0 stereo from 5.1 audio, 7.1 audio, or Dolby Atmos.
When you downmix to 2.0, you do not need to deliver a data file with the role audio.2_0.
You cannot remove the attribute to down mix if you do not replace it with stereo audio.
The name of the audio track file. The name should be relative to the package (it should not contain a path reference, such as "C:\" or "/Macintosh HD/") and it must include the file name extension (".m4a" in this example).
File formats accepted for audio.2_0: .wav, .flac, .caf, and .m4a
Important: Filenames are case-sensitive.
<size>99253792</size>
Track Audio Asset File Size (required)
Size in bytes of the provided audio asset file for the track.
The MD5 checksum of the data file. See Checksums for more information.
</audio_file>
End of Track Audio Delivery Options
Remaining Track Tags
<audio_language>en</audio_language>
Track Audio Language (required; can be updated)
Use the <audio_language> tag to specify the language of audio. If there are no words spoken in an audio file, you can use the code zxx (which represents “no linguistic content”).
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 (http://tools.ietf.org/html/rfc5646), which is part of BCP 47. An overview of these best practices is provided here: http://www.w3.org/International/articles/language-tags/.
Note: The language specified in the <audio_language> tag must not contain script information. For example, the language for Mandarin audio must be cmn, not zh-Hant or zh-Hans; the language for Cantonese audio must be yue, not yue-Hant. If a track is sung in Chinese, but you do not know if it is Mandarin or Cantonese, you can send zh as the audio language, but you will get a warning when you deliver the metadata. This tag can be updated, so you could change zh to yue once you know if it is Cantonese.
<preview_start_index>30</preview_start_index>
Track Preview Start (optional; can be updated)
Allows providers to specify a custom start time for the preview audio. The <preview_start_index> tag should be specified in seconds from track start.
Important: If not specified, the default is 45 seconds for content over 75 seconds in length and 0 seconds for shorter content.
<artists>
<artist>
<artist_name>Björk</artist_name>
<apple_id>295015</apple_id>
<isni>0000000110013823</isni>
<roles>
<role>Performer</role>
</roles>
<primary>true</primary>
</artist>
<artist>
<artist_name>Björk</artist_name>
<apple_id>295015</apple_id>
<isni>0000000110013823</isni>
<roles>
<role>Lead vocals</role>
</roles>
<primary>true</primary>
</artist>
<artist>
<artist_name>Tagaq</artist_name>
<apple_id>39294810</apple_id>
<roles>
<role>Inuit throat singing</role>
</roles>
<primary>true</primary>
</artist>
<artist>
<artist_name>Mike Patton</artist_name>
<apple_id>2987396</apple_id>
<roles>
<role>Background vocals</role>
</roles>
<primary>true</primary>
</artist>
<artist>
<artist_name>The Icelandic Choir</artist_name>
<apple_id>21160509</apple_id>
<roles>
<role>Choral vocals</role>
</roles>
<primary>true</primary>
</artist>
<artist>
<artist_name>Björk</artist_name>
<apple_id>295015</apple_id>
<isni>0000000110013823</isni>
<roles>
<role>Composer</role>
</roles>
<primary>true</primary>
</artist>
<artist>
<apple_id>458966378</apple_id>
<roles>
<role>Producer</role>
</roles>
<primary>false</primary>
</artist>
</artists>
Track Artists (required; can be updated, but may require a ticket; see Content Update Behavior)
Name, Apple ID, or International Standard Name Identifier (ISNI), plus primary status and roles for each artist. In this context, "artist" may be any contributor including non-performing persons (for example, producer), groups (for example, a band name), 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"), 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 an album). Note that you should always include composition-related contributor information to the extent you have it.
You can refer to the artist by Apple ID using the <apple_id> tag, by name using the <artist_name> tag, or by the ISNI using the <isni> tag.
Apple assigns every artist a unique Apple ID; Apple recommends that performing artists be delivered with the Apple ID to avoid the ambiguity in cases where artists share the same name as other music artists, or film actors or crew members. You can supply the <apple_id>, the <artist_name>, or both the <apple_id> and <artist_name>. If you supply both tags, the <artist_name> tag is ignored in favor of the Apple ID.
If you do not know the artist's Apple ID, you can do an artist lookup and look for the <apple_id> tag. See Use Lookup Artist Mode in the Transporter User Guide.
To create an artist, generate the artist and Apple ID using the artist feed. See Creating a New Artist. For subsequent updates, use the <apple_id> tag instead of or in addition to the name, to avoid ambiguity.
For single-byte characters (such as those drawn from the ASCII character set), an artist name is limited to 256 characters. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
ISNI
Use the <isni> tag to provide the ISNI for the artist delivered in this <artist> block. The ISNI is a 16-digit alphanumeric value. (The last character is a check character, either a decimal digit or an X to represent the number 10 as a single character.)
The ISNI provides a persistent, unique identifying number to the public name of a contributor to a creative work. The ISNI helps resolve the problem of name ambiguity so that every published work can be unambiguously attributed to its creator.
When you use the <isni> tag, you must also deliver the <artist_name> tag. The <artist_name> tag is optional when you deliver the <apple_id> tag instead.
Important: If the ISNI you supply is not the correct ISNI for the <apple_id> or the <artist_name> you supply, the delivery fails.
Role
Use the <role> tag to define the part that a particular artist performs on an album or track. Some roles are required (as shown in the list below) and other roles are optional (the chapter Recommended Contributor Roles lists all the roles recognized by Apple Music and the iTunes Store.)
Performer: always required for albums and tracks.
Songwriter (or Composer): always required for albums and tracks. Note that songwriter and composer are often used to refer to the same contributor; you can specify either songwriter or composer to refer to an artist, but at least one of those roles is required.
Featuring (or With): required if there is a featured artist on the album or track. Adding the artist with the Featuring or With role ensures that the album will show up on the featured artist’s page.
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: <role>Composer</role>, <role>Lyricist</role>, or <role>Songwriter</role>. You can add as many songwriters/composers as needed for the track. Failure to add full and accurate songwriter metadata in a timely manner may delay payment of royalties to publishers and songwriters.
Primary Status
Primary status indicates whether or not the artist appears on the album’s track listing on Apple Music and the iTunes Store. Typically, there are one or two primary artists and several supporting artists on each track. Primary status is reserved for the primary (lead) artists. Do not tag supporting artists or contributors as primary. Artist names will appear in the order in which they are specified in the provided metadata. Note that each track must include at least one artist with the <primary> status set to true.
Note: You can use the <language> tag under <artist> on a track to indicate the language in which the artist’s name appears. If you omit the <language> tag under <artist>, the <artist_name> is assumed to be in the language of the package (the <language> tag under <package>). Using <language> under <artist> is optional and would only be used in specific circumstances, for example, when a Japanese artist appears on a track on an English album.
Defines chapters within a given track. If used, then <chapter_start_time> and <chapter_title> are required. <artwork_file> (art shown at the beginning of each chapter that conforms to the Apple art specification) is optional, but if used, <file_name>, <size>, and <checksum> are required. Each chapter image must have a unique filename.
Chapter start time is in HH:MM:SS.MMM format (hour, minute, second, millisecond) and end time is inferred from the start time of the next defined chapter, or the track’s end time.
There is no limit to the total number of tracks specified, but generally tracks should follow the physical product chapter or track structure (if available). Chaptering is on the track-level and each track is entirely independent; therefore, in an album, one track may have chapters while others do not.
There is a 255-byte limit strictly enforced for chapter titles. 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.
</tracks>
</album>
</package>
Music Album Metadata-Only Update
When a package is delivered, it is processed in the following manner:
The update is compared to existing products and a match is found based on a combination of Vendor ID and UPC.
If no match is found, the incoming package is imported as new.
If a match is found, it is compared to the update and the differences that may be changed at the album-level are then applied.
For each song or video in the update, matches are found based on a combination of Vendor ID and ISRC.
If no matching song or video is found, and the album is complete, then no changes are made. If the album is not complete, then the new track or video is added to the album.
If a match is found, it is compared to the update and the differences that may be changed are applied to the existing song or video.
Important: Any changes should be considered "effective immediately" and cannot be made at a guaranteed date or time. Updates are usually applied within hours and should appear on Apple Music or the iTunes Store within 24-48 hours of delivery.
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.
For complete details on what can be updated, see Content Updates.
Music Album Metadata-Only Update Example
In the following example, only metadata changes are made (in bold) and all asset references have been removed. Asset files are also not provided in the package delivered to Apple.
After an initial import of the package, you can send a metadata update to add or modify territory rights and pricing at the <album>, <track>, <booklet>, and <video> levels. 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 the <products> block for both the <album> and <track> levels and both the album and track content identifiers (for example, <vendor_id>) used when the album was first delivered. You do not need to include the <assets> block or any other tags in the <metadata> block.
To remove content from Apple Music or the iTunes Store, 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.
The following metadata examples show how to update a previously delivered immersive audio and how to replace immersive audio with a new audio file.
Keep the following in mind when updating:
If you are replacing a track audio of the same type (for example, replacing 5.1 with 5.1), you do not need to remove the existing audio file using the remove="true" attribute.
If you are replacing a track audio of one type with another type (for example, replacing 5.1 with 7.1), you must remove the existing audio file using the remove="true" attribute.
You can only remove immersive audio if it is not yet live in any territory (controlled by the <available_for_immersive_date> tag) and if the track includes the stereo source after removing the immersive audio.
You cannot remove immersive audio if it has the downmix attribute set to true.
If you remove the downmix attribute and do not deliver a stereo audio source, delivery will fail.
If you update immersive audio to allow downmix to stereo and you do not remove the stereo source audio file, delivery will fail. You must explicitly remove the stereo source using the remove="true" attribute.
Update a Previously-Delivered Immersive Audio
In this example, the stereo audio is being removed and the downmix attribute is being added to the existing 7.1 immersive audio. If you omit an audio source when sending an update delivery, it will not be removed.
The package delivered would consist of the metadata file update; redelivering the 7.1 audio source is not required.
<package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>en</language> <provider>OneIndependent</provider> <album> <tracks> <track> <!-- NOTE: Some tags not related to delivering immersive audio have been omitted in this track example (as indicated by the three dots) for brevity and focus; see the Basic Metadata Example for information on sending other tags. Do not omit this data from your package. --> . . . <assets> <asset type="full"> <data_file role="audio.2_0" remove="true"> <file_name>pleasure.wav</file_name> <size>26556655</size> <checksum type="md5">6ddabb680edae6bf2ec84ffcfa730fda</checksum> </data_file> <data_file role="audio.7_1"> <file_name>pleasure.mov</file_name> <size>82554355</size> <checksum type="md5">e6bf2ecfa730fda84ffc6ddabb680eda</checksum> <attribute name="audio.transform_to.2_0">true</attribute> </data_file> </asset> </assets> </track> </tracks> </album> </package>
Remove Stereo Source Asset
As shown in the following example, the data file block must be included if you are removing an asset. For the audio data file being removed, set the attribute remove to "true".
In the following example, the 7.1 audio file will be downmixed to 2.0 stereo. This is specified using the <attribute name="audio.transform_to_2.0"> tag set to true.
Notes:
You can downmix to 2.0 stereo from 5.1 audio, 7.1 audio, or audio.object_based.
When you downmix to 2.0, you do not need to deliver a data file with the role audio.2_0.
The following metadata example shows how to remove a previously-delivered immersive audio asset using the remove="true" attribute on the <data_file> tag.
<package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>en</language> <provider>OneIndependent</provider> <album> <tracks> <track> <!-- NOTE: Some tags not related to delivering immersive audio have been omitted in this track example (as indicated by the three dots) for brevity and focus; see the Basic Metadata Example for information on sending other tags. Do not omit this data from your package. --> . . . <assets> <asset type="full"> <data_file role="audio.5_1" remove="true"> <file_name>pleasure.wav</file_name> <size>46086448</size> <checksum type="md5">bbe014ee2a2d74cf3a5327be226dde93</checksum> </data_file> </asset> </assets> </track> </tracks> </album> </package>
Remove and Replace Immersive Audio Example
The following metadata example shows how to replace an immersive audio with a new audio file. You must remove the previously delivered immersive audio. In this example, the 5.1 immersive audio is being replaced. The package would include the metadata file and the new 5.1 audio file. When updating immersive audio, you do not need to redeliver the audio.2_0 file.
<package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>en</language> <provider>OneIndependent</provider> <album> <tracks> <track> <!-- NOTE: Some tags not related to delivering immersive audio have been omitted in this track example (as indicated by the three dots) for brevity and focus; see the Basic Metadata Example for information on sending other tags. Do not omit this data from your package. --> . . . <assets> <asset type="full"> <data_file role="audio.5_1" remove="true"> <file_name>pleasure.wav</file_name> <size>47886448</size> <checksum type="md5">bbe014ee2a2d74cf3a5327be226dde93</checksum> </data_file> <data_file role="audio.5_1"> <file_name>replacement_pleasure.mov</file_name> <size>82554355</size> <checksum type="md5">444444ee2a2d74e226dde93cf3a5327b</checksum> </data_file> </asset> </assets> </track> </tracks> </album> </package>
Takedowns
Takedowns allow you to remove content from sale for any or all territories in one update without knowledge of track lineup, track ISRCs, or other track-level information. Takedowns are especially useful with older catalogue titles, or when the track-level information has changed in label copy systems after initial delivery.
Metadata is exactly the same as a metadata-only update (without asset data files), except that all of the track-level metadata is omitted, and <cleared_for_sale> is set to “false” for any territories in which the album is to be taken down.
May be for one or more territories.
Only apply to the specified territory. For example, if both “WW” and “CA” are specified on an album and “WW” is taken down, the album will be removed from sale in WW; however, it will remain live in Canada.
Takedown Metadata Example
For the sake of brevity, only two territories are shown.
The music video single is used for delivery of one video for individual sale. For albums with multiple videos or containing both video and audio, see Mixed Media Album.
The subtags of <video> are the same regardless of whether the <video> tag appears within the <tracks> block of a mixed media album or directly within the <package> tag of a video single package.
Component Metadata Fields
<?xml version="1.0" encoding="UTF-8"?>
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 metadata.xml file must not contain a byte-order mark (BOM).
The xmlns (for XML namespace) attribute is required and is needed for schema validation. It is used to declare the namespace (and associated schema) to which the tags in the XML are expected to conform. The namespace must be:
http://apple.com/itunes/importer
The version attribute is required. Packages created to this specification must indicate version="music5.3". The “music” portion of the attribute must be in lowercase letters.
<language>en</language>
Language (required)
The primary language of the metadata for this package. Fields (such as titles) are expected to appear in this language.
As a best practice when specifying a language, use the region subtag (for example, the US of en-US) only when it conveys helpful information, such as spelling variations between countries or regions. See Language Codes for more information. For information on how languages are displayed, see How Localized Content Displays on Apple Music and the iTunes Store.
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 (http://tools.ietf.org/html/rfc5646), which is part of BCP 47. An overview of these best practices is provided here: http://www.w3.org/International/articles/language-tags/.
Provider Metadata Fields
<provider>OneIndependent</provider>
Provider (required, Apple-supplied)
This value should be the Apple-defined provider name used for partner identification. The value must match the provider shortname used in Transporter (the value that is after -s in the Transporter command). Note that it is the value you pass as an argument to Transporter, not the value in the XML, that determines the account you are delivering to. Contact your Apple Technical Representative for this value.
Video Metadata Fields
<video>
Music Video (required)
For each package that contains video content, the video content must be defined within this tag. For mixed media albums or video albums, this is at the <tracks> level. In the case of a music video single, there is no album, and so the <video> tag is used by itself without <tracks>.
<vendor_id>GB5170300040</vendor_id>
Music Video Vendor ID (optional; cannot be updated)
Uniquely identifies the music video for sales that will be reported back through the Financial Report. 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. Although a vendor identifier may contain digits, it is treated as a string, not numbers, which means a vendor identifier of '00000000012345' is not the same as '12345'. Vendor identifiers have a limit of 100 bytes.
Apple recommends using the corresponding video ISRC as the vendor ID.
<grid>A10302B00002427998</grid>
Music Video GRid (optional; can be updated if not previously provided)
The GRid (Global Release Identifier) for the music video. GRids must be unique across all products (the combined set of both albums, tracks, and videos). If your company doesn’t use this identifier, you should remove this tag.
Important: The GRid must not be more than 18 alphanumeric characters. The GRid cannot contain dashes, spaces, underscores, other punctuation, or symbols.
<upc>825646307760</upc>
Music Video UPC (required; cannot be updated)
Identifier for the video. This may be UPC (Universal Product Code), EAN (European Article Number) or JAN (Japanese Article Number). UPC is 12-digit code mainly used for US market. Both the EAN and JAN have 13 digits.
<isrc>GB5170300040</isrc>
Music Video ISRC (required; cannot be updated)
The ISRC (international standard recording code) for the music video. ISRCs must be unique across all recordings. It is normal for an ISRC to appear on Apple Music and the iTunes Store more than once if the same recording is included in more than one album (for example, "greatest hits" albums tend to feature songs and videos from other albums). In this case, the two videos must have exactly the same audio and video. A re-recorded, remixed or otherwise different (no matter how similar) video must have a unique ISRC.
Important: ISRCs must not include dashes and should contain only letters and numbers as in the example, US56V0507710.
<title>Zeal</title>
Music Video Title (required; can be updated, but may require a ticket; see Content Update Behavior)
The title of the music video. This tag should be used for video titles based on ISO Latin-1 and Latin-2 language (for example, English or French). For videos with titles in double-byte languages (for example, Japanese, Chinese), refer to Multiple Language Support.
If the video features one or more artists, you can add the artist name(s) as follows: <title>If I Get Locked Up (feat. Eminem & Dr. Dre)</title>. This way the video will show up in the results when a customer searches for the artist.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for music video titles. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
<title_version>Extended Version</title_version>
Music Video Title Version (optional; can be updated, but may require a ticket; see Content Update Behavior)
The version title of the music video in the primary language of the package (see <language> above); in this example, the primary language is English. The <title_version> tag is used to distinguish different versions of the same video by the same artist (for example, "Live from San Francisco"). If not specified, remove the tag from the metadata. If the album’s native language is not an ISO Latin-1 or Latin-2 language (for example, Japanese or Greek), refer to the Multiple Language Support chapter for further details on how to supply album title version.
Note that when imported, Apple takes the information in the tag and appends it to the video title in parentheses for display. If you later do a metadata lookup, the <title_version> tag will not be returned in the metadata; instead you will see the value in the title version tag appended to the video title, for example: <title>Zeal (Extended Version)</title>.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for video title versions. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
To remove an existing title version, send an empty tag: <title_version/> or <title_version></title_version>.
Music Video Original Release Date (optional; can be updated)
The first date of release for the video. This is a cosmetic field and is presented to the user on Apple Music or the iTunes Store interface only.
This field does not impact date of release or "street date" for Apple Music or the iTunes Store.
For videos that are re-releases (for example, re-mastered, or releases on new media types such as DVD, digital, and so on), do not use the date of re-release. This field must be in YYYY-MM-DD format.
Note: The <original_release_date> tag replaces the <release_date> tag. Do not send both the <original_release_date> and <release_date> tags or delivery will fail.
<label_name>Warner Music</label_name>
Music Video Label Name (required; can be updated)
The name of the label that released the music video.
<genres>
<genre code="ROCK-00"/>
</genres>
Music Video Genres (required; can be updated, but may require a ticket; see Content Update Behavior)
Genres to associate with the video. Apple recommends defining at least one, but no more than two genres.
All music genres have an Apple genre code, which is supplied using the attribute named code. The code attribute is required. The following are currently supported for delivering genre information:
Required method using the genre code:
<genre code="ELECTRONIC-01"/>
Acceptable method using both the genre code and the genre label:
<genre code="ELECTRONIC-01">Electronic</genre>
If you use this method, the genre identified by code and the genre identified by genre label must resolve to the same genre, for example, <genre code="POLKA-00">Ragtime</genre> would be rejected.
For a complete list of genres, click Resources and Help on iTunes Connect to download the spreadsheet titled “Music, Music Video, and Ringtone Genre Codes.”
Important: Genre information may be reassigned at the discretion of Apple.
<copyright_cline>2003 Warner Music</copyright_cline>
<copyright_pline>2003 Warner Music</copyright_pline>
Music Video Copyright ℗ Line (optional; can be updated)
Performance copyright line for the music video. Must follow the format YYYY copyright info as in the example. Do not add the ℗ symbol or “p”; it will be added automatically. Some videos don't have this P-line in the slate. Remove this tag if this is the case.
Denotes whether a video contains explicit content—lyrics, visuals, or otherwise. May be clean, explicit, or none. If omitted, none (that is, a video for which neither a clean or explicit version exists) is assumed.
Important: A track must only be marked clean if it is an edited version of the original explicit form of the track.
In this example, the lyrics are delivered as a TTML file (.ttml). The song lyrics file is a TTML document using a restricted dialect of TTML and includes some extensions used for iTunes-specific properties.
If you do not supply the song lyrics in a file, you can use the <lyrics> tag to deliver the lyrics in plain text. See Mixed Media Album Metadata Example.
Music Video Asset File Name (required; can be updated)
The name of the video asset file included. The name should be relative to the package (containing no path reference "C:\" nor "/Macintosh HD/") and it must contain the file name extension (.mpg in this example). This name should be vendor ID, UPC, or ISRC that will be used for reporting.
Since the file sent is used as the source file for the Apple encode, the role must be "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.
The MD5 checksum of the data file. See Checksums for more information.
</data_file>
<data_file role="captions">
Music Video Closed Captioning Data File (optional; can be updated)
A data file block must be included if the captions are delivered for the associated video. The "captions" role specifies that the delivered file is intended to be used as the closed captioning file for the Apple encode. This role must be specified, or the package will be rejected.
In this block, the <file_name>, <size>, and <checksum> tags are required.
<file_name>GB5170300040-english.scc</file_name>
File Name (required)
The name of the caption file included in this delivery package. The name should be relative to the package (containing no path reference “C:\” or “/Macintosh HD/”) and must contain the file name extension (.scc in this example).
Important: File names are case sensitive and spaces are not allowed.
<size>9511</size>
File Size (required)
The size in bytes of the caption file. Do not specify any commas or period delimiters.
Indicates the timecode offset for the closed captions. Apple requires that timecodes start at a program start of 00:00:00:00, which may necessitate that captions be offset if they have been mastered to tape timecode. To keep closed captions in sync on the encoded file, use the "program.start.timecode" attribute. The value is a SMPTE HH:MM:SS:FF timecode in non-drop frame with an optional negative (-) sign for negative offsets, for example, -01:00:00:00. This feature is currently supported for non-drop frame timecodes.
Metadata-Based Preview Clipping and Screen Capture Image (optional; can be updated)
Begins the <previews> block that delivers the parameters for cutting a preview from the full video source. When you define the preview using the <previews> block, you specify the time you want the preview to start. Apple clips a 30-second preview starting at your selected start time. You can also specify the video frame to use for the preview image using the optional image_time attribute.
Use the following attributes to specify the timecode format, the start time of the clip, and the frame to use for the preview image:
timecode_format: defines the timecodes used for the start and image times. The format can be qt_text or one of the SMPTE formats illustrated in the Timecode Formats chapter. If you omit the <timecode_format> tag, the format defaults to qt_text.
start_time: specifies the start of the preview from the source video.
image_time (optional): specifies the frame to use for the preview image. The frame can be anywhere within the cut preview (based on the specified start_time and the preview duration of 30 seconds). If you omit the image_time attribute, the first frame of the preview is used. If you specify an image_time but use the qt_text format, the frame nearest the image_time is used for the preview image (qt_text allows milliseconds, not frames so you cannot specify an exact frame to use for the preview image).
Important: The <previews> block and <preview> tag replace the <preview starttime=""/> tag. The tag is still supported. However, if you want to specify a preview image, you must use the <previews> block and the <preview> tag instead of the <preview starttime=""/> tag. Do not use both the <previews> block and the <preview starttime=""/> tag in the same delivery. See the annotation Music Video Single Crop Dimensions Metadata Example for how to specify a preview start time.
Note: Apple strongly recommends that you submit a screen capture directly from the video using the image_time attribute. However, you can still submit the image as a separate asset file as shown below. See Music Video Single Crop Dimensions Metadata Annotations for a complete example and annotation. Note that you cannot use both the image_time attribute and a separate image asset in the same delivery.
For each territory in which an video is to be sold there must be a defined product.
Important: Omitting this tag indicates you would like the video available in all territories where you have an active contract. The clearances below will be added automatically for you:
If you have a contract in a single territory, a clearance will be added for this contracted territory only.
If you have a contract for more than one territory, world clearances will be added. This means that in the future if more contracts are signed, this product will appear in all new territories.
<territory>US</territory>
Music Video Territory (required; can be updated)
The territory in which this video is cleared for sale. Must be specified as an ISO 3166-1 alpha 2 country/region code. If a video is clear for every country or region, this may be indicated using "WW" as the country/region code. Some countries or regions in the ISO 3166-1 alpha 2 country/regions list contain other countries or regions (for example, United States includes Puerto Rico), and "WW" contains all territories.
Music Video Wholesale Price Tier (required; can be updated)
The wholesale price tier for the video. Must be a wholesale price tier number as specified in your contract with Apple.
See 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 Apple Technical Representative for more details.
Important: Omitting this tag will indicate that “default” video pricing should be used.
<sales_start_date>2006-01-16</sales_start_date>
Music Video Sales Start Date (optional; can be updated)
The date that this video is made available for sale to customers in the specified territory only. This is also known as the "street date" of the video and is written in the format YYYY-MM-DD.
In this example, "2006-01-16" is the sales start date and the video was made available for sale starting January 16, 2006.
Important: Omitting this tag on an initial upload will make the video available for sale immediately.
<cleared_for_sale>true</cleared_for_sale>
Music Video Cleared for Sale (optional; can be updated)
Specifies whether the video is cleared for sale in the territory for the product. Must be true or false. If not specified, the default is true.
It is preferred that the "WW" territory is used whenever possible so that the fewest number of necessary territories are included in the delivered metadata.
Because the product for the most specific territory is used, this can be used as an exclusion mechanism for a regional clearance. For example, if you have rights for the world except for the UK (GB), then you would have two products: one for the world with <cleared_for_sale> set to true, and one for the UK with <cleared_for_sale> set to false. The resulting video will be sold everywhere that you have a current contract with the exception of the UK.
</product>
</products>
<artists>
<artist>
<artist_name>Plaid</artist_name>
<apple_id>4514151</apple_id>
<roles>
<role>Performer</role>
</roles>
<primary>true</primary>
</artist>
</artists>
Music Video Artists (required; can be updated, but may require a ticket; see Content Update Behavior)
Name or Apple ID, primary status, and roles for each artist. In this context, "artist" may be any contributor including non-performing persons (for example, producer), groups (for example, a band name), 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"), 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 an album). Note that you should always include composition-related contributor information to the extent you have it.
You can refer to the artist by Apple ID (using the <apple_id> tag) or by name (using the <artist_name> tag). Apple assigns every artist a unique Apple ID; Apple recommends that performing artists be delivered with the Apple ID to avoid the ambiguity in cases where artists share the same name as other music artists, or film actors or crew members. You can supply the <apple_id>, the <artist_name>, or both the <apple_id> and <artist_name>. If you supply both tags, the <artist_name> tag will be ignored in favor of the Apple ID. If you do not know the artist's Apple ID, you can do an artist lookup and look for the <apple_id> tag. (See Use Lookup Artist Mode in the Transporter User Guide.) To create a new artist, you can generate the artist and Apple ID using the artist feed: see Creating a New Artist. For any subsequent updates, you can use the <apple_id> tag instead of or in addition to the name, to avoid ambiguity.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for artist names. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
Role
Use the <role> tag to define the part that a particular artist performs on an album or track. Some roles are required (as shown in the list below) and other roles are optional (the chapter Recommended Contributor Roles lists all the roles recognized by Apple Music and the iTunes Store.)
Performer: always required for video albums and tracks.
Songwriter (or Composer): always required for video albums and tracks. Note that songwriter and composer are often used to refer to the same contributor; you can specify either songwriter or composer to refer to an artist, but at least one of those roles is required.
Featuring (or With): required if there is a featured artist on the video. Adding the artist with the Featuring or With role ensures that the video will show up on the featured artist’s page.
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: <role>Composer</role>, <role>Lyricist</role>, or <role>Songwriter</role>. You can add as many songwriters/composers as needed for the video. Failure to add full and accurate songwriter metadata in a timely manner may delay payment of royalties to publishers and songwriters.
Primary Status
Primary status indicates whether or not the video appears on the artist’s page. 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. Note that the video must include at least one artist with the <primary> status set to true. Only primary artists are presently displayed with the video.
Note: You can use the <language> tag under <artist> on a video album to indicate the language in which the artist’s name appears. If you omit the <language> tag under <artist>, the <artist_name> is assumed to be in the language of the package (the <language> tag under <package>). Using <language> under <artist> is optional and would only be used in specific circumstances, for example, when a Japanese artist appears on a track on an English video album.
</video>
</package>
Music Video Single Crop Dimensions Metadata Example
Below is an example metadata.xml file for a music video (in HD or SD) that shows how to deliver crop dimensions. (See the iTunes Video and Audio Asset Guide for specific asset requirements.) The difference between this example and the music video single metadata example is the addition of crop dimension tags, which are in bold below. The example also shows how to use the <preview starttime=""/> tag and how to deliver the video screen capture artwork as a separate file as opposed to cutting a frame from the video itself.
Music Video Single Crop Dimensions Metadata Annotations
<attribute name="crop.top">0</attribute>
Metadata-Based Cropping (required; can be updated )
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 videos 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, Apple will default to 0,0,0,0.
The name attribute specifies the side of the image to be cropped. Accepted values are:
crop.left: The number of whole pixels from the left of the encoded image to remove.
crop.top: The number of whole pixels from the top of the encoded image to remove.
crop.right: The number of whole pixels from the right of the encoded image to remove.
crop.bottom: The number of whole pixels from the bottom of the encoded image to remove.
The values must be integers that represent the number of whole pixels of the encoded image.
<preview starttime="30"/>
Music Video Preview Start Time (optional; use until you start to use the previews block; can be updated)
Specifies the start time for the 30-second video previews available on Apple Music and the iTunes Store. If not specified, the default is 45 seconds.
Important: Do not use both the <previews> block and the <preview starttime=""/> tag in the same delivery. See Music Video Single Metadata Example for an example of using the <previews> block.
Music Video Screen Capture Image Asset File (optional; can be updated, but may require a ticket; see Content Update Behavior)
A screen capture from the video can be provided along with the video, to be used as the artwork for the video on Apple Music and the iTunes Store and when it is purchased. This must be taken from the video itself and can never be a cover of the corresponding single. Refer to the iTunes Video and Audio Asset Guide for more details and asset file requirements.
Note: Apple strongly recommends that you submit a frame cut directly from the video using the image_time attribute in the <previews> block and removing the <asset> block for the artwork (see the annotation for the <preview> tag here: Music Video Single Metadata Annotations. Sending an asset file may cause delays in displaying your content because the file needs to be evaluated for quality control.
Artwork can be provided with any kind of video, whether it is a video single or part of a playlist.
HDR Delivery Examples and Annotations
HDR Dolby® Vision Metadata Example
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.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.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> </assets></package>
HDR Dolby® Vision Metadata Annotations
Only the tags related to the HDR Dolby® Vision delivery are described. Refer to Basic Music Album Metadata Annotated for annotations on other tags.
Begins the assets block that references the assets being delivered. In an asset-only update, the vendor_id attribute value must match the vendor ID of the primary video. You do not need to re-deliver the primary source video data file.
<asset type="full">
<data_file role="source.hdr">
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 "source.hdr".
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 secondary video.
In this block, the <locale>, <file_name>, <size>, and <checksum> tags are required.
In this example, the HDR video source is Dolby® Vision, which must be specified with the hdr.format attribute. Specifying the HDR format is required. Roles allowed for the hdr.format attribute include DolbyVision and HDR10. Only one hdr.format value can be specified.
<locale name="en-US"/>
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.
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.
<asset type="full">
<data_file role="mapping.hdr">
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 <locale>, <file_name>, <size>, and <checksum> tags are required.
For instructions on constructing this sidecar metadata file, refer to the confidential document “Dolby Content Mapping (CM) Metadata Format Specification Version 2.0.5.1.” (The version number is subject to change.)
HDR10 Metadata Example
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 HDR10 Metadata Annotations for examples of value formatting.
Only the tags related to the HDR10 delivery are described. The attributes follow the SMPTE ST 2086 metadata guidelines. Refer to Basic Music Album 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.
Begins the assets block that references the assets being delivered. In an asset-only update, the vendor_id attribute value must match the vendor ID of the primary video. You do not need to re-deliver the primary source video data file.
<asset type="full">
<data_file role="source.hdr">
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 "source.hdr".
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 secondary video.
In this block, the <locale>, <file_name>, <size>, and <checksum> tags are required.
<attribute name="hdr.format">HDR10</attribute>
HDR Format (required)
In this example, the HDR video source is HDR10, which must be specified with the hdr.format attribute. Specifying the HDR format is required. Roles allowed for the hdr.format attribute include DolbyVision and HDR10. Only one hdr.format value can be specified. The value for HDR10 is case-sensitive and must be delivered as: HDR10
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.
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 and SDR Delivery
The following XML example shows how to deliver HDR and SDR videos in the same delivery.
Note: If you deliver embedded audio with the HDR source, it will be ignored. The audio on the SDR video will be used for bundling.
A mixed media album is an album that has both audio and video content. It is quite similar to an audio album in format, but has a new tag introduced to handle videos, <video>. Should a single video be delivered in this format, it will be rejected. For details on how to deliver video singles, see Music Video Single.
Note: On sales reports, videos on playlists (for example, a video delivered on an album with both audio and video content) are reported using the vendor ID of the album combined with the vendor ID of the video. For example, if the album vendor ID is 8256463821764 and the video vendor ID is USW980800331, sales are reported against the combined album vendor ID and video vendor ID separated by an underscore, such as 8256463821764_USW980800331.
Mixed Media Album Metadata Example
This example shows metadata for an album that contains both audio and music video tracks. An "album" is anything that has more than one video or audio track.
For the sake of brevity, only two audio tracks and a single video track are shown. Album metadata may contain any number of <track> and <video> blocks, one per audio or video track, respectively. All fields are explained earlier in the Music Video Single and Music Profile chapters.
Note that while audio tracks use the <track_number> tag, videos also use the <track_number> tag to indicate placement on the album track listing. The <track_number> tag is required for videos within a playlist.
Mixed Media Album With Video and Booklet Metadata Example
This example shows metadata for an album that contains one music video track and one booklet.
All tags are explained in the Music Video Single, Booklets, and Music Profile chapters.
Note that while audio tracks use the <track_number> tag, videos also use the <track_number> tag to indicate placement on the album track listing. The <track_number> tag is required for videos within a playlist.
Note: For an initial delivery of a music video, delivery of the video asset source is required.
Music Video Album Metadata Example
This example shows metadata for an album that contains only music video tracks.
For the sake of brevity, three videos are shown, but in practical use, there is no limit to the number of videos that may be provided. All fields are annotated in the Music Video Single and Music Profile chapters.
Video assets can be delivered independently of metadata. This is especially helpful if two different companies deliver the audio and the video assets, or if videos need to be replaced due to encoding or other issues. Assets may not be delivered unless the metadata has already been sent and imported. If the video is sent without metadata to which it can be attached, it will fail delivery.
Important: Individual videos have globally unique identifiers (IDs) manufactured from a combination of the album and video IDs provided in the first metadata delivery. For video singles, this identifier is simply the previously supplied vendor ID (ISRC if vendor ID is not available). If, however, a video is attached to an album, the importer will use the album's vendor ID (or UPC if the vendor ID is not available), followed by an underscore, followed by ONE of the following from the video itself, in order of preference:
Expressly-supplied vendor ID
ISRC
UPC
GRid
So, for example, if the album's vendor ID is 093624996941, and the video's ISRC is USWBV0700477, the video doesn't expressly specify a vendor ID, then the video's effective vendor ID will be:
093624996941_ USWBV0700477
Therefore, to deliver a video without its associated metadata, it must be accompanied by the complete and correct vendor ID that references the already delivered metadata.
For any questions regarding asset-only delivery, contact your Apple Technical Representative.
Music Video Asset-Only Delivery Package
Video asset-only deliveries still need to be in an iTunes package, but only consist of a short metadata file, the video asset and the cover art (optional). For example, a package for an album with a UPC 00602517411838 would be delivered in a package directory titled "093624996941.itmsp" and might look like this:
Music Video Asset-Only Delivery Metadata Annotation
Only the additions for music video asset-only are described.
<provider>Warner</provider>
Provider Name (required)
This value should be the Apple-defined provider name used for partner identification. The value must match the provider shortname used in Transporter (the value that is after -s in the Transporter command). Note that it is the value you pass as an argument to Transporter, not the value in the XML, that determines the account you are delivering to. Contact your Apple Technical Representative for this value.
The type and vendor identifier of the video asset. The attribute media_type will always be "video" however, the vendor_id should be the specific vendor identifier for the video as specified in the previously delivered metadata. All items within this tag are provided to supply the assets for the described vendor_id.
<asset type="full">
Music Video Asset Type (required)
The type of file delivered. This should always be "full" for the video asset file.
<data_file role="source">
Music Video Asset Role (required)
The role of video file delivered. Since the file sent is used as the source file for the Apple encode, the role must be "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.
The name of the video asset file included. The name should be relative to the package (containing no path reference "C:\" nor "/Macintosh HD/") and it must contain the file name extension (.mpg in this example). This name should be vendor ID, UPC or ISRC that will be used for reporting.
Music Video Screen Capture Image Asset File (optional; can be updated, but may require a ticket; see Content Update Behavior)
A screen capture from the video can be provided along with the video, to be used as the artwork for the video on Apple Music and the iTunes Store and when it is purchased. This must be taken from the video itself and may never be a cover of the corresponding single. Refer to the iTunes Video and Audio Asset Guide for more details and asset file requirements.
If you do not provide the video screen capture image file, Apple will use a frame from the previously-cut video preview as the video artwork image.
</asset>
</assets>
</package>
Japanese Language Metadata Example for Music Video
The following metadata example shows a music video by the Japanese artist Sheena Ringo. The video is to be sold on the Japanese Store so the language used in the metadata is Japanese (the <language> tag directly below <package>). In addition, English localizations for the title and artist can be delivered in the metadata.
Japanese Language Metadata Annotations for Music Video
Only the tags relevant to title and artist localization support are described. Refer to Basic Music Album Metadata Annotated for annotations on the remaining tags.
<language>ja</language>
Language (required)
The primary language of the metadata for this video package. Titles and artist names are expected to appear in this language. In this example, the video is in Japanese and is to be sold on the Japanese Store, so the language in the <language> tag is Japanese. The video will also be sold where English is spoken, so English localizations can be delivered in the metadata.
See the Language Codes chapter for language code formatting and links to detailed information.
<title>ありあまる富</title>
Video (required)
The title of the video in the language specified in the <language> tag, in this example, Japanese.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for music video titles. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
<phonetic_title>ありあまるとみ</phonetic_title>
Video Phonetic Title (optional)
The phonetic title of the video in Japanese. The <phonetic_title> tag (optional) provides the reading (furigana) of the video title in full-width Hiragana or Katakana. If any meaningful separation units exist they should be delimited using a space character. Providing the phonetic title provides a better search experience for the user.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for video phonetic titles. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
<title_version>ライブ・バージョン</title_version>
Music Video Title Version (optional; can be updated, but may require a ticket; see Content Update Behavior)
The version title of the music video in the primary language of the package (see <language> above); in this example, the primary language is English. The <title_version> tag is used to distinguish different versions of the same video by the same artist (for example, "Live from San Francisco"). If not specified, remove the tag from the metadata. If the album’s native language is not an ISO Latin-1 or Latin-2 language (for example, Japanese or Greek), refer to the Multiple Language Support chapter for further details on how to supply album title version.
Note that when imported, Apple takes the information in the tag and appends it to the video title in parentheses for display. If you later do a metadata lookup, the <title_version> tag will not be returned in the metadata; instead you will see the value in the title version tag appended to the video title, for example: <title>ありあまるとみ (ライブ・バージョン)</title>.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for video title versions. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
To remove an existing title version, send an empty tag: <title_version/> or <title_version></title_version>.
<locale name="en">
<title>The Invaluable</title>
Localized Video Title (required within the <locale> tag)
The title of the video localized into the language specified in the <locale> tag.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for music video titles. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
See the Language Codes chapter for language code formatting and links to detailed information.
<title_version>Live Version</title_version>
</locale>
Localized Video Title Version (optional)
The title version of the video localized into the language specified in the enclosing <locale> tag.
<artists>
<artist>
<artist_name>椎名林檎</artist_name>
<apple_id>74576999</apple_id>
<phonetic_name>しいな りんご</phonetic_name>
Video Artist Name (required)
Name, Apple ID, primary status, and roles for each artist on the video in the language specified in the <language> tag, in this example, Japanese.
The <phonetic_name> tag (optional) provides the reading (furigana) of the video artist name in full-width Hiragana or Katakana. If any meaningful separation units exist they should be delimited using a space character. Providing the phonetic title provides a better search experience for the user.
<locales>
<locale name="en">
<artist_name>Sheena Ringo</artist_name>
Localized Video Artist (required within the <locale> tag when it appears within the <artist> tag)
The name of the video artist localized into the language specified in the <locale> tag.
See the Language Codes chapter for language code formatting and links to detailed information.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for artist names. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
Multiple Language Support
Multiple Language Support
Apple provides support for multiple languages in a single playlist or video that will be sold in countries or regions where different languages are spoken. Using the <locale> tags, you can supply localizations for titles and artists at the <album>, <track>, <booklet>, and <video> levels.
Title and Artist Localizations Metadata Basic Example
The following metadata example shows an album by the Korean singer Park Ji Yoon. The album metadata is in Korean (the <language> tag directly below <package>). In addition, English, Japanese, Russian, and Chinese localizations for titles and artists can be delivered in the metadata. This album includes a booklet. One song track is sung in Japanese.
The primary language of the metadata for this package. Titles and artist names are expected to appear in this language. In this example, the album metadata is Korean, so the language in the <language> tag is Korean. The album will also be sold where English, Japanese, Russian, and Chinese are spoken; localized metadata for those languages can be delivered under the <locales> tag (see below).
Album Title (required; can be updated, but may require a ticket; see Content Update Behavior)
The title of the album in the primary language of the package (see <language> above); in this example, the primary language is Korean.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for album titles. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
<title_version>디럭스 에디션</title_version>
Album Title Version (optional; can be updated, but may require a ticket; see Content Update Behavior)
The version title of the album in the primary language of the package (see <language> above); in this example, the primary language is Korean. Generally used to distinguish different versions of the same album by the same artist (for example, "Live from San Francisco", "Deluxe Edition").
Note that when imported, Apple takes the information in the tag and appends it to the album title in parentheses for display. If you later do a metadata lookup, the <title_version> tag will not be returned in the metadata; instead you will see the value in the title version tag appended to the album title, for example: <title>Medúlla (Remastered)</title>.
To remove an existing title version, send an empty tag: <title_version/> or <title_version></title_version>.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for album title versions. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
<locales>
Locales (optional)
Provides a mechanism to specify localizations for album title and title version. In this example, English, Japanese, Russian, and Traditional and Simplified Chinese localizations are being delivered.
<locale name="en">
Locale Name (required within the <locales> tag)
Identifies the language of the localization provided in the <title> and optional <phonetic_title> tags within the <locale> block. Specify only the language code, not the region subtag.
Localized Album Title and Title Version (<title> required within the <locale> tag; can be updated, but may require a ticket; see Content Update Behavior)
The title and title version (optional) of the album localized into the language specified in the enclosing <locale> tag.
To remove an existing title version, send an empty tag: <title_version/> or <title_version></title_version>.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for album titles and title versions. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
<locale name="ja">
<title>木になる夢</title>
<phonetic_title>きになるゆめ</phonetic_title>
<title_version>デラックス・エディション</title_version>
</locale>
Localized Album Titles (required within the <locales> tag; <phonetic_title> and <title_version> are optional; can be updated, but may require a ticket; see Content Update Behavior)
In this example, the <locale> specifies that the localization in the enclosed <title> tag is Japanese. Specify only the language code, not the region subtag.
Note: Do not enter phonetic title information in the <title> or <title_version> tags. Whatever you enter in those tags is displayed on the Store, so the tags should not include phonetic information. Use the <phonetic_title> tag to provide the phonetic information.
The <phonetic_title> tag (optional) should only be used where the language is Japanese, Chinese, Korean, Thai, Russian, Bulgarian, or Ukrainian. For Japanese, the tag provides the reading (furigana) of the album title in full-width Hiragana or Katakana. If any meaningful separation units exist they should be delimited using a space character. Providing the phonetic title provides a better search experience for the user.
To remove an existing title version, send an empty tag: <title_version/> or <title_version></title_version>.
Localized Album Title and Title Version (<title> required within the <locales> tag; <phonetic_title> and <title_version> are optional; can be updated, but may require a ticket; see Content Update Behavior)
In this example, the <locale> specifies that the localization in the enclosed <title> and <title_version> tags are Mandarin Chinese written in traditional characters. The language subtag (zh) indicates Mandarin Chinese and the script subtag (Hant) indicates that the language is written in traditional characters (as opposed to simplified). Note that the script subtag is currently supported only for Chinese (Mandarin), and is required for textual metadata where the language is Chinese.
Acceptable locales for Chinese written language include:
zh-Hant (Mandarin Chinese traditional script)
zh-Hans (Mandarin Chinese simplified script)
As a best practice, supply the title and title version in both traditional (Hant) and simplified (Hans) script when available.
Do not provide a region tag for Chinese metadata text. (For example, do not use "zh-Hant-TW".)
To remove an existing title version, send an empty tag: <title_version/> or <title_version></title_version>.
The <phonetic_title> tag (optional) should only be used where the language is Japanese, Chinese, Korean, Thai, Russian, Bulgarian, or Ukrainian. For Chinese, the tag provides the reading of the album title in Pinyin. If any meaningful separation units exist they should be delimited using a space character. Providing the phonetic title provides a better search experience for the user.
If you have "WW" (world-wide) clearance for a product, Apple recommends that you deliver a "WW" product for albums and tracks, if possible, to avoid having to deliver products for individual territories.
<artists>
<artist>
<artist_name>박지윤</artist_name>
<apple_id>503753248</apple_id>
Album Artist Name (required; can be updated, but may require a ticket; see Content Update Behavior)
Name or Apple ID for each artist on the album in the primary language of the package (see <language> above); in this example, the primary language is Korean. Note that the <artist> block also includes the artist’s role (the <role> tag) and primary status (the <primary> tag). See Basic Music Album Metadata Annotated for tag annotations.
Artist names will appear on Apple Music and the iTunes Store in the order in which they are specified in the provided metadata.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for artist names. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
Note: You can use the <language> tag under <artist> on an album to indicate the language in which the artist’s name appears. If you omit the <language> tag under <artist>, the <artist_name> is assumed to be in the language of the package (the <language> tag under <package>). Using <language> under <artist> is optional and would only be used in specific circumstances, for example, when a Japanese artist appears on an English album.
<locales>
Locales (optional)
Provides a mechanism to specify localizations for booklet artists. If the album is to be sold on a Store using a language other than the primary language specified in the <language> tag, you must supply translations for those Stores.
<locale name="en">
Locale Name (required within the <locales> tag)
Identifies the language of the localization provided in the <artist_name> and optional <phonetic_name> tags within the <locale> block. Specify only the language code, not the region subtag.
<artist_name>Park Ji Yoon</artist_name>
</locale>
Localized Album Artist (required within the <locale> tag when it appears within the <artist> tag; can be updated, but may require a ticket; see Content Update Behavior)
The name of the album artist localized into the language specified in the enclosing <locale> tag.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for artist names. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
<locale name="ja">
<artist_name>パク・チユン</artist_name>
<phonetic_name>ぱく ちゆん</phonetic_name>
</locale>
Localized Album Artist (required within the <locales> tag; <phonetic_name> is optional; can be updated, but may require a ticket; see Content Update Behavior)
In this example, the <locale> specifies that the localization in the enclosed <artist_name> tag is Japanese. Specify only the language code, not the region subtag.
The <phonetic_name> tag (optional) should only be used where the language is Japanese, Chinese, Korean, Thai, Russian, Bulgarian, or Ukrainian. For Japanese, the tag provides the reading (furigana) of the artist in full-width Hiragana or Katakana. If any meaningful separation units exist they should be delimited using a space character. Providing the phonetic name provides a better search experience for the user.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for artist names. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
<locale name="zh-Hant">
<artist_name>朴志胤</artist_name>
<phonetic_name>Pǔ Zhì Yìn</phonetic_name>
</locale>
Localized Album Artist (required within the <locales> tag; <phonetic_name> is optional; can be updated, but may require a ticket; see Content Update Behavior)
In this example, the <locale> specifies that the localization in the enclosed <artist_name> tag is Mandarin Chinese written in traditional characters. The language subtag (zh) indicates Mandarin Chinese and the script subtag (Hant) indicates that the language is written in traditional characters (as opposed to simplified). Note that the script subtag is currently supported only for Chinese (Mandarin), and is required for textual metadata where the language is Chinese.
Acceptable locales for Chinese written language include:
zh-Hant (Mandarin Chinese traditional script)
zh-Hans (Mandarin Chinese simplified script)
As a best practice, supply the artist name in both traditional (Hant) and simplified (Hans) script when available.
Do not provide a region tag for Chinese metadata text. (For example, do not use "zh-Hant-TW".)
The <phonetic_name> tag (optional) should only be used where the language is Japanese, Chinese, Korean, Thai, Russian, Bulgarian, or Ukrainian. For Chinese, the tag provides the reading of the artist in Pinyin. If any meaningful separation units exist they should be delimited using a space character. Providing the phonetic title provides a better search experience for the user.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for artist names. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
Track Title (required; can be updated, but may require a ticket; see Content Update Behavior)
The title of the track in the primary language of the package (see <language> above); in this example, the primary language is Korean.
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.
<locales>
Locales (optional)
Provides a mechanism to specify localizations for booklet artists. If the album is to be sold on a Store using a language other than the primary language specified in the <language> tag, you must supply translations for those Stores.
<locale name="en">
Locale Name (required within the <locales> tag)
Identifies the language of the localization provided in the <title> tag (and optional <phonetic_title> tag) within the <locale> block. Specify only the language code, not the region subtag.
Refer to the Album Title annotations for more information on specifying locales. See Language Codes for language code formatting and links to detailed information.
<title>That Time</title>
</locale>
Localized Track Title (<title> required within the <locale> tag; <title_version> is optional; can be updated, but may require a ticket; see Content Update Behavior)
The title and title version (optional) of the track localized into the language specified in the enclosing <locale> tag.
To remove an existing title version, send an empty tag: <title_version/> or <title_version></title_version>.
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.
<locale name="ja">
<title>その時には</title>
<phonetic_title>そのときには</phonetic_title>
</locale>
Localized Track Titles (Japanese) (<title> required within the <locales> tag; <phonetic_title> and <title_version> are optional; can be updated, but may require a ticket; see Content Update Behavior)
In this example, the <locale> specifies that the localization in the enclosed <title> tag is Japanese. Specify only the language code, not the region subtag.
The <phonetic_title> tag (optional) should only be used where the language is Japanese, Chinese, Korean, Thai, Russian, Bulgarian, or Ukrainian. For Japanese, the tag provides the reading (furigana) of the track title in full-width Hiragana or Katakana. If any meaningful separation units exist they should be delimited using a space character. Providing the phonetic title provides a better search experience for the user.
<locale name="zh-Hant">
<title>在時</title>
<phonetic_title>zài shí</phonetic_title>
</locale>
Localized Track Titles (Chinese) (<title> required within the <locales> tag; <phonetic_title> and <title_version> are optional; can be updated, but may require a ticket; see Content Update Behavior)
In this example, the <locale> specifies that the localization in the enclosed <title> tag is Mandarin Chinese written in traditional characters. The language subtag (zh) indicates Mandarin Chinese and the script subtag (Hant) indicates that the language is written in traditional characters (as opposed to simplified). Note that the script subtag is currently supported only for Chinese (Mandarin), and is required for textual metadata where the language is Chinese.
Acceptable locales for Chinese written language include:
zh-Hant (Mandarin Chinese traditional script)
zh-Hans (Mandarin Chinese simplified script)
As a best practice, supply the track title in both traditional (Hant) and simplified (Hans) script when available.
Do not provide a region tag for Chinese metadata text. (For example, do not use "zh-Hant-TW".)
The <phonetic_title> tag (optional) should only be used where the language is Japanese, Chinese, Korean, Thai, Russian, Bulgarian, or Ukrainian. For Chinese, the tag provides the reading of the track title in Pinyin. If any meaningful separation units exist they should be delimited using a space character. Providing the phonetic title provides a better search experience for the user.
Use the <audio_language> tag to specify the language of audio. If there are no words spoken in an audio file, you can use the code zxx (which represents “no linguistic content”). In this example, the language for this track is Japanese.
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 (http://tools.ietf.org/html/rfc5646), which is part of BCP 47. An overview of these best practices is provided here: http://www.w3.org/International/articles/language-tags/.
Note: The language specified in the <audio_language> tag must not contain script information. For example, the language for Mandarin audio must be zh, not zh-Hant or zh-Hans; the language for Cantonese audio must be yue, not yue-Hant. If a track is sung in Chinese, but you do not know if it is Mandarin or Cantonese, you can send zh as the audio language, but you will get a warning when you deliver the metadata. This tag can be updated, so you could change zh to yue once you know if it is Cantonese.
<artists>
<artist>
<artist_name>박지윤</artist_name>
<apple_id>503753248</apple_id>
Track Artist Name (required; can be updated, but may require a ticket; see Content Update Behavior)
Name or Apple ID for each artist on the track in the primary language of the package (see <language> above); in this example, the primary language is Korean. Note that the <artist> block also includes the artist’s role (the <role> tag) and primary status (the <primary> tag). See Basic Music Album Metadata Annotated for tag annotations.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for artist names. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
Artist names will appear on Apple Music and the iTunes Store in the order in which they are specified in the provided metadata.
Note: You can use the <language> tag under <artist> on a track to indicate the language in which the artist’s name appears. If you omit the <language> tag under <artist>, the <artist_name> is assumed to be in the language of the package (the <language> tag under <package>). Using <language> under <artist> is optional and would only be used in specific circumstances, for example, when a Japanese artist appears on a track on an English album.
<locales>
Locales (optional)
Provides a mechanism to specify localizations for booklet artists. If the album is to be sold on a Store using a language other than the primary language specified in the <language> tag, you must supply translations for those Stores.
<locale name="en">
Locale Name (required within the <locales> tag)
Identifies the language of the localization provided in the <artist_name> and optional <phonetic_name> tags within the <locale> block. Specify only the language code, not the region subtag.
<locale name="en">
<artist_name>Park Ji Yoon</artist_name>
</locale>
Localized Track Artist (required within the <locale> tag when it appears within the <artist> tag; can be updated, but may require a ticket; see Content Update Behavior)
The name of the track artist localized into the language specified in the enclosing <locale> tag.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for artist names. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
<locale name="ja">
<artist_name>パク・チユン</artist_name>
<phonetic_name>ぱく ちゆん</phonetic_name>
</locale>
Localized Track Artist (required within the <locale> tag when it appears within the <artist> tag; <phonetic_name> is optional; can be updated, but may require a ticket; see Content Update Behavior)
In this example, the <locale> specifies that the localization in the enclosed <artist_name> tag is Japanese. Specify only the language code, not the region subtag.
The <phonetic_name> tag (optional) should only be used where the language is Japanese, Chinese, Korean, Thai, Russian, Bulgarian, or Ukrainian. For Japanese, the tag provides the reading (furigana) of the artist in full-width Hiragana or Katakana. If any meaningful separation units exist they should be delimited using a space character. Providing the phonetic name provides a better search experience for the user.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for artist names. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
<locale name="zh-Hant">
<artist_name>朴志胤</artist_name>
<phonetic_name>Pǔ Zhì Yìn</phonetic_name>
</locale>
Localized Track Artist (required within the <locale> tag when it appears within the <artist> tag; <phonetic_name> is optional; can be updated, but may require a ticket; see Content Update Behavior)
In this example, the <locale> specifies that the localization in the enclosed <artist_name> tag is Mandarin Chinese written in traditional characters. The language subtag (zh) indicates Mandarin Chinese and the script subtag (Hant) indicates that the language is written in traditional characters (as opposed to simplified). Note that the script subtag is currently supported only for Chinese (Mandarin), and is required for textual metadata where the language is Chinese.
Acceptable locales for Chinese written language include:
zh-Hant (Mandarin Chinese traditional script)
zh-Hans (Mandarin Chinese simplified script)
As a best practice, supply the artist name in both traditional (Hant) and simplified (Hans) script when available.
Do not provide a region tag for Chinese metadata text. (For example, do not use "zh-Hant-TW".)
The <phonetic_name> tag (optional) should only be used where the language is Japanese, Chinese, Korean, Thai, Russian, Bulgarian, or Ukrainian. For Chinese, the tag provides the reading of the artist in Pinyin. If any meaningful separation units exist they should be delimited using a space character. Providing the phonetic name provides a better search experience for the user.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for artist names. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for booklet titles. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
<locales>
Locales (optional)
Provides a mechanism to specify localizations for booklet artists. If the album is to be sold on a Store using a language other than the primary language specified in the <language> tag, you must supply translations for those Stores.
<locale name="en">
<title>Digital Booklet - Tree of Life</title>
</locale>
Localized Booklet Title (<title> required within the <locale> tag)
The title of the booklet localized into the language specified in the enclosing <locale> tag.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for booklet titles. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
Localized Booklet Titles (<title> required within the <locales> tag; <phonetic_title> is optional)
In this example, the <locale> specifies that the localization in the enclosed <title> tag is Japanese. Specify only the language code, not the region subtag.
The <phonetic_title> tag (optional) should only be used where the language is Japanese, Chinese, Korean, Thai, Russian, Bulgarian, or Ukrainian. For Japanese, the tag provides the reading (furigana) of the booklet title in full-width Hiragana or Katakana. If any meaningful separation units exist they should be delimited using a space character. Providing the phonetic title provides a better search experience for the user.
Localized Booklet Titles (<title> required within the <locales> tag; <phonetic_title> is optional)
In this example, the <locale> specifies that the localization in the enclosed <title> tag is Mandarin Chinese written in traditional characters. The language subtag (zh) indicates Mandarin Chinese and the script subtag (Hant) indicates that the language is written in traditional characters (as opposed to simplified). Note that the script subtag is currently supported only for Chinese (Mandarin), and is required for textual metadata where the language is Chinese.
Acceptable locales for Chinese written language include:
zh-Hant (Mandarin Chinese traditional script)
zh-Hans (Mandarin Chinese simplified script)
As a best practice, supply the booklet title in both traditional (Hant) and simplified (Hans) script when available.
Do not provide a region tag for Chinese metadata text. (For example, do not use "zh-Hant-TW".)
The <phonetic_title> tag (optional) should only be used where the language is Japanese, Chinese, Korean, Thai, Russian, Bulgarian, or Ukrainian. For Chinese, the tag provides the reading of the booklet title in Pinyin. If any meaningful separation units exist they should be delimited using a space character. Providing the phonetic title provides a better search experience for the user.
Booklet Artist Name (required; can be updated, but may require a ticket; see Content Update Behavior)
Name or Apple ID for each artist in the booklet in the primary language of the package (see <language> above); in this example, the primary language is Korean. Note that the <artist> block also includes the artist’s role (the <role> tag) and primary status (the <primary> tag). See Basic Music Album Metadata Annotated for tag annotations.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for artist names. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
Artist names will appear on Apple Music and the iTunes Store in the order in which they are specified in the provided metadata.
<locales>
Locales (optional)
Provides a mechanism to specify localizations for booklet artists. If the album is to be sold on a Store using a language other than the primary language specified in the <language> tag, you must supply translations for those Stores.
<locale name="en">
Locale Name (required within the <locales> tag)
Identifies the language of the localization provided in the <artist_name> and optional <phonetic_name> tags within the <locale> block. Specify only the language code, not the region subtag.
<locale name="en">
<artist_name>Park Ji Yoon</artist_name>
</locale>
Localized Booklet Artist (required within the <locale> tag when it appears within the <artist> tag; can be updated, but may require a ticket; see Content Update Behavior)
The name of the booklet artist localized into the language specified in the enclosing <locale> tag.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for artist names. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
<locale name="ja">
<artist_name>パク・チユン</artist_name>
<phonetic_name>ぱく ちゆん</phonetic_name>
</locale>
Localized Booklet Artist (required within the <locale> tag when it appears within the <artist> tag; <phonetic_name> is optional; can be updated, but may require a ticket; see Content Update Behavior)
In this example, the <locale> specifies that the localization in the enclosed <artist_name> tag is Japanese. Specify only the language code, not the region subtag.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for artist names. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
The <phonetic_name> tag (optional) should only be used where the language is Japanese, Chinese, Korean, Thai, Russian, Bulgarian, or Ukrainian. For Japanese, the tag provides the reading (furigana) of the artist in full-width Hiragana or Katakana. If any meaningful separation units exist they should be delimited using a space character. Providing the phonetic name provides a better search experience for the user.
<locale name="zh-Hant">
<artist_name>朴志胤</artist_name>
<phonetic_name>Pǔ Zhì Yìn</phonetic_name>
</locale>
Localized Booklet Artist (required within the <locale> tag when it appears within the <artist> tag; <phonetic_name> is optional; can be updated, but may require a ticket; see Content Update Behavior)
In this example, the <locale> specifies that the localization in the enclosed <artist_name> tag is Mandarin Chinese written in traditional characters. The language subtag (zh) indicates Mandarin Chinese and the script subtag (Hant) indicates that the language is written in traditional characters (as opposed to simplified). Note that the script subtag is currently supported only for Chinese (Mandarin), and is required for textual metadata where the language is Chinese.
Acceptable locales for Chinese written language include:
zh-Hant (Mandarin Chinese traditional script)
zh-Hans (Mandarin Chinese simplified script)
As a best practice, supply the booklet title in both traditional (Hant) and simplified (Hans) script when available.
Do not provide a region tag for Chinese metadata text. (For example, do not use "zh-Hant-TW".)
The <phonetic_name> tag (optional) should only be used where the language is Japanese, Chinese, Korean, Thai, Russian, Bulgarian, or Ukrainian. For Chinese, the tag provides the reading of the artist in Pinyin. If any meaningful separation units exist they should be delimited using a space character. Providing the phonetic name provides a better search experience for the user.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for artist names. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
Title and Artist Localizations Metadata Video Example
The following metadata example shows a music video by the Japanese artist Sheena Ringo. The video is to be sold on the Japanese Store so the language used in the metadata is Japanese (the <language> tag directly below <package>). In addition, English localizations for the title and artist are delivered in the metadata.
Title and Artist Localizations Metadata Video Annotations
Only the tags relevant to title and artist localization support are described. Refer to Music Video Album for annotations on the remaining tags.
<language>ja</language>
Language (required)
The primary language of the metadata for this video package. Titles and artist names are expected to appear in this language. In this example, the video is in Japanese and is to be sold on the Japanese Store, so the language in the <language> tag is Japanese. The video will also be sold where English is spoken, so English localizations can be delivered in the metadata.
Video Title (required; can be updated, but may require a ticket; see Content Update Behavior)
The title of the video in the primary language of the package (see <language> above); in this example, the primary language is Japanese.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for video titles. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
<phonetic_title>ありあまるとみ</phonetic_title>
Video Phonetic Title (optional; can be updated, but may require a ticket; see Content Update Behavior)
The phonetic title of the video in Japanese.
The <phonetic_title> tag (optional) should only be used where the language is Japanese, Chinese, Korean, Thai, Russian, Bulgarian, or Ukrainian. For Japanese, the tag provides the reading (furigana) of the video title in full-width Hiragana or Katakana. For Chinese, the tag provides the reading of the video title in Pinyin. If any meaningful separation units exist they should be delimited using a space character. Delivering the phonetic title provides a better search experience for the user.
<title_version>ライブ・バージョン</title_version>
Video Title Version (optional)
The title version of the video in Japanese.
To remove an existing title version, send an empty tag: <title_version/> or <title_version></title_version>.
<locales>
Locales (optional)
Provides a mechanism to specify localizations for video title and the optional title version. In this example, English is being delivered.
<locale name="en">
<title>The Invaluable</title>
Localized Video Title (<title> required within the <locale> tag; can be updated, but may require a ticket; see Content Update Behavior)
The title and title version (optional) of the video localized into the language specified in the enclosing <locale> tag.
<title_version>Live Version</title_version>
Localized Video Title Version (optional)
The title version of the video localized into the language specified in the enclosing <locale> tag.
To remove an existing title version, send an empty tag: <title_version/> or <title_version></title_version>.
</locale>
</locales>
<artists>
<artist>
<artist_name>椎名林檎</artist_name>
<apple_id>74576999</apple_id>
Video Artist Name (required; can be updated, but may require a ticket; see Content Update Behavior)
Name or Apple ID for each artist on the video in the primary language of the package (see <language> above); in this example, the primary language is Japanese. Note that the <artist> block also includes the artist’s role (the <role> tag) and primary status (the <primary> tag). See Basic Music Album Metadata Annotated for tag annotations.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for artist names. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
Artist names will appear on Apple Music and the iTunes Store in the order in which they are specified in the provided metadata.
<locales>
Locales (optional)
Provides a mechanism to specify localizations for video artists. If the video is to be sold on a Store using a language other than the one specified in the <language> tag, you must supply translations for those Stores.
<locale name="en">
<artist_name>Sheena Ringo</artist_name>
</locale>
Localized Video Artist(required within the <locale> tag when it appears within the <artist> tag; can be updated, but may require a ticket; see Content Update Behavior)
The name of the video artist localized into the language specified in the enclosing <locale> tag.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for artist names. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
</locales>
</artist>
</artists>
</video>
</package>
Booklets
Overview
One or more booklets may optionally be included with an album. A booklet can be any track in the album; booklets are no longer required to be the last track. If an album has more than one volume, the <volume_number> tag is required for booklets. See Overview for an example of a multi-volume album.
See the iTunes Video and Audio Asset Guide for details regarding acceptable file types and other relevant details. Note that booklets of any type or file extension other than those specified in the iTunes Video and Audio Asset Guide will be rejected, and the entire associated package will fail import.
In the 5.0 version of the schema, the <bonus_material> tag was deprecated and replaced by the <booklet> tag. If you send metadata that includes the <bonus_material> tag, you will see a warning; at some point in the future, delivery will fail.
If you send a metadata update to a prior delivery that used the old <bonus_material> structure, you must use the new <booklet> structure. Your update delivery using <booklet> will be compatible with the existing album that used <bonus_material>. If you perform a metadata lookup on existing content previously delivered with the <bonus_material> structure, the <booklet> structure will be returned.
A booklet is described in the album package’s metadata.xml file by adding a <booklet> XML tag. There must be one <booklet> tag for each booklet file added.
Booklet Asset
The asset is the actual file that will be downloaded from the iTunes Store and is delivered to Apple in the same way as audio track assets: it must be included in the package directory alongside the metadata and audio, and must be referenced in the metadata.xml file.
However, unlike for-sale track assets, booklet assets do not have FairPlay DRM applied to them. The customer can only obtain the booklet by purchasing the entire associated album, and after initial purchase, its use is not controlled.
Important: PDF booklets are currently the only accepted type of booklets. Albums containing QuickTime movie assets will be rejected at time of delivery.
Booklet Metadata Example
In this example, a PDF document is delivered in an iTunes Package as a booklet.
The additional XML for the booklet is shown in bold below. Some of the tags are optional. See the Booklet Metadata Annotations for details.
Only the additional tags added for booklets are described. Items marked "required" below are required only if a booklet is to be included.
<booklet>
Booklet (required)
Identifies a booklet within the metadata. Any number of booklets may be included in a package.
<vendor_id>GBBFT0501345</vendor_id>
Vendor Identifier (required)
A unique and unchanging identifier for this booklet. Only has to be unique with respect to the vendor identifiers of any other booklets included in the same package.
Important: Vendor identifiers may only contain alphanumeric characters and the underscore mark; they may not contain spaces, other punctuation or symbols, and must not start with an underscore. The vendor identifier is case-sensitive.
<title>Digital Booklet - Medúlla</title>
Title (required)
The title of the booklet, as it will appear on the iTunes Store and the purchaser’s Library.
The naming convention for PDF booklets is "Digital Booklet - album name"
<copyright>2004 One Independent</copyright>
Copyright (required; can be updated)
The copyright of the booklet, as it will appear on the iTunes Store.
<volume_number>1</volume_number>
Booklet Volume Number (optional on a single-volume album)
The volume number (that is, disc number) on which the booklet resides. If specified, it must be a positive integer. If omitted, the booklet is assumed to be on volume one. If an album has more than one volume, the <volume_number> tag is required for booklets.
<track_number>3</track_number>
Booklet Track Number (required)
The track number identifies the order in which the booklet appears. A booklet can be any track in the album; booklets are no longer required to be the last track.
The booklet must be ordered sequentially over the entire album, which means that the booklet starts with whatever the next track number would have been on the album. The album in this example has two song tracks; the track number for the booklet is 3.
Note that the booklet track must be counted in the total <track_count> tag. In this example, the <track_count> is 3: two song tracks and one booklet.
Denotes whether or not a booklet contains explicit content. May be clean, explicit, or none. If omitted, none (that is, a booklet for which neither a clean or explicit version exists) is assumed.
Important: A booklet must only be marked clean if it is an edited version of the original explicit form of the booklet.
<products>
<product>
<cleared_for_sale>true</cleared_for_sale>
Cleared For Sale (optional; can be updated)
Specifies whether the booklet is cleared for download in the territory for the product. Must be true. If not specified, the default is true.
Note: If you leave out the <products> block for a booklet track on initial import, the booklet will inherit the product information from the album playlist level. See the annotation for the <products> tag for the album in Basic Music Album Metadata Annotated.
Name or Apple ID, 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 booklet).
For booklets, at least one artist must be designated as Primary. You can designate others as Primary as well, but there must be at least one.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for artist names. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
Information identifying the file within the package that contains the actual booklet asset (downloadable file).
This tag and all sub-tags are optional as it is permitted to initially deliver the booklet metadata and then deliver the asset in a subsequent package update.
When the <file> tag is present, the <file_name>, <size>, and <checksum> tags are required. See the annotation of these tags in Basic Music Album Metadata Annotated for details of their contents.
</booklet>
Pre-Orders
Pre-Orders/Pre-Adds
You can deliver pre-release content in two ways: as pre-orders for iTunes Store or as pre-adds for Apple Music.
Pre-Orders
An album is eligible for automated pre-order for one or more territories when the <preorder_sales_start_date> tag is included in the metadata for each territory (album product) in which the pre-order should be offered.
There are two delivery options for pre-orders:
"Asset-complete," delivering all assets required in the initial content delivery.
"Metadata-only," delivering just the metadata with pre-order information and then delivering the assets at a later date. Note that not all providers have access to this feature.
Once it is activated, the pre-order becomes available on the date specified in all territories that have a <preorder_sales_start_date>. Optionally available are <preorder_previews> which provide the same song and video previews for pre-orders as are available for all products on Apple Music and the iTunes Store.
When the pre-order period ends, the pre-orders fulfill on the <sales_start_date> or "street date," for each territory.
Important: Pre-order only tracks must appear at the end of an album. If they are not, all tracks following the pre-order only content will not appear on Apple Music or the iTunes Store. Only <booklet> can appear after pre-order only content.
Pre-Adds
On Apple Music, you can set up an album for “pre-add.” This allows users to add an album into their library during a pre-release period. As a new song becomes available, it is automatically added to the album in the library.
To set up a pre-add album, deliver it as a pre-order for the iTunes Store, with at least one instant-gratification track included. Pre-add does not require a dedicated tag to set up. Note that pre-add is not supported for singles.
Pre-Order Types
Pre-order tracks can be classified by type using the <preorder_type> tag: standard, preorder only, or instant-gratification.
Any song, video, or booklet can be designated as "preorder only," meaning that it will only be received by customers who purchase the album as a pre-order. Note that the <preorder_type> is specified at the track-level, rather than at the level of album products. Therefore, when <preorder_type>preorder only</preorder_type> is used, items become pre-order only in all territories where a pre-order is available.
If you assign a track “instant-gratification” pre-order type, purchasers who pre-order the album can download the tracks immediately, both during and after the pre-order period; they do not have to wait until the album is available for sale. You can also stagger the release of instant-gratification tracks so that different tracks can have different sales start dates, leading up to the album's street date. You can specify up to 50% of the album tracks as instant-gratification tracks.
Asset-Complete Pre-Order Metadata Example
This example shows a global pre-order, with four audio tracks (including two instant-gratification tracks with staggered sales start dates) and a pre-order only video track.
Only the additional tags added for pre-orders are described.
Album Metadata Fields
<preorder_upc>8899642874956</preorder_upc>
Pre-order UPC (optional; can be updated if not previously provided, otherwise cannot be updated)
Identifier for the album pre-orders used for reporting transactions associated with pre-orders both during the pre-order period and ongoing fulfillments of pre-orders after the pre-order period. Supplying this identifier allows you to specify a distinct UPC for the pre-order as opposed to the released version of the album. The identifier may be UPC (Universal Product Code), EAN (European Article Number) or JAN (Japanese Article Number). UPC is 12-digit code mainly used for the US market. Both the EAN and JAN have 13 digits. All of these identifiers require a check digit, generated mathematically from the rest of the number for consistency checking purposes.
The Pre-Order UPC must be unique—it must not be the same as any existing <upc> or <preorder_upc> across all products from the same provider.
<preorder_grid>C2330239R00011401T</preorder_grid>
Pre-order GRid (optional; can be updated if not previously provided )
The GRid (Global Release Identifier) for the album during the pre-order period. The Pre-order GRid must be unique–it must not be the same as any existing <grid> or <preorder_grid> across all products from the same provider.
Important: The GRid must not be more than 18 alphanumeric characters. The GRid cannot contain dashes, spaces, underscores, other punctuation, or symbols.
<preorder_previews>true</preorder_previews>
Pre-order Preview Availability (optional; can be updated)
Indicates whether or not a pre-order’s media will be available for preview during the pre-order period. Note that this only affects preview availability during the pre-order period. When the pre-order ends and the album is released for sale, previews will be available regardless of this flag.
Allowed values are true and false. If the <preorder_previews> tag is omitted in an initial upload, it is assumed false and previews will not be available during the pre-order period. If this tag is omitted in an update, it is interpreted to mean no change to the value originally sent.
Important: This tag is available at the album-level only, and applies to every territory and every track.
Incentive Pricing: Pre-Order Wholesale Price Tier (optional; can be updated)
Indicates the wholesale price tier for the album in the specified territory during the pre-order period, which is the time span between <preorder_sales_start_date> and <sales_start_date>. Must be a wholesale price tier number as specified in your contract with Apple and must correspond to a wholesale price that is less than the wholesale price of the <wholesale_price_tier>. Use this tag to provide incentive pricing during the pre-order period. If you do not supply this tag, the <wholesale_price_tier> will be used during the pre-order period. If you use both the <wholesale_price_tier> and the <preorder_wholesale_price_tier> during the pre-order period, the <preorder_wholesale_price_tier> will be respected.
Note: This tag cannot be used within an <interval> block; it is only valid within a <product> block at the <album> level.
Pre-order Sales Start Date (optional; can be updated)
Indicates the date on which a pre-order should become available in the specified territory.
The pre-order ends (and fulfills) on the <sales_start_date> of each territory. Note that the maximum length of the pre-order period is 366 days. This means that the date specified with the <preorder_sales_start_date> tag cannot be more than 366 days prior to the date specified with the <sales_start_date> tag.
If a <preorder_sales_start_date> is not specified for a given territory’s album product then the pre-order will not be available in that territory. The presence of this tag therefore enables pre-ordering on a per-territory (product) basis.
The <preorder_sales_start_date> tag can be updated if the updated value is not in the past (that is, not earlier than the current date) and if the date is not later than the <sales_start_date>.
Updates: When sending a metadata update, if you omit the <preorder_sales_start_date> tag, the date previously delivered is not changed and remains in effect. To remove the existing pre-order sales start date, send an empty tag: <preorder_sales_start_date/>.
<cleared_for_stream>true</cleared_for_stream>
Album Cleared for Streaming (optional; can be updated)
Indicates if the album can be streamed on demand. Allowed values are true and false.
Set the value to true if you have the rights to distribute the album for streaming; set the value to false to if you do not have the rights to streaming. (If you have rights to stream individual tracks, see the annotation below for track-level <cleared_for_stream>.)
Tip: If you have the rights to stream most tracks on an album, you could use <cleared_for_stream> at the album <product> level set to true, and use <cleared_for_stream> at the track <product> level set to false for each track that cannot be streamed.
In some cases, a provider might only have streaming rights; in that situation, <cleared_for_sale> would be set to false and <cleared_for_stream> set to true.
If you omit the tag, the previously delivered value remains the same. If you have never delivered the tag, the default value is null for streaming. The result is false if the content is not available for sale and true if the content is available for sale.
<stream_start_date>2019-10-22</stream_start_date>
Album Stream Start Date (optional; can be updated)
Indicates the date that the album should be available for streaming. The date must be in the format YYYY-MM-DD. If you do not specify a date, the content is made available for streaming immediately after normal quality assurance processing.
The specified date applies to all tracks on the album. If a specific track should be released for streaming on a date different from that of the album release, use the <stream_start_date> tag at the track level.
Note: The album level stream start date should match with the earliest track level stream start date. For example, if you have an instant gratification track with the <stream_start_date> set to 10/01/2020, but the album <stream_start_date> is set to 10/05/2020, the instant gratification track will not go live until 10/05/2020. In this case, you would set the album <stream_start_date> to 10/01/2020.
Indicates how this track or video will be treated in a pre-order situation. Available options are:
preorder only: the track will only be available as part of the pre-order and will not appear on the album after street date
instant-gratification: the purchaser can download the track or video both during and after the pre-order period. You can specify a date for the release of each instant-gratification track using the <sales_start_date> tag; if you do not specify a date, the instant-gratification track goes live on the album's <preorder_sales_start_date>.
standard: the track or video will appear normally on the album and all customers may purchase it
Up to 50% of the album's tracks can be specified as instant-gratification tracks. Instant-gratification tracks should be listed in the order they appear on the album and should appear before the “Preorder only” tracks. “Preorder only” tracks must appear at the end of an album. If they are not, all tracks following the pre-order only content will not appear on Apple Music or the iTunes Store. Only <booklet> can appear after pre-order only content.
Notes:
An instant-gratification track must be cleared for sale in every territory in which the pre-order is sold (<cleared_for_sale> must be set to true in each territory).
Apple requires that instant-gratification items be less than 10 minutes long; instant-gratification items that are longer than 10 minutes will be blocked. Also, an "album-only" track cannot be an instant-gratification track.
If the preorder type is not set to preorder only or instant-gratification, standard is assumed and the track or video is available after the pre-order period.
<track>
<products>
<product>
. . .
<sales_start_date>2019-10-22</sales_start_date>
Pre-Order Track Sales Start Date (optional; can be updated)
Indicates the date on which the instant-gratification track should become available in the specified territory. Use this tag when you want the instant-gratification track to be sold on a date later than the album's pre-order sales start date, but before the album's street date. The date must be in the format YYYY-MM-DD and it must fall between the album's pre-order sales start date and the album's sales start date.
If the <sales_start_date> is omitted on the instant-gratification track (as in track 3 of the example above), the instant-gratification track goes live on the album's <preorder_sales_start_date>.
<cleared_for_stream>true</cleared_for_stream>
Track Cleared for Streaming (optional; can be updated)
Indicates if the track can be streamed on demand. Allowed values are true and false.
Set the value to true to if you have the rights to distribute the track for streaming.
Set the value to false to if you do not have the rights to streaming.
Tip: If you have the rights to stream an entire album except for one track, you could use <cleared_for_stream> at the album <product> level set to true, and use <cleared_for_stream> at the track <product> level set to false for the track that cannot be streamed.
If you omit the tag, the previously delivered value remains the same. If you have never delivered the tag, the default value is null for streaming. The result is false if the content is not available for sale and true if the content is available for sale.
<stream_start_date>2019-10-22</stream_start_date>
Track Stream Start Date (optional; can be updated)
Indicates the date that the track should be available for streaming. The date must be in the format YYYY-MM-DD. If you do not specify a date, the content is made available for streaming immediately after normal quality assurance processing.
If the album is set to stream on a certain date, a specific track can be released for streaming on a date different from that of the album release using this tag, if necessary. Note that if the track stream start date is set earlier than the album stream start date, the track won’t go live until the album stream start date.
</product>
</products>
Metadata-Only Pre-Order Metadata Example
This example shows the same global pre-order as above, but without audio or video assets included. Note that cover art is still required. Refer to Basic Music Album Metadata Annotated for Album Artwork tag details.
Pre-Order Sales Start Date (optional; can be updated)
To remove a pre-order, send a <preorder_sales_start_date> tag without any value specified (called an empty tag). For example, send one of the following within the <product> block:
Delivering the metadata without the tag does not remove the pre-order; you must explicitly send the tag as an empty tag.
Classical Works Support
Classical Works Support
This is used exclusively for classical titles, where the work uniquely defines a complete classical composition containing two or more tracks.
Standard examples of works are concertos, sonatas and symphonies which can be divided into individual movements at the track level. The <work> tag is used to define the name and content of each "work" and includes all tracks contained in the given work. For example, "Symphony No. 5 in C Minor, Op. 55" would be the work name for Beethoven's 5th Symphony and all four movements would then be bundled together for a customer to purchase independently of the album.
Note that not all classical pieces are classified as "works." For example, opera arias, overtures and incomplete selections from a ballet or suite may not use this functionality and doing so will increase processing time.
If there are multiple complete works on a given album—in this case, Beethoven's 5th Symphony paired with the 5th Piano Concerto—there would be two separate <work> tags in the metadata.xml:
Work 1: Symphony No. 5 in C Minor, Op. 67
Track 1: Symphony No. 5 in C Minor, Op. 67: I. Allegro con brio
Track 2: Symphony No. 5 in C Minor, Op. 67: II. Andante con moto
Track 3: Symphony No. 5 in C Minor, Op. 67: III. Allegro
Track 4: Symphony No. 5 in C Minor, Op. 67: IV. Allegro
Work 2: Piano Concerto No. 5 in E-Flat Major, Op. 73 - "Emperor"
Track 5: Piano Concerto No. 5 in E-Flat Major, Op. 73 - "Emperor": I. Allegro
Track 6: Piano Concerto No. 5 in E-Flat Major, Op. 73 - "Emperor": II. Adagio
Track 7: Piano Concerto No. 5 in E-Flat Major, Op. 73 - "Emperor": III. Rondo
For albums with multiple works (for example, a collection of Piano Sonatas), all the collected tracks within a given work need to be sequential on the album and all the specified works must be complete (that is, have all tracks present). If a sonata is recorded attaca (that is, a three-movement work recorded as a single track running 12 minutes), this should not be regarded as a work.
Work (optional; can be updated (except the work name)
Longer music such as concertos or symphonies are divided into movements, or "works." This tag is used exclusively for classical titles to define the name and content of each "work," and includes all tracks in that work as in the above example.
You may define multiple works on an album, and not all tracks on the album must be part of a work, but all tracks within a given work must be sequential and the work must be complete (that is, not missing any tracks).
Important: If using this tag, a name is required and the name cannot be updated.
Interval Pricing
Overview
This chapter specifies the iTunes Package format for delivering pricing in an interval format. You can deliver interval pricing for albums and individual tracks. Using interval pricing, you can set prices over an unlimited number of specific time periods. Interval pricing, if used, replaces the previous pricing model. You are not required to use interval pricing. Use intervals only when you want the price to change automatically. 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.
This chapter describes the metadata.xml for delivering interval pricing only. To see the complete annotations, see Basic Music Album Metadata Annotated. For questions, contact your Apple 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
Interval pricing allows an album's or track’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.
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 above Basic Music Album example) can 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 U.S., 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 on the iTunes Store 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 Interval Pricing Examples).
If two intervals overlap, the last interval specified in a given metadata update will take precedence.
Product updates should contain all known pricing intervals from date of delivery forward.
Interval Pricing Examples
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.
Example 1
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
Jun
Jul
Aug
Sept
Oct
Nov
Dec
Jan
Tier 3
Tier 2
All intervals are collapsed into a single timeline when processed by Apple. The above two intervals will therefore collapse into the following:
May
Jun
Jul
Aug
Sept
Oct
Nov
Dec
Jan
Tier 3
Tier 3
Tier 2
Example 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
Jun
Jul
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
Jun
Jul
Aug
Sept
Oct
Nov
Dec
Jan
Tier 3
Tier 3
Tier 3
Tier 3
Tier 3
Tier 3
Tier 3
Tier 3
Tier 3
Tier 2
Tier 2
Example 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
Jun
Jul
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
Jun
Jul
Aug
Sept
Oct
Nov
Dec
Jan
Tier 3
Example 4
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
Jun
Jul
Aug
Sept
Oct
Nov
Dec
Jan
Tier 3
Tier 2
Tier 3
The intervals as implemented:
May
Jun
Jul
Aug
Sept
Oct
Nov
Dec
Jan
Tier 3
Tier 2
Tier 3
Interval Pricing Update Example
All intervals supplied in metadata updates will be applied in the same manner as described in Interval Pricing Examples.
Example
Three intervals currently exist in the iTunes database (as created by previous deliveries):
May
Jun
Jul
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
Jun
Jul
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
Jun
Jul
Aug
Sept
Oct
Nov
Dec
Jan
Tier 3
Tier 2
Interval Pricing Metadata Example
For the sake of brevity, only two audio tracks are shown. Changes made for interval pricing are in bold.
Begin the product in the same manner of the basic music album. The territory specified here is the only one affected by the intervals defined within this product tag.
<intervals>
Interval Declaration (required)
The beginning of a group of intervals for a specific territory.
<interval>
Interval (required)
The beginning of an individual interval for a specific territory. This interval applies only to the territory specified in the <product> tag. Any number of intervals can be provided in an initial product delivery or subsequent updates.
<start_date>2008-07-01</start_date>
Interval Start Date (required except for the first interval; can be updated)
The start date for the given interval in YYYY-MM-DD format. For the first start date, this tag must either be omitted or must be set to the current date (the same day that the import is sent). For subsequent start dates, the date may be any point in the future.
If you leave out the <start_date> tag for the first interval, the interval starts immediately by default. If the <start_date> of the first interval is other than the current date (either by default or by explicitly sending the current date), delivery will fail.
<end_date>2008-10-01</end_date>
Interval End Date (optional; can be updated)
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 YYYY-MM-DD format. If the end date is not specified, the interval will last until the start date of the following interval. If no further intervals are specified, the interval will last indefinitely.
<wholesale_price_tier>3</wholesale_price_tier>
Interval Wholesale Price Tier (optional; can be updated)
The wholesale price tier for the album for the given interval. Must be a wholesale price tier number as specified in your contract with Apple.
See 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. Speak to your Apple Technical Representative for more details.
</interval>
</intervals>
<sales_start_date>2008-01-22</sales_start_date>
. . .
</product>
</products>
Product (required; can be updated)
The rest of the product tag remains the same as the Basic Music Album, except for pricing. When interval pricing is used, pricing may not be located outside of the <interval> tag.
Track Interval Pricing Metadata Fields
<product>
<territory>IE</territory>
Product (required; can be updated)
Begins the product block for the track. The territory specified here is the only one affected by the intervals defined within this product tag.
<intervals>
<interval>
Interval (required)
The beginning of an individual interval for a specific territory. This interval applies only to the territory specified in the <product> tag. Any number of intervals can be provided in an initial product delivery or subsequent updates.
<start_date>2008-08-01</start_date>
Interval Start Date (required except for the first interval; can be updated)
The start date for the given interval in YYYY-MM-DD format. For the first start date, this tag must either be omitted or must be set to the current date (the same day that the import is sent). For subsequent start dates, the date may be any point in the future.
If you leave out the <start_date> tag for the first interval, the interval starts immediately by default. If the <start_date> of the first interval is other than the current date (either by default or by explicitly sending the current date), delivery will fail.
<end_date>2008-10-01</end_date>
Interval End Date (optional; can be updated)
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 YYYY-MM-DD format. If the end date is not specified, the interval will last until the start date of the following interval. If no further intervals are specified, the interval will last indefinitely.
<wholesale_price_tier>100</wholesale_price_tier>
Interval Wholesale Price Tier (optional; can be updated)
The wholesale price tier for the track for the given interval. Must be a wholesale price tier number as specified in your contract with Apple.
See Wholesale Price Tiers for a list of available price tiers for albums and tracks. 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. Speak to your Apple Technical Representative for more details.
</interval>
</intervals>
<sales_start_date>2008-01-22</sales_start_date>
. . .
</product>
</products>
Product (required; can be updated)
The rest of the product tag remains the same as the Basic Music Profile for tracks, except for pricing. When interval pricing is used, pricing may not be located outside of the <interval> tag.
Ringtones
Overview
This chapter specifies the iTunes Package format for delivering ringtones to the Store. You can send an audio file pre-cut to the length of the ringtone or you can send an audio file of any duration and use tags to specify the start time and optional duration of the ringtone. If you do not specify a duration, Apple trims the audio file 30 seconds from the start time you set.
Use the XML tags described in this chapter to deliver a ringtone customers will be able to purchase. Deliver the ringtone in an iTunes Package directory that contains the XML, the audio file, and cover art. Each package represents a single ringtone product within the Store. A ringtone can only be delivered in its own package; a ringtone cannot be added as a track on an album with other tracks.
There are two mandatory tags specific to ringtones:
<album_type> identifies the album as a ringtone
<type>ringtone</type> under <track> specifies the track as a ringtone as opposed to a regular song
Additional tags have been added that are optional (for example, <source_isrc>, <source_grid>, and so on) and are used to reference the master song the ringtone is cut from.
The examples and annotations cover the tags specific to ringtones. For complete explanations of other tags, see Basic Music Album Metadata Annotated.
For questions, contact your Apple Technical Representative.
Pre-Cut Ringtone Metadata Example
The metadata example is used to deliver one ringtone for individual sale in the Store.
The xmlns (for XML namespace) attribute is required and is needed for schema validation. It is used to declare the namespace (and associated schema) to which the tags in the XML are expected to conform. The namespace must be:
http://apple.com/itunes/importer
The version attribute is required and should refer to the version of the specification used to create the metadata. The “music” portion of the attribute must be in lowercase letters.
Provider Metadata Fields
<provider>ABCMusic</provider>
Provider (required, Apple-supplied)
This value should be the Apple-defined provider shortname used for partner identification. Contact your Apple Technical Representative for this value.
Ringtone Metadata Fields
<album>
<album_type>ringtone</album_type>
Album Type (required)
Specifies that the “album” being delivered is a ringtone. You must indicate the type as ringtone to distinguish it from a standard album.
<upc>10000000020081</upc>
Ringtone Album UPC (optional if GRid supplied; cannot be updated)
Identifier for the ringtone. This may be UPC (Universal Product Code), EAN (European Article Number) or JAN (Japanese Article Number). UPC is 12-digit code mainly used for US market. Both the EAN and JAN have 13 digits.
Supplying the ringtone identifier is required; but you can use either <upc> or <grid> as the ringtone identifier.
<grid>A10302B00002427900</grid>
Ringtone Album GRid (optional if UPC supplied)
The GRid (Global Release Identifier) for the ringtone. GRids must be unique across all products.
Supplying the ringtone identifier is required; but you can use either <upc> or <grid> as the ringtone identifier.
Important: The GRid must not be more than 18 alphanumeric characters. The GRid cannot contain dashes, spaces, underscores, other punctuation, or symbols.
<title>So It Goes</title>
Ringtone Album Title (required; can be updated, but may require a ticket; see Content Update Behavior)
The title of the ringtone. This would typically be the name of the song the ringtone is cut from.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for ringtone album titles. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
Original Album Release Date (required; can be updated)
The original date of the first consumer-available song release from which the ringtone is cut. This is the field presented to the customer in the Store interface.
This field is cosmetic only and does not impact "available date" or "street date" on the Store.
This field must be in YYYY-MM-DD format.
<label_name>ABC Records</label_name>
Ringtone Album Label Name (required; can be updated)
The name of the label that released the ringtone album.
<genres>
<genre code="ROCK-00"/>
<genre code="POP-00"/>
</genres>
Ringtone Album Genres (required; can be updated, but may require a ticket; see Content Update Behavior)
Genres to associate with the ringtone. Apple recommends content providers to define at least one but no more than two genres.
For a complete list of genres, click Resources and Help on iTunes Connect to download the spreadsheet titled “Music, Music Video, and Ringtone Genre Codes.”
Important: Genre information may be reassigned at the discretion of Apple.
Ringtone Album Copyright P-Line (optional; can be updated)
Performance copyright line for the ringtone album. Must follow the format YYYY copyright info as in the example. Do not add the ℗ symbol or “p”; it will be added automatically.
Artwork must be provided for the ringtone album to be used in the Store and when it is purchased. The <file_name>, <size>, and <checksum> tags are required. See the annotation of these tags in Basic Music Album Metadata Annotated for details of their contents.
Ringtone album artwork can be 800 by 800 pixels, but Apple recommends delivering 1400 by 1400 pixels for best results. Refer to the iTunes Video and Audio Asset Guide for more details and asset file requirements.
<products>
<product>
<territory>US</territory>
<sales_start_date>2009-09-05</sales_start_date>
</product>
Ringtone Album Product (required; can be updated)
For each territory in which a ringtone album is to be sold there must be a defined product.
Ringtone Album Artists (required; can be updated, but may require a ticket; see Content Update Behavior)
Name or Apple ID, primary status, and roles for each artist. 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 single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for artist names. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
Primary is used to indicate whether or not the ringtone album appears on the artist’s page in the Store.
Specifies the track as a ringtone as opposed to a regular song.
<isrc>USMPK0508101</isrc>
Track ISRC (required; cannot be updated)
The ISRC (international standard recording code) for the track. ISRCs must be unique across all recordings.
Important: ISRCs must not include dashes and should contain only letters and numbers as in the example, USMPK0508101.
<iswc>T1235996341</iswc>
Track ISWC (optional; can be updated)
The ISWC (International Standard Work Code) for the track. The ISWC is a unique identifier for a particular piece, which helps distinguish a song from other songs with similar or identical titles. The <iswc> tag can be used more than once on the same album, for example a piece could appear twice on an album: one track performed with vocals and another track could be instrumental only. This tag is currently optional; at some point in the future, you may see a warning if the tag is not delivered.
ISWCs begin with the letter “T”, followed by a nine-digit unique number (from 000000001 to 999999999), and an additional check digit at the end. The letter “T” is currently the only prefix element defined and indicates a musical work.
Important: ISWC identifiers are commonly written in the form T-123.456.789-1 with punctuation to help with readability. For the <iswc> tag, the value delivered must not include dashes or punctuation marks and should contain only letters and numbers as in the example, T1235996341.
<source_isrc>USMPK0508000</source_isrc>
Source ISRC (optional; can be updated if not previously provided otherwise cannot be updated)
Use this tag to reference the original master song that the ringtone was cut from if the master song was imported with a <isrc> tag.
This tag is optional. If the ringtone is not cut from a song on the Store, you can omit the tag. If the tag was omitted during the initial import, you can provide a value during a subsequent update. However, the value cannot be changed through an update once set.)
Important: ISRCs must not include dashes and should contain only letters and numbers as in the example, USMPK0508000.
<source_vendor_id>USMPK0502201</source_vendor_id>
Source Vendor ID (optional; can be updated if not previously provided otherwise cannot be updated)
Use this tag to reference the original master song that the ringtone was cut from if the master song was imported with a <vendor_id> tag.
Note: Apple recommends relying on GRid and/or ISRC for identifying tracks and omitting the <vendor_id> tag except in cases where an ISRC for a track is not unique on an album.
This tag is optional. If the ringtone is not cut from a song on the Store, you can omit the tag. If the tag was omitted during the initial import, you can provide a value during a subsequent update. However, the value cannot be changed through an update once set.)
Important: Vendor identifiers may only contain alphanumeric characters and the underscore mark; they may not contain spaces, other punctuation or symbols, and must not start with an underscore. The vendor identifier is case-sensitive and letters, if used, must be in uppercase.
<source_grid>A10302B00002427998</source_grid>
Source GRid (optional; can be updated if not previously provided)
Use this tag to reference the original master song that the ringtone was cut from if the master song was imported with a <grid> tag.
This tag is optional. If the ringtone is not cut from a song on the Store, you can omit the tag. If the tag was omitted during the initial import, you can provide a value during a subsequent update. However, the value cannot be changed through an update once set.)
Important: The GRid must not be more than 18 alphanumeric characters. The GRid cannot contain dashes, spaces, underscores, other punctuation, or symbols.
<title>So It Goes</title>
Track Title (required; can be updated, but may require a ticket; see Content Update Behavior)
The title of the ringtone track. This would typically be the name of the song the ringtone is cut from and can be the same as the title specified in <title> under the <album> block.
The name of the label which released the track. If not specified, the <label_name> from the album is used.
<copyright_pline>2009 ABCMusic</copyright_pline>
Track Copyright P-Line (optional; can be updated)
Performance copyright line for the track. Must follow the format YYYY copyright info as in the example. Do not add the ℗ symbol or “p”; it will be added automatically.
Important: If not specified, the copyright line from the album is used.
The audio file must be lossless and be one of these formats: WAV, FLAC, ALAC. The minimum length is 5 seconds and the maximum length is 30 seconds. Refer to the iTunes Video and Audio Asset Guide for details.
The <file_name>, <size>, and <checksum> tags are required. See the annotation of these tags in Basic Music Album Metadata Annotated for details of their contents.
<products>
<product>
<territory>US</territory>
<cleared_for_sale>true</cleared_for_sale>
</product>
</products>
Track Products (optional; can be updated)
Define a product for each territory in which the ringtone track is to be sold.
Ringtone Track Artists (optional; can be updated, but may require a ticket; see Content Update Behavior)
Name or Apple ID, primary status, and roles for each artist on the track.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for artist names. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
Primary is used to indicate whether or not the ringtone track appears on the artist’s page in the Store.
The annotations below describe only the tags used in ringtone trimming. See the annotations in Pre-Cut Ringtone Metadata Annotation for the remaining tags.
Track Metadata Fields
<tracks>
<track>
<type>ringtone</type>
Track Type (required)
Specifies the track as a ringtone as opposed to a regular song.
<tone_start_time>72</tone_start_time>
Ringtone Start Time (optional)
Define the time in seconds when the ringtone trimming should start. Apple cuts a 30 second file starting at the specified time. If the file is less than 30 seconds, Apple uses the file as provided.
This tag can be used only when the <album_type> and the track <type> is ringtone.
<tone_duration>23</tone_duration>
Ringtone Duration (optional)
To set the duration to a time other than 30 seconds, use this tag to specify the length of time in seconds. The duration must be longer than 5 seconds and less than 30 seconds.
</track>
</tracks>
</album>
</package>
Box Sets
Overview
Box sets are used to release two or more albums together to be sold as a set. The sets can cover a wide range of music by a given artist or band, such as a greatest hits collection or a compilation of all albums released during a band’s career. In addition to song tracks, a box set can include videos and booklets.
Adding a Box Set XML Example
When delivering a box set, the <track_group> tag can be used to distinguish individual albums that are part of the box set. Each <track_group> tag inside a <tracks> tag designates one individual album in a box set. Within each <track_group> tag, you can include song tracks, videos, and booklets. On Apple Music and the iTunes Store, the track group content is grouped under the group name. Customers can click the group name to expand it and see the content it contains. Each <track_group> can have its own cover art; if you do not supply cover art for an individual album, the box set cover art is used.
Note: If a double album (an album with two discs) is included as part of a boxed set, use one <track_group> for the double album and specify two volumes using the <volume_number> tag within the track group, each volume representing one album.
Box Set Metadata Example
The following example shows how to deliver a box set. The example includes two individual albums in the box set. The first album (volume 1) includes two song tracks and a booklet; the second album (volume 2) includes two song tracks and a video.
For the sake of brevity, only two track groups are shown with just a few tracks and territories in each. However, in reality, a track group may contain any number of song tracks, booklets, and video tracks, and as many territories as needed. A booklet can be any track in the album; booklets are no longer required to be the last track. In a box set, the <volume_number> tag is required for booklets.
Only the tags used to specify and deliver box sets are described. Refer to the Basic Music Album Metadata Example for detailed annotations on the other tags.
Album Metadata Fields
<album>
Album (required)
Begins the <album> block.
<vendor_id>093624970989</vendor_id>
Box Set Album Vendor ID (optional; cannot be updated)
This is the vendor ID for the whole box set and it uniquely identifies the box set in sales reporting. 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. Although a vendor identifier may contain digits, it is treated as a string, not numbers, which means a vendor identifier of '00000000012345' is not the same as '12345'. Vendor identifiers have a limit of 100 bytes. Refer to the Basic Music Album Metadata Example for detailed annotations on <vendor_id>.
Artwork Files (required; can be updated, but may require a ticket; see Content Update Behavior)
This is the album cover art for the whole box set. When the <file> tag is present, the <file_name>, <size>, and <checksum> tags are required. The artwork file should have a recommended minimum resolution of 3000 by 3000 pixels. See the iTunes Video and Audio Asset Guide for complete file requirements.
Note: Artwork for each individual album (a track group) in the box set is optional (see below for how to deliver cover art for a track group). If you do not provide artwork for the track group, the cover art for the box set will be used for the track group art.
Tracks Metadata Fields
<tracks>
Track Group Metadata Fields
<track_group>
Track Group (optional)
Identifies an individual album in a box set (which is a group of two or more tracks). At least two tracks must be included in a track group, which can include song tracks, videos, and booklets. Note that if the album contains two or more discs, specify each disc using the <volume_number> tag within the <track_group>. A booklet can be any track in the album; booklets are no longer required to be the last track. If an album has more than one volume, the <volume_number> tag is required for booklets.
<vendor_id>5099900700343</vendor_id>
Vendor Identifier (required)
The identifier for the track group. Each track group in a box set must have a unique identifier.
Note: The track group vendor identifier can have the same vendor ID as another album, as long as the identifier is unique within the box set. For example, an individual album within the box set can have the same vendor identifier as the same album sold separately.
Name for the track group. This is what the customer will see for the track group on Apple Music and the iTunes Store. When customers download the content of the track group, the specified group name appears in their Library as the album name for that content.
Artwork for the track group is optional. When the <file> tag is present, the <file_name>, <size>, and <checksum> tags are required. The artwork file should have a recommended minimum resolution of 3000 by 3000 pixels. See the iTunes Video and Audio Asset Guide for complete file requirements.
If you do not provide artwork for the track group, the cover art for the box set will be used for the track group art.
Track Group/Track Metadata Fields
<track>
Track (required)
Identifies a track within the track group. There must be one <track> tag for each song added to the track group. For videos within the track group, use the <video> tag; for booklets within the track group, use the <booklet> tag. A track group must contain two or more tracks.
<isrc>USTCZ0976948</isrc>
Track Identifier (required)
This is your identifier for this track within the track group, which can be imparted using one of several existing tags for the purpose of uniquely identifying the item on the album.
For song and video tracks, use the <isrc> tag as the track identifier. If two items in a box set (even if in different track groups) have the same ISRC, you must also supply a unique <vendor_id> tag to differentiate between the two items that have the same ISRC.
For a booklet, use the <vendor_id> tag as the track identifier.
Track Title (required; can be updated, but may require a ticket; see Content Update Behavior)
The title of the track in the track group.
<volume_number>1</volume_number>
Track Volume Number (optional)
The volume number (the individual album number within the box set) on which the track resides. If omitted, the track is assumed to be on volume one. The volume numbers must be ordered sequentially over the entire box set, which means that if the first <track_group> contained two volumes, the first volume of the next <track_group> would be volume 3.
Note: If a double album (an album with two discs) is included as part of a boxed set, use one <track_group> for the double album and specify two volumes using the <volume_number> tag within the track group, each volume representing one disc of the double album.
<track_number>1</track_number>
Track Number (required)
The track number identifies the order in which the track appears within the track group. The track numbers in each volume in a box set should always start over, which means that if the last track number of the last volume of a <track_group> is volume 2, track 24, the first track of the next volume in the next <track_group> should be volume 3, track 1.
Important: All tracks within a given track group must be sequential.
Track Group/Booklet Metadata Fields
<booklet>
Booklet (required)
Identifies a booklet. For track groups, the <booklet> tag must be nested within the <track_group> block and must be at the same level as the <track> tag.
<vendor_id>5099749642829_GBBFT0501345</vendor_id>
Vendor Identifier (required)
A unique identifier for the booklet in the box set. The identifier must be different from the vendor identifiers of any other booklets included in the same box set. The booklet vendor identifier can have the same vendor identifier as another booklet, as long as the identifier is unique within the box set.
<title>Digital Booklet - Tegan and Sara</title>
Title (required)
The title of the booklet, as it will appear on the iTunes Store and in the purchaser’s Library.
<copyright>2010 EMI Records Ltd</copyright>
Copyright (required; can be updated)
The copyright of the booklet, as it will appear on the iTunes Store.
<volume_number>1</volume_number>
Booklet Volume Number (required for booklets in box sets)
The volume number (that is, disc number) on which the booklet resides. It must be a positive integer. If an album has more than one volume, the <volume_number> tag is required for booklets. A booklet can be any track in the album; booklets are no longer required to be the last track.
<track_number>2</track_number>
Booklet Track Number (required)
The track number identifies the order in which the booklet appears. A booklet can be any track in the album; booklets are no longer required to be the last track.
The booklet must be ordered sequentially over the entire album, which means that the booklet starts with whatever the next track number would have been on the album. The album in this example has two song tracks and a booklet; the booklet is track number 2.
Note that the booklet track must be counted in the total <track_count> tag, if supplied. In this example, the <track_count> is 3: two song tracks and one booklet.
</booklet>
</track_group>
Track Group/Video Metadata Fields
<video>
Box Set Music Video (optional)
If the track group contains a video, the video content must be defined within the <video> tag. The <video> tag must be nested within the <track_group> block and must be at the same level as the <track> tag.
Depending on the structure of the box set content, you could have a <track_group> consisting of just videos.
<isrc>GBBTF0200256</isrc>
Box Set Video ISRC (required; cannot be updated)
The ISRC (international standard recording code) for the video. If two items in a box set (even if in different track groups) have the same ISRC, you must also supply a unique <vendor_id> tag to differentiate between the two items that have the same ISRC.
After you submit a package to the iTunes Store, 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 chapter explains read-only information in detail.
What is Read-Only Information?
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 IDs for album artists, among others.
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.
Read-Only Metadata Album Example
The following partial example shows where read-only information appears in the returned metadata for an album.
This key attribute ("content-review-status") supplies the current review status of the album or music video.
Before content can go live on the iTunes Store, 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:
Not Live / Waiting for Review: Content has not yet been reviewed, and must be reviewed before it can go live.
Ready / Reviewed: Content has been reviewed and will go live on the specified sales start date or pre-order start date.
Ready / Not Reviewed: Content has not been reviewed, and will go live on the specified sales start date or pre-order start date.
Live / Reviewed: Content has been reviewed, and is live based on the specified sales start date or pre-order start date.
Live / Not Reviewed: Content has not been reviewed, and is live based on the specified sales start date or pre-order date.
This key attribute ("content-review-date") supplies the date the album or music video was last reviewed. If the content has not yet been reviewed, the value null will be returned.
If the album you are looking up has any tickets associated with it, this read-only tag explains the ticket type, ticket ID, and the current status of the ticket. Ticket types can be for Metadata, Cover (for cover art), and Audio File. Statuses can include: Pending, Your Action Needed, or No Action Needed.
<read_only_value key="content-hiding-reason">Hidden: Bad Metadata</read_only_value>
Hidden Content Read-Only Value
This key attribute ("content-hiding-reason") supplies a code that represents the reason an album is hidden. For more information on the codes, see iTunes Store Music Style Guide.
A read-only info block appears in the <product> block of the album. Each <product> block is territory-specific and the <read_only_info> block applies to the product’s territory.
The key attribute is "apple-id". iTunes assigns every album a unique Apple ID. You can refer to the album by Apple ID when communicating with iTunes support instead of the album name.
Note: The Apple ID is also returned in a “comment” field <!--Apple ID: 21393649--> just below the <album> tag. That value is the same as the value in the <read_only_value> tag. When you do a metadata lookup and then redeliver that metadata, comment fields and read-only tags are ignored.
Store URL Read-Only Value
The key attribute "storeURL" indicates where this content appears on the iTunes Store, linking to the page in iTunes that shows this album for this territory. Note that the country/region code portion of the "storeURL" (the -GB in this example) refers to the territory.
A read-only info block appears in the <artist> block for the album. The read-only info in this block applies to the artist Björk; each artist will have their own read-only info block.
The key attribute is "apple-id". iTunes assigns every artist a unique Apple ID. You can refer to the artist by name (using the <artist_name> tag) or by Apple ID (using the <apple_id> tag). Apple recommends using the Apple ID to avoid the ambiguity in cases where artists share the same name. By doing a metadata lookup, you can find an artist’s Apple ID to use in any subsequent updates. You can also do an artist lookup (see Use Lookup Artist Mode in the Transporter User Guide).
Note: The Apple ID is also returned in a “comment” field <!--Apple ID: 295015--> and in an <apple_id> tag. Those values are the same as the value in the <read_only_value> tag. When you do a metadata lookup and then redeliver that metadata, comment fields and <read_only> tags are ignored, but the <apple_id> under <artist> is not ignored and has been entered in the metadata for you.
Curated Artist Read-Only Value
The key attribute is "curated-artist" and the value returned is either true or false. If the value is true and you do not have authorization to deliver for the artist, your content may be prevented from going live on Apple Music or the iTunes Store.
A read-only info block appears in the <product> block of the track. Each <product> block is territory-specific and the <read_only_info> block applies to the product’s territory.
The key attribute is "apple-id". iTunes assigns every track a unique Apple ID. You can refer to the track by Apple ID when communicating with iTunes support instead of the track name.
Note: The Apple ID is also returned in a “comment” field <!--Apple ID: 21393652--> just below the <track> tag. That value is the same as the value in the <read_only_value> Apple ID tag. When you do a metadata lookup and then redeliver that metadata, comment fields and <read_only> tags are ignored.
Store URL Read-Only Value
The key attribute "storeURL" indicates where this track appears on the iTunes Store, linking to the page in iTunes that shows this track for this territory. Note that the country/region code portion of the "storeURL" (the -GB in this example) refers to the territory.
A read-only info block appears in the <artist> block for each track. The read-only info in this block applies to the artist Björk; each artist will have their own read-only info block.
The key attribute is "apple-id". iTunes assigns every artist a unique Apple ID. You can refer to the artist by name (using the <artist_name> tag) or by Apple ID (using the <apple_id> tag). Apple recommends using the Apple ID to avoid the ambiguity in cases where artists share the same name. By doing a metadata lookup, you can find an artist’s Apple ID to use in any subsequent updates.
Note: The Apple ID is also returned in a “comment” field <!--Apple ID: 295015--> and in an <apple_id> tag. Those values are the same as the value in the <read_only_value> tag. When you do a metadata lookup and then redeliver that metadata, comment fields and <read_only> tags are ignored, but the <apple_id> under <artist> is not ignored and has been entered in the metadata for you.
Curated Artist Read-Only Value
The key attribute is "curated-artist" and the value returned is either true or false. If the value is true and you do not have authorization to deliver for the artist, your content may be prevented from going live on Apple Music or the iTunes Store.
Read-Only Metadata Music Video Example
The following partial example shows where read-only information appears in the returned metadata for a music video. See the annotations in Read-Only Metadata Album Example Annotations for more information on the read-only tags.
This chapter describes the process behind updating your content. Most tags can be updated by sending a redelivery, while other tags require a ticket. In addition, the following conditions may affect whether or not a tag can be updated:
current review status of the content
date the redelivery is sent (before or after the sales start date)
Before content can go live on Apple Music or the iTunes Store, Apple may review and confirm the quality of the metadata, cover art, and audio. Your ability to update your content changes based on the status your content is in during that review process. To see the current content review status of your content, do a metadata lookup on the package (see Use Lookup Metadata Mode in the Transporter User Guide) and locate the key="content-review-status" attribute in the <read_only_info> block:
Content has not yet been reviewed, and must be reviewed before it can go live.
Ready / Reviewed
Content has been reviewed and will go live on the specified sales start date or pre-order start date.
Ready / Not Reviewed
Content has not been reviewed, and will go live on the specified sales start date or pre-order start date.
After the Sales Start Date
Not Live / Waiting for Review
Content has not yet been reviewed, and must be reviewed before it can go live.
Live / Reviewed
Content has been reviewed, and is live based on the specified sales start date or pre-order start date.
Live / Not Reviewed
Content has not been reviewed, and is live based on the specified sales start date or pre-order date.
Content Update Behavior
By default, most tags can be updated, regardless of the content review status. When you send a metadata delivery to update those tags, the changes are applied without a review (see the definition of Pass-Through below).
Note: Most tags within the <product> block can be updated. However the <preorder_sales_start_date> and <preorder_type> tags have some restrictions:
The album <preorder_sales_start_date> can be updated if the pre-order sales start date is earlier than the sales start date of the album in the same territory and if that sales start date is in the future.
When sending a metadata update, if you omit the <preorder_sales_start_date> tag, the date previously delivered is not changed and remains in effect. To remove the existing pre-order sales start date, send an empty tag: <preorder_sales_start_date/>.
The <preorder_type> tag can be updated as long as the track has not yet been available to customers in any country/region:
- When transitioning from Standard or Pre-order only to Instant Grat, the earliest <sales_start_date> for any territory on the track cannot have been reached. If the track does not have a <sales_start_date>, the earliest <sales_start_date> for any territory on the album cannot have been reached.
- When transitioning from Instant Grat to Standard or Pre-order only, the earliest <sales_start_date> for any territory on the track cannot have been reached. If the track does not have a <sales_start_date>, the earliest <preorder_sales_start_date> for any territory on the album cannot have been reached.
Updates to the following tags will be ignored:
Language (the <language> tag under <package> and <artist>)
Provider
Vendor ID
UPC and Pre-order UPC
ISRC
GRid and Pre-order GRid
Work Name
Keep the following definitions in mind when sending metadata updates:
Pass-Through: When you send a metadata update to make changes to tags that do not require a ticket, those changes are applied without having to be reviewed by Apple; this is referred to as Pass-Through because the changes are applied automatically without a ticket and without review.
Ticket Required: For these fields, an outstanding ticket is required in order to make changes via XML. Changes will be applied to the ticket for review. When the ticket is approved by Apple, the changes will go live. If there is no outstanding ticket on the content when the XML is submitted, changes to these fields are ignored.
Ticket Optional: For these fields, changes will be applied immediately as a Pass-Through unless there is an outstanding ticket. If there is an outstanding ticket, then the changes are appended to the ticket instead of being applied immediately; when Apple approves the ticket, the changes will go live.
Create Ticket: For these fields, Apple will automatically create a ticket when you submit an update. The ticket is subject to review by Apple. When Apple approves the ticket, the change will go live. Note that you must include the returned metadata token in your metadata update (the <metadata_token> tag is returned in a metadata lookup and appears just below the <package> tag). This ensures you are using the most recent, edited version of the metadata.
The table below lists only the tags that may require a ticket in certain circumstances; it does not list the tags that are always Pass-Through or always ignored. Below each tag, review statuses are listed. Checkmarks appear in a column to indicate if the tag can be updated and under which conditions.
Album, Track, and Video Titles and Title Versions
Pass-Through
Ticket Optional
Create Ticket
Ticket Required
Cannot Be Updated
Not Live / Waiting for Review
✓
Ready / Reviewed
✓
Ready / Not Reviewed
✓
Live / Reviewed
✓
Live / Not Reviewed
✓
Album and Track Artists; Artist Apple ID; Artist ISNI (Primary, Featuring or With)
Note: When you update a primary artist, an artist where the <role> is Featuring, or an artist where <role> is With, you can add or remove the artist, change the order of the artists, or change the primary status. You cannot update an artist to correct a typo or misspelling. All other roles can be updated as a pass-through.
Pass-Through
Ticket Optional
Create Ticket
Ticket Required
Cannot Be Updated
Not Live / Waiting for Review
✓
Ready / Reviewed
✓
Ready / Not Reviewed
✓
Live / Reviewed
✓
Live / Not Reviewed
✓
Album, Track, and Video Original Release Date
Pass-Through
Ticket Optional
Create Ticket
Ticket Required
Cannot Be Updated
Not Live / Waiting for Review
✓
Ready / Reviewed
✓
Ready / Not Reviewed
✓
Live / Reviewed
✓
Live / Not Reviewed
✓
Pre-order Types
Pass-Through
Ticket Optional
Create Ticket
Ticket Required
Cannot Be Updated
Not Live / Waiting for Review
✓
Ready / Reviewed
✓
Ready / Not Reviewed
✓
Live / Reviewed
✓
Live / Not Reviewed
✓
Album and Track Genres and Flags
Pass-Through
Ticket Optional
Create Ticket
Ticket Required
Cannot Be Updated
Not Live / Waiting for Review
✓
Ready / Reviewed
✓
Ready / Not Reviewed
✓
Live / Reviewed
✓
Live / Not Reviewed
✓
Track Audio Language
Pass-Through
Ticket Optional
Create Ticket
Ticket Required
Cannot Be Updated
Not Live / Waiting for Review
✓
Ready / Reviewed
✓
Ready / Not Reviewed
✓
Live / Reviewed
✓
Live / Not Reviewed
✓
Album Cover Art
Note: This change is applied only if the checksum of the new cover differs from the checksum of the cover currently in the iTunes database.
Pass-Through
Ticket Optional
Create Ticket
Ticket Required
Cannot Be Updated
Not Live / Waiting for Review
✓
Ready / Reviewed
✓
Ready / Not Reviewed
✓
Live / Reviewed
✓
Live / Not Reviewed
✓
Music Video Cover Art
Note: This change is applied only if the checksum of the new cover differs from the checksum of the cover currently in the iTunes database.
Pass-Through
Ticket Optional
Create Ticket
Ticket Required
Cannot Be Updated
Not Live / Waiting for Review
✓
Ready / Reviewed
✓
Ready / Not Reviewed
✓
Live / Reviewed
✓
Live / Not Reviewed
✓
Parental Advisory for Songs, Booklets, and Videos
Pass-Through
Ticket Optional
Create Ticket
Ticket Required
Cannot Be Updated
Not Live / Waiting for Review
✓
Ready / Reviewed
✓
Ready / Not Reviewed
✓
Live / Reviewed
✓
Live / Not Reviewed
✓
Track Group Name
Pass-Through
Ticket Optional
Create Ticket
Ticket Required
Cannot Be Updated
Not Live / Waiting for Review
✓
Ready / Reviewed
✓
Ready / Not Reviewed
✓
Live / Reviewed
✓
Live / Not Reviewed
✓
Track Group Artwork
Note: This change is applied only if the checksum of the new artwork differs from the checksum of the artwork currently in the iTunes database.
Pass-Through
Ticket Optional
Create Ticket
Ticket Required
Cannot Be Updated
Not Live / Waiting for Review
✓
Ready / Reviewed
✓
Ready / Not Reviewed
✓
Live / Reviewed
✓
Live / Not Reviewed
✓
Audio Files
Note: This change is applied only if the checksum of the new audio differs from the checksum of the audio currently in the iTunes database.
Pass-Through
Ticket Optional
Create Ticket
Ticket Required
Cannot Be Updated
Not Live / Waiting for Review
✓
Ready / Reviewed
✓
Ready / Not Reviewed
✓
Live / Reviewed
✓
Live / Not Reviewed
✓
Booklet Files
Note: This change is applied only if the checksum of the new file differs from the checksum of the booklet currently in the iTunes database.
Pass-Through
Ticket Optional
Create Ticket
Ticket Required
Cannot Be Updated
Not Live / Waiting for Review
✓
Ready / Reviewed
✓
Ready / Not Reviewed
✓
Live / Reviewed
✓
Live / Not Reviewed
✓
Recommended Contributor Roles
The tables below suggest instruments and roles when delivering credits for music. For additional roles, see the Extended Contributor Roles document and follow the formatting of the roles listed. Using the word “Performer” as a role is not recommended.
Required Roles
Primary
Featuring
With
Note: The “Featuring” and “With” roles are required only when there are special guests or featured artists.
Performer Roles
Accordion
Ensemble
Oboe
Synthesizer
Background Vocals
Fiddle
Orchestra
Tambourine
Banjo
Flute
Organ
Trombone
Bass Guitar
Guitar
Percussion
Trumpet
Bassoon
Harmonica
Piano
Viola
Bells
Harp
Programming
Viola de Gamba
Cello
Horn
Rap
Violin
Choir
Keyboards
Recorder
Vocals
Clarinet
Lute
Remixer
Whistle
Conductor
Metallophone
Sampled Artist
Xylophone
Drums
Mixed Artist
Saxophone
Production & Engineering Roles
Assistant Engineer
Graphic Design
Mixing Engineer
Recording Engineer
Co-Producer
Mastering Engineer
Producer
Composition & Lyrics Roles
Adapter
Composer
Lyrics
Songwriter
Arranger
Prices & Genres
Wholesale Price Tiers
These are the standard wholesale price tiers. This list is by no means exhaustive, so check your contract for more details, or to see if additional tiers may be applicable.
Tier
Tier Name
Album Tiers
14
Digital 451
30
Mini EP2
5
EP3
31
Mini Album One
42
Mini Album Two
1
Budget One
32
Budget Two
2
Back
33
Mid
3
Mid/Front
34
Front One4
40
Front Two4
4
Front/Plus
50
Deluxe One
51
Deluxe Two
52
Deluxe Three
53
Deluxe Four
Track Tiers
96
Lowest#
97
Low#
98
Back^
99
Mid§
100
Front
Video Tiers
98
Back
99
Mid§
100
Front
101
Japan: Premium
1 Use of this tier is limited to albums with four or fewer tracks.
2 Use of this tier is limited to albums with seven or fewer tracks.
3 Use of this tier is limited to albums with ten or fewer tracks.
4 If your contract lists only the Front tier, then Front One and Front Two are the same. Not applicable to all territories. Refer to your contract.
^ Default price tier for Japan if no tier is specified.
§ Default price tier for all territories (except for Japan) if no tier is specified.
# Not all countries or regions can use this tier. Review your contract to see a list of countries/regions that can use this tier.
Music Genres
All music 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 Apple Music or the iTunes 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 required. The following are currently supported for delivering genre information:
Required method using the genre code:
<genre code="ELECTRONIC-01"/>
Acceptable method using both the genre code and the genre label:
<genre code="ELECTRONIC-01">Electronic</genre>
If you use this method, the genre identified by code and the genre identified by genre label must resolve to the same genre, for example, <genre code="POLKA-00">Ragtime</genre> would be rejected.
Apple has expanded worldwide, and as a result, new genres have been added for new countries/regions. Because of the increased number of countries/regions, the genres have been moved from this spec to a spreadsheet titled “Music, Music Video, and Ringtone Genre Codes,” which can be downloaded from the Resources and Help section on iTunes Connect.
Language Codes
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 (http://tools.ietf.org/html/rfc5646), which is part of BCP 47. An overview of these best practices is provided here: http://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/regions. For example, there is generally not a need to distinguish between Japanese as used in one country or region 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 zh-Hant or zh-Hans.
Note: Although BCP 47 also includes support for UN M.49 region codes in addition to commonly-used alphabetic country/region codes, the only UN M.49 region code supported by iTunes 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 in the paragraphs above will be accepted, the iTunes Store only displays content in a limited set of languages as shown in the table below.
The SMPTE timecode format is expressed as: framerate/framerate multiplier/mode. The W3C standard for expressing the frame rate multiplier has changed: the colon (:) used to separate the frame rate 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 video):
Description
Effective FPS
Timecode format (<timecode_format>)
<start_time> example (HH:MM:SS:FF)
Default (legacy)
N/A
(Note: qt_text does not include frames.)
qt_text
00:55:13.124
(Note:qt_text allows milliseconds, not frames.)
NTSC Video
29.97
30/999 1000/nonDrop1
30/1000 1001/nonDrop2
00:55:09:20
NTSC Video
29.97
30/999 1000/dropNTSC1
30/1000 1001/dropNTSC2
00:55:13;00
(Note: Drop frame mode requires the use of the semicolon after the seconds.)
NTSC Film (Imprecise)
23.976
24/999 1000/nonDrop
01:08:57:02
PAL
25
25/1 1/nonDrop
01:06:11:15
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 frame rate.
Frequently Encountered Issues
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 chapter. 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?
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. Tag 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>
I don’t have a value for a tag that is shown in the XML.
For tags marked optional for which you have no value, Apple requires that you remove the tag entirely from the XML rather than leaving the tag empty. If the tag is marked required, you may not omit the tag.
Helpful Tools
These products are neither endorsed nor supported by Apple.
The following table lists the previously-released specifications and the revisions:
Date/Version
Summary
July 2023 - Version 5.3.18
A list of extended contributor roles is available in a separate document. Additional minor updates and clarifications.
February 2023 - Version 5.3.17
Minor corrections.
January 2023 - Version 5.3.16
Added information on how to specify album motion art. Made some additional corrections.
August 2022 - Version 5.3.15
Added information on specifying the International Standard Name Identifier using the <isni> tag.
Added Atmos Mixing Engineer and Atmos Mastering Engineer to the list of recommended production and engineering roles.
Additional corrections and clarifications.
October 11, 2021 - Version 5.3.14
Added a new <available_for_immersive_date> tag.
June 30, 2021 - Version 5.3.13
Clarified removal of immersive audio. Reorganized the contributor roles. Clarified immersive and Spatial Audio. Minor corrections.
May 17, 2021 - Version 5.3.12
Added immersive audio. Added new attribute for secondary ISRC. Updated tool link.
November 30, 2020 - Version 5.3.11
Added a new tag for Apple Fitness+ clearances: <cleared_for_fitness>.
August 10, 2020 - Version 5.3.10
Added “pre-add” albums. Added <original_release_date> to Content Updates chapter. Added new genres. Clarified use of phonetic titles. Added <metadata_token> tag to metadata lookup example. Removed the Subscription Services chapter.
April 6, 2020 - Version 5.3.9
Streaming tags (<cleared_for_stream> and <stream_start_date>) can be used for all music content, not just for subscription services. Interval pricing is now supported for tracks. Added new genres.
August 26, 2019 - Version 5.3.8
Changes to cover art update behavior. Changes to genres.
May 13, 2019 - Version 5.3.7
Added DJ Mix as a value for <flag>. Removed some contributor roles.
April 1, 2019 - Version 5.3.6
Added artist roles. Title versions for music and music video can be removed by sending an empty tag. The tag <audio_language> for tracks is required.
October 24, 2018 - Version 5.3.5
Added a new tag, <lyrics_set>, to deliver multiple lyrics files in different languages.
Added a new <flags> block for album and track categorization.
Deprecated <cleared_for_ticketmaster>. Added Anime Character as a vocal role. Updated genres and language codes. Clarified content identifiers.
May 2, 2018 - Version 5.3.4
The requirements for music video artwork have changed. Music video examples have changed to reflect the preference for capturing the screen capture artwork by specifying the frame to use.
February 21, 2018 - Version 5.3.3
Changes to music video screen capture art Removed references to deprecated iTunes LPs. Additional tags added to basic music example for track audio language and additional band member roles within the <artists> blocks for tracks. Minor corrections.
October 18, 2017 - Version 5.3.2
Added 4K video and HDR (high dynamic range) video in either Dolby® Vision or HDR10 format.
July 26, 2017 - Version 5.3.1
Clarified artist roles. The <original_release_date> tag can be used for song and music video tracks. New read-only tags have been added to metadata lookup. Clarified <vendor_offer_code>. Clarified schema and spec versioning.
March 15, 2017 - Version 5.3
Updated schema and spec version numbers. Clarified crop dimensions for music video. Delivering a music video artwork file is now optional. Delivering the <bonus_material> tag (which is deprecated) will display a warning.
January 26, 2017 - Version 5.2.7
Added a new tag to support delivery of lyrics in TTML format. Changes to content updates including album cover art and preorders. Minor corrections.
July 22, 2016 - Version 5.2.6
Added a <previews> block, a <preview> tag within the block, and attributes to specify the preview clip and the preview image. The <vendor_offer_code> tag can be used to track sales of tracks. Added a section that explains timecode formats. Clarifications to language codes.
May 25, 2016 - Version 5.2.5
Clarified <publisher> tag. Deprecated ad-supported iTunes Radio-related tags: <cleared_for_itunes_radio> and <cleared_for_itunes_radio_during_preorder>. Support for 4.x and lower schemas is being discontinued.
January 29, 2016 - Version 5.2.4
Added new tags to support improved sales reporting: <publishers>, <publisher>, and <iswc>.
July 30, 2015 - Version 5.2.3
Added three tags related to special clearances for radio and streaming. Clarified pre-orders, interval pricing, audio language, and gapless audio. Changes to album cover art size.
March 2, 2015 - Version 5.2.2
Languages have been added for use in the <language> and <locale> tags. Clarified maximum length of pre-orders. The role attribute on the <data_file> tag for a music video is required. Clarified music video screen capture image. Changes to Latin genres. Clarified <isrc>.
September 29, 2014 - Version 5.2.1
Added a new tag <cleared_for_itunes_radio_during_preorder>. Added the <title_version> tag for albums back into the spec. Clarified the <preorder_sales_start_date> tag. Added storefront languages for Russia and India. Added a new appendix to explain <read_only_info> tags. Minor changes to the Content Update appendix. Incorporated the Pre-Orders Addendum. Updated genre codes.
April 9, 2014 - Version 5.2
Changed the allowed length of titles and title versions for albums, tracks, videos, and booklets. 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.
February 14, 2014 - Version 5.1.2
Added an appendix to describe tag updating behavior. Territory rights and pricing can be delivered in a metadata-only update that includes only the <products> block and the content identifier. Added an XML example to Mixed Media Album chapter. Vendor offer codes can be updated. Clarified metadata updates. Added new languages supported for phonetic tags.
June 25, 2013- Version 5.1.1
Closed captions can optionally be delivered with music videos. Apple genre codes are now required. Added Cantonese Jyutping to localization metadata example.
February 6, 2013- Version 5.1
Added a new tag to reference artists by Apple ID. Added a new attribute on the <genre> tag to specify the Apple genre code. Added a new tag to indicate the language in which a song is sung. Added newly supported languages. The <volume_count> tag is deprecated and has been removed from the examples and annotations. Added ringtone trimming. The <volume> tag used in booklet examples should be <volume_number>. Track price tiers have changed for Japan and two new tiers have been added.
January 22, 2013 - Version 5.0.3
Chinese phonetic translations can now be delivered using Pinyin.
October 22, 2012- Version 5.0.2
Added interval pricing validations. Clarified delivery of booklets. Removed the text that mentioned language translations are not supported at this time except for Japanese content.
June 20, 2012- Version 5.0.1
Corrected the copyright tag in the multiple language support example for booklets. The tag <copyright_pline> has been replaced with the correct tag, which is <copyright>.
June 6, 2012- Version 5.0
Added new tags to support multiple language localizations for artist names and album, track, booklet, and video titles. New languages and music genres are supported. Changed requirements for cover art. Made changes to price tiers. Added new genres. Removed the <description> tag from all XML examples. Changed how booklet metadata is delivered. Added a section to explain how the Store handles localized content. Clarified 255-byte limit.
Changed the version number of this specification from 4.8 to 5.0 to keep the version number in sync with the schema version. There was no release of this spec for 4.9.
September 22, 2011- Version 4.8
Updated and corrected the list of language codes. Added a tag for <vendor_offer_code>. Clarified <original_release_date>. Changes made to <cleared_for_user_generated_ringtones>, <title>, <description_long> tags.
April 15, 2011- Version 4.7
Added tags to support the delivery of box sets. Changed the R&B genre to R&B/Soul. Clarified sales reporting for videos on playlists. Clarified pricing intervals. Changed the title of the Asset Specification Guide to match its new title: iTunes Video and Audio Asset Guide.
Changed the version number of this specification from 4.5 to 4.7 to keep the version number in sync with the schema version. There was no release of this spec for 4.6.
November 5, 2010- Version 4.5
Clarified use of crop dimensions for HD video source. Changed the Inspirational genre to Christian & Gospel. Incorporated the Pre-Cut Ringtones Addendum. Clarified size limits in string fields (for example, description fields).
August 4, 2010- Version 4.4
Music videos can now be delivered in HD. Added a new attribute to the <lyrics> tag to deliver song and music video lyrics styled in HTML. Clarified that album and track “artists” include composition-related contributors. Clarified Japanese price tiers.
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.
Added a list of artist roles supported. Clarified that replacing cover art requires that a ticket be open. Clarified the default price tier for Japan.
February 3, 2010- Version 4.3
Changed Health & Fitness genre to Fitness & Workout. Added the Anime genre. Corrected capitalization of genres. Corrected typo in version number. Music video cover art can be updated. Clarified that the video asset source is required for an initial delivery. Added an explanation for the xmlns attribute of the <package> tag. Added interval pricing.
November 10, 2009 - Version 4.1
Added new music genres. Clarified package version attribute name requirements. Added explanation on how to handle featured artists. Clarified pre-order previews and pre-order sales start date. Clarified that at least one artist must be designated Primary for both the album and each track.
September 11, 2009 - Version 4.0
Simplified naming of tags. Unified vendor identifier tags. <label_name> under the <track> block can be updated. Added new genres. Added the <size> tag to all data files referenced in the XML examples. Chapter image filenames must be unique. Clarified that artist roles must be in English in order to be imported.
August 10, 2009 - Version 3.3.3
<album_preorder_previews> and GRid can now be updated. Matching the <provider> name with the provider shortname used in Transporter is now enforced. Added new price tiers. Introduced new page design.
July 1, 2009 - Version 3.3.2
<track_gapless_play> can now be updated. Clarified the requirements for GRid (Global Release Identifier). Change to videos within playlists. Clarified vendor identifier, chapter titles, and image requirements. Video release dates can now be updated through metadata updates. Clarified that music videos use the <volume_number> tag, not the <track_volume_number> tag. Corrected the bonus material and pre-order metadata examples.
May 12, 2009 - Version 3.3
Introduction to takedown notices. Change with pre-order tracks. Additional fields may now be updated. Vendor identifier format restrictions are now enforced. Added track-level pricing. Changed Folk genre to Singer/Songwriter. Added a table that lists common language codes. Clarified the <language> and <provider> tags. Indicated in the metadata annotations the fields that can be updated. Deprecated <album_products>. Video artwork is now required.
August 15, 2008 - Version 3.2
Limited release draft.
May 8, 2007 - Version 3.1.1
Clarifications have been added for wholesale price tier, bonus material updates and artist names. Foreign language support has changed. New tags are now updatable through the feed. Complete example is now provided for metadata-only updates.
January 21, 2007 - Version 3.1
New items are able to be updated through the feed, Ticketmaster availability, video metadata examples clarified.
August 15, 2007 - Version 3.0
New tags added, document reorganized, restraints on title and artist field lengths, video asset-only delivery added.
April 2, 2007 - Version 2.3
Addition of classical works support, removal of <sales_end_date> tag, combination of music and music video profiles.
November 30, 2006 - Version 2.2.1
Minor updates to text.
October 24, 2006 - Version 2.2
Deprecated several tags, added chaptering, gapless audio, and revised foreign language support.
June 29, 2006 - Version 2.1
Addition of Bonus Material and Pre-Orders.
June 2, 2006 - Version 2.0
Separate Music, Music Video and TV Specifications.
What’s New in iTunes Package Music Specification 5.3.18?
Changes in iTunes Package Music Specification 5.3.15
Music Profile: International Standard Name Identifier
The International Standard Name Identifier is the ISO-certified, global standard number for identifying contributors to creative works, including performers, musicians, producers, writers, artists, and more across all disciplines. To deliver an ISNI identifier, use the optional <isni> tag within an <artist> block at the <album> level and <track> level. See Basic Music Album Metadata Annotated.
Music Profile: Tag Changes
Added
<isni>
Recommended Contributor Roles
Added Atmos Mixing Engineer and Atmos Mastering Engineer to the list of recommended production and engineering roles. See Recommended Contributor Roles.
Corrections/Clarifications
Clarified the behavior for updating artists where the <role> is Featuring or With. See Content Update Behavior.
Changes in iTunes Package Music Specification 5.3.14
Music Profile: Immersive Audio Availability Date
You can indicate that an immersive audio track be made available by territory on a date that is different from the album sales start date, the track’s sales start date, or a stereo track’s pre-order sales start date, if specified. You use the <available_for_immersive_date> tag in the immersive audio track’s <product> block for a territory. If you do not specify a date, the immersive track will be available when the stereo audio goes live for the specified territory (or immediately if the track’s stereo audio is already live). Note that the date delivered in the <available_for_immersive_date> tag must not be before the date delivered in the <stream_start_date> tag for the track; otherwise the immersive track will not go live until the stream start date.
Music Profile: Immersive Audio Removal Clarification
When replacing immersive audio, you need to remove the existing immersive audio at the same time. However, you can only remove immersive audio if it is not yet live in any territory (controlled by the <available_for_immersive_date> tag). See Immersive Audio Updates for more information.
Music Profile: Tag Changes
Added
<available_for_immersive_date>
Changes in iTunes Package Music Specification 5.3.13
Music Profile: Immersive Audio Removal Clarification
When replacing immersive audio, you need to remove the existing immersive audio at the same time. You also cannot remove immersive audio for a track if it has the downmix attribute set to true. See Immersive Audio Updates for more information.
Music Profile: Contributor Roles
The contributor roles tables have been reorganized into five categories: Standard/Generic, Performer, Production & Engineering, Composition & Lyrics, and Administrative. See Recommended Contributor Roles.
Music Profile: Cleared for Fitness
The <cleared_for_fitness> tag is available only for individual tracks, and not for the whole album. The album-level <cleared_for_fitness> tag has been removed from the examples and annotations.
Immersive and Spatial Audio: Clarification
Immersive audio and Spatial Audio refer to different things. Apple takes your audio source assets and creates immersive audio. On devices, Spatial Audio is a feature of the OS that is applied to the immersive audio for playback.
Changes in iTunes Package Music Specification 5.3.12
Music Profile: Immersive Audio
To deliver immersive audio for a track, you provide multiple audio sources that follow specific asset requirements. See "Immersive Audio Source Profile” in the iTunes Video and Audio Asset Guide for the immersive audio source requirements.
For immersive audio delivery, you use an <asset> block to deliver the audio data files for a track instead of using the <audio_file> block. You supply a role to specify the type of audio. Allowed roles for the audio data file include:
audio.2_0 for 2.0 stereo
audio.5_1 for 5.1 surround audio
audio.7_1 for Dolby Digital Plus surround audio
audio.object.based for Dolby Atmos audio
Only two audio sources per track (one stereo, one immersive) are allowed. On initial delivery, you must deliver a data file with the role audio.2_0 containing the 2.0 stereo audio source unless you instruct Apple to downmix, using the audio.transform_to.2_0 attribute. See Basic Music Album Metadata Example for metadata examples and annotations.
Music Profile: Secondary ISRC
A new, optional attribute has been added for the ISRC (International Standard Recording Code) for a track’s immersive audio recording. ISRC is used to reflect a specific recording and the immersive audio is considered a new recording. If used, you can supply the ISRC using the attribute "external_identifier.isrc" on the data file for the immersive audio. For example, <attribute name="external_identifier.isrc">GCGHY12345678</attribute>.
<assets> block can be used to deliver track audio files
external_identifier.isrc as an attribute on a datafile
Changes in iTunes Package Music Specification 5.3.11
Music Profile: Apple Fitness+ Clearances
A new tag (<cleared_for_fitness>) has been added to indicate that an album or track can be made available on Apple Fitness+. You must have an Apple fitness contract in place to use this tag.
You do not need to specify the <cleared_for_fitness> tag unless:
You want to block content that is cleared for Apple Music from being available on Fitness+.
You want to allow content that is not cleared for Apple Music to be available on Fitness+.
The table below summarizes the tag behaviors:
Value supplied with <cleared_for_fitness> tag
Available on Apple Music/Streaming
Not available on Apple Music/Streaming
true
Available for Fitness+
Available for Fitness+. The true value overrides the stream behavior.
false
Not available for Fitness+. The false value overrides the stream behavior.
Not available for Fitness+
tag unspecified
Available for Fitness+
Not available for Fitness+
Music Profile: Tag Changes
Added
<cleared_for_fitness> can be used for albums and tracks
Changes in iTunes Package Music Specification 5.3.10
Music Profile: Pre-release Content
In addition to pre-orders, you can set up an album as “pre-add.” On Apple Music, this allows users to add a pre-released album into their library. As a new song becomes available, it is automatically added to the album in the library. See Pre-Orders/Pre-Adds for information on how to set up a pre-add album.
Music Profile: Content Updates
You can send a metadata update to change the <original_release_date> of an album, track, or video. If the content metadata has been reviewed by Apple (whether ready for the Store or already live), updating the original release date requires a ticket. Apple will automatically create a ticket when you submit an update with the metadata token returned from doing a metadata lookup. See Use metadata lookup mode in the Transporter User Guide for more information. If the content metadata has not been reviewed by Apple, changes to the original release date will be applied immediately as a Pass-Through. See the chapter Content Updates for more information.
Music Profile: Subscription Services and Streaming Tags
The Subscription Services chapter has been removed. As of the 5.3.9 version of the Music Specification, the two tags (<cleared_for_stream> and <stream_start_date>) related to subscription services are included in the metadata XML for all music offerings. The tags are optional and can be used at the album <product> or track (song or music video) <product> levels.
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 Album Example for an example.
Music Profile: Phonetic Title Clarification
Do not enter phonetic title information in title tags. Whatever you enter in the <title> or <title_version> tags is displayed on the Store, so it should not include phonetic information. Use the <phonetic_title> tag to provide the phonetic information.
Genres
New genres for Africa have been added to the music, music video, and ringtone genres. The genre codes document can be downloaded from Resources and Help in iTunes Connect, but the changes are summarized in the table below.
Genre Country/Region
Changes Made
Africa
Added sub-genres to Music | African:
Music | African | African Dancehall
Music | African | African Reggae
Music | African | Afro-folk
Music | African | Afro-fusion
Music | African | Alte
Music | African | Amapiano
Changes in iTunes Package Music Specification 5.3.9
Music Profile: Streaming Tags
Two tags related to special clearances for streaming can be used in the metadata XML for all music offerings, not just for subscription services. The tags include <cleared_for_stream> and <stream_start_date>. Those tags have been added to the XML example and annotations. The tags are optional and can be used at the album <product> or track (song or music video) <product> levels.
Music Profile: Interval Pricing for Tracks
You can now deliver interval pricing on a track-by-track basis. When you deliver interval pricing for tracks, the pricing takes effect immediately, unless you set a specific start date.
Genres
Changes have been made to the music, music video, and ringtone genres. Genres have been added and reorganized. The genre codes document can be downloaded from Resources and Help in iTunes Connect, but the changes are summarized in the table below.
Genre Country/Region
Changes Made
Middle Eastern
Added sub-genres to Music | Arabic:
Music | Arabic | Levant
Music | Arabic | Arabic | Levant | Dabke
Music | Arabic | Maghreb Rai
Added sub-genres to Music | Arabic | Khaleeji:
Music | Arabic | Khaleeji | Khaleeji Jalsat
Music | Arabic | Khaleeji | Khaleeji Shailat
Added new sub-genres to existing genres:
Music | Alternative | Indie Egyptian
Music | Alternative | Indie Levant
Music | Alternative | Indie Maghreb
Music | Dance | Maghreb Dance
Music | Electronic | Electro-Cha'abi
Music | Electronic | Levant Electronic
Music | Electronic | Maghreb Electronic
Music | Folk | Iraqi Folk
Music | Folk | Khaleeji Folk
Music | Hip Hop/Rap | Egyptian Hip-Hop
Music | Hip Hop/Rap | Khaleeji Hip-Hop
Music | Hip Hop/Rap | Levant Hip-Hop
Music | Hip Hop/Rap | Maghreb Hip-Hop
Music | Pop | Egyptian Pop
Music | Pop | Iraqi Pop
Music | Pop | Khaleeji Pop
Music | Pop | Levant Pop
Music | Pop | Maghreb Pop
Added new genre and sub-genres:
Music | Tarab
Music | Tarab | Egyptian Tarab
Music | Tarab | Iraqi Tarab
Music | Tarab | Khaleeji Tarab
Russian
Moved from Music | World | Russian to Music | Russian
Added new sub-genres:
Music | Russian | Russian Bard
Music | Russian | Russian Chanson
Music | Russian | Russian Romance
Added new sub-genres to existing genres:
Music | Pop | Russian Pop
Music | Rock | Russian Rock
Music | Hip-Hop | Russian Hip-Hop
Music Profile: Tag Changes
Changed
<cleared_for_stream> can be used for albums, tracks, and videos
<stream_start_date> can be used for albums, tracks, and videos
<intervals> <interval> can be used for tracks
Changes in iTunes Package Music Specification 5.3.8
Music Profile: Content Updates
The updating behavior for album cover art has changed from Pass-Through to Ticket Optional. Changes will be applied immediately as a Pass-Through unless there is an outstanding ticket. If there is an outstanding ticket, then the changes are appended to the ticket instead of being applied immediately; when Apple approves the ticket, the changes will go live. See the appendix Content Updates for more information. Note that this change does not apply to music video cover art.
Genres
Changes have been made to the music, music video, and ringtone genres. Genres have been added and reorganized. The genre codes document can be downloaded from Resources and Help in iTunes Connect, but the changes are summarized in the table below.
Genre
Changes Made
Turkish
Moved from World | Turkish to Music | Turkish
Added new sub-genres:
Music | Turkish | Fantezi
Music | Turkish | Halk
Music | Turkish | Özgün
Music | Turkish | Religious
Music | Turkish | Sanat
Added new sub-genres of existing genres:
Music | Pop | Turkish Pop
Music | Rock | Turkish Rock
Music | Alternative | Turkish Alternative
Music | Hip Hop/Rap | Turkish Hip-Hop/Rap
Arabesque
Moved Arabesque from World | Arabesque to Turkish. Changed display name to Arabesk:
Music | Turkish | Arabesk
Africa
Changed display name to African.
Moved from World | Africa to Music | African.
Moved existing Africa sub-genres to be under African:
Music | African | Afrikaans
Music | African | Afro-Beat
Music | African | Afro-Pop
Added new sub-genres of African:
Music | African | Afro House
Music | African | Afro Soul
Music | African | Afrobeats
Music | African | Benga
Music | African | Bongo-Flava
Music | African | Coupé-Décalé
Music | African | Gqom
Music | African | Highlife
Music | African | Kuduro
Music | African | Kizomba
Music | African | Kwaito
Music | African | Maskandi
Music | African | Mbalax
Music | African | Ndombolo
Music | African | Shangaan Electro
Music | African | Soukous
Music | African | Taarab
Music | African | Zouglou
Changes in iTunes Package Music Specification 5.3.7
Music Profile: DJ Mix
A new value (DJ Mix) for use with the <flag> tag has been added to indicate that a track or album is a DJ Mix. When used at the album level, iTunes appends (DJ Mix) to the album version title. When used at the track level, iTunes appends [Mixed] to the end of the track title, after all other versioning and featured artist information. If you deliver the DJ Mix flag for a track, you must also deliver the flag at the album level.
Music Profile: Artist Roles
The following roles have been removed from the Recommended Contributor Roles appendix: E-Bow Guitar, Effects, Electronic Valve Instrument, and Rhodes Guitar.
Changes in iTunes Package Music Specification 5.3.6
Music Profile: Artist Roles
New roles have been added to the Recommended Contributor Roles appendix. Apple recommends that you supply as much role data as you have for your content.
Music and Music Video Profiles: Title Version
You can remove an existing title version by sending an empty tag: <title_version/> or <title_version></title_version>.
Music Profile: Track Audio Language
Supplying the track audio language (<audio_language>) is now required.
Changes in iTunes Package Music Specification 5.3.5
Music Profile: Lyrics
You can now deliver lyrics for a song in multiple languages. New tags have been added to use in the metadata when delivering lyrics in more than one language. If you do not need to send lyrics in more than one language, you can still use the existing tags (see below for a partial example and see Music Video Single Metadata Example for a complete example). When sending multiple languages, enclose the files within a <lyrics_set> block. The locales for each lyrics file must be different, for example, you can’t send two sets of lyrics files both with the locale fr-FR. If you send a file within the <lyrics_set> block without a locale specified, it is assumed that the lyrics match the locale in xml:lang in the TTML file of the song.
Currently, the option to choose between lyric localizations is not supported for display, however Apple recommends that you start supplying localized lyrics to prepare for the time in the future when they will be supported.
When sending lyrics in Chinese, you must indicate the script information to inform users if the script is in simplified or traditional Chinese characters. For example, the locale for Mandarin lyrics in simplified characters must be zh-Hans, not zh. For traditional characters, it must be zh-Hant. For Cantonese, the locale must be yue-Hant.
<lyrics format="plain">'Twas brillig, and the slithy toves Did gyre and gimble in the wabe: All mimsy were the borogoves, And the mome raths outgrabe. Beware the Jabberwock, my son! The jaws that bite, the claws that catch! Beware the Jubjub bird, and shun The frumious Bandersnatch!</lyrics>
Music Profile: Album and Track Categorization
You can provide information on album and track categories that will be used to place content appropriately on Artist pages. You deliver the categories using a <flag> tag within the <flags> block on the album and/or track levels. For albums, you can set the value to Remix, Compilation, or Live; for tracks, you can set the value to Remix or Live.
Music Profile: UPC, Vendor ID, and ISRC Clarification
The UPC, Vendor ID, and ISRC identifiers cannot be updated once you deliver them. The annotations for the relevant tags have been changed to indicate they cannot be updated.
Genres
Changes have been made to the music, music video, and ringtone genres to help better classify music on the iTunes Store. New genres and sub-genres for Indian music have been added. The genre codes document is available in “Resources and Help” in iTunes Connect, but the changes are summarized in the table below.
The option to sell albums through the Ticketmaster website when customers buy event tickets is being deprecated. The <cleared_for_ticketmaster> tag has been removed from the examples and annotations. If you send metadata that includes the <cleared_for_ticketmaster> tag, you will see a warning; at some point in the future, delivery will fail.
Language Codes
Currently, the language code used to specify Simplified Chinese is cmn-Hans and the language code used to specify Traditional Chinese is cmn-Hant. Apple recommends that you use zh-Hans for Simplified Chinese and zh-Hant for Traditional Chinese. These codes apply only to written text (for example, lyrics), not audio (for example, the <audio_language> tag). The codes cmn-Hans and cmn-Hant are still supported, but using zh-Hans and zh-Hant is preferred. The codes have been changed throughout the specification.
Music Profile: Element Changes
Added
<lyrics_set>
locale as an attribute for <lyrics_file>
<flags> and <flag> for both albums and tracks
Anime Character as a value for <role> tag
Deprecated
<cleared_for_ticketmaster>
Changes in iTunes Package Music Specification 5.3.4
Music Video Profile: Screen Capture Artwork
For music videos, the artwork for the video in the iTunes Store and on the customer’s device is a screen capture from the video itself. The screen capture can be sent as a separate asset file, or as a timecode attribute in the XML. The timecode you provide specifies the frame that Apple can use to cut the screen capture image. To do this, use the image_time attribute in the <previews> block and remove the <asset> block for the artwork. Apple strongly recommends that you submit a frame cut directly from the video.The music video examples have changed to reflect this preference.
The requirements for music video artwork have changed. The image must be at least 1920 wide OR 1080 high. Refer to the iTunes Video and Audio Asset Guide for details.
Changes in iTunes Package Music Specification 5.3.3
Currently, you can submit a screen capture directly from the video to use as the artwork for the video in the iTunes Store and on the customer’s device. As an alternative to sending an asset file, you can provide the image_time attribute in the <preview> tag to cut a frame from the preview and that image can also be used as the video artwork. Apple recommends using the image_time attribute over sending an asset file. Sending an asset file may cause delays in displaying your content on the Store because the file needs to be evaluated for quality control. See the annotations in Music Video Single Metadata Annotations for details on how to use the image_time attribute.
iTunes LP
iTunes LPs are being deprecated so all references to them have been removed from this specification.
Basic Music Profile: Examples
The basic music example now includes tags for track audio language (previously shown only in the multiple languages example) and additional band member roles within the <artists> blocks for tracks.
Music Video Profile: Correction
The ISWC (International Standard Work Code) tag <iswc> is not supported for music videos and the tags and annotations have been removed for music videos.
Changes in iTunes Package Music Specification 5.3.2
Music Video 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 Video Source Delivery Requirements for the list of requirements. In addition, the HDR source assets must meet the requirements listed in Music Video HDR Source Profile in the Video and Audio Asset Guide.
You can now deliver 4K video. See the requirements listed in 4K Source Profile in the Video and Audio Asset Guide for more information.
Music Profile: Element Changes
Added
source.hdr and mapping.hdr for use on the <asset> tag
Changes in iTunes Package Music Specification 5.3.1
Music Profile: Artist Roles
Roles define the part that a particular artist performs on an album or track. Performer and Songwriter (or Composer) roles are always required and the Featuring and With roles are required when there is a featured artist on an album or track. 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), a new appendix (Recommended Contributor Roles) lists all the roles preferred by Apple Music and the iTunes Store. Note that primary status is reserved for the primary (lead) artists; do not tag supporting artists or contributors as primary.
Music Profile: Original Release Date
The <original_release_date> tag can now be used at the track level, in addition to the album level. Supplying the tag for tracks is optional. For music video tracks, the <original_release_date> tag replaces the <release_date> tag. At some point in the future, the <release_date> tag will be deprecated. Do not send both the <original_release_date> and <release_date> tags or delivery will fail.
Music Profile: Metadata Lookup
When you perform a metadata lookup on a package, the metadata that is returned includes read-only tags, which are supplied by Apple to provide information about the package. The read-only value tags include a key="XXX" attribute to describe what the information returned represents. New read-only attributes have been added and include: content-review-date, curated-artist, content-hiding-reason, and open-content-tickets. These new attributes are returned at the album, track, and artist levels. See Read-Only Metadata Album Example Annotations for descriptions.
Music Profile: Vendor Offer Code
Previously, the annotation for the <vendor_offer_code> tag indicated that the tag was used for sales reporting and would appear on financial reports. The information does not appear on financial reports, but you can use the tag for other provider-specific identifier tracking reasons (still following the identifier restrictions as noted in the annotations). The <vendor_id> tag does appear on financial reports.
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.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, for this revision of the spec, 5.3 is the schema version and 5.3.1 is the specification revision (so the attribute value is 5.3, not 5.3.1):
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.
Music Profile: Element Changes
Added
key="content-review-date" as an attribute in the <read_only_value> tag
key="curated-artist" as an attribute in the <read_only_value> tag
key="content-hiding-reason" as an attribute in the <read_only_value> tag
key="open-content-tickets" as an attribute in the <read_only_value> tag
Changed
<original_release_date> can be used at the track level for songs and music videos
<original_release_date> replaces the <release_date> tag for music videos
Changes in iTunes Package Music Specification 5.3
Music Profile: Schema Update
The version number of this specification has changed from 5.2 to 5.3 due to the addition of the new <artist> feed to the schema. The <package> tag version attribute has been updated in all examples to 5.3:
Crop dimensions are required for music videos 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.
Music Profile: Music Video Artwork
Delivering a music video artwork file is now optional. If you do not provide the video artwork file, iTunes will use the frame specified (using the image_time attribute of the <preview> tag, or the first frame of the cut preview if you omit the image_time attribute) as the video artwork image. See the <previews> tag or <preview starttime=""/> tag for more information on preview cutting.
Music Profile: Booklets
In the 5.0 version of the schema, the <bonus_material> tag was deprecated and replaced by the <booklet> tag. If you send metadata that includes the <bonus_material> tag, you will see a warning; at some point in the future, delivery will fail.
If you send a metadata update to a prior delivery that used the old <bonus_material> structure, you must use the new <booklet> structure. Your update delivery using <booklet> will be compatible with the existing album that used <bonus_material>. If you perform a metadata lookup on existing content previously delivered with the <bonus_material> structure, the <booklet> structure will be returned.
Changes in iTunes Package Music Specification 5.2.7
Music Profile: Lyrics for Album Tracks
Previously, you could deliver lyrics in either HTML or plain text. The HTML format is being deprecated. You can still provide song lyrics using plain text in the <lyrics> tag, however Apple prefers that you deliver lyrics using TTML instead of plain text (or HTML). You provide the lyrics as a file at the track level with the <lyrics_file> tag rather than providing the actual text using the <lyrics> tag. The basic music profile example shows the new TTML format and the <lyrics> tag has been removed. To see an example of delivering lyrics in plain text using the <lyrics> tag, see the metadata example in Mixed Media Album Metadata Example.
Album Cover Art: For album cover art, updating art that has been reviewed (whether ready for the Store or already live) no longer requires a ticket. You can deliver the new album cover art with a metadata update. Note that this change does not apply to music video cover art.
Preorders: The update behavior for preorders has been clarified. The sentence “The <preorder_type> tag cannot be changed once the earliest <sales_start_date> for any territory on the playlist (on the album or on any track) has been reached.” has been replaced with:
The <preorder_type> tag can be updated as long as the track has not yet been available to customers in any country or region:
- When transitioning from Standard or Pre-order only to Instant Grat, the earliest <sales_start_date> for any territory for the track cannot have been reached. If the track does not have a <sales_start_date>, the earliest <sales_start_date> for any territory on the album cannot have been reached.
- When transitioning from Instant Grat to Standard or Pre-order only, the earliest <sales_start_date> for any territory on the track cannot have been reached. If the track does not have a <sales_start_date>, the earliest <preorder_sales_start_date> for any territory on the album cannot have been reached.
The <track_count> tag has been removed from the Takedown Metadata Example since it is not required for take-downs.
Music Profile: Element Changes
Added
<lyrics_file>
Deprecated
"html" as a value of the format attribute for the <lyrics> tag on album song tracks
Changes in iTunes Package Music Specification 5.2.6
Music Profile: Previews
New tags have been added so you can define a music video preview by clipping a continuous segment of the video and audio. The new <previews> block and <preview> tag replace the <preview starttime=""/> tag. When you define the preview using the <preview> tag, you specify the time you want the preview to start. iTunes clips a 30-second preview starting at your selected start time. You can also specify the video frame to use for the preview image using the optional image_time attribute. For example:
If you do not specify the image_time, the first frame of the preview is the default image. If you specify an image_time but use the qt_text format, the frame nearest the image_time is used for the preview image (qt_text allows milliseconds, not frames so you cannot specify an exact frame to use for the preview image).
The <preview starttime=""/> tag is still supported and can be found in Music Video Single Crop Dimensions Metadata Example. However, if you want to specify a preview image, you must use the <previews> block and the <preview> tag instead of the <preview starttime=""/> tag. See Music Video Single Metadata Example for an XML example of defining a preview using the <previews> block and <preview> tag.
Music Profile: Vendor Offer Code for Tracks
The <vendor_offer_code> tag can be used for tracks as well as for albums. Using the optional tag for a track provides individual track sales insights that appear in Financial Reports, which you can generate through iTunes Connect.
Timecode Formats
A new appendix that explains the supported timecode formats used for the <previews> block has been added. See Timecode Formats for more information.
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. The table in Language Codes shows the Storefront languages.
Music Profile: Element Changes
Added
<previews> block
<preview> for use within the <previews> block
timecode_format="valid_format" as an attribute of <preview> within the <previews> block
start_time="valid_timecode" as an attribute of <preview> within the <previews> block
image_time="valid_timecode" as an attribute of <preview> within the <previews> block
Changes in iTunes Package Music Specification 5.2.5
Music Profile: Publisher Clarification
The publisher name provided with a <publisher> tag is limited to 256 bytes. Within the <publisher> tag, you deliver only one publisher name; individual publishers should be listed separately and not grouped together in one <publisher> tag (see incorrect and correct examples below):
Ad-supported iTunes Radio stations are no longer available as of January 2016. As a result, the <cleared_for_itunes_radio> (at both the album <product> or track <product> levels) and <cleared_for_itunes_radio_during_preorder> tags have been deprecated. All references to the feature have been removed from examples and annotations (but not from the revision history).
Music Profile: Track Count
An album can include up to a maximum of 500 tracks.
Music Profile: Corrections
The acronym GRID (for Global Release Identifier) has been changed to GRid throughout the specification.
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 music5.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:
<cleared_for_itunes_radio> (at both the album <product> or track <product> levels)
<cleared_for_itunes_radio_during_preorder>
Changes in iTunes Package Music Specification 5.2.4
Music Profile: Musical Works Reporting
You are already required to provide the songwriter information, including artist names and roles, within the <artist> block for each track. You can use the following roles to designate the songwriter: <role>Composer</role>, <role>Lyricist</role>, or <role>Songwriter</role>. You can add as many songwriters/composers as needed for the track and you can update the information at any time, for example if you don’t have all of the information available at the time of initial delivery, you can do a metadata-only update to add the missing information later. Failure to add full and accurate songwriter metadata in a timely manner may delay payment of royalties to publishers and songwriters.
In addition to songwriter information, two new optional tags have been added to help provide better reporting and matching for sound recordings to their underlying musical works and owners. Use the <publishers> block to indicate who controls the underlying work. You can add as many publishers as needed for the piece using a <publisher> tag within the <publishers> block. The <publishers> block can be used at the track level for songs, ringtones, and music videos.
A new ISWC (International Standard Work Code) tag <iswc> uniquely identifies the underlying musical work of a particular piece and helps distinguish a song from other songs with similar or identical titles.The <iswc> tag complements the ISRC (International Standard Recording Code) tag (<isrc>) that uniquely identifies a sound recording performed by an artist or band. Each song should only have one ISWC, but different recordings of that song can have their own unique ISRCs.
The <iswc> tag can be used more than once on the same album, for example a piece could appear twice on an album: one track performed with vocals and another track could be instrumental only. The <iswc> tag can be used at the track level for songs and ringtones.
Supplying the publishers and ISWC identifiers is currently optional; at some point in the future, you may see a warning if the tags are not delivered.
Music Profile: Tag Changes
Added
<iswc>
<publishers>
<publisher>
Changes in iTunes Package Music Specification 5.2.3
Music Profile: Subscription Services
Three tags related to special clearances for radio and streaming have been added. The subscription service offers a comprehensive set of music services accessible to users through their Apple ID. The tags can be used at the album <product> or track (song or music video) <product> levels as noted in the annotations.
Music Profile: Cover Artwork
Album cover artwork (.jpg or .png) should have a recommended minimum resolution of 3000 by 3000 pixels. If you deliver cover art less than 3000 by 3000 pixels, at some point in the future you will see a warning. This requirement applies to artwork for albums, box sets, and track groups; artwork for ringtones does not have this size requirement. See the iTunes Video and Audio Asset Guide for specifications.
Music Profile: Audio Language Clarification
Use the <audio_language> tag to specify the language of audio whenever possible. If there are no words spoken in an audio file, you can use the code zxx (which represents “no linguistic content”). It is especially important to include the <audio_language> for audio performed in languages other than English.
Music Profile: Pre-Orders
Removed the sentence: “The pre-order will not appear in the store automatically, however, it must first be activated by Apple before it will go live.”
Previous versions of the specification indicated that Apple recommends that instant-gratification items be less than 10 minutes long, however instant-gratification items that are longer than 10 minutes are actually blocked. Also, an “album-only” track cannot be an instant-gratification track.
Music Profile: Interval Pricing
Interval pricing for single track albums is not supported.
Music Profile: Gapless Audio
Previous versions of this specification incorrectly indicated that iTunes adds a gap between tracks if the <gapless_play> tag for a track is omitted or set to false. In normal playback, iTunes always plays songs without a gap, regardless of the value sent with the tag. The <gapless_play> tag applies if the user has turned on the cross-fade feature in iTunes Preferences. When cross-fade is turned on, iTunes cross-fades each track with the following track, except for those tracks marked <gapless_play>true</gapless_play>. In other words, when <gapless_play> is set to true, the song will play to completion and then immediately and seamlessly continue playing to the next song with no overlap, even if cross-fade is enabled. This allows the cross-fade feature to preserve the artistic intent of songs that are meant to play back with no audible gap or overlap between tracks.
Music Profile: Tag Changes
Added
<cleared_for_stream>
<stream_start_date>
<cleared_for_itunes_radio>
Changes in iTunes Package Music Specification 5.2.2
Music Profile: Languages
Seven languages have been added for use in the <language> and <locale> tags. (See Language Codes for details.) The languages include:
bn: Bengali
ht: Haitian
ga: Irish
la: Latin
fa: Persian
pa: Punjabi
sa: Sanskrit
Music Profile: Pre-orders
The maximum length of the pre-order period is 366 days. This means that the date specified with the <preorder_sales_start_date> tag cannot be more than 366 days prior to the date specified with the <sales_start_date> tag. For example, delivering the following tags would result in an error:
When you deliver a music video, you specify and deliver the assets, such as the source video and 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 music videos, currently two roles can be specified: the role called “source” for the full asset and the role called “captions” for a closed captions file. 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.
Music Profile: ISRC Clarification
The ISRC refers to a particular recording, and in some cases, such as in a box set, a recording may appear more than once in the same package delivery. If two items (videos or tracks) in a package have the same ISRC, you must supply a unique <vendor_id> tag to differentiate between the two items.
Genres
The names of two Latin genres for music, music videos, and ringtones have been changed. The genre codes document is available in “Resources and Help” in iTunes Connect, but the changes are summarized in the table below.
Renamed genres:
Old Name
New Name
Pop Latino
Pop in Spanish
Alternativo & Rock Latino
Alternative & Rock in Spanish
Music Video: Screen Capture Image Clarification
The image used for music video is a screen capture from the delivered video and the phrase “music video artwork” has been changed to “music video screen capture image” to keep the name consistent between this specification and the iTunes Video and Audio Asset Guide.
Changes in iTunes Package Music Specification 5.2.1
Music Profile: iTunes Radio
A new tag (<cleared_for_itunes_radio_during_preorder>) can be used at the <album> and <track> levels to indicate that the entire album or individual tracks can be made available for customers to play on iTunes Radio during the pre-order period. Note that all content that is already for sale on the Store can be played on iTunes Radio; this tag is used to give permission to play the content expressly during the pre-order period.
You must deliver the <cleared_for_itunes_radio_during_preorder> tag before the actual sales start date. Once you deliver the tag set to true during the pre-order period (which is on or after the <preorder_sales_start_date> and before the <sales_start_date>), you cannot change the value to false. If you deliver the tag on or after the <sales_start_date>, the tag will have no effect and you will see a warning.
Music Profile: Album Title Version
The <album_title_version> tag (now shortened to <title_version>) was deprecated in the 3.1.1 version of the specification, although it has always been supported on import. The album <title_version> tags and annotations have been added to the XML examples where appropriate. Note that when imported, iTunes takes the information in the tag and appends it to the album title in parentheses for display on the Store. If you later do a metadata lookup, the <title_version> tag will not be returned in the metadata; instead you will see the value in the title version tag appended to the album title: <title>Medúlla (Remastered)</title>.
Music Profile: Pre-Order Sales Start Date Clarification
When sending a metadata update, if you omit the <preorder_sales_start_date> tag, the date previously delivered is not changed and remains in effect. To remove the existing pre-order sales start date, send an empty tag: <preorder_sales_start_date/>.
Music Profile: Artist Language
The <language> tag can be delivered in an <artist> block at both the album level and track level to indicate that the language in which the artist metadata appears is different from the <language> tag for the package. If you omit the <language> tag under <artist>, the language in which the artist’s name appears should be the same as the language of the package. Using <language> under <artist> is optional and would only be used in specific circumstances, for example, when a Japanese artist appears on a track on an English album.
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 album and track artists, among others. See About Metadata Lookup for a description of metadata lookup and the read-only tags returned.
Pre-Orders
The Pre-Order Addendum, which explained the “instant-gratification” pre-order type, has been incorporated into this specification. Additional tags for managing pre-orders have been added.
Genres
Changes have been made to the music, music video, and ringtone genres to help better classify music on the iTunes Store. New genres have been added, some have been renamed, and some are no longer supported. Any existing genres that are no longer supported have been moved to similar supported genres. When selecting a genre for your content, keep in mind that it is better to select specific genres such as Salsa y Tropical rather than generic genres such as Latin. The genre codes document is available in “Resources and Help” in iTunes Connect, but the changes are summarized in the tables below.
New and updated music genres:
Genre
Sub-Genre
Alternative
EMO
Indie Pop
Pop Punk
Classical
Art Song
Brass & Woodwinds
Cantata
Cello
Contemporary Era
Electronic
Opera
Oratorio
Percussion
Piano
Sacred, Guitar
Solo Instrumental
Violin
Electronic
Bass
Dubstep
Hip Hop Rap
UK Hip Hop
Reggae
Lovers Rock
Pop
K-Pop
New Age
Yoga
World
Dangdut
Renamed genres:
Old Name
New Name
Baroque
Baroque Era
Cantopop/HK-Pop
Cantopop
Dancehall
Classic/Modern Dancehall
High Classical
Classical Era
Korean Classical
Korean Traditional
Medieval
Medieval Era
Modern Composition
Modern Era
Romantic
Romantic Era
Genres no longer supported:
Genre
Sub-Genre
C-Pop
Christian & Gospel
Inspirational
Classical
Early-Music
Wedding Music
Dance
Exercise
Holiday
Holiday: Other
Korean Trad Instrumental
Korean Trad Song
Korean Trad Theatre
Music Videos
Christian & Gospel
Podcasts
New Age
Environmental
R&B/Soul
Quiet Storm
World
Drinking Songs
Japanese Pop
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.”
Music Profile: Tag Changes
Added
<cleared_for_itunes_radio_during_preorder>
<title_version> for albums
instant-gratification used as a value in <preorder_type> tag
<preorder_wholesale_price_tier>
<preorder_upc>
<preorder_grid>
Changed
<language> tag can be used under <artist> at the album and track levels
Changes in iTunes Package Music Specification 5.2
Music Profile: Titles and Title Versions
The allowed length of titles and title versions has changed. The length of titles applies to albums, song tracks, videos, and booklets; the length of title versions applies to albums and song tracks. 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).
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:
Changes in iTunes Package Music Specification 5.1.2
Music Profile: Content Update Behavior
A new appendix describes the process behind updating content and includes definitions, descriptions of content review statuses, and a table listing the tags that may require a ticket in certain circumstances. The section “Metadata Updates” in the Delivery and Formatting Guidelines chapter has been removed. See the appendix Content Updates for more information.
Music Profile: Phonetic Title and Name Fields
Additional languages are now supported for use with the <phonetic_title> and <phonetic_name> tags. These languages include Korean, Thai, Russian, Bulgarian, or Ukrainian. See Title and Artist Localizations Metadata Annotations for more details.
The Cantonese (yue-Hant) localizations shown in the Title and Artist Localizations XML Example have been replaced with Russian localizations.
Music Profile: Mixed Media Album Example
A new XML example has been added to the Mixed Media Album chapter. This example shows how to deliver a mixed media album that includes one video and one booklet.
Music 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 <album> 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 Music Album Product-Only Update Example for an example.
Music 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.
Music Profile: Clarifications
If you leave out the <products> block for tracks (including videos and booklets) on initial import, those tracks will inherit the product information from the album playlist level. When delivering an update, this rule does not apply.
Music Profile: Tag Changes
Changed
<vendor_offer_code> can be updated
<phonetic_title> and <phonetic_name> can now be used for Korean, Thai, Russian, Bulgarian, or Ukrainian (in addition to Japanese and Chinese)
Changes in iTunes Package Music Specification 5.1.1
Music Profile: Music Video Closed Captions
Closed captions can optionally be delivered with music videos. The closed caption file is delivered as a data file for the source asset. The "captions" role specifies that the delivered data file is intended to be used as the closed captioning file for the iTunes Store encode.
Music Profile: Localizations
Title and name localizations for Cantonese Jyutping have been added to the multiple language metadata example. For example, the Jyutping for a title is supplied as follows:
<locale name="yue-Hant"> <title>生命之树</title> <phonetic_title>Sang Ming Zi Syu</phonetic_title> <title_version>豪华版</title_version> </locale>
When specifying the genre(s) for an album, music video, or track, you must supply the Apple genre codes, for example: <genre code="ELECTRONIC-01"/>. Currently, you can supply both the code and the genre label as follows: <genre code="ELECTRONIC-01">Electronic</genre>, however, supplying only the genre label (<genre>Electronic</genre>) is not allowed. For a complete list of genres, click Resources and Help on iTunes Connect to download the spreadsheet titled “Music, Music Video, and Ringtone Genre Codes.”
Intervals Clarification
The interval <start_date> is required except for the first interval. 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 start dates, the date may be any point in the future. For subsequent intervals, the <start_date> may be any point in the future.
If you leave out the <start_date> tag for the first interval, the interval starts immediately by default. If the <start_date> of the first interval is other than the current date (either by default or by explicitly sending the current date), delivery will fail.
Gapless Play Clarification
The <gapless_play> tag only applies to the gap between a specified track and the track that precedes it.
Music Profile: Tag Changes
Added
role="captions" as an attribute of <data_file> for the full music video asset
Changes in iTunes Package Music Specification 5.1
Music Profile: Artist Reference
You can refer to an album and track artist by name (using the <artist_name> tag) or by Apple ID (using the <apple_id> tag). iTunes assigns every artist a unique Apple ID; Apple recommends using the Apple ID to avoid the ambiguity in cases where artists share the same name as other music artists, or film actors or crew members. You can supply the <artist_name>, the <apple_id>, or both the <artist_name> and <apple_id>. If you supply both tags, only the <apple_id> tag will be considered in looking up an existing artist. If you do not know the artist’s Apple ID, you can do a metadata lookup on an existing album and look for the <apple_id> tag. For any subsequent updates, you can use the <apple_id> tag instead of or in addition to the name, to avoid ambiguity.
Music Profile: Genres
All music 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:
Required Method Using the Genre Code
<genre code="ELECTRONIC-01"/>
Deprecated Method Using the Genre Label
<genre>Electronic</genre>
Acceptable Method Using Both the Genre Code and the Genre Label
<genre code="ELECTRONIC-01">Electronic</genre>
If you use this method, the genre identified by code and the genre identified by genre label must resolve to the same genre, for example, <genre code="POLKA-00">Ragtime</genre> would be rejected.
iTunes has expanded worldwide, and as a result, new genres have been added for new countries/regions. Because of the increased number of countries/regions, the genres have been moved from this spec to a spreadsheet titled “Music, Music Video, and Ringtone Genre Codes,” which can be downloaded from the Resources and Help section on iTunes Connect.
Music Profile: Track Language
A new <audio_language> tag can be specified for a track to indicate that the language in which the song is sung is different from the language specified with the <language> tag. For example, an album of opera arias sold in the U.S. includes arias sung in Italian and German. The <language> tag specifies English; the <audio_language> tag for an Italian track indicates Italian as the audio track language: <audio_language>it</audio_language>; the <audio_language> tag for a German track indicates German as the audio track language: <audio_language>de</audio_language>. Using the <audio_language> tag is optional; if it is not specified, the language in the <language> tag is used.
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 (http://tools.ietf.org/html/rfc5646), which is part of BCP 47. An overview of these best practices is provided here: http://www.w3.org/International/articles/language-tags/.
The language specified in the <audio_language> tag must not contain script information. For example, the language for Mandarin audio must be cmn, not cmn-Hant or cmn-Hans; the language for Cantonese audio must be yue, not yue-Hant. If a track is sung in Chinese, but you do not know if it is Mandarin or Cantonese, you can send zh as the audio language, but you will get a warning when you deliver the metadata. This tag can be updated, so you could change zh to cmn or yue once you know if it is Mandarin or Cantonese.
When sending a ringtone package, you can deliver an audio file of any duration and use optional tags to trim the file: <tone_start_time> and <tone_duration>. Use <tone_start_time> to indicate the point (in seconds) at which the ringtone should start; iTunes will cut a 30 second file beginning at the specified time. To set a duration other than 30 seconds, use <tone_duration> to set the length of time in seconds. The duration must be longer than 5 seconds and less than 30 seconds. Note that pre-cut ringtones are still supported. See Ringtone Trimming Metadata Example for more information.
Ringtone album artwork can be 800 by 800 pixels, but Apple recommends delivering 1400 by 1400 pixels for best results.
Music Profile: Booklets
The <volume> tag has changed to <volume_number> for booklets. A volume can include more than one booklet and a booklet can be any track in the volume (booklets are no longer required to be the last track). If an album has more than one volume, the <volume_number> tag is required for booklets. See Overview for an example of a multi-volume album.
Track Price Tiers
The track price tiers for Japan have changed. Tier 98 (Back) is the default track tier for Japan. Tier 99 is now Mid and Tier 100 is now Front; Tier 101 has been eliminated. See Wholesale Price Tiers for details.
For countries/regions on the U.S. Dollar, two new track price tiers have been added: 96 (Lowest) and 97 (Low), in addition to 98 (Back), 99 (Mid), and 100 (Front). Refer to your contract to see the countries/regions allowed to use Tiers 96 and 97. All other currencies can use 98 (Back), 99 (Mid), and 100 (Front).
Languages
Several languages have been added that are supported for <language> and metadata level <locale> tags. See Language Codes for details.
Intervals Validation
If you provide interval pricing, the start date of the first interval must be today or it should not have a start date. If you provide a date other than the current date for the start date of the first interval, delivery will fail.
Corrections
Added the missing closing </description> tag in the example showing how to use CDATA.
Music Profile: Tag Changes
Added
<apple_id> for use within the <artist> tag
code as an attribute of the <genre> tag
<audio_language>
<tone_start_time> for use in a ringtone package
<tone_duration> for use in a ringtone package
Changed
<volume> has changed to <volume_number> for booklets
Deprecated
<volume_count>
Changes in iTunes Package Music Specification 5.0.3
Music Profile: Localizations
The optional <phonetic_title> and <phonetic_name> tags can now be used when supplying localizations in Chinese (in addition to Japanese). For Chinese, the tag provides the reading of the title and artist name in Pinyin. Delivering phonetic titles and names provides a better search experience for the user. See Title and Artist Localizations Metadata Basic Example for how to use these tags.
When supplying localizations in Chinese, as a best practice, supply the titles, title versions, and artist names in both traditional (Hant) and simplified (Hans) script when available.
Music Profile: Tag Changes
Changed
<phonetic_title> and <phonetic_name> can now be used for Chinese to provide Pinyin
Changes in iTunes Package Music Specification 5.0.2
Music Profile: Bonus Material
If you send a metadata update to a prior delivery that used the old <bonus_material> structure, you can use the new <booklet> structure, however for these existing albums that were previously delivered with the <bonus_material> structure, the <bonus_material> structure will continue to be returned if you do a metadata lookup. Your update delivery using <booklet> will be compatible with the existing album that used <bonus_material>.
Music Profile: Interval Pricing
New validations have been added for interval pricing. Packages that do not adhere to the requirements will fail delivery. See Interval Pricing for a list of the requirements.
Changes in iTunes Package Music Specification 5.0
Music Profile: Title and Artist Localizations
iTunes provides support for multiple languages in a single playlist or video that will be sold in multiple languages. Using <locale> tags, you can supply localized metadata for titles and artists at the <album>, <track>, <video>, and <booklet> levels. Tags used previously (for example, <name translation="native">) to provide translations for Japanese providers have been deprecated. For metadata examples and tag annotations, see Multiple Language Support.
Music Profile: Languages and Codes Best Practices
The list of languages has been changed to include only currently accepted codes. As a best practice when specifying a language, use only the “language” subtag of the language code; do not provide the “region” subtag unless it supplies useful information, such as spelling variations between countries/regions. For example, for Dutch, you should use <language>nl</language> instead of <language>nl-NL</language>. For English, use <language>en</language> instead of <language>en-US</language> or <language>en-GB</language>. See Language Codes for more information.
Additional languages are now supported. See Language Codes for a list of accepted language codes.
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 (http://tools.ietf.org/html/rfc5646), which is part of BCP 47. An overview of these best practices is provided here: http://www.w3.org/International/articles/language-tags/.
Cover art size must be a minimum of 1400 by 1400 pixels. See the iTunes Video and Audio Asset Guide for specifications.
Music Profile: Genres
iTunes provides new genres for the countries/regions now supported in the 5.0 version of the spec. For a complete list of genres, click Resources and Help on iTunes Connect to download the spreadsheet titled “Music, Music Video, and Ringtone Genre Codes.”
Music Profile: Bonus Material
The XML structure for supplying bonus material metadata has changed. It now uses the <booklet> tag instead of the <bonus_material> tag structure. See Booklet Metadata Example for more information.
Price Tiers
The table of Japanese price tiers has been removed and the Japanese price tiers have been incorporated into Wholesale Price Tiers.
A new price tier for indie music has been added. The former Mini Album tier is now called Mini Album One. The new Mini Album Two tier includes price optimizations for the Eurozone, U.K., Norway, Sweden, Denmark, and Switzerland. For all other countries or regions, Mini Album One and Mini Album Two are the same.
Music Profile: Tag Changes, Corrections, and Clarifications
The <description> tag has been removed from all XML examples. The information provided in the tag does not appear on the Store, so there is no need to supply it. The <wholesale_price_tier> tag has been removed from the ringtones XML example.
The <explicit_content> tag can now be used to indicate whether the content of a booklet is explicit or clean. See Booklet Metadata Example for an example of how to use the tag. In the <explicit_content> tag, a track (or booklet) must only be marked clean if it is an edited version of the original explicit form of the track or booklet.
The <sell_plus_quality> tag previously deprecated can be used under one specific case: when content has been incorrectly removed from the Store because it was not cleared for DRM Free. To put the content back on the Store, send a metadata update with <sell_plus_quality> set to true. The only acceptable value for the tag is true.
There is a 255-byte limit strictly enforced for data such as album and track titles, and artists’ names. 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.
Music 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. For example, starting with the 5.0 version of the music specification, tags deprecated or changed in the 4.0 version distributed in 2009 (such as <album_upc> and <track_gapless_play>) will not be valid. Review Previous Spec Revisions for tags that have been changed or deprecated.
Music Profile: Tag Changes
Added
<locales><locale>
<phonetic_title>
<phonetic_name>
<booklet>
Changed
<name> (under <artist>) has changed to <artist_name>
<explicit_content> can be specified within the <booklet> block
Deprecated
<name translation="phonetic">
<name translation="native">
<name translation="english">
<name translation="japanese">
<title translation="phonetic">
<title translation="native">
<title translation="english">
<title translation="japanese">
<title_version translation="phonetic"> (not being replaced)
<title_version translation="native">
<title_version translation="english">
<title_version translation="japanese">
<sell_plus_quality> for Japanese providers
<bonus_material>
<bonus_material_name>
<vendor_identifier> used with <bonus_material>
<description>
Changes in iTunes Package Music Specification 4.8
Music Profile: Language Codes
Languages not supported by iTunes in the <language> tag have been removed from Appendix B. The list now contains only the language codes available for use in the <language> tag. See Language Codes for more information.
Music Profile: Vendor Offer Code
A new optional tag has been added that can be reported back through sales reporting channels.
Music Profile: Updates
The <title> for music videos can be modified unless Apple has reviewed and confirmed the quality of the metadata (referred to as polished).
Music Profile: Clarifications
If the <original_release_date> is more than 90 days later than the earliest <sales_start_date>, the package will be rejected.
Pre-cut Ringtones: Explicit Content
Added the <explicit_content> tag to the pre-cut ringtone metadata example that had been inadvertently left out.
Music Profile: Tag Changes
Added
<vendor_offer_code>
Renamed
<description_long> is now <description>
Deprecated
<cleared_for_user_generated_ringtones>
Changes in iTunes Package Music Specification 4.7
Music Profile: Box Sets
You can deliver box sets to the iTunes Store using the <track_group> tag. The <track_group> tag is not new to 4.7, but it is new to this specification. The feature was previously covered in the iTunes Pass Addendum and the tag has been adapted to deliver box sets. When delivering a box set, the <track_group> tag can be used to distinguish individual albums that are part of the box set. Each <track_group> tag inside a <tracks> tag designates one individual album in a box set. You can include song tracks, videos, and booklets inside each <track_group> tag. Each <track_group> can have its own cover art; if you do not supply cover art for an individual album, the box set cover art is used. See Adding a Box Set XML Example for details.
Music Profile: Genres
The R&B genre has been changed to R&B/Soul Gospel.
Music Profile: Music Videos on Playlists
Sales for videos on playlists (that is, not a standalone video) are reported using the vendor ID of the album combined with the vendor ID of the video. For example, if the album vendor ID is 8256463821764 and the video vendor ID is USW980800331, sales are reported against the combined album vendor ID and video vendor ID separated by an underscore, such as 8256463821764_USW980800331.
Music Profile: Interval Pricing Clarifications
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.
Music Profile: Tag Changes
Added
<track_group>
<group_name>
<booklet> for delivering a booklet within the <track_group> tag
Changes in iTunes Package Music Specification 4.5
Music Profile: HD Video Clarifications
Crop dimensions for HD video are required. If the HD video’s QuickTime source file is delivered matted (letterbox, pillarbox, or windowbox), specify the crop rectangle to crop the inactive pixels. If the HD source file is not delivered matted or if there are no inactive pixels, we recommend setting all the crop dimensions to 0 (zero). See Music Video Single Crop Dimensions Metadata Example for an example on specifying the crop rectangle. See the iTunes Video and Audio Asset Guide for specific HD video asset requirements.
Music Profile: Genres
The Inspirational genre has been changed to Christian & Gospel.
Music Profile: Pre-cut Ringtones
This specification now includes pre-cut ringtones. Pre-cut ringtones are not new to 4.5; the feature was previously covered in an addendum that has now been incorporated.
The ringtone is delivered in an iTunes Package directory that contains the XML, the audio file, and cover art. Each package represents a single ringtone product within the iTunes Store. A ringtone can only be delivered in its own package; a ringtone cannot be added as a track on an album with other tracks.
There are two mandatory tags specific to ringtones:
<album_type> identifies the album as a ringtone
<type>ringtone</type> under <track> specifies the track as a ringtone as opposed to a regular song
Music 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 (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.
Changes in iTunes Package Music Specification 4.4
Music Profile: HD Music Videos
Music videos can now be delivered in HD. The HD source of the music video will be automatically cropped on delivery. If the video is delivered matted (letterbox, pillarbox, or windowbox), you must override the automatic cropping by specifying crop dimensions in the metadata. See Music Video Single Crop Dimensions Metadata Example for an example on specifying the crop rectangle. (See the iTunes Video and Audio Asset Guide for specific HD video asset requirements.)
Music Profile: Lyrics
The <lyrics> tag now includes an attribute used to specify the format of the lyrics text for songs and music videos. The lyrics can be delivered as plain text ("plain") or styled using HTML ("html"). (Note: Lyrics in HTML format deprecated January 2017.) Lyrics can be updated.
Music Profile: Artist Roles Clarification
The “artist” can be any contributor including composition-related contributors (for example, songwriter/lyricist, or composer). Note that you should always include composition-related contributor information if it is available.
Price Tiers: Clarification
Changes were made to the price tier tables to clarify tiers for Japan (see Wholesale Price Tiers.
Music Profile: Tag Changes
Changes
New format attribute for lyrics: <lyrics format="html">
Deprecated
<liner_notes>
<beats_per_minute>
<description_short>
Changes in iTunes Package Music Specification 4.3.2
Music Profile: Artist Roles
The roles accepted for artists include Composer, DJ, Featuring, Narrator, Performer, Producer, Remixer, Songwriter, and With. Artists with the roles listed have their own artist page.
Music Profile: Updates
To replace album cover art or music video cover art through the feed, a ticket must be opened prior to update delivery.
Price Tiers
The default track and video price tier for Japan is Front.
Changes in iTunes Package Music Specification 4.3
Music Profile: Genres
The genre Health & Fitness has been renamed to Fitness & Workout. The Anime genre has been added.
Music Profile: Corrections/Clarifications
The first letter of each word in genre names has been capitalized, for example “alternative” is now “Alternative” and “heavy metal” is now “Heavy Metal.” These changes were made in the XML examples and in the Genre Table.
The version number in the XML examples contained an extra period. “music.4.1” was changed to “music4.1” and updated to reflect the current version, 4.4.
The <package> tag annotations omitted the description of the xmlns attribute. It serves as a declaration that the tags in the XML are expected to conform to the schema associated with the specified namespace, which is http://apple.com/itunes/importer.
When initially delivering a music video, delivery of the video asset source is required (except for preorders with a sales start date in the future).
Music Profile: Metadata Updates
Music video cover art can be updated through metadata updates.
Music Profile: Interval Pricing
Interval pricing allows an album’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.
Music Profile: Tag Changes
Added
<intervals>
<interval>
Changes in iTunes Package Music Specification 4.1
Music Profile: Genres
New genres have been added for Music: Health & Fitness, K-Pop, Karaoke, Instrumental, and High Classical. The Big Band sub-genre has been moved from the Easy Listening genre to Jazz. Note that these genres do not apply to Music Videos or Ringtones.
Music Profile: Corrections/Clarifications
When specifying the version attribute of the package (<package xmlns="http: //apple.com/itunes/importer" version="music4.1">), the “music” portion of the version attribute must be in lowercase letters.
For pre-orders, if the <preorder_previews> tag is omitted in an initial upload, it is assumed false and previews will not be available during the pre-order period. If the tag is omitted in an update, it is assumed that there is no change to the value originally sent. Also, the <preorder_sales_start_date> tag cannot be updated; once you send it, it can’t be changed or removed. However, additional territories can be added in an update.
When listing the artists who perform on the album and each track, at least one artist must be designated as a primary artist for both the album and each track.
Music Profile: Featured Artists
If an artist on a song, album, or video is a “featured” artist, assign the featuring role to the artist as shown in the XML example below. If the song, album, or video features more than one artist, enter the artists in order of importance in the XML.
This ensures that the album will show up on the featured artist’s page. To ensure that the featuring artist shows up when customers search for the artist, add the artist’s name(s) to the track title as in the following example:
<title>If I Get Locked Up (feat. Eminem)</title>
The term “feat.” must be in lower case. No other spelling is acceptable.
Changes in iTunes Package Music Specification 4.0
Music Profile: Tag Naming
Several tag names have been simplified. Tags that fall under an <album> block have been renamed to remove the <album_...> prefix of the tag. For example, <album_upc> has been renamed to <upc>. Similarly, tags that fall under a <track> block have been renamed to remove the <track_...> prefix of the tag. For example, <track_gapless_play> has been renamed to <gapless_play>. The only exception to this is <track_number>, which remains <track_number>.
In addition, the vendor identifier tag has been unified for album, track, and video. The tag is now <vendor_id> for all.
Music Profile: Metadata Updates
<label_name> under the <track> block (previously called <track_label_name>) can be updated.
Music Profile: Genres
Four new genres have been added: Health & Fitness, K-Pop, Karaoke, and Metal.
Music Profile: Chapters
Each chapter image file referenced in the package must have a unique filename.
Music Profile: Clarifications
Role names for artists (for example, Performer) must be in English to be imported by the iTunes Store, but the names will be localized if needed when displayed in the Store.
Music Profile: Tag Changes
Important: Even though the tag names have changed, the old tag names will still be accepted for a period of time. A future version of this specification will notify you when the new tag names will be strictly enforced.
Changes in iTunes Package Music Specification 3.3.3
Music Profile: Metadata Updates
The <album_preorder_previews> tag can now be updated through metadata updates.
GRid can be updated if the field did not contain a value in a prior package delivery. This includes: <album_grid>, <track_grid>, and <grid>.
iTunes Store Package: Price Tiers
Replaced Album Front price tier with Front One and Front Two price tiers. See Wholesale Price Tiers.
Changes in iTunes Package Music Specification 3.3.2
Music Profile: GRid
GRid (Global Release Identifiers) used in the <grid>, <album_grid>, and <track_grid> tags must not be more than 18 alphanumeric characters. The GRid cannot contain dashes, spaces, underscores, other punctuation, or symbols. Packages delivered with GRid containing non-alphanumeric characters will be rejected.
Music Profile: Track Numbering for Videos
On mixed media albums that include a video, specifying the <track_number> for videos tracks is required. When specifying a volume number for videos, use the <volume_number> tag, not the <track_volume_number> tag.
Music Profile: Metadata Updates
<release_date> for videos and <track_gapless_play> can now be updated through metadata updates.
Music Profile: Clarifications
The vendor identifier must not start with an underscore character. Images must be at least 72 dpi. Chapter titles have a 255-byte limit.
Changes in iTunes Package Music Specification 3.3
Music Profile: Album Label Name
<album_label_name> is now automatically updated through metadata updates.
Music Profile: Bonus Material Updates
Bonus material may now be updated.
Music Profile: Pre-Orders
All pre-order only tracks must now be cleared for sale.
Music Profile: Track-Level Wholesale Pricing
Wholesale price tiers can now be applied to individual tracks. All wholesale pricing is strictly validated. Invalid price tiers will be rejected from delivery—this includes track-level pricing. Track-level pricing is not required; if you don’t provide track-level pricing information, the pricing defaults to Mid tier. Track-level pricing is dependent on contracts. Contact your iTunes Technical Representative for details.
Music Profile: Takedowns
A new, simplified metadata format is now available for taking down content. This is intended to ease content removal from the store especially in instances where the track lineup or ISRCs have changed.
Music Profile: Video
Previous error has been corrected. Music video titles and music video artwork are required.
iTunes Store Package: Vendor Identifiers
Vendor identifiers are case-sensitive and may only contain alphanumeric characters and underscores (“_”). Packages delivered with identifiers containing other characters will be rejected.
Music Profile: Tag Changes
Changes
<wholesale_price_tier> can now be used for track-level pricing within the <track_products> tag.
<album_products> is deprecated. Use <products> instead.
Deprecated
<sell_plus_quality> (deprecated except for Japan)
<album_products>
<album_title_version>
<album_title_version translation="native">
<album_title_version translation="japanese">
<album_title_version translation="phonetic">
Changes in iTunes Package Music Specification 3.1.1
Music Profile: Album, Track and Video Artists
Artist names will now appear in the iTunes Store in the order in which they are specified in the provided metadata. This only applies to albums provided on or after April 1, 2008.
Music Profile: Album Track Count
If specified, the <album_track_count> is compared to the total number of tracks received and the associated album is automatically marked complete at time of import (pending iTunes approval). Note: This is a clarification and not a change in the specification.
Music Profile: Bonus Material
Bonus materials may not be updated via the feed at this time. If changes are necessary, contact your Apple Technical Representative. Note: This is a clarification and not a change in the specification.
Music Profile: Explicit Content
“Clean,” “explicit” and “none” are acceptable values. Previously, the “none” option was omitted from the specification.
Music Profile: Foreign Language Albums and Tracks
Only Japanese albums and tracks or non-Japanese albums and tracks for sale in Japan may include translation information. Refer to the Multiple Language Support chapter for more details on how to best provide Japanese and non-Japanese language metadata.
Music Profile: Metadata Updates
If a metadata ticket has been opened by iTunes, track and album titles as well as title versions may be updated via the feed (subject to iTunes ticket approval).
Music Profile: Metadata-Only Pre-Orders
Pre-orders no longer need to include all assets up-front. Instead, they may be simply metadata-only (with the addition of the album cover), and the audio may be added at a later date.
iTunes Store Package: Wholesale Price Tier
If an invalid price tier is provided, iTunes reserves the right to reject the package or to use default pricing. Check your contract for allowed price tiers. Speak to your iTunes Technical Representative for more details. Note: This is a clarification and not a change in the specification.
Changes in iTunes Package Music Specification 3.1
Music Profile: Bonus Material
Note that QuickTime movie content is no longer acceptable as bonus material. Only PDF booklets are valid bonus material at this time. If a QuickTime movie is supplied, the package will be rejected.
Music Profile: Foreign Language Support
Support has been clarified for phonetic or pronunciation translations. Going forward, only “phonetic” and not “pronunciation” translation types will be allowed in metadata.
Music Profile: Metadata & Asset Updates
New items may be updated through the feed including: cover art, iTunes Plus clearances, track preview start times, video preview start times, and copyright notices (p and c-lines). A complete example of metadata-only updates is now provided.
Music Profile: Pre-Order Type
Pre-orders may have tracks that are “standard” (that is, a normal track that has no special pre-order function and will remain on the album after the pre-order period ends) or “pre-order only” (that is, a track that is exclusive to the pre-order period only and may not be purchased apart from the entire pre-order before the album’s street date). This is now specified with the <preorder_type> flag.
Music Profile: Related Albums
Related album information is no longer accepted.
Music Profile: Ticketmaster
Albums may now be sold via the Ticketmaster website when customers buy event tickets. This is currently only available in select territories.
Music Profile: Track-Level Wholesale Pricing (Japanese only)
All wholesale pricing is strictly validated. Invalid price tiers will be rejected from delivery—this includes track-level pricing, which is only valid for Japanese local content in Music Profile 3.1.
Music Profile: Track Numbering
The tag for track numbering has been simplified to make it more consistent across specifications. This is now specified with the <track_number> flag for all videos and audio tracks.
Music Profile: User-Generated Ringtones
Customers can now purchase the right to use a song they have already purchased to use as ringtones.
Music Profile: Video Preview Start Time
Music video start times may now be specified in the video’s initial delivery, or updated in subsequent metadata updates.
Music Profile: Video Data and Artwork File Tagging
Music video asset tag structure has been revised to be consistent across specification profiles.
Music Profile: Video Wholesale Price Tiers
With new contracts, one of three price tiers are now available for videos: 98, 99, 100 (actual tier names may vary by contract).
Artist names now have a 255 7-bit (Roman) character limit, and as few as 71 Unicode characters. Japanese, Greek or other non-Roman languages use Unicode characters and artist names that use these character sets therefore must use a reduced number of characters (71 or fewer).
Music Profile: Asset-Only Delivery for Video
Video assets can now be delivered independent of metadata. These deliveries are for video asset replacement or for labels that have metadata delivered by one party and the videos delivered by a video encoding company.
Music Profile: Foreign Language Support
Restrictions to use have been added. Note that incorrect use of artist or title translations may result in discontinued eligibility for this feature.
Music Profile: Plus Quality
Support is now added to handle specifying availability of iTunes Plus high-quality audio. This is indicated at the album-level (or video-level for video singles) per territory.
Music Profile: Pre-Orders
Preview audio is now available on all pre-orders. This is an optional tag that makes thirty-second previews available for customers to sample before they commit to purchasing a pre-order album.
Music Profile: Title and Version Title Clarifications
Use of titles and title versions has been expanded and clarified in this specification. Titles now have a 255-byte limit. This is 255 Roman alphabet and 71 double-byte characters. Here again, Japanese, Greek or other non-Roman languages use Unicode characters and titles and title versions that use these character sets therefore must use a reduced number of characters (71 or fewer).
Music Profile: Track Ringtone Clearance
Availability for ringtone sale may now specified at the territory level.
Music Profile: Tag Changes
Deprecated
<original_release_year>
<track_explicit_lyrics>
Changed (new tag = old tag)
<explicit_content> = <track_explicit_lyrics>
Added
<album_preorder_previews>
<explicit_content>
<sell_plus_quality>
Changes in iTunes Package Music Specification 2.3
iTunes Store Package: Empty XML Tags
Empty XML tags are no longer accepted in metadata. If not used, the tags should be removed; otherwise, unintended results may occur, such as marking an album “clean” when it is not in fact a clean version.
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 may be specified using “WW” only. It is preferred that the “WW” territory is used whenever possible so that the fewest number of necessary territories are included in the delivered metadata.
Music Profile: Classical Works
Support is now added to handle longer classical music such as concertos or symphonies that are divided into movements, or “works.”
Music Profile: Title and Version Title Clarifications
Use of titles and title versions has been expanded and clarified in this specification.
Music Profile: Track Additions and Updates Support
XML-only updates are now supported through the feed for the following: track additions, audio updates, territory clearance additions, release date changes and track additions.
Music Profile: Wholesale Price Tier
Price tiers are required. If they are not specified, then the album will be offered as an incomplete album in all territories missing wholesale pricing.
Music Profile: Tag Changes
Deprecated
<sales_end_date>
Added
<work>
Changes in iTunes Package Music Specification 2.2.1
Introduction of Profiles
The addition of multiple types of content (music video, music, film and TV) has led to the introduction of profiles to the specification structure. This approach has been taken, rather than separate specifications, to ensure that as much commonality as possible is preserved.
Music Profile: Chaptering
Audio chaptering is now supported at the track level. This is especially useful for long mixed tracks or audio interviews.
Music Profile: Gapless audio
Gapless audio (tracks that have no auditory space between them) is now supported and is flagged at the track-level between tracks that have no gap.
