This document specifies the package format for delivering music content to Apple.
A 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.
For questions regarding other kinds of content, such as television or film, contact your Apple Technical Representative.
Date/Version | Changes Made |
|---|---|
December 2024 - Version 5.3.21 | Updated information on the |
For a complete history of changes, see Previous Spec Revisions.
Music Profile: Role
Updated information on the <role> tag. See Basic Music Album Metadata Annotated.
Music Profile: Track Flags
Updated the list of track flags. See Basic Music Album Metadata Annotated.
Music Video Single: Flags
Added the list of video flags. See Music Video Single Metadata Example and Music Video Single Metadata Annotations.
General
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 Apple Video and Audio Asset Guide.
All delivered metadata and asset files must be delivered in the package format.
A 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.
A schema is used to validate the XML document you send in a 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):
<package xmlns="http://apple.com/itunes/importer" version="music5.3">
Note that this information is for clarification purposes; the numbering schemes have not changed and do not affect the delivery process as long as you follow the numbering rules.
All metadata files must use UTF-8 Unicode character encoding. UTF-8 efficiently encodes non-Roman characters and helps to ensure that metadata displayed on Apple Music 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.
All content files delivered to Apple must include an industry-standard MD5 checksum, a measure that helps to guarantee that the asset files received by Apple are correct and complete. Once received, the MD5 checksum contained in the metadata file (one for each asset file provided) is compared against the actual file received by Apple. If any differences are detected, the asset file and the entire corresponding package are rejected. See the Helpful Tools section of this document for tools that can generate MD5 checksums for your content.
There should be no null data or empty tags in the XML (except 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 Schema Validation Guide for more information.
This section describes HDR (high dynamic range) video and provides delivery requirements for HDR video source (either Dolby® Vision or HDR10). The HDR source can be delivered in an asset-only update or with a new delivery. For Dolby® Vision XML examples and annotations, see HDR Dolby® Vision Metadata Example and HDR Dolby® Vision Metadata Annotations. For HDR10 XML examples and annotations, see HDR10 Metadata Example and HDR10 Metadata Annotations. For XML example showing how to deliver HDR and SDR videos in the same delivery, see HDR and SDR Delivery.
For HDR and 4K source asset requirements, see Music Video HDR Source Profile and Music Video 4K Source Profile in Apple Video and Audio Asset Guide.
The following terms are used in this section:
Primary video Refers to the SDR source video
Secondary video Refers to the HDR source video
Sidecar metadata Refers to the accompanying mapping metadata XML file for Dolby® Vision or HDR asset metadata for HDR10
Compared to current non-HDR standards, HDR video can display a wider range of color, brightness, and shades of darkness, which enhances details in the brightest and darkest areas in a video frame. These dynamic variations can change based on the target display and also for individual scenes within the video. To specify these variations, you must deliver additional metadata when delivering the HDR source video. This sidecar metadata lists the following:
Details of the display monitor used for mastering the HDR source
Display targets (their sizes, bit depth, color space, chroma formats, and so on)
Content luminance details
Changes in color corrections either to shots (scenes) or individual frames, if needed
Note: Detailed instructions on constructing this additional metadata are beyond the scope of this specification. For Dolby® Vision mapping metadata, refer to the confidential document “Dolby Content Mapping (CM) Metadata Format Specification Version 2.0.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.
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 Apple Video and Audio Asset Guide in the appropriate section based on the format.
The HDR source video can be delivered with a new delivery or in an asset-only update delivery. For a new, complete delivery, you must deliver the primary video, the 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.
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 has 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 app has English as its default language, but also supports Spanish. A user who signs into the US app with their OS language set to English will see the app’s UI in English; a user who signs into the US app with their OS language set to Spanish will see the app’s UI in Spanish. Whichever language is chosen to display the app’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 |
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. 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.
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.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>en</language> <provider>OneIndependent</provider> <album> <vendor_id>5099749642829</vendor_id> <upc>5099749642829</upc> <grid>A10302B0000114391R</grid> <vendor_offer_code>408CH98720X103</vendor_offer_code> <title>Medúlla</title> <title_version>Remastered</title_version> <original_release_date>2004-08-30</original_release_date> <label_name>One Independent</label_name> <genres> <genre code="ALTERNATIVE-00"/> <genre code="WORLD-00"/> </genres> <flags> <flag>DJ Mix</flag> <flag>Remix</flag> <flag>Compilation</flag> <flag>Live</flag> </flags> <copyright_pline>2004 One Independent</copyright_pline> <copyright_cline>2004 One Independent</copyright_cline> <artwork_files> <file> <file_name>cover.jpg</file_name> <size>6591649</size> <checksum type="md5">ffa9327b444559d4d72312b2c7d660ff</checksum> </file> </artwork_files> <assets> <asset type="motion_art_3:4"> <data_file role="source"> <file_name>motion_art_tall.mov</file_name> <size>918842964</size> <checksum type="md5">772ee9ed2ed40a6d19eebbf039ef3075</checksum> </data_file> </asset> <asset type="motion_art_1:1"> <data_file role="source"> <file_name>motion_art_square.mov</file_name> <size>341635940</size> <checksum type="md5">b0718c2fe9143dceb266e042ac668162</checksum> </data_file> </asset> </assets> <track_count>3</track_count> <products> <product> <territory>GB</territory> <wholesale_price_tier>3</wholesale_price_tier> <sales_start_date>2019-10-22</sales_start_date> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> <product> <territory>IE</territory> <wholesale_price_tier>3</wholesale_price_tier> <sales_start_date>2019-10-22</sales_start_date> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </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> <tracks> <track> <vendor_id>GBBFT0501345_9083</vendor_id> <isrc>GBBFT0501345</isrc> <iswc>T1235996341</iswc> <grid>A10302B00002427998</grid> <vendor_offer_code>408CH98720X103</vendor_offer_code> <title>The Pleasure Is All Mine</title> <title_version>Dub Remix</title_version> <original_release_date>2004-08-30</original_release_date> <gapless_play>true</gapless_play> <genres> <genre code="ELECTRONIC-00"/> <genre code="WORLD-00"/> </genres> <flags> <flag>Remix</flag> </flags> <products> <product> <territory>GB</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>98</wholesale_price_tier> <available_for_immersive_date>2021-10-22</available_for_immersive_date> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date><!-- NOTE: Use the tag below at the <product> level for the track if the track is cleared for streaming, but you do not want the track to be available for Apple Fitness+.--> <cleared_for_fitness>false</cleared_for_fitness> </product> <product> <territory>IE</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>98</wholesale_price_tier> <available_for_immersive_date>2021-10-22</available_for_immersive_date> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> <cleared_for_fitness>false</cleared_for_fitness> </product> </products> <label_name>One Independent</label_name> <publishers> <publisher>Kobalt Music Publishing</publisher> <publisher>Universal Music Publishing</publisher> </publishers> <copyright_pline>2004 One Independent</copyright_pline> <explicit_content>none</explicit_content> <lyrics_set> <lyrics_file> <file_name>pleasure.ttml</file_name> <size>993</size> <checksum type="md5">40619cd971b4d41987f7dd3c28738a9f</checksum> </lyrics_file> <lyrics_file locale="zh-Hans"> <file_name>zh-Hans-pleasure.ttml</file_name> <size>1067</size> <checksum type="md5">8738a9f9cd977f7d4d4106d311b98c24</checksum> </lyrics_file> <lyrics_file locale="zh-Hant"> <file_name>zh-Hant-pleasure.ttml</file_name> <size>1132</size> <checksum type="md5">19cd971b988738a9f7f7d44d4106d3c2</checksum> </lyrics_file> </lyrics_set> <volume_number>1</volume_number> <track_number>1</track_number><!-- NOTE: Use the track <assets> block to deliver immersive audio.--> <assets> <asset type="full"> <data_file role="audio.2_0"> <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="external_identifier.isrc">GCGHY12345678</attribute> </data_file> </asset> </assets> <audio_language>en</audio_language> <preview_start_index>30</preview_start_index> <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> <apple_id>295015</apple_id> <roles> <role>Composer</role> </roles> <primary>false</primary> </artist> <artist> <apple_id>458966378</apple_id> <roles> <role>Producer</role> </roles> <primary>false</primary> </artist> </artists> </track> <track> <vendor_id>GBBFT0460211_2369</vendor_id> <isrc>GBBFT0460211</isrc> <vendor_offer_code>408CH98720X103</vendor_offer_code> <title>Vokuro</title> <title_version>Super DJ Mix</title_version> <gapless_play>false</gapless_play> <genres> <genre code="ELECTRONIC-00"/> <genre code="DANCE-00"/> </genres> <flags> <flag>DJ Mix</flag> </flags> <products> <product> <territory>GB</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>98</wholesale_price_tier> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> <product> <territory>IE</territory> <wholesale_price_tier>98</wholesale_price_tier> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> </products> <label_name>One Independent</label_name> <copyright_pline>2004 One Independent</copyright_pline> <explicit_content>explicit</explicit_content> <lyrics_file> <file_name>vokuro.ttml</file_name> <size>3285</size> <checksum type="md5">80ed6dd4ffca0fdabb6ae6bf2ec8fa73</checksum> </lyrics_file> <volume_number>1</volume_number> <track_number>2</track_number><!-- NOTE: Use the track <assets> block to deliver immersive audio. This track includes Dolby Atmos audio, specified to downmix to stereo, so the delivery of audio.2_0 is not required for this track. --> <assets> <asset type="full"> <data_file role="audio.object_based"> <file_name>Vokuro.mov<</file_name> <size>76556834</size> <checksum type="md5">84ffcfa76ddae30fdad6bf2ecabb680e</checksum> <attribute name="audio.transform_to.2_0">true</attribute> </data_file> </asset> </assets> <audio_language>en</audio_language> <preview_start_index>30</preview_start_index> <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> </artists> </track> <track> <vendor_id>GBBFT2500811_0912</vendor_id> <isrc>GBBFT2500811</isrc> <title>Medúlla Medley</title> <title_version>Radio Edit</title_version> <gapless_play>false</gapless_play> <genres> <genre code="ELECTRONIC-00"/> <genre code="WORLD-00"/> </genres> <products> <product> <territory>GB</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>98</wholesale_price_tier> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> <product> <territory>IE</territory> <cleared_for_sale>true</cleared_for_sale> </product> </products> <label_name>One Independent</label_name> <copyright_pline>2004 One Independent</copyright_pline> <lyrics_file> <file_name>medley.ttml</file_name> <size>4014</size> <checksum type="md5">73dae6bf2eccfa0fda84ff6ddabb680e</checksum> </lyrics_file> <volume_number>1</volume_number> <track_number>3</track_number> <audio_file> <file_name>medley.m4a</file_name> <size>99253792</size> <checksum type="md5">c3330a3565baf58300bba711e3c26966</checksum> </audio_file> <audio_language>en</audio_language> <preview_start_index>30</preview_start_index> <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>Rahzel</artist_name> <apple_id>1466117</apple_id> <roles> <role>Beatbox 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> <apple_id>458966378</apple_id> <roles> <role>Producer</role> </roles> <primary>false</primary> </artist> </artists> <chapters> <chapter> <chapter_start_time>00:00:00.000</chapter_start_time> <chapter_title>Triumph of a Heart</chapter_title> <artwork_file> <file_name>triumph.jpg</file_name> <size>5866324</size> <checksum type="md5">ed93d0f322c8d4175d4a353a4c645130</checksum> </artwork_file> </chapter> <chapter> <chapter_start_time>00:02:45.000</chapter_start_time> <chapter_title>Who Is It</chapter_title> <artwork_file> <file_name>who.jpg</file_name> <size>6852291</size> <checksum type="md5">86bed345f40d1117ef05c34c1e8537a9</checksum> </artwork_file> </chapter> </chapters> </track> </tracks> </album></package>Package Metadata Fields |
|
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). |
|
 Package Container (required) The
The |
|
 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 The language codes are formatted according to the best practices recommended by the Internet Engineering Task Force (IETF) in a group of documents known collectively as BCP 47, and in particular, RFC 5646, which is part of BCP 47. An overview of these best practices is provided at the W3C Internationalization site. |
Provider Metadata Fields |
|
 Provider (required, Apple-supplied) This value should be the Apple-defined provider name used for partner identification. The value must match the provider |
Album Metadata Fields |
|
 Album (required) Begins the |
|
 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. |
|
 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. |
|
 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'. |
|
 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 If an album has a title version, use the 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. |
|
 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 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 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: |
|
 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 interface. Note: This field is cosmetic only and does not impact the "available date" or "street date" on Apple Music. 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 |
|
 Album Label Name (required; can be updated) The name of the label that released the album. |
|
 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 Required method using the genre code:
Acceptable method using both the genre code and the genre label:
For a complete list of genres, go to iTunes Connect Resources and Help to download the spreadsheet titled “Music, Music Video, and Ringtone Genre Codes.” Important: Genre information may be reassigned at the discretion of Apple. |
|
 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.
You can use the following flags for album categories:
|
|
 Album Copyright P-Line (optional; can be updated) Performance copyright line for the album. Must follow the format |
|
 Album Copyright © Line (optional; can be updated) Copyright line for the album. Must follow the format |
|
 Album Artwork (required; may be updated; see Content Update Behavior) Album artwork is required, and you must provide the Important: If providing a metadata-only update, the |
|
 Album Motion Art (optional; may be updated) The The
The In this block, the |
|
 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 Note: An album can include up to a maximum of 500 tracks. |
Album Products Metadata Fields |
|
|
 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 leave out the |
|
 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 For a list for ISO 3166-1 alpha 2 codes, see https://en.wikipedia.org/wiki/ISO_3166-1. For more information on ISO codes, see https://www.davros.org/misc/iso3166.html. |
|
 Wholesale Price Tier (required; can be updated) 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 (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 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 (optional; can be updated) Specifies whether the album is cleared for sale in the territory for the product. Must be Whenever possible, use the 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 As a further example, to indicate album clearance for world less France and US, add only three album products: one for world with |
Album Cleared for Streaming (optional; can be updated) Indicates if the album can be streamed on demand. Allowed values are Set the value to Tip: If you have the rights to stream most tracks on an album, you could use In some cases, a provider might only have streaming rights; in that situation, 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. |
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 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 |
|
|
 Album Artists (required; can be updated, but may require a ticket; see Content Update Behavior) Name, Apple identifier, 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 identifier using the Apple assigns every artist a unique Apple identifier; Apple recommends that performing artists be delivered with the Apple identifier to avoid the ambiguity in cases where artists share the same name as other music artists, or film actors or crew members. Make sure to use the unique Apple identifier for the contributing artist name. For example, the person Aubrey Graham performs music under the identity "Drake" and also composes under the identity "Aubrey Graham." These identities should have their own unique Apple identifiers. You can supply the If you do not know the artist's Apple identifier, you can do an artist lookup and look for the To create an artist, generate the artist and Apple identifier using the artist feed. See Creating a New Artist. For subsequent updates, use the 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 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. Make sure to use the unique ISNI for the specific contributing artist identity. For example, the person Onika Maraj performs her music under the identity "Nicki Minaj" and also composes under the identity "Onika Maraj." These identities should have their own unique ISNI. To find an ISNI, search the ISNI database. When you use the Role Use the
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: Failure to add full and accurate songwriter metadata in a timely manner may delay payment of royalties to publishers and songwriters. Primary Status The primary role indicates whether the album appears on the artist’s page on Apple Music. Typically, there are one or two primary (lead) artists and several supporting artists. The primary role is reserved for the primary (lead) artists. Do not use Only primary artists are displayed with the album. Artist names appear in the order in which they are specified in the provided metadata. You can consolidate all roles for an artist into a single
Note: You can use the |
Track Metadata Fields |
|
 Tracks (required) Begins the |
|
 Track (required) Begins the |
|
 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 |
|
 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 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. |
|
 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 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 |
|
 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'. |
|
 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: 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. |
|
 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: Important: Because parentheses are automatically added to the title version, do not use parentheses in the value for 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. Note: This field is cosmetic only and does not impact the "available date" or "street date" on Apple Music. 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 |
|
 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 Accepted values are |
|
 Track Label Name (optional; can be updated) The name of the label which released the album. If not specified, the |
|
 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 |
|
 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 Required method using the genre code:
Acceptable method using both the genre code and the genre label:
For a complete list of genres, go to iTunes Connect Resources and Help to download the spreadsheet titled “Music, Music Video, and Ringtone Genre Codes.” Important: Genre information may be reassigned at the discretion of Apple. |
|
 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.
You can use the following flags for track categories:
|
|
 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 Note: If you leave out the |
|
 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 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
|
|
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 Set the value to Tip: If you have the rights to stream an entire album except for one track, you could use 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. |
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 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. |
Track Cleared for Fitness+ (optional; can be updated) Indicates if the track is available on Fitness+. Allowed values are Set the value to Notes:
|
|
|
 Track Copyright P-Line (optional; can be updated) Performance copyright line for the track. Must follow the format Important: If not specified, the copyright line from the album is used. |
|
 Track Parental Advisory (optional; may be updated; see Content Update Behavior) Denotes whether or not a track contains explicit content. May be Important: A track must only be marked |
|
 Track Lyrics Set (optional; can be updated) Use The lyrics are delivered as a TTML file ( 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 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 |
|
 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 (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. |
Track Audio Delivery Options |
|
 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 In this Notes:
To remove or replace immersive audio, see Immersive Audio Updates. |
|
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 In this File format accepted for immersive audio.7_1 and audio.5_1:
|
|
Immersive Track 1: Secondary ISRC (required) The ISRC (International Standard Recording Code) for the track’s immersive audio recording. The ISRC is required when you deliver an immersive audio recording. The ISRC is used to reflect a specific recording and the immersive audio is considered a new recording. Supply the ISRC using the attribute ISRCs must be unique across all recordings. A re-recorded, remixed or otherwise different track (no matter how similar) must have a unique ISRC. Important: ISRCs must not include dashes and should contain only letters and numbers as in the example, GCGHY12345678. |
|
|
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: In this File format accepted for the Dolby Atmos master file:
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 Notes:
To remove or replace immersive audio, see Immersive Audio Updates. |
|
 Track 3 Audio File (required; may be updated; see Content Update Behavior) See Apple Video and Audio Asset Guide for complete audio file requirements. |
|
 File Name (required) 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 Important: Filenames are case-sensitive. |
|
 Track Audio Asset File Size (required) Size in bytes of the provided audio asset file for the track. |
|
 Checksum (required) The MD5 checksum of the data file. See Checksums for more information. |
|
End of Track Audio Delivery Options |
Remaining Track Tags |
|
 Track Audio Language (required; can be updated) Use the The language codes are formatted according to the best practices recommended by the Internet Engineering Task Force (IETF) in a group of documents known collectively as BCP 47, and in particular, RFC 5646, which is part of BCP 47. An overview of these best practices is provided at the W3C Internationalization site. Note: The language specified in the |
|
 Track Preview Start (optional; can be updated) Allows providers to specify a custom start time for the preview audio. The Important: If not specified, the default is 45 seconds for content over 75 seconds in length and 0 seconds for shorter content. |
|
 Track Artists (required; can be updated, but may require a ticket; see Content Update Behavior) Name, Apple identifier, 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 identifier using the Apple assigns every artist a unique Apple identifier; Apple recommends that performing artists be delivered with the Apple identifier to avoid the ambiguity in cases where artists share the same name as other music artists, or film actors or crew members. Make sure to use the unique Apple identifier for the contributing artist name. For example, the person Aubrey Graham performs music under the identity "Drake" and also composes under the identity "Aubrey Graham." These identities should have their own unique Apple identifiers. You can supply the If you do not know the artist's Apple identifier, you can do an artist lookup and look for the To create an artist, generate the artist and Apple identifier using the artist feed. See Creating a New Artist. For subsequent updates, use the 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 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. Make sure to use the unique ISNI for the specific contributing artist identity. For example, the person Onika Maraj performs her music under the identity "Nicki Minaj" and also composes under the identity "Onika Maraj." These identities should have their own unique ISNI. To find an ISNI, search the ISNI database. When you use the Important: If the ISNI you supply is not the correct ISNI for the Role Use the
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: Failure to add full and accurate songwriter metadata in a timely manner may delay payment of royalties to publishers and songwriters. Primary Status The primary role indicates whether the album appears on the artist’s page on Apple Music. Typically, there are one or two primary (lead) artists and several supporting artists. The primary role is reserved for the primary (lead) artists. Do not use Artist names 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 In Apple Music, the track display shows the primary artist only when different from the album’s primary artist. For example, if an album has two artists with primary status, then the only tracks that display a primary artist are tracks that have additional primary artists or tracks that don't include both primary artists. Note: You can use the |
|
 Track Chaptering (optional; can be updated) Defines chapters within a given track. If used, then Chapter start time is in 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. |
|
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 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.
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.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>en</language> <provider>OneIndependent</provider> <album> <vendor_id>5099749642829</vendor_id> <upc>5099749642829</upc> <grid>A10302B0000114391R</grid> <title>Medúlla</title> <title_version>Remastered</title_version> <original_release_date>2004-08-30</original_release_date> <label_name>One Independent</label_name> <genres> <genre code="ALTERNATIVE-00"/> <genre code="WORLD-00"/> </genres> <copyright_pline>2005 One Independent</copyright_pline> <copyright_cline>2005 One Independent</copyright_cline> <track_count>3</track_count> <products> <product> <territory>GB</territory> <wholesale_price_tier>4</wholesale_price_tier> <sales_start_date>2019-10-22</sales_start_date> <cleared_for_sale>true</cleared_for_sale> </product> <product> <territory>IE</territory> <wholesale_price_tier>3</wholesale_price_tier> <sales_start_date>2004-10-22</sales_start_date> <cleared_for_sale>false</cleared_for_sale> </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> <tracks> <track> <vendor_id>GBBFT0501345_9083</vendor_id> <isrc>GBBFT0501345</isrc> <iswc>T1235996341</iswc> <grid>A10302B00002427998</grid> <title>The Pleasure Is All Mine</title> <title_version>Dub Remix</title_version> <original_release_date>2004-08-30</original_release_date> <gapless_play>true</gapless_play> <genres> <genre code="ELECTRONIC-00"/> <genre code="WORLD-00"/> </genres> <products> <product> <territory>GB</territory> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> <product> <territory>IE</territory> <cleared_for_sale>false</cleared_for_sale> </product> </products> <label_name>One Independent</label_name> <copyright_pline>2004 One Independent</copyright_pline> <explicit_content>none</explicit_content> <lyrics_file> <file_name>pleasure.ttml</file_name> <size>2655</size> <checksum type="md5">6bdaef2ec86ddabb680e4fffdacfa730</checksum> </lyrics_file> <volume_number>1</volume_number> <track_number>1</track_number> <preview_start_index>30</preview_start_index> <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> </artists> </track> <track> <vendor_id>GBBFT0460211_2369</vendor_id> <isrc>GBBFT0460211</isrc> <title>Vokuro</title> <title_version>Super DJ Remix</title_version> <gapless_play>false</gapless_play> <genres> <genre code="ELECTRONIC-00"/> <genre code="DANCE-00"/> </genres> <products> <product> <territory>GB</territory> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> <product> <territory>IE</territory> <cleared_for_sale>false</cleared_for_sale> </product> </products> <label_name>One Independent</label_name> <copyright_pline>2004 One Independent</copyright_pline> <explicit_content>explicit</explicit_content> <lyrics_file> <file_name>vokuro.ttml</file_name> <size>3285</size> <checksum type="md5">80ed6dd4ffca0fdabb6ae6bf2ec8fa73</checksum> </lyrics_file> <volume_number>1</volume_number> <track_number>2</track_number> <preview_start_index>30</preview_start_index> <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> </artists> </track> <track> <vendor_id>GBBFT2500811_0912</vendor_id> <isrc>GBBFT2500811</isrc> <title>Medúlla Medley</title> <title_version>Radio Edit</title_version> <gapless_play>false</gapless_play> <genres> <genre code="ELECTRONIC-00"/> <genre code="WORLD-00"/> </genres> <products> <product> <territory>GB</territory> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> <product> <territory>IE</territory> <cleared_for_sale>false</cleared_for_sale> </product> </products> <label_name>One Independent</label_name> <copyright_pline>2004 One Independent</copyright_pline> <lyrics_file> <file_name>medley.ttml</file_name> <size>4014</size> <checksum type="md5">73dae6bf2eccfa0fda84ff6ddabb680e</checksum> </lyrics_file> <volume_number>1</volume_number> <track_number>3</track_number> <preview_start_index>30</preview_start_index> <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> </artists> <chapters> <chapter> <chapter_start_time>00:00:00.000</chapter_start_time> <chapter_title>Triumph of a Heart</chapter_title> </chapter> <chapter> <chapter_start_time>00:02:45.000</chapter_start_time> <chapter_title>Who Is It</chapter_title> </chapter> </chapters> </track> </tracks> </album></package>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, set <cleared_for_sale> to false for the specified <territory>. In the <product> block, supply only the <cleared_for_sale> and <territory> tags; you do not need to supply any other tags within the <product> block for the territory you are removing.
Note: Include only the territories you are adding, modifying, or removing; you do not need to deliver all territories.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>en</language> <provider>OneIndependent</provider> <album> <vendor_id>5099749642829</vendor_id> <products> <product> <territory>AU</territory> <wholesale_price_tier>4</wholesale_price_tier> <sales_start_date>2019-10-22</sales_start_date> <cleared_for_sale>true</cleared_for_sale> </product> <product> <territory>NZ</territory> <wholesale_price_tier>3</wholesale_price_tier> <sales_start_date>2019-10-22</sales_start_date> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> <product> <territory>CA</territory> <cleared_for_sale>false</cleared_for_sale> </product> </products> <tracks> <track> <vendor_id>GBBFT2500811_0912</vendor_id> <products> <product> <territory>AU</territory> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> <product> <territory>NZ</territory> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> <product> <territory>CA</territory> <cleared_for_sale>false</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> </products> </track> </tracks> </album></package>Assets can be delivered independent of metadata for asset-only updates. This kind of update is especially helpful if the assets need to be replaced due to encoding or other issues. Assets cannot be delivered unless the metadata has already been sent and imported. If the assets are sent without metadata to which they can be attached, delivery fails.
In order to deliver assets separately from the metadata, you must supply the correct vendor ID and ISRC to match the already delivered metadata.
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 within 24-48 hours of delivery.
For any questions regarding asset-only delivery, contact your Technical Representative.
Example: Asset-only update of a stereo audio data file
The following metadata example shows how to replace an existing stereo audio asset.
<package version="music5.2"> <provider>OneIndependent</provider> <assets media_type="music_playlist" vendor_id="5099749642829"> <asset type="full" media_type="song" vendor_id="USMPK0591601"> <data_file role="audio.2_0"> <file_name>how-you-remember.wav</file_name> <size>5292044</size> <checksum type="md5">6f85303a0b81fb0939cdbd263ddf4601</checksum> <attribute name="isrc">USMPK0591601</attribute> </data_file> </asset> </assets></package>Example: Asset-only update that removes a 5.1 audio asset
The following metadata example assumes you have a single with stereo and 5.1 audio assets. This example removes the 5.1 audio asset.
<package version="music5.2"> <provider>OneIndependent</provider> <assets media_type="music_playlist" vendor_id="5099749642829"> <asset type="full" media_type="song" vendor_id="USMPK0111201"> <data_file remove="true" role="audio.5_1"> <file_name>Audio5_1.mov</file_name> <size>140129967</size> <checksum type="md5">c30b02ead8125079697020b38db89906</checksum> <attribute name="external_identifier.isrc">USMPK0111251</attribute> <attribute name="audio.transform_to.2_0">false</attribute> </data_file> </asset> </assets></package>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.
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 |
|
Downmix to Stereo In the following example, the 7.1 audio file will be downmixed to 2.0 stereo. This is specified using the Notes:
|
|
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> The following metadata example shows how to replace an immersive audio with a new audio file. 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"> <file_name>replacement_pleasure.mov</file_name> <size>82554355</size> <checksum type="md5">444444ee2a2d74e226dde93cf3a5327b</checksum> </data_file> </asset> </assets> </track> </tracks> </album> </package>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.
For the sake of brevity, only two territories are shown.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>en</language> <provider>OneIndependent</provider> <album> <vendor_id>5099749642829</vendor_id> <upc>5099749642829</upc> <grid>A10302B0000114391R</grid> <title>Medúlla</title> <title_version>Remastered</title_version> <original_release_date>2004-08-30</original_release_date> <label_name>One Independent</label_name> <genres> <genre code="ALTERNATIVE-00"/> </genres> <copyright_pline>2004 One Independent</copyright_pline> <copyright_cline>2004 One Independent</copyright_cline> <products> <product> <territory>GB</territory> <cleared_for_sale>false</cleared_for_sale> </product> <product> <territory>IE</territory> <cleared_for_sale>false</cleared_for_sale> </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> </artists> </album></package>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.
Music videos can be delivered in HD and must include crop dimensions. See Music Video Single Crop Dimensions Metadata Example for an example.
Note: For an initial delivery of a music video, delivery of the video asset source is required.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>en</language> <provider>Warner</provider> <video> <vendor_id>GB5170300040</vendor_id> <grid>A10302B00002427998</grid> <upc>825646307760</upc> <isrc>GB5170300040</isrc> <title>Zeal</title> <title_version>Extended Version</title_version> <original_release_date>2003-01-10</original_release_date> <label_name>Warner Music</label_name> <genres> <genre code="ROCK-00"/> </genres> <flags> <flag>Official Music Video</flag> <flag>Remix</flag> <flag>Lyric</flag> <flag>Live</flag> </flags> <copyright_cline>2003 Warner Music</copyright_cline> <copyright_pline>2003 Warner Music</copyright_pline> <explicit_content>none</explicit_content> <assets> <asset type="full"> <data_file role="source"> <file_name>GB5170300040.mpg</file_name> <size>93664213</size> <checksum type="md5">a8900fb356b7c23badeca6f3010a98aa</checksum> </data_file> <data_file role="captions"> <file_name>GB5170300040-english.scc</file_name> <size>9511</size> <checksum type="md5">5a793a8b46037fe8aa2bdd739b49911a</checksum> <attribute name="program.start.timecode">-01:00:00:00</attribute> </data_file> </asset> </assets> <!-- Defined preview and artwork image clip --> <previews> <preview timecode_format="qt_text" start_time="00:05:13.002" image_time="00:05:20.128"/> </previews> <products> <product> <territory>US</territory> <wholesale_price_tier>98</wholesale_price_tier> <sales_start_date>2006-01-16</sales_start_date> <cleared_for_sale>true</cleared_for_sale> </product> </products> <artists> <artist> <artist_name>Plaid</artist_name> <apple_id>4514151</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> </video></package>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 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). |
|
Package Container (required) The
The |
|
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 The language codes are formatted according to the best practices recommended by the Internet Engineering Task Force (IETF) in a group of documents known collectively as BCP 47, and in particular, RFC 5646, which is part of BCP 47. An overview of these best practices is provided at the W3C Internationalization site. |
Provider Metadata Fields |
|
Provider (required, Apple-supplied) This value should be the Apple-defined provider name used for partner identification. The value must match the provider |
Video Metadata Fields |
|
 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 |
|
 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. |
|
 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. |
|
 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. |
|
 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 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. |
|
 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: 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. |
|
 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 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 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: |
|
 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 the Apple Music interface only. This field does not impact date of release or "street date" for Apple Music. 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 Note: The |
|
 Music Video Label Name (required; can be updated) The name of the label that released the music video. |
|
 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 Required method using the genre code:
Acceptable method using both the genre code and the genre label:
For a complete list of genres, go to iTunes Connect Resources and Help to download the spreadsheet titled “Music, Music Video, and Ringtone Genre Codes.” Important: Genre information may be reassigned at the discretion of Apple. |
|
 Music Video Flags (optional; can be updated, but may require a ticket; see Content Update Behavior) Music video flags specify categories used to place music videos appropriately on artist pages.
You can use the following flags for categories:
|
|
 Music Video Copyright © Line (optional; can be updated) Copyright line for the music video. Must follow the format |
|
 Music Video Copyright ℗ Line (optional; can be updated) Performance copyright line for the music video. Must follow the format |
|
 Music Video Parental Advisory (required; may be updated; see Content Update Behavior) Denotes whether a video contains explicit content—lyrics, visuals, or otherwise. May be Important: A track must only be marked |
|
 Assets (required) Begins the |
|
 Music Video Asset File (required; can be updated) The music video asset is required with initial deliveries. Refer to Apple Video and Audio Asset Guide for all asset file requirements. |
|
 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 ( Since the file sent is used as the source file for the Apple encode, the role must be Important: Filenames are case-sensitive. |
|
 Music Video Asset File Size (required) The size of the video file. |
|
 Music Video Asset File Checksum (required) The MD5 checksum of the data file. See Checksums for more information. |
|
|
 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 In this block, the |
|
File Name (required) The name of the caption file included in this delivery package. The name should be relative to the package (containing no path reference “C:\” or “/Macintosh HD/”) and must contain the file name extension ( Important: File names are case sensitive and spaces are not allowed. |
|
File Size (required) The size in bytes of the caption file. Do not specify any commas or period delimiters. |
|
Checksum (required) The MD5 checksum of the caption file. See the Checksums section for more information. |
|
 Timecode Offset (optional) Indicates the timecode offset for the closed captions. Apple requires that timecodes start at a program start of 00:00:00:00, which may necessitate that captions be offset if they have been mastered to tape timecode. To keep closed captions in sync on the encoded file, use the |
|
Metadata-Based Preview Clipping and Screen Capture Image (optional; can be updated) Begins the Use the following attributes to specify the timecode format, the start time of the clip, and the frame to use for the preview image:
Important: The Note: Apple strongly recommends that you submit a screen capture directly from the video using the
|
|
|
|
 Music Video Product (required; can be updated) 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:
|
|
 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. For a list for ISO 3166-1 alpha 2 codes, see https://en.wikipedia.org/wiki/ISO_3166-1. For more information on ISO codes, see https://www.davros.org/misc/iso3166.html. |
|
 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. |
|
 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 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. |
|
 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 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 |
|
|
 Music Video Artists (required; can be updated, but may require a ticket; see Content Update Behavior) Name or Apple identifier, 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 identifier (using the 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
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: 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 Note: You can use the |
|
Below is an example metadata.xml file for a music video (in HD or SD) that shows how to deliver crop dimensions. (See Apple 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.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>en</language> <provider>Warner</provider> <video> <vendor_id>GB5170300040</vendor_id> <grid>A10302B00002427998</grid> <upc>825646307760</upc> <isrc>GB5170300040</isrc> <title>Zeal</title> <title_version>Extended Version</title_version> <original_release_date>2012-01-10</original_release_date> <label_name>Warner Music</label_name> <genres> <genre code="ROCK-00"/> </genres> <copyright_cline>2003 Warner Music</copyright_cline> <copyright_pline>2003 Warner Music</copyright_pline> <explicit_content>none</explicit_content> <preview starttime="30"/> <assets> <asset type="full"> <data_file role="source"> <file_name>GB5170300040.mov</file_name> <size>93664213</size> <checksum type="md5">a8900fb356b7c23badeca6f3010a98aa</checksum> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name="crop.right">0</attribute> </data_file> </asset> <asset type="artwork"> <data_file> <file_name>videoart.jpg</file_name> <size>6846623</size> <checksum type="md5">263e9f7612598fad35130716f15d7bde</checksum> </data_file> </asset> </assets> <products> <product> <territory>US</territory> <wholesale_price_tier>98</wholesale_price_tier> <sales_start_date>2012-01-16</sales_start_date> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> </products> <artists> <artist> <artist_name>Plaid</artist_name> <apple_id>4514151</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> </video></package>
|
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
The values must be integers that represent the number of whole pixels of the encoded image. |
|
 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. If not specified, the default is 45 seconds. Important: Do not use both the |
|
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 when it is purchased. This must be taken from the video itself and can never be a cover of the corresponding single. Refer to Apple 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 Artwork can be provided with any kind of video, whether it is a video single or part of a playlist. |
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>Only the tags related to the HDR Dolby® Vision delivery are described. Refer to Basic Music Album Metadata Annotated for annotations on other tags.
Asset Level Tags |
Assets (required; can be updated) Begins the assets block that references the assets being delivered. In an asset-only update, the |
HDR Source Asset (required) The data file block specifies the source video file and describes the role of the associated file. In this example, the file sent is used as the HDR source, so the role must be The 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 |
HDR Format (required) In this example, the HDR video source is Dolby® Vision, which must be specified with the |
HDR Source Asset Locale (required) The locale for the HDR source video must match the locale of the primary video. If they do not match, delivery will fail. |
Textless Master (required) The value for textless master for the HDR source video must match the value for textless master primary video. If they do not match, delivery will fail. |
HDR Sidecar Mapping File (required) The data file block specifies the sidecar file and describes the role of the associated file. The maximum frame number (edit unit) referenced in the sidecar metadata file must be less than or equal to the last frame number of the secondary HDR video. For initial delivery, both the source HDR video file and the mapping file must be included or delivery will fail. When you send an update to deliver a new source HDR, the mapping file should be supplied (either by sending it with the update delivery or by using the previously-delivered mapping file). The mapping file, however, can be delivered (and updated) without specifying the source HDR. In this block, the 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.) |
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.
<?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 SDR video. --> <assets media_type="video" vendor_id="09736156444"> <asset type="full"> <data_file role="source.hdr"> <locale name="en-US"/> <file_name>09736156444-hdr-source.mov</file_name> <size>3244032000</size> <checksum type=“md5">9df86c3e43e7b43ddeabb2ddfe4b8a42</checksum> <attribute name="hdr.format">HDR10</attribute> <attribute name="hdr.red.chroma.x">0.6800</attribute> <attribute name="hdr.red.chroma.y">0.3200</attribute> <attribute name="hdr.green.chroma.x">0.2650</attribute> <attribute name="hdr.green.chroma.y">0.6900</attribute> <attribute name="hdr.blue.chroma.x">0.1500</attribute> <attribute name="hdr.blue.chroma.y">0.0600</attribute> <attribute name="hdr.whitepoint.chroma.x">0.3127</attribute> <attribute name="hdr.whitepoint.chroma.y">0.3290</attribute> <attribute name="hdr.max.display.luminance">1000</attribute> <attribute name="hdr.min.display.luminance">0.005</attribute> <attribute name="hdr.max.content.lightlevel">967</attribute> <attribute name="hdr.max.frame.avg.lightlevel">343</attribute> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name=“crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> </asset> </assets></package>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.
Asset Level Tags |
Assets (required; can be updated) Begins the assets block that references the assets being delivered. In an asset-only update, the |
HDR Source Asset (required) The data file block specifies the source video file and describes the role of the associated file. In this example, the file sent is used as the HDR source, so the role must be The secondary source video must be the same duration as the primary source video so that components such as subtitles and audio can be used with the secondary video. In this block, the |
HDR Format (required) In this example, the HDR video source is HDR10, which must be specified with the |
HDR10 Chromaticity Attributes (required) The mastering display chromaticity attributes are required and include:
The value listed for each attribute above must be a number with 4 decimal places and the value must be between 0.0 and 1.0 inclusive. The chromaticity attributes can only be used for a source HDR file with format HDR10. For a BT.2020 mastering display with D65, the following values are expected: <attribute name=“hdr.red.chroma.x”>0.7080</attribute><attribute name=“hdr.red.chroma.y”>0.2920</attribute><attribute name=“hdr.green.chroma.x”>0.1700</attribute><attribute name=“hdr.green.chroma.y”>0.7970</attribute><attribute name=“hdr.blue.chroma.x”>0.1310</attribute><attribute name=“hdr.blue.chroma.y”>0.0460</attribute><attribute name=“hdr.whitepoint.chroma.x”>0.3127</attribute><attribute name=“hdr.whitepoint.chroma.y”>0.3290</attribute> |
HDR10 Min Luminance Attribute (required) The minimum luminance attribute is required and the value must be a number with up to 3 significant digits and up to 4 decimal places. Value must be greater than or equal to 0.0. The minimum luminance attribute can only be used for source HDR file with format HDR10. |
HDR10 Max Light Level Attribute (optional) The maximum light level attribute is optional. The value is an unsigned short integer. Value must be between 0 and 65535 inclusive. If you provide 0 (zero) as the value, Apple will compute the value based on the cropped source content and insert the calculated value in the encoded bitstream. The maximum light level attribute can only be used for source HDR file with format HDR10. |
HDR10 Max Frame Average Light Level Attribute (optional) The maximum frame average light level attribute is optional. The value is an unsigned short integer. Value must be between 0 and 65535 inclusive. If you provide 0 (zero) as the value, Apple will compute the value based on the cropped source content and insert the calculated value in the encoded bitstream. The maximum frame average light level attribute can only be used for source HDR file with format HDR10. |
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.
<?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>8244032000</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> <data_file role="source"> <locale name="en-US"/> <file_name>09736156444-sdr-source.mov</file_name> <attribute name="crop.top">0</attribute> <attribute name="crop.bottom">0</attribute> <attribute name="crop.left">0</attribute> <attribute name=“crop.right">0</attribute> <attribute name="image.textless_master">true</attribute> </data_file> </asset> </assets></package>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.
Music videos can be delivered in HD and must include crop dimensions. See Music Video Single Crop Dimensions Metadata Example for an example on specifying the crop rectangle.
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.
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.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>en</language> <provider>OneIndependent</provider> <album> <vendor_id>5099749642829</vendor_id> <upc>5099749642829</upc> <grid>A10302B0000114391R</grid> <title>The Pleasure Is All Mine</title> <original_release_date>2004-08-30</original_release_date> <label_name>One Independent</label_name> <genres> <genre code="ALTERNATIVE-00"/> <genre code="WORLD-00"/> </genres> <copyright_pline>2004 One Independent</copyright_pline> <copyright_cline>2004 One Independent</copyright_cline> <artwork_files> <file> <file_name>cover.jpg</file_name> <size>6591649</size> <checksum type="md5">ffa9327b444559d4d72312b2c7d660ff</checksum> </file> </artwork_files> <track_count>3</track_count> <products> <product> <territory>GB</territory> <wholesale_price_tier>3</wholesale_price_tier> <sales_start_date>2004-10-22</sales_start_date> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> <product> <territory>IE</territory> <wholesale_price_tier>3</wholesale_price_tier> <sales_start_date>2004-10-22</sales_start_date> <cleared_for_sale>true</cleared_for_sale> </product> </products> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> <artist> <artist_name>Tiefschwarz</artist_name> <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> <roles> <role>Producer</role> </roles> <primary>false</primary> </artist> </artists> <tracks> <track> <vendor_id>5099749642829_GBBFT0501345</vendor_id> <isrc>GBBFT0501345</isrc> <grid>A10302B00002427998</grid> <title>The Pleasure Is All Mine</title> <title_version>Radio Version</title_version> <gapless_play>true</gapless_play> <genres> <genre code="ELECTRONIC-00"/> <genre code="WORLD-00"/> </genres> <products> <product> <territory>GB</territory> <cleared_for_sale>true</cleared_for_sale> </product> <product> <territory>IE</territory> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-11-04</stream_start_date> </product> </products> <label_name>One Independent</label_name> <copyright_pline>2004 One Independent</copyright_pline> <explicit_content>none</explicit_content> <lyrics format="plain">'Twas brillig, and the slithy tovesDid 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 shunThe frumious Bandersnatch!</lyrics> <volume_number>1</volume_number> <track_number>1</track_number> <audio_file> <file_name>pleasure.m4a</file_name> <size>26556655</size> <checksum type="md5">6ddabb680edae6bf2ec84ffcfa730fda</checksum> </audio_file> <preview_start_index>30</preview_start_index> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> <artist> <artist_name>Tiefschwarz</artist_name> <apple_id>458966378</apple_id> <roles> <role>Producer</role> </roles> <primary>false</primary> </artist> </artists> </track> <track> <vendor_id>5099749642829_GBBFT0460211</vendor_id> <isrc>GBBFT0460211</isrc> <title>The Pleasure Is All Mine</title> <title_version>DJ Dan Remix</title_version> <gapless_play>false</gapless_play> <genres> <genre code="ELECTRONIC-00"/> <genre code="WORLD-00"/> </genres> <products> <product> <territory>GB</territory> <cleared_for_sale>true</cleared_for_sale> </product> <product> <territory>IE</territory> <cleared_for_sale>true</cleared_for_sale> </product> </products> <label_name>One Independent</label_name> <copyright_pline>2004 One Independent</copyright_pline> <explicit_content>none</explicit_content> <lyrics_file> <file_name>pleasure.ttml</file_name> <size>2655</size> <checksum type="md5">6ddabb999edae6bf2ec84ffcfa730fda</checksum> </lyrics_file> <volume_number>1</volume_number> <track_number>2</track_number> <audio_file> <file_name>pleasure_remix.m4a</file_name> <size>38770214</size> <checksum type="md5">58cba368bd1fdf50cc7d3e44a59e4dc4</checksum> </audio_file> <preview_start_index>30</preview_start_index> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> <artist> <artist_name>Tiefschwarz</artist_name> <apple_id>458966378</apple_id> <roles> <role>Producer</role> </roles> <primary>false</primary> </artist> </artists> </track> <video> <vendor_id>GB5170300040</vendor_id> <grid>A10302B00002427998</grid> <isrc>GB5170300040</isrc> <title>The Pleasure Is All Mine</title> <title_version>Radio Version</title_version> <original_release_date>2004-10-22</original_release_date> <label_name>Warner Music</label_name> <genres> <genre code="ELECTRONIC-00"/> <genre code="WORLD-00"/> </genres> <copyright_cline>2003 Warner Music</copyright_cline> <copyright_pline>2003 Warner Music</copyright_pline> <explicit_content>none</explicit_content> <lyrics_file> <file_name>pleasure.ttml</file_name> <size>2655</size> <checksum type="md5">6ddabb999edae6bf2ec84ffcfa730fda</checksum> </lyrics_file> <preview starttime="30"/> <assets> <asset type="full"> <data_file role="source"> <file_name>5099749642829_GB5170300040.mpg</file_name> <size>93664213</size> <checksum type="md5">3c579894ca25b9af338e7ba0fb3e4fab</checksum> </data_file> <data_file role="captions"> <file_name>5099749642829_GB5170300040-english.scc</file_name> <size>9511</size> <checksum type="md5">60375a79739b49911a3a8b4fe8aa2bdd</checksum> <attribute name="program.start.timecode">-01:00:00:00</attribute> </data_file> </asset> <!-- Defined preview and artwork image clip --> <previews> <preview timecode_format="qt_text" start_time="00:05:13.002" image_time="00:05:20.128"/> </previews> <volume_number>1</volume_number> <track_number>3</track_number> <products> <product> <territory>GB</territory> <cleared_for_sale>true</cleared_for_sale> </product> <product> <territory>IE</territory> <cleared_for_sale>true</cleared_for_sale> </product> </products> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> </video> </tracks> </album></package>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.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>en</language> <provider>OneIndependent</provider> <album> <vendor_id>5099749642829</vendor_id> <upc>5099749642829</upc> <grid>A10302B0000114391R</grid> <title>The Pleasure Is All Mine</title> <original_release_date>2004-08-30</original_release_date> <label_name>One Independent</label_name> <genres> <genre code="ALTERNATIVE-00"/> <genre code="WORLD-00"/> </genres> <copyright_pline>2004 One Independent</copyright_pline> <copyright_cline>2004 One Independent</copyright_cline> <artwork_files> <file> <file_name>cover.jpg</file_name> <size>6591649</size> <checksum type="md5">ffa9327b444559d4d72312b2c7d660ff</checksum> </file> </artwork_files> <track_count>2</track_count> <products> <product> <territory>GB</territory> <wholesale_price_tier>3</wholesale_price_tier> <sales_start_date>2004-10-22</sales_start_date> <cleared_for_sale>true</cleared_for_sale> </product> <product> <territory>IE</territory> <wholesale_price_tier>3</wholesale_price_tier> <sales_start_date>2004-10-22</sales_start_date> <cleared_for_sale>true</cleared_for_sale> </product> </products> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> <artist> <artist_name>Tiefshwarz</artist_name> <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> <roles> <role>Producer</role> </roles> <primary>false</primary> </artist> </artists> <tracks> <video> <vendor_id>GB5170300040</vendor_id> <grid>A10302B00002427998</grid> <isrc>GB5170300040</isrc> <title>The Pleasure Is All Mine</title> <title_version>Radio Version</title_version> <original_release_date>2004-10-22</original_release_date> <label_name>Warner Music</label_name> <genres> <genre code="ELECTRONIC-00"/> <genre code="WORLD-00"/> </genres> <copyright_cline>2003 Warner Music</copyright_cline> <copyright_pline>2003 Warner Music</copyright_pline> <explicit_content>none</explicit_content> <lyrics_file> <file_name>pleasure.ttml</file_name> <size>2655</size> <checksum type="md5">6ddabb999edae6bf2ec84ffcfa730fda</checksum> </lyrics_file> <preview starttime="30"/> <assets> <asset type="full"> <data_file role="source"> <file_name>5099749642829_GB5170300040.mpg</file_name> <size>93664213</size> <checksum type="md5">3c579894ca25b9af338e7ba0fb3e4fab</checksum> </data_file> <data_file role="captions"> <file_name>5099749642829_GB5170300040-english.scc</file_name> <size>9511</size> <checksum type="md5">60375a79739b49911a3a8b4fe8aa2bdd</checksum> <attribute name="program.start.timecode">-01:00:00:00</attribute> </data_file> </asset> </assets> <!-- Defined preview and artwork image clip --> <previews> <preview timecode_format="qt_text" start_time="00:05:13.002" image_time="00:05:20.128"/> </previews> <volume_number>1</volume_number> <track_number>1</track_number> <products> <product> <territory>GB</territory> <cleared_for_sale>true</cleared_for_sale> </product> <product> <territory>IE</territory> <cleared_for_sale>true</cleared_for_sale> </product> </products> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> </video> <booklet> <vendor_id>GBBFT0501345</vendor_id> <title>Digital Booklet - Medúlla</title> <copyright>2004 One Independent</copyright> <volume_number>1</volume_number> <track_number>2</track_number> <products> <product> <territory>GB</territory> <cleared_for_sale>true</cleared_for_sale> </product> <product> <territory>IE</territory> <cleared_for_sale>true</cleared_for_sale> </product> </products> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> <file> <file_name>booklet.pdf</file_name> <size>9651488</size> <checksum type="md5">ddfe4b8ab433e43e7dde429df86cabb2</checksum> </file> </booklet> </tracks> </album></package>A music video album is a special case of the above mixed media album, where there are no audio tracks.
Music videos can be delivered in HD and must include crop dimensions. See Music Video Single Crop Dimensions Metadata Example for an example on specifying the crop rectangle.
Note: For an initial delivery of a music video, delivery of the video asset source is required.
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.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>en</language> <provider>WarnerMusicGroup</provider> <album> <vendor_id>8256463821764</vendor_id> <upc>8256463821764</upc> <grid>A10302B0000279612Q</grid> <title>Life in Slow Motion</title> <original_release_date>2006-07-17</original_release_date> <label_name>Warner Vision International/WMI</label_name> <genres> <genre code="POP-00"/> </genres> <copyright_pline>2006 IHT Records Limited</copyright_pline> <copyright_cline>2006 IHT Records Limited</copyright_cline> <artwork_files> <file> <file_name>5051011277023.jpg</file_name> <size>6852291</size> <checksum type="md5">6ddabb680edae6bf2ec84ffcfa730fda</checksum> </file> </artwork_files> <products> <product> <territory>GB</territory> <wholesale_price_tier>3</wholesale_price_tier> <sales_start_date>2006-07-17</sales_start_date> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> </products> <artists> <artist> <artist_name>David Gray</artist_name> <apple_id>316381</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> <tracks> <video> <vendor_id>USW987200306</vendor_id> <isrc>USW987200306</isrc> <title>Alibi</title> <original_release_date>2006-07-17</original_release_date> <label_name>Warner Vision International/WMI</label_name> <genres> <genre code="POP-00"/> </genres> <copyright_cline>2006 IHT Records Limited</copyright_cline> <copyright_pline>2006 IHT Records Limited</copyright_pline> <explicit_content>none</explicit_content> <assets> <asset type="full"> <data_file role="source"> <file_name>8256463821764_USW987200306.mpg</file_name> <size>93664213</size> <checksum type="md5">ffa9327b444559d4d72312b2c7d660ff</checksum> </data_file> <data_file role="captions"> <file_name>8256463821764_USW987200306-english.scc</file_name> <size>9511</size> <checksum type="md5">5a793a8b46037fe8aa2bdd739b49911a</checksum> <attribute name="program.start.timecode">-01:00:00:00</attribute> </data_file> </asset> </assets> <!-- Defined preview and artwork image clip --> <previews> <preview timecode_format="qt_text" start_time="00:05:13.002" image_time="00:05:20.128"/> </previews> <track_number>1</track_number> <products> <product> <territory>GB</territory> <cleared_for_sale>true</cleared_for_sale> </product> </products> <artists> <artist> <artist_name>David Gray</artist_name> <apple_id>316381</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> </video> <video> <vendor_id>USW980400926</vendor_id> <isrc>USW980400926</isrc> <title>The One I Love</title> <original_release_date>2006-07-17</original_release_date> <label_name>Warner Vision International/WMI</label_name> <genres> <genre code="POP-00"/> </genres> <copyright_cline>2006 IHT Records Limited</copyright_cline> <copyright_pline>2006 IHT Records Limited</copyright_pline> <explicit_content>none</explicit_content> <assets> <asset type="full"> <data_file role="source"> <file_name>USW980400926.mpg</file_name> <size>93667654</size> <checksum type="md5">0be843136d836bae06772574e65ddf04</checksum> </data_file> <data_file role="captions"> <file_name>USW980400926-english.scc</file_name> <size>9511</size> <checksum type="md5">037fe8aa911a2bdd735a793a8b469b49</checksum> <attribute name="program.start.timecode">-01:00:00:00</attribute> </data_file> </asset> </assets> <!-- Defined preview and artwork image clip --> <previews> <preview timecode_format="qt_text" start_time="00:03:53.002" image_time="00:03:59.028"/> </previews> <track_number>2</track_number> <products> <product> <territory>GB</territory> <cleared_for_sale>true</cleared_for_sale> </product> </products> <artists> <artist> <artist_name>David Gray</artist_name> <apple_id>316381</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> </video> <video> <vendor_id>USW980800331</vendor_id> <isrc>USW980800331</isrc> <title>Nos Da Cariad</title> <original_release_date>2006-07-17</original_release_date> <label_name>Warner Vision International/WMI</label_name> <genres> <genre code="POP-00"/> </genres> <copyright_cline>2006 IHT Records Limited</copyright_cline> <copyright_pline>2006 IHT Records Limited</copyright_pline> <explicit_content>none</explicit_content> <assets> <asset type="full"> <data_file role="source"> <file_name>USW980800331.mpg</file_name> <size>93664213</size> <checksum type="md5">01ae8931de3909baa02c02b947a3d404</checksum> </data_file> <data_file role="captions"> <file_name>USW980800331-english.scc</file_name> <size>9511</size> <checksum type="md5">5a793a8b46037fe8aa2bdd739b49911a</checksum> <attribute name="program.start.timecode">-01:00:00:00</attribute> </data_file> </asset> </assets> <!-- Defined preview and artwork image clip --> <previews> <preview timecode_format="qt_text" start_time="00:05:04.102" image_time="00:06:14.120"/> </previews> <track_number>3</track_number> <products> <product> <territory>GB</territory> <cleared_for_sale>true</cleared_for_sale> </product> </products> <artists> <artist> <artist_name>David Gray</artist_name> <apple_id>316381</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> </video> </tracks> </album></package>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.
Video asset-only deliveries still need to be in a 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:
metadata.xml
093624996941_USWBV0700477.mpg
093624996941_USWBV0700477_cover.jpg
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>en</language> <provider>Warner</provider> <assets media_type="video" vendor_id="093624996941_USWBV0700477"> <asset type="full"> <data_file role="source"> <size>494209028</size> <file_name>093624996941_USWBV0700477.mpg</file_name> <checksum type="md5">2de647fd3febffbe39b4bb0dd50bd2a3</checksum> </data_file> </asset> <asset type="artwork"> <data_file> <file_name>093624996941_USWBV0700477_cover.jpg</file_name> <size>4209028</size> <checksum type="md5">5e10a3e7d6e19a9a4c00c1f2fb0197dd</checksum> </data_file> </asset> </assets></package>Only the additions for music video asset-only are described.
|
Provider Name (required) This value should be the Apple-defined provider name used for partner identification. The value must match the provider |
|
Music Video Assets Description (required) The type and vendor identifier of the video asset. The attribute |
|
Music Video Asset Type (required) The type of file delivered. This should always be |
|
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 |
|
Music Video Asset File Size (required) Size in bytes of the provided video asset file. |
|
Music Video Asset File Name (required) 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 ( |
|
Music Video Asset Checksum (required) Size in bytes of the provided video asset file. |
|
|
Music Video Artwork Asset Type (required) The type of file delivered. This should always be |
|
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 when it is purchased. This must be taken from the video itself and may never be a cover of the corresponding single. Refer to Apple 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. |
|
The following metadata example shows a music video by the Japanese artist Sheena Ringo. The video is to be sold on the Japanese app 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.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>ja</language> <provider>EMI</provider> <video> <vendor_id>5099996828052</vendor_id> <grid>A10302B00002427998</grid> <upc>5099996828052</upc> <isrc>JPTO00970474</isrc> <title>ありあまる富</title> <phonetic_title>ありあまるとみ</phonetic_title> <title_version>ライブ・バージョン</title_version> <!-- Localized Video Title Start--> <locales> <locale name="en"> <title>The Invaluable</title> <title_version>Live Version</title_version> </locale> </locales> <!-- Localized Video Title End--> <original_release_date>2003-01-10</original_release_date> <label_name>EMI</label_name> <genres> <genre code="ROCK-00"/> </genres> <copyright_cline>2003 EMI</copyright_cline> <copyright_pline>2003 EMI</copyright_pline> <explicit_content>none</explicit_content> <preview starttime="30"/> <assets> <asset type="full"> <data_file role="source"> <file_name>GB5170300040.mpg</file_name> <size>93664213</size> <checksum type="md5">a8900fb356b7c23badeca6f3010a98aa</checksum> </data_file> </asset> </assets> <!-- Defined preview and artwork image clip --> <previews> <preview timecode_format="qt_text" start_time="00:05:13.002" image_time="00:05:20.128"/> </previews> <products> <product> <territory>JP</territory> <wholesale_price_tier>98</wholesale_price_tier> <sales_start_date>2006-01-16</sales_start_date> <cleared_for_sale>true</cleared_for_sale> </product> <product> <territory>US</territory> <wholesale_price_tier>98</wholesale_price_tier> <sales_start_date>2006-01-16</sales_start_date> <cleared_for_sale>true</cleared_for_sale> </product> </products> <artists> <artist> <artist_name>椎名林檎</artist_name> <apple_id>74576999</apple_id> <phonetic_name>しいな りんご</phonetic_name> <!-- Localized Video Artist Start--> <locales> <locale name="en"> <artist_name>Sheena Ringo</artist_name> </locale> </locales> <!-- Localized Video Artist End--> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> </video></package>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 (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 app, so the language in the See the Language Codes chapter for language code formatting and links to detailed information. |
|
Video (required) The title of the video in the language specified in the 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. |
|
 Video Phonetic Title (optional) The phonetic title of the video in Japanese. The 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. |
|
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 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 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: |
|
 Localized Video Title (required within the <locale> tag) The title of the video localized into the language specified in the 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. |
|
 Localized Video Title Version (optional) The title version of the video localized into the language specified in the enclosing |
|
Video Artist Name (required) Name, Apple identifier, primary status, and roles for each artist on the video in the language specified in the The |
|
 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 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. |
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.
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.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>ko</language> <provider>dfsb</provider> <album> <vendor_id>8809259907861</vendor_id> <upc>8809259907861</upc> <title>나무가 되는 꿈</title> <title_version>디럭스 에디션</title_version> <!-- Localized Album Title Start--> <locales> <locale name="en"> <title>Tree of Life</title> <title_version>Deluxe Edition</title_version> </locale> <locale name="ja"> <title>木になる夢</title> <phonetic_title>きになるゆめ</phonetic_title> <title_version>デラックス・エディション</title_version> </locale> <locale name="zh-Hant"> <title>生命之樹</title> <phonetic_title>Shēng mìng zhī shù</phonetic_title> <title_version>豪華版</title_version> </locale> <locale name="zh-Hans"> <title>生命之树</title> <phonetic_title>Shēng mìng zhī shù</phonetic_title> <title_version>豪华版</title_version> </locale> <locale name="ru"> <title>Дерево жизни</title> <phonetic_title>Dyeryevo Zhizni</phonetic_title> <title_version>Deluxe Version</title_version> </locale> </locales> <!-- Localized Album Title End--> <original_release_date>2012-02-20</original_release_date> <label_name>Parkjiyooncreative</label_name> <genres> <genre code="SINGER-SONGWRITER-00"/> <genre code="K-POP-00"/> </genres> <copyright_pline>2012 Parkjiyooncreative</copyright_pline> <copyright_cline>2012 Parkjiyooncreative</copyright_cline> <artwork_files> <file> <file_name>parkjiyoonalbumcover3000.jpg</file_name> <size>763257</size> <checksum type="md5">2222d58c430e3d276136b15e1afa6bf1</checksum> </file> </artwork_files> <track_count>11</track_count> <products> <product> <territory>WW</territory> <wholesale_price_tier>34</wholesale_price_tier> <sales_start_date>2019-10-22</sales_start_date> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> </products> <artists> <artist> <artist_name>박지윤</artist_name> <apple_id>503753248</apple_id> <!-- Localized Album Artist Start--> <locales> <locale name="en"> <artist_name>Park Ji Yoon</artist_name> </locale> <locale name="ja"> <artist_name>パク・チユン</artist_name> <phonetic_name>ぱく ちゆん</phonetic_name> </locale> <locale name="zh-Hant"> <artist_name>朴志胤</artist_name> <phonetic_name>Pǔ Zhì Yìn</phonetic_name> </locale> <locale name="zh-Hans"> <artist_name>朴志胤</artist_name> <phonetic_name>Pǔ Zhì Yìn</phonetic_name> </locale> <locale name="ru"> <artist_name>Пак Чжи Юн</artist_name> <phonetic_name>Pak Chzhi Yun</phonetic_name> </locale> </locales> <!-- Localized Album Artist End--> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> <tracks> <track> <vendor_id>KRA351202352</vendor_id> <isrc>KRA351202352</isrc> <title>그땐</title> <!-- Localized Track Title Start--> <locales> <locale name="en"> <title>That Time</title> </locale> <locale name="ja"> <title>その時には</title> <phonetic_title>そのときには</phonetic_title> </locale> <locale name="zh-Hant"> <title>在時</title> <phonetic_title>zài shí</phonetic_title> </locale> <locale name="zh-Hans"> <title>在肘</title> <phonetic_title>zài shí</phonetic_title> </locale> <locale name="ru"> <title>То время</title> <phonetic_title>To vryemya</phonetic_title> </locale> </locales> <!-- Localized Track Title End--> <genres> <genre code="SINGER-SONGWRITER-00"/> <genre code="K-POP-00"/> </genres> <label_name>Parkjiyooncreative</label_name> <copyright_pline>2012 Parkjiyooncreative</copyright_pline> <volume_number>1</volume_number> <track_number>1</track_number> <audio_file> <file_name>01_Park_Ji_Yoon.wav</file_name> <size>54482152</size> <checksum type="md5">f8efb8cf0acacd2c5df4b989195363a4</checksum> </audio_file> <audio_language>ja</audio_language> <products> <product> <territory>WW</territory> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> </products> <artists> <artist> <artist_name>박지윤</artist_name> <apple_id>503753248</apple_id> <!-- Localized Track Artist Start--> <locales> <locale name="en"> <artist_name>Park Ji Yoon</artist_name> </locale> <locale name="ja"> <artist_name>パク・チユン</artist_name> <phonetic_name>ぱく ちゆん</phonetic_name> </locale> <locale name="zh-Hant"> <artist_name>朴志胤</artist_name> <phonetic_name>Pǔ Zhì Yìn</phonetic_name> </locale> <locale name="zh-Hans"> <artist_name>朴志胤</artist_name> <phonetic_name>Pǔ Zhì Yìn</phonetic_name> </locale> <locale name="ru"> <artist_name>Пак Чжи Юн</artist_name> <phonetic_name>Pak Chzhi Yun</phonetic_name> </locale> </locales> <!-- Localized Track Artist End--> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> </track> <!-- Additional Tracks Here--> <booklet> <vendor_id>8809259907861</vendor_id> <title>Digital Booklet - 나무가 되는 꿈</title> <!-- Localized Booklet Title Start--> <locales> <locale name="en"> <title>Digital Booklet - Tree of Life</title> </locale> <locale name="ja"> <title>Digital Booklet - 木になる夢</title> <phonetic_title>Digital Booklet - きになるゆめ</phonetic_title> </locale> <locale name="zh-Hant"> <title>Digital Booklet - 生命之樹</title> <phonetic_title>Digital Booklet - Shēng mìng zhī shù</phonetic_title> </locale> <locale name="zh-Hans"> <title>Digital Booklet - 生命之树</title> <phonetic_title>Digital Booklet - Shēng mìng zhī shù</phonetic_title> </locale> <locale name="ru"> <title>Digital Booklet - Дерево жизни</title> <phonetic_title>Digital Booklet - Dyeryevo Zhizni</phonetic_title> </locale> </locales> <!-- Localized Booklet Title End--> <volume_number>1</volume_number> <track_number>11</track_number> <copyright>2012 Parkjiyooncreative</copyright> <file> <file_name>Park_Ji_Yoon_Full.pdf</file_name> <size>1791302</size> <checksum type="md5">d5646c93e2a7fbc25edf720dde10efd4</checksum> </file> <products> <product> <territory>WW</territory> <cleared_for_sale>true</cleared_for_sale> </product> </products> <artists> <artist> <artist_name>박지윤</artist_name> <apple_id>503753248</apple_id> <!-- Localized Booklet Artist Start--> <locales> <locale name="en"> <artist_name>Park Ji Yoon</artist_name> </locale> <locale name="ja"> <artist_name>パク・チユン</artist_name> <phonetic_name>ぱく ちゆん</phonetic_name> </locale> <locale name="zh-Hant"> <artist_name>朴志胤</artist_name> <phonetic_name>Pǔ Zhì Yìn</phonetic_name> </locale> <locale name="zh-Hans"> <artist_name>朴志胤</artist_name> <phonetic_name>Pǔ Zhì Yìn</phonetic_name> </locale> <locale name="ru"> <artist_name>Пак Чжи Юн</artist_name> <phonetic_name>Pak Chzhi Yun</phonetic_name> </locale> </locales> <!-- Localized Booklet Artist End--> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> </booklet> </tracks> </album></package>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 and Booklet Metadata Annotations for annotations on booklet tags.
|
Language (required) 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 See Language Codes for language code formatting and links to detailed information. For information on how languages are displayed, see How Localized Content Displays on Apple Music. |
|
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 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. |
|
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 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 To remove an existing title version, send an empty tag: 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 (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 (required within the <locales> tag) Identifies the language of the localization provided in the See Language Codes for language code formatting and links to detailed information. For information on how languages are displayed, see How Localized Content Displays on Apple Music. |
|
 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 To remove an existing title version, send an empty tag: 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. |
|
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 Note: Do not enter phonetic title information in the The To remove an existing title version, send an empty tag: |
|
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 Acceptable locales for Chinese written language include:
As a best practice, supply the title and title version in both traditional ( Do not provide a region tag for Chinese metadata text. (For example, do not use To remove an existing title version, send an empty tag: The See Language Codes for language code formatting and links to detailed information. For information on how languages are displayed, see How Localized Content Displays on Apple Music. |
|
Album Product (required; can be updated) 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. |
|
 Album Artist Name (required; can be updated, but may require a ticket; see Content Update Behavior) Name or Apple identifier for each artist on the album in the primary language of the package (see Artist names will appear on Apple Music 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 |
|
 Locales (optional) Provides a mechanism to specify localizations for booklet artists. If the album is to be sold on an app using a language other than the primary language specified in the |
|
 Locale Name (required within the <locales> tag) Identifies the language of the localization provided in the |
|
 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 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. |
|
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 The 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. |
|
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 Acceptable locales for Chinese written language include:
As a best practice, supply the artist name in both traditional ( Do not provide a region tag for Chinese metadata text. (For example, do not use The 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. See Language Codes for language code formatting and links to detailed information. For information on how languages are displayed, see How Localized Content Displays on Apple Music. |
|
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 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 (optional) Provides a mechanism to specify localizations for booklet artists. If the album is to be sold on an app using a language other than the primary language specified in the |
|
 Locale Name (required within the <locales> tag) Identifies the language of the localization provided in the Refer to the Album Title annotations for more information on specifying locales. See Language Codes for language code formatting and links to detailed information. |
|
 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 To remove an existing title version, send an empty tag: 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. |
|
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 The |
|
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 Acceptable locales for Chinese written language include:
As a best practice, supply the track title in both traditional ( Do not provide a region tag for Chinese metadata text. (For example, do not use The See Language Codes for language code formatting and links to detailed information. For information on how languages are displayed, see How Localized Content Displays on Apple Music. |
|
|
Track Audio Language (required; can be updated) Use the The language codes are formatted according to the best practices recommended by the Internet Engineering Task Force (IETF) in a group of documents known collectively as BCP 47, and in particular, RFC 5646, which is part of BCP 47. An overview of these best practices is provided at the W3C Internationalization site. Note: The language specified in the |
|
 Track Artist Name (required; can be updated, but may require a ticket; see Content Update Behavior) Name or Apple identifier for each artist on the track in the primary language of the package (see 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 in the order in which they are specified in the provided metadata. Note: You can use the |
|
 Locales (optional) Provides a mechanism to specify localizations for booklet artists. If the album is to be sold on an using a language other than the primary language specified in the |
|
 Locale Name (required within the <locales> tag) Identifies the language of the localization provided in the |
|
 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 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. |
|
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 The 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. |
|
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 Acceptable locales for Chinese written language include:
As a best practice, supply the artist name in both traditional ( Do not provide a region tag for Chinese metadata text. (For example, do not use The 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. See Language Codes for language code formatting and links to detailed information. For information on how languages are displayed, see How Localized Content Displays on Apple Music. |
|
Booklet Metadata Fields |
|
 Booklet Title (required) The title of the booklet in the primary language of the package (see For annotations on booklets not covered in this section, see Booklet Metadata Annotations. 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 (optional) Provides a mechanism to specify localizations for booklet artists. If the album is to be sold on an app using a language other than the primary language specified in the |
|
 Localized Booklet Title (<title> required within the <locale> tag) The title of the booklet localized into the language specified in the enclosing 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 The |
|
Localized Booklet Titles (<title> required within the <locales> tag; <phonetic_title> is optional) In this example, the Acceptable locales for Chinese written language include:
As a best practice, supply the booklet title in both traditional ( Do not provide a region tag for Chinese metadata text. (For example, do not use The See Language Codes for language code formatting and links to detailed information. For information on how languages are displayed, see How Localized Content Displays on Apple Music. |
|
|
 Booklet Artist Name (required; can be updated, but may require a ticket; see Content Update Behavior) Name or Apple identifier for each artist in the booklet in the primary language of the package (see 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 in the order in which they are specified in the provided metadata. |
|
 Locales (optional) Provides a mechanism to specify localizations for booklet artists. If the album is to be sold on an app using a language other than the primary language specified in the |
|
 Locale Name (required within the <locales> tag) Identifies the language of the localization provided in the |
|
 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 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. |
|
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 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 |
|
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 Acceptable locales for Chinese written language include:
As a best practice, supply the booklet title in both traditional ( Do not provide a region tag for Chinese metadata text. (For example, do not use The 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. See Language Codes for language code formatting and links to detailed information. For information on how languages are displayed, see How Localized Content Displays on Apple Music. |
|
See the annotations of the other booklet tags in Booklet Metadata Annotations for details of their contents. |
|
The following metadata example shows a music video by the Japanese artist Sheena Ringo. The video is to be sold on the Japanese app 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.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>ja</language> <provider>EMI</provider> <video> <vendor_id>5099996828052</vendor_id> <grid>A10302B00002427998</grid> <upc>5099996828052</upc> <isrc>JPTO00970474</isrc> <title>ありあまる富</title> <phonetic_title>ありあまるとみ</phonetic_title> <title_version>ライブ・バージョン</title_version> <!-- Localized Video Title Start--> <locales> <locale name="en"> <title>The Invaluable</title> <title_version>Live Version</title_version> </locale> </locales> <!-- Localized Video Title End--> <original_release_date>2003-01-10</original_release_date> <label_name>EMI</label_name> <genres> <genre code="ROCK-00"/> </genres> <copyright_cline>2003 EMI</copyright_cline> <copyright_pline>2003 EMI</copyright_pline> <explicit_content>none</explicit_content> <preview starttime="30"/> <assets> <asset type="full"> <data_file role="source"> <file_name>GB5170300040.mpg</file_name> <size>93664213</size> <checksum type="md5">a8900fb356b7c23badeca6f3010a98aa</checksum> </data_file> </asset> <asset type="artwork"> <data_file> <file_name>videoart.jpg</file_name> <size>6846623</size> <checksum type="md5">263e9f7612598fad35130716f15d7bde</checksum> </data_file> </asset> </assets> <products> <product> <territory>JP</territory> <wholesale_price_tier>98</wholesale_price_tier> <sales_start_date>2006-01-16</sales_start_date> <cleared_for_sale>true</cleared_for_sale> </product> <product> <territory>US</territory> <wholesale_price_tier>98</wholesale_price_tier> <sales_start_date>2006-01-16</sales_start_date> <cleared_for_sale>true</cleared_for_sale> </product> </products> <artists> <artist> <artist_name>椎名林檎</artist_name> <apple_id>74576999</apple_id> <phonetic_name>しいな りんご</phonetic_name> <!-- Localized Video Artist Start--> <locales> <locale name="en"> <artist_name>Sheena Ringo</artist_name> </locale> </locales> <!-- Localized Video Artist End--> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> </video></package>Only the tags relevant to title and artist localization support are described. Refer to Music Video Album for annotations on the remaining tags.
|
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 app, so the language in the See Language Codes for language code formatting and links to detailed information. For information on how languages are displayed, see How Localized Content Displays on Apple Music. |
|
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 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. |
|
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 |
|
Video Title Version (optional) The title version of the video in Japanese. To remove an existing title version, send an empty tag: |
|
Locales (optional) Provides a mechanism to specify localizations for video title and the optional title version. In this example, English is being delivered. |
|
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 |
|
Localized Video Title Version (optional) The title version of the video localized into the language specified in the enclosing To remove an existing title version, send an empty tag: |
|
|
Video Artist Name (required; can be updated, but may require a ticket; see Content Update Behavior) Name or Apple identifier for each artist on the video in the primary language of the package (see 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 in the order in which they are specified in the provided metadata. |
|
Locales (optional) Provides a mechanism to specify localizations for video artists. If the video is to be sold on an app using a language other than the one specified in the |
|
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 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. |
|
|
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 Apple 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 Apple 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.
The asset is the actual file that is downloaded from the app 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.
In this example, a PDF document is delivered in a 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.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>en</language> <provider>OneIndependent</provider> <album> <vendor_id>5099749642829</vendor_id> <upc>5099749642829</upc> <grid>A10302B0000114391R</grid> <title>Medúlla</title> <original_release_date>2004-08-30</original_release_date> <label_name>One Independent</label_name> <genres> <genre code="ALTERNATIVE-00"/> <genre code="WORLD-00"/> </genres> <copyright_pline>2004 One Independent</copyright_pline> <copyright_cline>2004 One Independent</copyright_cline> <artwork_files> <file> <file_name>cover.jpg</file_name> <size>6836623</size> <checksum type="md5">ffa9327b444559d4d72312b2c7d660ff</checksum> </file> </artwork_files> <track_count>3</track_count> <products> <product> <territory>GB</territory> <wholesale_price_tier>3</wholesale_price_tier> <sales_start_date>2004-10-22</sales_start_date> <cleared_for_sale>true</cleared_for_sale> </product> <product> <territory>IE</territory> <wholesale_price_tier>3</wholesale_price_tier> <sales_start_date>2004-10-22</sales_start_date> <cleared_for_sale>true</cleared_for_sale> </product> </products> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> <artist> <artist_name>Tiefshwarz</artist_name> <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> <roles> <role>Producer</role> </roles> <primary>false</primary> </artist> </artists> <tracks> <track> <vendor_id>GBBFT0501345_9083</vendor_id> <isrc>GBBFT0501345</isrc> <grid>A10302B00002427998</grid> <title>The Pleasure Is All Mine</title> <title_version>Radio Version</title_version> <gapless_play>true</gapless_play> <genres> <genre code="ELECTRONIC-00"/> <genre code="WORLD-00"/> </genres> <products> <product> <territory>GB</territory> <cleared_for_sale>true</cleared_for_sale> </product> <product> <territory>IE</territory> <cleared_for_sale>true</cleared_for_sale> </product> </products> <label_name>One Independent</label_name> <copyright_pline>2004 One Independent</copyright_pline> <explicit_content>none</explicit_content> <volume_number>1</volume_number> <track_number>1</track_number> <audio_file> <file_name>pleasure.m4a</file_name> <size>26556655</size> <checksum type="md5">6ddabb680edae6bf2ec84ffcfa730fda</checksum> </audio_file> <preview_start_index>30</preview_start_index> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> <artist> <apple_id>458966378</apple_id> <roles> <role>Producer</role> </roles> <primary>false</primary> </artist> </artists> </track> <track> <vendor_id>GBBFT0460211_2369</vendor_id> <isrc>GBBFT0460211</isrc> <title>The Pleasure Is All Mine</title> <title_version>DJ Dan Remix</title_version> <gapless_play>false</gapless_play> <genres> <genre code="ELECTRONIC-00"/> <genre code="WORLD-00"/> </genres> <products> <product> <territory>GB</territory> <cleared_for_sale>true</cleared_for_sale> </product> <product> <territory>IE</territory> <cleared_for_sale>true</cleared_for_sale> </product> </products> <label_name>One Independent</label_name> <copyright_pline>2004 One Independent</copyright_pline> <explicit_content>none</explicit_content> <volume_number>1</volume_number> <track_number>2</track_number> <audio_file> <file_name>pleasure_remix.m4a</file_name> <size>38770214</size> <checksum type="md5">58cba368bd1fdf50cc7d3e44a59e4dc4</checksum> </audio_file> <preview_start_index>30</preview_start_index> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> <artist> <apple_id>458966378</apple_id> <roles> <role>Producer</role> </roles> <primary>false</primary> </artist> </artists> </track> <booklet> <vendor_id>GBBFT0501345</vendor_id> <title>Digital Booklet - Medúlla</title> <copyright>2004 One Independent</copyright> <volume_number>1</volume_number> <track_number>3</track_number> <explicit_content>none</explicit_content> <products> <product> <territory>GB</territory> <cleared_for_sale>true</cleared_for_sale> </product> <product> <territory>IE</territory> <cleared_for_sale>true</cleared_for_sale> </product> </products> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> <file> <file_name>booklet.pdf</file_name> <size>7243623</size> <checksum type="md5">ddfe4b8ab433e43e7dde429df86cabb2</checksum> </file> </booklet> </tracks> </album></package>Only the additional tags added for booklets are described. Items marked "required" below are required only if a booklet is to be included.
|
 Booklet (required) Identifies a booklet within the metadata. Any number of booklets may be included in a package. |
|
 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 (required) The title of the booklet, as it will appear on Apple Music and the purchaser’s Library. The naming convention for PDF booklets is "Digital Booklet - album name" |
|
 Copyright (required; can be updated) The copyright of the booklet, as it will appear on Apple Music. |
|
 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 |
|
 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 |
|
 Booklet Parental Advisory (optional; may be updated; see Content Update Behavior) Denotes whether or not a booklet contains explicit content. May be Important: A booklet must only be marked |
|
|
 Cleared For Sale (optional; can be updated) Specifies whether the booklet is cleared for download in the territory for the product. Must be Note: If you leave out the |
|
|
 Artists (optional; can be updated, but may require a ticket; see Content Update Behavior) Name or Apple identifier, 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. |
|
 File (optional; can be updated; see Content Update Behavior) 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 |
|
You can deliver pre-release content in two ways: as pre-orders 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.
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. 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 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 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.
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.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>en</language> <provider>OneIndependent</provider> <album> <vendor_id>5099749642829</vendor_id> <upc>5099749642829</upc> <grid>A10302B0000114391R</grid> <title>Medúlla</title> <original_release_date>2004-08-30</original_release_date> <label_name>One Independent</label_name> <genres> <genre code="ALTERNATIVE-00"/> </genres> <copyright_pline>2004 One Independent</copyright_pline> <copyright_cline>2004 One Independent</copyright_cline> <artwork_files> <file> <file_name>cover.jpg</file_name> <size>6528853</size> <checksum type="md5"> ffa9327b444559d4d72312b2c7d660ff</checksum> </file> </artwork_files> <track_count>5</track_count> <preorder_upc>8899642874956</preorder_upc> <preorder_grid>C2330239R00011401T</preorder_grid> <preorder_previews>true</preorder_previews> <products> <product> <territory>WW</territory> <wholesale_price_tier>3</wholesale_price_tier> <preorder_wholesale_price_tier>2</preorder_wholesale_price_tier> <sales_start_date>2019-10-22</sales_start_date> <preorder_sales_start_date>2019-10-01</preorder_sales_start_date> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-01</stream_start_date> </product> </products> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> <tracks> <track> <vendor_id>5099749642829_GBBFT0501345</vendor_id> <isrc>GBBFT0501345</isrc> <grid>A10302B00002427998</grid> <title>The Pleasure Is All Mine</title> <title_version>Radio Version</title_version> <gapless_play>true</gapless_play> <genres> <genre code="ELECTRONIC-00"/> </genres> <products> <product> <territory>WW</territory> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> </products> <preorder_type>standard</preorder_type> <label_name>One Independent</label_name> <copyright_pline>2004 One Independent</copyright_pline> <explicit_content>none</explicit_content> <lyrics_file> <file_name>pleasure.ttml</file_name> <size>2655</size> <checksum type="md5">6ddabb999edae6bf2ec84ffcfa730fda</checksum> </lyrics_file> <volume_number>1</volume_number> <track_number>1</track_number> <audio_file> <file_name>pleasure.m4a</file_name> <size>26556655</size> <checksum type="md5">6ddabb680edae6bf2ec84ffcfa730fda</checksum> </audio_file> <preview_start_index>30</preview_start_index> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> </track> <track> <vendor_id>5099749642829_GBBFT0460211</vendor_id> <isrc>GBBFT0460211</isrc> <title>The Pleasure Is All Mine</title> <title_version>DJ Dan Remix</title_version> <gapless_play>false</gapless_play> <genres> <genre code="ELECTRONIC-00"/> </genres> <products> <product> <territory>WW</territory> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> </products> <preorder_type>standard</preorder_type> <label_name>One Independent</label_name> <copyright_pline>2004 One Independent</copyright_pline> <volume_number>1</volume_number> <track_number>2</track_number> <audio_file> <file_name>pleasure_remix.m4a</file_name> <size>38770214</size> <checksum type="md5">58cba368bd1fdf50cc7d3e44a59e4dc4</checksum> </audio_file> <preview_start_index>30</preview_start_index> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> </track> <track> <vendor_id>GBBFT0460211_2369</vendor_id> <isrc>GBBFT0460211</isrc> <title>Vokuro</title> <title_version>Super DJ Remix</title_version> <gapless_play>false</gapless_play> <genres> <genre code="ELECTRONIC-00"/> <genre code="DANCE-00"/> </genres> <products> <product> <territory>GB</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>98</wholesale_price_tier> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-01</stream_start_date> </product> <product> <territory>IE</territory> <wholesale_price_tier>98</wholesale_price_tier> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-01</stream_start_date> </product> </products> <preorder_type>instant-gratification</preorder_type> <label_name>One Independent</label_name> <copyright_pline>2004 One Independent</copyright_pline> <explicit_content>explicit</explicit_content> <lyrics_file> <file_name>vokuro.ttml</file_name> <size>3285</size> <checksum type="md5">80ed6dd4ffca0fdabb6ae6bf2ec8fa73</checksum> </lyrics_file> <volume_number>1</volume_number> <track_number>3</track_number> <audio_file> <file_name>vokuro.m4a</file_name> <size>78256392</size> <checksum type="md5">58cba368bd1fdf50cc7d3e44a59e4dc4</checksum> </audio_file> <preview_start_index>30</preview_start_index> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> <artist> <apple_id>458966378</apple_id> <roles> <role>Producer</role> </roles> <primary>false</primary> </artist> </artists> </track> <track> <vendor_id>GBBFT2500811_0912</vendor_id> <isrc>GBBFT2500811</isrc> <title>Medúlla Medley</title> <title_version>Radio Edit</title_version> <gapless_play>false</gapless_play> <genres> <genre code="ELECTRONIC-00"/> <genre code="WORLD-00"/> </genres> <products> <product> <territory>GB</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>98</wholesale_price_tier> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-01</stream_start_date> </product> <product> <territory>IE</territory> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-01</stream_start_date> </product> </products> <preorder_type>instant-gratification</preorder_type> <label_name>One Independent</label_name> <copyright_pline>2004 One Independent</copyright_pline> <lyrics_file> <file_name>medley.ttml</file_name> <size>4014</size> <checksum type="md5">73dae6bf2eccfa0fda84ff6ddabb680e</checksum> </lyrics_file> <volume_number>1</volume_number> <track_number>4</track_number> <audio_file> <file_name>medley.m4a</file_name> <size>99253792</size> <checksum type="md5">c3330a3565baf58300bba711e3c26966</checksum> </audio_file> <preview_start_index>30</preview_start_index> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> <artist> <apple_id>458966378</apple_id> <roles> <role>Producer</role> </roles> <primary>false</primary> </artist> </artists> </track> <video> <vendor_id>GB5170300040</vendor_id> <grid>A10302B00002427998</grid> <upc>825646307760</upc> <isrc>GB5170300040</isrc> <title>The Pleasure Is All Mine</title> <title_version>Radio Version</title_version> <original_release_date>2004-10-22</original_release_date> <label_name>Warner Music</label_name> <genres> <genre code="ELECTRONIC-00"/> </genres> <copyright_cline>2003 Warner Music</copyright_cline> <copyright_pline>2003 Warner Music</copyright_pline> <explicit_content>none</explicit_content> <track_number>5</track_number> <assets> <asset type="full"> <data_file role="source"> <file_name>GB5170300040.mpg</file_name> <size>93664213</size> <checksum type="md5">38cba368bd1fdf57cc7d3e44a59e4da4</checksum> </data_file> </asset> <asset type="artwork"> <data_file> <file_name>videoart.jpg</file_name> <size>6423613</size> <checksum type="md5">ddfe4b8ab433e43e7dde429df86cabb2</checksum> </data_file> </asset> </assets> <products> <product> <territory>WW</territory> <cleared_for_sale>true</cleared_for_sale> </product> </products> <preorder_type>preorder only</preorder_type> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> </video> </tracks> </album></package>Only the additional tags added for pre-orders are described.
Album Metadata Fields |
|
 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 |
|
 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 Important: The GRid must not be more than 18 alphanumeric characters. The GRid cannot contain dashes, spaces, underscores, other punctuation, or symbols. |
|
 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 Important: This tag is available at the album-level only, and applies to every territory and every track. |
Album Product Metadata Fields |
|
 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 Note: This tag cannot be used within an |
|
 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 If a The Updates: When sending a metadata update, if you omit the |
Album Cleared for Streaming (optional; can be updated) Indicates if the album can be streamed on demand. Allowed values are Set the value to Tip: If you have the rights to stream most tracks on an album, you could use In some cases, a provider might only have streaming rights; in that situation, 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. |
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 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 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 |
|
Track Metadata Fields |
|
  Pre-Order Type (optional; may be updated; see Content Update Behavior) Indicates how this track or video will be treated in a pre-order situation. Available options are:
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. Only Notes:
|
|
  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 |
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 Set the value to Tip: If you have the rights to stream an entire album except for one track, you could use 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. |
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 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. |
|
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.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>en</language> <provider>OneIndependent</provider> <album> <vendor_id>5099749642829</vendor_id> <upc>5099749642829</upc> <grid>A10302B0000114391R</grid> <title>Medúlla</title> <original_release_date>2004-08-30</original_release_date> <label_name>One Independent</label_name> <genres> <genre code="ALTERNATIVE-00"/> </genres> <copyright_pline>2004 One Independent</copyright_pline> <copyright_cline>2004 One Independent</copyright_cline> <track_count>5</track_count> <preorder_upc>8899642874956</preorder_upc> <preorder_grid>C2330239R00011401T</preorder_grid> <preorder_previews>true</preorder_previews> <products> <product> <territory>WW</territory> <wholesale_price_tier>3</wholesale_price_tier> <preorder_wholesale_price_tier>2</preorder_wholesale_price_tier> <sales_start_date>2019-10-22</sales_start_date> <preorder_sales_start_date>2019-10-01</preorder_sales_start_date> <cleared_for_sale>true</cleared_for_sale> <stream_start_date>2019-10-01</stream_start_date> </product> </products> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> <tracks> <track> <vendor_id>5099749642829_GBBFT0501345</vendor_id> <isrc>GBBFT0501345</isrc> <grid>A10302B00002427998</grid> <title>The Pleasure Is All Mine</title> <title_version>Radio Version</title_version> <gapless_play>true</gapless_play> <genres> <genre code="ELECTRONIC-00"/> </genres> <products> <product> <territory>WW</territory> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> </products> <preorder_type>standard</preorder_type> <label_name>One Independent</label_name> <copyright_pline>2004 One Independent</copyright_pline> <explicit_content>none</explicit_content> <lyrics_file> <file_name>pleasure.ttml</file_name> <size>2655</size> <checksum type="md5">6ddabb999edae6bf2ec84ffcfa730fda</checksum> </lyrics_file> <volume_number>1</volume_number> <track_number>1</track_number> <preview_start_index>30</preview_start_index> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> </track> <track> <vendor_id>5099749642829_GBBFT0460211</vendor_id> <isrc>GBBFT0460211</isrc> <title>The Pleasure Is All Mine</title> <title_version>DJ Dan Remix</title_version> <gapless_play>false</gapless_play> <genres> <genre code="ELECTRONIC-00"/> </genres> <products> <product> <territory>WW</territory> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> </products> <preorder_type>standard</preorder_type> <label_name>One Independent</label_name> <copyright_pline>2004 One Independent</copyright_pline> <volume_number>1</volume_number> <track_number>2</track_number> <preview_start_index>30</preview_start_index> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> </track> <track> <vendor_id>GBBFT0460211_2369</vendor_id> <isrc>GBBFT0460211</isrc> <title>Vokuro</title> <title_version>Super DJ Remix</title_version> <gapless_play>false</gapless_play> <genres> <genre code="ELECTRONIC-00"/> <genre code="DANCE-00"/> </genres> <products> <product> <territory>GB</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>98</wholesale_price_tier> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-01</stream_start_date> </product> <product> <territory>IE</territory> <wholesale_price_tier>98</wholesale_price_tier> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-01</stream_start_date> </product> </products> <preorder_type>instant-gratification</preorder_type> <label_name>One Independent</label_name> <copyright_pline>2004 One Independent</copyright_pline> <explicit_content>explicit</explicit_content> <lyrics_file> <file_name>vokuro.ttml</file_name> <size>3285</size> <checksum type="md5">80ed6dd4ffca0fdabb6ae6bf2ec8fa73</checksum> </lyrics_file> <volume_number>1</volume_number> <track_number>3</track_number> <preview_start_index>30</preview_start_index> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> <artist> <apple_id>458966378</apple_id> <roles> <role>Producer</role> </roles> <primary>false</primary> </artist> </artists> </track> <track> <vendor_id>GBBFT2500811_0912</vendor_id> <isrc>GBBFT2500811</isrc> <title>Medúlla Medley</title> <title_version>Radio Edit</title_version> <gapless_play>false</gapless_play> <genres> <genre code="ELECTRONIC-00"/> <genre code="WORLD-00"/> </genres> <products> <product> <territory>GB</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>98</wholesale_price_tier> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-01</stream_start_date> </product> <product> <territory>IE</territory> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-01</stream_start_date> </product> </products> <preorder_type>instant-gratification</preorder_type> <label_name>One Independent</label_name> <copyright_pline>2004 One Independent</copyright_pline> <lyrics_file> <file_name>medley.ttml</file_name> <size>4014</size> <checksum type="md5">73dae6bf2eccfa0fda84ff6ddabb680e</checksum> </lyrics_file> <volume_number>1</volume_number> <track_number>4</track_number> <preview_start_index>30</preview_start_index> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> <artist> <apple_id>458966378</apple_id> <roles> <role>Producer</role> </roles> <primary>false</primary> </artist> </artists> </track> <video> <vendor_id>GB5170300040</vendor_id> <grid>A10302B00002427998</grid> <upc>825646307760</upc> <isrc>GB5170300040</isrc> <title>The Pleasure Is All Mine</title> <title_version>Radio Version</title_version> <original_release_date>2004-10-22</original_release_date> <label_name>Warner Music</label_name> <genres> <genre code="ELECTRONIC-00"/> </genres> <copyright_cline>2003 Warner Music</copyright_cline> <copyright_pline>2003 Warner Music</copyright_pline> <explicit_content>none</explicit_content> <track_number>5</track_number> <products> <product> <territory>WW</territory> <cleared_for_sale>true</cleared_for_sale> </product> </products> <preorder_type>preorder only</preorder_type> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> </video> </tracks> </album></package>The following example shows how to turn off a pre-order.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>en</language> <provider>OneIndependent</provider> <album> <vendor_id>5099749642829</vendor_id> . . . <track_count>5</track_count> <preorder_upc>8899642874956</preorder_upc> <preorder_grid>C2330239R00011401T</preorder_grid> <preorder_previews>true</preorder_previews> <products> <product> <territory>WW</territory> <wholesale_price_tier>3</wholesale_price_tier> <preorder_wholesale_price_tier>2</preorder_wholesale_price_tier> <sales_start_date>2019-10-22</sales_start_date> <preorder_sales_start_date></preorder_sales_start_date> <cleared_for_sale>true</cleared_for_sale> </product> </products> . . . </album></package>Album Metadata Fields
Pre-Order Sales Start Date (optional; can be updated) To remove a pre-order, send a
Note:
|
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.
For details on abbreviations and album style standards, see Apple Music Style Guide.
Additions for works support are printed in bold.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>en</language> <provider>IODA</provider> <album> <upc>723721237257</upc> <title>Excursions: Piano Music From Barber and Bauer</title> <title_version>Remastered</title_version> <original_release_date>2006-09-12</original_release_date> <label_name>Endeavour Classics</label_name> <genres> <genre code="CLASSICAL-00"/> </genres> <copyright_pline>2006 Endeavour Classics</copyright_pline> <copyright_cline>2006 Endeavour Classics</copyright_cline> <artwork_files> <file> <file_name>cover.jpg</file_name> <size>6591649</size> <checksum type="md5">0e3878dce4edc81a0368d01879f7e948</checksum> </file> </artwork_files> <track_count>5</track_count> <products> <product> <territory>WW</territory> <wholesale_price_tier>3</wholesale_price_tier> <sales_start_date>2019-10-22</sales_start_date> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> </products> <artists> <artist> <artist_name>Stephen Beus</artist_name> <apple_id>81599248</apple_id> <primary>true</primary> <roles> <role>Performer</role> </roles> </artist> <artist> <artist_name>Samuel Barber</artist_name> <apple_id>325414</apple_id> <primary>false</primary> <roles> <role>Composer</role> </roles> </artist> <artist> <artist_name>Marion Bauer</artist_name> <apple_id>88771000</apple_id> <primary>false</primary> <roles> <role>Composer</role> </roles> </artist> </artists> <tracks> <work name="Sonata in E-flat Minor, Op. 26"> <track> <isrc>US89R0692262</isrc> <title>Sonata in E-flat Minor, Op. 26: I. Allergro energico</title> <label_name>Endeavour Classics</label_name> <copyright_pline>2006 Endeavour Classics </copyright_pline> <genres> <genre code="CLASSICAL-00"/> </genres> <volume_number>1</volume_number> <track_number>1</track_number> <audio_file> <file_name>track-1.m4a</file_name> <size>87256392</size> <checksum type="md5">4d2b3bfda95809187580d08272a9af94</checksum> </audio_file> <products> <product> <territory>WW</territory> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> </products> <artists> <artist> <artist_name>Stephen Beus</artist_name> <apple_id>81599248</apple_id> <primary>true</primary> <roles> <role>Performer</role> </roles> </artist> <artist> <artist_name>Samuel Barber</artist_name> <apple_id>325414</apple_id> <primary>false</primary> <roles> <role>Composer</role> </roles> </artist> </artists> </track> <track> <isrc>US89R0692263</isrc> <title>Sonata in E-flat Minor, Op. 26: II. Allegro vivace e leggiero</title> <label_name>Endeavor Classics</label_name> <copyright_pline>2006 Endeavor Classics</copyright_pline> <genres> <genre code="CLASSICAL-00"/> </genres> <volume_number>1</volume_number> <track_number>2</track_number> <audio_file> <file_name>track-2.m4a</file_name> <size>85279363</size> <checksum type="md5">e6a27c8fced2c6549664e47e571d9631</checksum> </audio_file> <products> <product> <territory>WW</territory> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> </products> <artists> <artist> <artist_name>Stephen Beus</artist_name> <apple_id>81599248</apple_id> <primary>true</primary> <roles> <role>Performer</role> </roles> </artist> <artist> <artist_name>Samuel Barber</artist_name> <apple_id>325414</apple_id> <primary>false</primary> <roles> <role>Composer</role> </roles> </artist> </artists> </track> <track> <isrc>US89R0692263</isrc> <title>Sonata in E-flat Minor, Op. 26: III. Adagio mesto</title> <title_version>Digital Remaster</title_version> <label_name>Endeavour Classics</label_name> <copyright_pline>2006 Endeavour Classics</copyright_pline> <genres> <genre code="CLASSICAL-00"/> </genres> <volume_number>1</volume_number> <track_number>3</track_number> <audio_file> <file_name>track-3.m4a</file_name> <size>93638527</size> <checksum type="md5">e6a27c8fced2c6549664e47e571d9631</checksum> </audio_file> <products> <product> <territory>WW</territory> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> </products> <artists> <artist> <artist_name>Stephen Beus</artist_name> <apple_id>81599248</apple_id> <primary>true</primary> <roles> <role>Performer</role> </roles> </artist> <artist> <artist_name>Samuel Barber</artist_name> <apple_id>325414</apple_id> <primary>false</primary> <roles> <role>Composer</role> </roles> </artist> </artists> </track> <track> <isrc>US89R0692264</isrc> <title>Sonata in E-flat Minor, Op. 26: IV. Fuga: Allegro con spirito</title> <title_version>Digital Remaster</title_version> <label_name>Endeavour Classics</label_name> <copyright_pline>2006 Endeavour Classics</copyright_pline> <genres> <genre code="CLASSICAL-00"/> </genres> <volume_number>1</volume_number> <track_number>4</track_number> <audio_file> <file_name>track-4.m4a</file_name> <size>74526489</size> <checksum type="md5">0cb55d875a955adf77a073dc8af9d397</checksum> </audio_file> <products> <product> <territory>WW</territory> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> </products> <artists> <artist> <artist_name>Stephen Beus</artist_name> <apple_id>81599248</apple_id> <primary>true</primary> <roles> <role>Performer</role> </roles> </artist> <artist> <artist_name>Samuel Barber</artist_name> <apple_id>325414</apple_id> <primary>false</primary> <roles> <role>Composer</role> </roles> </artist> </artists> </track> </work> <track> <isrc>US89R0692265</isrc> <title>Violin Concerto, Op. 52</title> <title_version>Digital Remaster</title_version> <label_name>Endeavour Classics</label_name> <copyright_pline>2006 Endeavour Classics</copyright_pline> <genres> <genre code="CLASSICAL-00"/> </genres> <volume_number>1</volume_number> <track_number>5</track_number> <audio_file> <file_name>track-5.m4a</file_name> <size>88341356</size> <checksum type="md5">7d338c611ba0e9fb34d610f919375239</checksum> </audio_file> <products> <product> <territory>WW</territory> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> </products> <artists> <artist> <artist_name>Stephen Beus</artist_name> <apple_id>81599248</apple_id> <primary>true</primary> <roles> <role>Performer</role> </roles> </artist> <artist> <artist_name>Samuel Barber</artist_name> <apple_id>325414</apple_id> <primary>false</primary> <roles> <role>Composer</role> </roles> </artist> </artists> </track> </tracks> </album></package>
|
 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. |
This chapter specifies the 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 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 takes several hours to appear on Apple Music 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.
Intervals may start and end on any date; the intervals below start and end on the first day of the month for ease of explanation.
Two intervals are provided, both without end dates:
Interval | Start Date | End Date | Wholesale Price Tier |
|---|---|---|---|
1 | 2008-05-01 | Unspecified | 3 |
2 | 2008-10-01 | Unspecified | 2 |
These two intervals as supplied, in a timeline-like format:
May | 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 |
|
|
|
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 |
|
|
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 |
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 |
|
All intervals supplied in metadata updates will be applied in the same manner as described in Interval Pricing Examples.
Three intervals currently exist in the 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 |
For the sake of brevity, only two audio tracks are shown. Changes made for interval pricing are in bold.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>en</language> <provider>OneIndependent</provider> <album> <vendor_id>5099749642829</vendor_id> <upc>5099749642829</upc> <grid>A10302B0000114391R</grid> <title>Medúlla</title> <title_version>Remastered</title_version> <original_release_date>2004-08-30</original_release_date> <label_name>One Independent</label_name> <genres> <genre code="ALTERNATIVE-00"/> </genres> <copyright_pline>2004 One Independent</copyright_pline> <copyright_cline>2004 One Independent</copyright_cline> <artwork_files> <file> <file_name>cover.jpg</file_name> <size>42576</size> <checksum type="md5">ffa9327b444559d4d72312b2c7d660ff</checksum> </file> </artwork_files> <track_count>2</track_count> <products> <product> <territory>GB</territory> <intervals> <interval> <start_date>2008-07-01</start_date> <end_date>2008-09-01</end_date> <wholesale_price_tier>5</wholesale_price_tier> </interval> <interval> <start_date>2008-09-01</start_date> <end_date>2008-10-01</end_date> <wholesale_price_tier>3</wholesale_price_tier> </interval> <interval> <start_date>2008-10-01</start_date> <wholesale_price_tier>5</wholesale_price_tier> </interval> </intervals> <sales_start_date>2008-01-22</sales_start_date> <cleared_for_sale>true</cleared_for_sale> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> <product> <territory>IE</territory> <intervals> <interval> <start_date>2008-07-01</start_date> <end_date>2008-09-01</end_date> <wholesale_price_tier>5</wholesale_price_tier> </interval> <interval> <start_date>2008-09-01</start_date> <end_date>2008-10-01</end_date> <wholesale_price_tier>3</wholesale_price_tier> </interval> <interval> <start_date>2008-10-01</start_date> <wholesale_price_tier>5</wholesale_price_tier> </interval> </intervals> <sales_start_date>2008-01-22</sales_start_date> <cleared_for_sale>true</cleared_for_sale> </product> </products> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> <tracks> <track> <vendor_id>GBBFT0501345_9083</vendor_id> <isrc>GBBFT0501345</isrc> <grid>A10302B00002427998</grid> <title>The Pleasure Is All Mine</title> <title_version>Dub Remix</title_version> <gapless_play>true</gapless_play> <genres> <genre code="ELECTRONIC-00"/> <genre code="WORLD-00"/> </genres> <products> <product> <territory>GB</territory> <intervals> <interval> <start_date>2008-08-01</start_date> <end_date>2008-10-01</end_date> <wholesale_price_tier>100</wholesale_price_tier> </interval> <interval> <start_date>2008-10-01</start_date> <end_date>2008-11-01</end_date> <wholesale_price_tier>98</wholesale_price_tier> </interval> <interval> <start_date>2008-11-01</start_date> <wholesale_price_tier>100</wholesale_price_tier> </interval> </intervals> <cleared_for_sale>true</cleared_for_sale> </product> <product> <territory>IE</territory> <cleared_for_sale>true</cleared_for_sale> </product> </products> <copyright_pline>2004 One Independent</copyright_pline> <explicit_content>none</explicit_content> <volume_number>1</volume_number> <track_number>1</track_number> <audio_file> <file_name>pleasure.m4a</file_name> <size>7734621</size> <checksum type="md5">6ddabb680edae6bf2ec84ffcfa730fda</checksum> </audio_file> <preview_start_index>30</preview_start_index> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> </track> <track> <vendor_id>GBBFT0460211_2369</vendor_id> <isrc>GBBFT0460211</isrc> <title>Vokuro</title> <title_version>Super DJ Remix</title_version> <gapless_play>false</gapless_play> <genres> <genre code="ELECTRONIC-00"/> <genre code="DANCE-00"/> </genres> <products> <product> <territory>GB</territory> <cleared_for_sale>true</cleared_for_sale> </product> <product> <territory>IE</territory> <cleared_for_sale>true</cleared_for_sale> </product> </products> <copyright_pline>2004 One Independent</copyright_pline> <explicit_content>explicit</explicit_content> <volume_number>1</volume_number> <track_number>2</track_number> <audio_file> <file_name>vokuro.m4a</file_name> <size>498424</size> <checksum type="md5">58cba368bd1fdf50cc7d3e44a59e4dc4</checksum> </audio_file> <preview_start_index>30</preview_start_index> <artists> <artist> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> </track> </tracks> </album></package>Album Interval Pricing Metadata Fields |
|
Product (required; can be updated) 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. |
|
 Interval Declaration (required) The beginning of a group of intervals for a specific territory. |
|
 Interval (required) The beginning of an individual interval for a specific territory. This interval applies only to the territory specified in the |
|
 Interval Start Date (required except for the first interval; can be updated) The start date for the given interval in If you leave out the |
|
 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 |
|
 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. |
|
|
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 |
Track Interval Pricing Metadata Fields |
|
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. |
|
 Interval (required) The beginning of an individual interval for a specific territory. This interval applies only to the territory specified in the |
|
 Interval Start Date (required except for the first interval; can be updated) The start date for the given interval in If you leave out the |
|
 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 |
|
 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. |
|
|
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 |
This chapter specifies the package format for delivering ringtones. 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 a package directory that contains the XML, the audio file, and cover art. Each package represents a single ringtone product. 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.
The metadata example is used to deliver one ringtone for individual sale.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>en</language> <provider>ABCMusic</provider> <album> <album_type>ringtone</album_type> <upc>10000000020081</upc> <grid>A10302B00002427900</grid> <title>So It Goes</title> <original_release_date>2009-09-05</original_release_date> <label_name>ABC Records</label_name> <genres> <genre code="ROCK-00"/> <genre code="POP-00"/> </genres> <copyright_pline>2009 ABCMusic</copyright_pline> <copyright_cline>2009 ABCMusic</copyright_cline> <artwork_files> <file> <file_name>cover.jpg</file_name> <checksum type="md5">39af338c579894ca25be7ba0fb3e4fab</checksum> <size>6591649</size> </file> </artwork_files> <products> <product> <territory>US</territory> <sales_start_date>2009-09-05</sales_start_date> </product> </products> <artists> <artist> <artist_name>The Sirens</artist_name> <apple_id>4299625</apple_id> <primary>true</primary> <roles> <role>Artist</role> </roles> </artist> </artists> <tracks> <track> <type>ringtone</type> <isrc>USMPK0508101</isrc> <iswc>T0115201916</iswc> <source_isrc>USMPK0508000</source_isrc> <title>So It Goes</title> <label_name>ABC Records</label_name> <copyright_pline>2009 ABCMusic</copyright_pline> <explicit_content>none</explicit_content> <volume_number>1</volume_number> <track_number>1</track_number> <audio_file> <file_name>SoItGoesRingtone.flac</file_name> <checksum type="md5">cca25713017feb9150ebbb4b7a0714e6</checksum> <size>256392</size> </audio_file> <products> <product> <territory>US</territory> <cleared_for_sale>true</cleared_for_sale> </product> </products> <artists> <artist> <artist_name>The Sirens</artist_name> <apple_id>4299625</apple_id> <primary>true</primary> <roles> <role>Artist</role> </roles> </artist> </artists> </track> </tracks> </album></package>
|
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). |
|
Package Container (required) The
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 (required, Apple-supplied) This value should be the Apple-defined provider |
Ringtone Metadata Fields |
|
 Album Type (required) Specifies that the “album” being delivered is a ringtone. You must indicate the type as |
|
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 |
|
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 Important: The GRid must not be more than 18 alphanumeric characters. The GRid cannot contain dashes, spaces, underscores, other punctuation, or symbols. |
|
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 storefront. This field is cosmetic only and does not impact "available date" or "street date." This field must be in |
|
Ringtone Album Label Name (required; can be updated) The name of the label that released the ringtone album. |
|
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, go to iTunes Connect Resources and Help 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 © Line (optional; can be updated) Copyright line for the ringtone album. Must follow the format |
|
Ringtone Album Copyright P-Line (optional; can be updated) Performance copyright line for the ringtone album. Must follow the format |
|
Ringtone Album Artwork (required; can be updated) Artwork must be provided for the ringtone album and when it is purchased. The Ringtone album artwork can be 800 by 800 pixels, but Apple recommends delivering 1400 by 1400 pixels for best results. Refer to the Apple Video and Audio Asset Guide for details and asset file requirements. |
|
|
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. Refer to Basic Music Album Metadata Annotated for tag details. |
|
|
Ringtone Album Artists (required; can be updated, but may require a ticket; see Content Update Behavior) Name or Apple identifier, 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. Refer to Basic Music Album Metadata Annotated for tag details. |
Track Metadata Fields |
|
 Track Type (required) Specifies the track as a ringtone as opposed to a regular song. |
|
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. |
|
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 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 |
|
 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 This tag is optional. If the ringtone is not cut from a song, 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 (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 Note: Apple recommends relying on GRid and/or ISRC for identifying tracks and omitting the This tag is optional. If the ringtone is not cut from a song, 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 (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 This tag is optional. If the ringtone is not cut from a song, 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. |
|
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 Refer to Basic Music Album Metadata Annotated for tag details. |
|
Track Label Name (optional; can be updated) The name of the label which released the track. If not specified, the |
|
Track Copyright P-Line (optional; can be updated) Performance copyright line for the track. Must follow the format Important: If not specified, the copyright line from the album is used. |
|
Track Parental Advisory (optional; may be updated; see Content Update Behavior) Denotes whether or not the ringtone contains explicit content. Can be Important: A track must only be marked |
|
Track Volume Number (optional) The volume number of the track. If specified, it must be a positive integer. |
|
Track Number (required) The track number must be "1”. A ringtone album can contain only one track. |
|
Track Audio File (required; may be updated; see Content Update Behavior) 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 Apple Video and Audio Asset Guide for details. The |
|
Track Products (optional; can be updated) Define a product for each territory in which the ringtone track is to be sold. Refer to Basic Music Album Metadata Annotated for tag details. |
|
Ringtone Track Artists (optional; can be updated, but may require a ticket; see Content Update Behavior) Name or Apple identifier, 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. Refer to Basic Music Album Metadata Annotated for tag details. |
|
This metadata example is used to deliver an audio file of any duration using optional tags to trim the file.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3> <language>en</language> <provider>ABCMusic</provider> <album> <album_type>ringtone</album_type> <upc>10000000020081</upc> <grid>A10302B00002427900</grid> <title>So It Goes</title> <original_release_date>2009-09-05</original_release_date> <label_name>ABC Records</label_name> <genres> <genre code="ROCK-00"/> <genre code="POP-00"/> </genres> <copyright_pline>2009 ABCMusic</copyright_pline> <copyright_cline>2009 ABCMusic</copyright_cline> <artwork_files> <file> <file_name>cover.jpg</file_name> <checksum type="md5">39af338c579894ca25be7ba0fb3e4fab</checksum> <size>6591649</size> </file> </artwork_files> <products> <product> <territory>US</territory> <sales_start_date>2009-09-05</sales_start_date> </product> </products> <artists> <artist> <artist_name>The Sirens</artist_name> <apple_id>4299625</apple_id> <primary>true</primary> <roles> <role>Artist</role> </roles> </artist> </artists> <tracks> <track> <type>ringtone</type> <isrc>USMPK0508101</isrc> <title>So It Goes</title> <label_name>ABC Records</label_name> <copyright_pline>2009 ABCMusic</copyright_pline> <explicit_content>none</explicit_content> <volume_number>1</volume_number> <track_number>1</track_number> <audio_file> <file_name>SoItGoesRingtone.flac</file_name> <checksum type="md5">7feb9150ebbb4bcca25713017a0714e6</checksum> <size>99253792</size> </audio_file> <tone_start_time>72</tone_start_time> <tone_duration>23</tone_duration> <products> <product> <territory>US</territory> <cleared_for_sale>true</cleared_for_sale> </product> </products> <artists> <artist> <artist_name>The Sirens</artist_name> <apple_id>4299625</apple_id> <primary>true</primary> <roles> <role>Artist</role> </roles> </artist> </artists> </track> </tracks> </album></package>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 |
|
Track Type (required) Specifies the track as a ringtone as opposed to a regular song. |
|
 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 |
|
 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. |
|
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.
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, 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.
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.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>en</language> <provider>Warner</provider> <album> <vendor_id>093624970989</vendor_id> <upc>093624970989</upc> <title>The Complete Recollection</title> <title_version>1999-2010</title_version> <original_release_date>2010-09-21</original_release_date> <label_name>Vapor/Sire</label_name> <genres> <genre code="ROCK-00"/> <genre code="ALTERNATIVE-00"/> </genres> <copyright_pline>2010 Sire Records, Marketed by Reprise Records, A Warner Music Group Company.</copyright_pline> <copyright_cline>2010 Sire Records, Marketed by Reprise Records, A Warner Music Group Company.</copyright_cline> <artwork_files> <file> <file_name>box_set_cover_art.jpg</file_name> <size>237918</size> <checksum type="md5">9e977a2509f22f716da3774f1324cd45</checksum> </file> </artwork_files> <products> <product> <territory>CA</territory> <cleared_for_sale>true</cleared_for_sale> <sales_start_date>2010-11-30</sales_start_date> <preorder_sales_start_date>2010-11-16</preorder_sales_start_date> </product> <product> <territory>US</territory> <cleared_for_sale>true</cleared_for_sale> <sales_start_date>2019-10-22</sales_start_date> <preorder_sales_start_date>2010-09-07</preorder_sales_start_date> <cleared_for_stream>true</cleared_for_stream> <stream_start_date>2019-10-22</stream_start_date> </product> </products> <preorder_previews>false</preorder_previews> <artists> <artist> <artist_name>Tegan and Sara</artist_name> <apple_id>3204427</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> </artist> </artists> <tracks> <track_group> <group_name>Under Feet Like Ours</group_name> <vendor_id>5099900700343</vendor_id> <artwork_files> <file> <file_name>album1_cover_art.jpg</file_name> <size>1049268</size> <checksum type="md5">41af9ce3ec9b520c059069b20d4a1cc9</checksum> </file> </artwork_files> <track> <vendor_id>USTCZ0976948</vendor_id> <isrc>USTCZ0976948</isrc> <title>Divided</title> <gapless_play>false</gapless_play> <label_name>Vapor/Sire</label_name> <products> <product> <territory>CA</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>99</wholesale_price_tier> </product> <product> <territory>US</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>99</wholesale_price_tier> </product> </products> <explicit_content>none</explicit_content> <volume_number>1</volume_number> <track_number>1</track_number> <preview_start_index>69</preview_start_index> <artists> <artist> <primary>true</primary> <artist_name>Tegan and Sara</artist_name> <apple_id>3204427</apple_id> <roles> <role>Performer</role> </roles> </artist> <artist> <primary>false</primary> <artist_name>Jared Kuemper</artist_name> <apple_id>214329395</apple_id> <roles> <role>Producer</role> </roles> </artist> <artist> <primary>false</primary> <artist_name>Sara Quin</artist_name> <apple_id>30370603</apple_id> <roles> <role>Producer</role> </roles> </artist> <artist> <primary>false</primary> <artist_name>Tegan Quin</artist_name> <apple_id>30370599</apple_id> <roles> <role>Producer</role> </roles> </artist> </artists> <audio_file> <size>20436848</size> <file_name>093624970989_00001_LL.flac</file_name> <checksum type="md5">f05c33ffe648d13ec2f0126aee8721fb</checksum> </audio_file> </track><!-- This track group includes a booklet --> <booklet> <vendor_id>5099749642829_GBBFT0501345</vendor_id> <title>Digital Booklet - Tegan and Sara</title> <copyright>2010 Sire</copyright> <volume_number>1</volume_number> <track_number>2</track_number> <products> <product> <territory>CA</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>99</wholesale_price_tier> </product> <product> <territory>US</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>99</wholesale_price_tier> </product> </products> <file> <file_name>booklet.pdf</file_name> <size>67438659</size> <checksum type="md5">ddfe4b8ab433e43e7dde429df86cabb2</checksum> </file> </booklet> <track> <vendor_id>USTCZ0976953</vendor_id> <isrc>USTCZ0976953</isrc> <title>Our Trees</title> <gapless_play>false</gapless_play> <label_name>Vapor/Sire</label_name> <products> <product> <territory>CA</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>99</wholesale_price_tier> </product> <product> <territory>US</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>99</wholesale_price_tier> </product> </products> <explicit_content>none</explicit_content> <volume_number>1</volume_number> <track_number>3</track_number> <preview_start_index>73</preview_start_index> <artists> <artist> <primary>true</primary> <artist_name>Tegan and Sara</artist_name> <apple_id>3204427</apple_id> <roles> <role>Performer</role> </roles> </artist> <artist> <primary>false</primary> <artist_name>Jared Kuemper</artist_name> <apple_id>214329395</apple_id> <roles> <role>Producer</role> </roles> </artist> <artist> <primary>false</primary> <artist_name>Sara Quin</artist_name> <apple_id>30370603</apple_id> <roles> <role>Producer</role> </roles> </artist> <artist> <primary>false</primary> <artist_name>Tegan Quin</artist_name> <apple_id>30370599</apple_id> <roles> <role>Producer</role> </roles> </artist> </artists> <audio_file> <size>22908864</size> <file_name>093624970989_00002_LL.flac</file_name> <checksum type="md5">384fbc7c58c92998fdf77bcec01cfc50</checksum> </audio_file> </track><!-- Additional song tracks here --> <track_group> <group_name>This Business of Art</group_name> <vendor_id>5099900700344</vendor_id> <artwork_files> <file> <size>1049268</size> <file_name>album2_cover_art.jpg</file_name> <checksum type="md5">41af9ce3ec9b520c059069b20d4a1cc9</checksum> </file> </artwork_files> <track> <vendor_id>USVP10000001</vendor_id> <isrc>USVP10000001</isrc> <title>The First</title> <gapless_play>false</gapless_play> <label_name>Vapor/Sire</label_name> <products> <product> <territory>CA</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>99</wholesale_price_tier> </product> <product> <territory>US</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>99</wholesale_price_tier> </product> </products> <explicit_content>none</explicit_content> <volume_number>2</volume_number> <track_number>1</track_number> <preview_start_index>43</preview_start_index> <artists> <artist> <primary>true</primary> <artist_name>Tegan and Sara</artist_name> <apple_id>3204427</apple_id> <roles> <role>Performer</role> </roles> </artist> <artist> <primary>false</primary> <artist_name>Hawksley Workman</artist_name> <apple_id>13074574</apple_id> <roles> <role>Producer</role> </roles> </artist> </artists> <audio_file> <size>22614208</size> <file_name>093624768463_00001_LL.flac</file_name> <checksum type="md5">29d88d533e93e73d035692cdd5842e7b</checksum> </audio_file> </track> <track> <vendor_id>USVP10000002</vendor_id> <isrc>USVP10000002</isrc> <title>Proud</title> <gapless_play>false</gapless_play> <label_name>Vapor/Sire</label_name> <products> <product> <territory>CA</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>99</wholesale_price_tier> </product> <product> <territory>US</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>99</wholesale_price_tier> </product> </products> <explicit_content>none</explicit_content> <volume_number>2</volume_number> <track_number>2</track_number> <preview_start_index>43</preview_start_index> <artists> <artist> <primary>true</primary> <artist_name>Tegan and Sara</artist_name> <apple_id>3204427</apple_id> <roles> <role>Performer</role> </roles> </artist> <artist> <primary>false</primary> <artist_name>Hawksley Workman</artist_name> <apple_id>13074574</apple_id> <roles> <role>Producer</role> </roles> </artist> </artists> <audio_file> <size>21551280</size> <file_name>093624768463_00002_LL.flac</file_name> <checksum type="md5">663d4abad9ce93b49b0de0e89a25e235</checksum> </audio_file> </track><!-- Additional song tracks here --><!-- This track group includes a video --> <video> <vendor_id>USREV1000104</vendor_id> <isrc>USREV1000104</isrc> <title>The First</title> <original_release_date>2011-09-21</original_release_date> <label_name>Vapor/Sire</label_name> <genres> <genre code="ALTERNATIVE-00"/> </genres> <copyright_cline>2010 Sire Records, Marketed by Reprise Records, A Warner Music Group Company.</copyright_cline> <copyright_pline>2011 Vapor Records</copyright_pline> <explicit_content>none</explicit_content> <volume_number>2</volume_number> <track_number>3</track_number> <products> <product> <territory>CA</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>99</wholesale_price_tier> </product> <product> <territory>US</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>99</wholesale_price_tier> </product> </products> <artists> <artist> <primary>true</primary> <artist_name>Tegan and Sara</artist_name> <apple_id>3204427</apple_id> <roles> <role>Performer</role> </roles> </artist> </artists> <assets> <asset type="full"> <data_file role="source"> <size>478619652</size> <file_name>USREV1000104_15384.mpg</file_name> <checksum type="md5">0ca11675499c464dbc2bb08b6708ce09</checksum> </data_file> </asset> <asset type="artwork"> <data_file> <size>424797</size> <file_name>video_poster_art.jpg</file_name> <checksum type="md5">7781cf3fcdf4e24756733e5b802c5f7e</checksum> </data_file> </asset> </assets> </video> </track_group><!-- Additional track groups here --> </tracks> </album></package>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 (required) Begins the |
|
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 |
|
Box Set Album UPC (required; cannot be updated) This is the UPC for the whole box set. Refer to the Basic Music Album Metadata Example for detailed annotations on |
|
Box Set Album Title (required; can be updated, but may require a ticket; see Content Update Behavior) The title of the whole box set. Refer to the Basic Music Album Metadata Example for detailed annotations on |
|
Box Set Title Version (optional; can be updated, but may require a ticket; see Content Update Behavior) The version title of the box set. Refer to the Basic Music Album Metadata Example for detailed annotations on |
|
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 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 |
|
Track Group Metadata Fields |
|
 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 |
|
 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. |
|
 Group Name (required; may be updated; see Content Update Behavior) Name for the track group. This is what the customer see for the track group on Apple Music. 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 Files (optional; may be updated; see Content Update Behavior) Artwork for the track group is optional. When the 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 (required) Identifies a track within the track group. There must be one |
|
 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 For a booklet, use the Refer to the Basic Music Album Metadata Example for detailed annotations on the |
|
 Track Title (required; can be updated, but may require a ticket; see Content Update Behavior) The title of the track in the track group. |
|
 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 Note: If a double album (an album with two discs) is included as part of a boxed set, use one |
|
 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 Important: All tracks within a given track group must be sequential. |
Track Group/Booklet Metadata Fields |
|
 Booklet (required) Identifies a booklet. For track groups, the |
|
 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 (required) The title of the booklet, as it will appear on Apple Music and in the purchaser’s Library. |
|
 Copyright (required; can be updated) The copyright of the booklet, as it will appear on Apple Music. |
|
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 |
|
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 Group/Video Metadata Fields |
|
 Box Set Music Video (optional) If the track group contains a video, the video content must be defined within the Depending on the structure of the box set content, you could have a |
|
 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 Refer to the Music Video Single Metadata Annotations for detailed annotations on |
|
|
After you submit a package, 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.
Read-only tags are returned in the metadata lookup and are supplied by Apple to provide information about the package, such as the status of the content review and Apple identifiers for 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.
The following partial example shows where read-only information appears in the returned metadata for an album.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3"> <metadata_token>1405704088101-ae534236053dbb0b082dd6319857a403bce91396e5753fa6ff70f8b3047609fc</metadata_token> <language>en</language> <provider>OneIndependent</provider> <album> <read_only_info> <read_only_value key="content-review-status">Live-Reviewed</read_only_value> <read_only_value key="content-review-date">2004-09-15</read_only_value> <read_only_value key="open-content-tickets">Metadata #68461076 - Pending</read_only_value> <read_only_value key="content-hiding-reason">Hidden: Bad Metadata</read_only_value> </read_only_info> <vendor_id>5099749642829</vendor_id> . . . <products> <product> <territory>GB</territory> <wholesale_price_tier>3</wholesale_price_tier> <sales_start_date>2004-10-22</sales_start_date> <cleared_for_sale>true</cleared_for_sale> <read_only_info> <read_only_value key="apple-id">21393649</read_only_value> <read_only_value key="storeURL-GB">https://itunes.apple.com/gb/album/medulla/id21393649?ls=1</read_only_value> </read_only_info> </product> <product> <territory>IE</territory> <wholesale_price_tier>3</wholesale_price_tier> <sales_start_date>2004-10-22</sales_start_date> <cleared_for_sale>true</cleared_for_sale> <read_only_info> <read_only_value key="apple-id">21393649</read_only_value> <read_only_value key="storeURL-IE">https://itunes.apple.com/ie/album/medulla/id21393649?ls=1</read_only_value> </read_only_info> </product> </products> <artists> <artist> <!--Apple ID: 295015--> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> <read_only_info> <read_only_value key="apple-id">295015</read_only_value> <read_only_value key="curated-artist">true</read_only_value> </read_only_info> </artist> . . . <tracks> <track> <vendor_id>GBBFT0501345_9083</vendor_id> <isrc>GBBFT0501345</isrc> <grid>A10302B00002427998</grid> <title>The Pleasure Is All Mine</title> <products> <product> <territory>GB</territory> <cleared_for_sale>true</cleared_for_sale> <wholesale_price_tier>98</wholesale_price_tier> <read_only_info> <read_only_value key="apple-id">21393652</read_only_value> <read_only_value key="storeURL-GB">https://itunes.apple.com/gb/album/pleasure-is-all-mine/id21393649?i=21393652&amp;ls=1</read_only_value> </read_only_info> </product> . . . <artists> <artist> <!--Apple ID: 295015--> <artist_name>Björk</artist_name> <apple_id>295015</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> <read_only_info> <read_only_value key="apple-id">295015</read_only_value> <read_only_value key="curated-artist">true</read_only_value> </read_only_info> </artist> . . . </track> </tracks> </album></package>
Review Status Read-Only Value This key attribute ( Before content can go live, 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:
|
Review Date Read-Only Value This |
Open Tickets Read-Only Value 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. |
Hidden Content Read-Only Value This |
Apple ID Read-Only Value A read-only info block appears in the The Note: The Apple identifier is also returned in a “comment” field Store URL Read-Only Value The |
Apple ID Read-Only Value A read-only info block appears in the The Note: The Apple identifier is also returned in a “comment” field Curated Artist Read-Only Value The |
Apple ID Read-Only Value A read-only info block appears in the The Note: The Apple identifier is also returned in a “comment” field Store URL Read-Only Value The |
Apple ID Read-Only Value A read-only info block appears in the The Note: The Apple identifier is also returned in a “comment” field Curated Artist Read-Only Value The |
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.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3"> <metadata_token>0814057048101-53fa6ff70f8ae5342360d653dbb0b082d319857a403bce91396e57b3047609fc</metadata_token> <language>en</language> <provider>WarnerMusicGroup</provider> <album> <read_only_info> <read_only_value key="content-review-status">Live-Reviewed</read_only_value> <read_only_value key="content-review-date">null</read_only_value> </read_only_info> <vendor_id>8256463821764</vendor_id> <upc>8256463821764</upc> <grid>A10302B0000279612Q</grid> <title>Life in Slow Motion</title> <original_release_date>2006-07-17</original_release_date> <label_name>Warner Vision International/WMI</label_name> <genres> <genre code="POP-00"/> </genres> <copyright_pline>2006 IHT Records Limited</copyright_pline> <copyright_cline>2006 IHT Records Limited</copyright_cline> <artwork_files> <file> <file_name>5051011277023.jpg</file_name> <size>6852291</size> <checksum type="md5">6ddabb680edae6bf2ec84ffcfa730fda</checksum> </file> </artwork_files> <products> <product> <territory>GB</territory> <wholesale_price_tier>3</wholesale_price_tier> <sales_start_date>2006-07-17</sales_start_date> <cleared_for_sale>true</cleared_for_sale> <read_only_info> <read_only_value key="apple-id">889106257</read_only_value> <read_only_value key="storeURL-GB">https://itunes.apple.com/gb/album/life-in-slow-motion/id889106257?ls=1</read_only_value> </read_only_info> </product> </products> <artists> <artist> <!--Apple ID: 316381--> <artist_name>David Gray</artist_name> <apple_id>316381</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> <read_only_info> <read_only_value key="apple-id">316381</read_only_value> <read_only_value key="curated-artist">false</read_only_value> </read_only_info> </artist> </artists> <tracks> <video> <vendor_id>USW987200306</vendor_id> <title>Alibi</title> . . . <products> <product> <territory>GB</territory> <cleared_for_sale>true</cleared_for_sale> <read_only_info> <read_only_value key="apple-id">889106555</read_only_value> <read_only_value key="storeURL-GB">https://itunes.apple.com/gb/album/alibi/id889106257?i=889106555&amp;ls=1</read_only_value> </read_only_info> </product> </products> <artists> <artist> <!--Apple ID: 316381--> <artist_name>David Gray</artist_name> <apple_id>316381</apple_id> <roles> <role>Performer</role> </roles> <primary>true</primary> <read_only_info> <read_only_value key="apple-id">316381</read_only_value> <read_only_value key="curated-artist">false</read_only_value> </read_only_info> </artist> </artists> </video> </tracks> </album></package>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)
To see a metadata update example, read Music Album Metadata-Only Update.
Before content can go live on Apple Music, 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:
<read_only_info> <read_only_value key="content-review-status">Live-Reviewed</read_only_value></read_only_info>The table below defines the various statuses:
Review Status | What It Means |
|---|---|
Before the Sales Start Date | |
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. |
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. |
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 Identifier; Artist ISNI (Primary, Featuring or With) |
|---|
Note: When you update a primary artist, an artist where the |
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 music 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 music 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 music 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 music 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 music 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 | ✓ |
|
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.
When delivering credits
Performer as a role is not recommended.
Each individual member of a band or group should be credited with the respective instrument or role performed on each specific song. A band or group should not be collectively credited with multiple roles like Vocals, Guitar, Bass, and Drums.
“Composition & Lyrics” roles should be given to the artists that created the original written work, both the music and the words, if applicable.
The role Composer is used to refer to the artist who wrote the music.
The role Lyrics is used to refer to the artist who wrote the words.
The role Songwriter is commonly used for artists who wrote both the music and words, or when there is ambiguity regarding their contributions.
“Production & Engineering” roles should be comprehensive and include all of the staff involved in the final recording.
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 |
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.
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 is accepted but the content is not categorized by genre on Apple Music. 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 iTunes Connect Resources and Help.
Language codes should be formatted according to the best practices recommended by the Internet Engineering Task Force (IETF) in a group of documents known collectively as BCP 47, and in particular, RFC 5646, which is part of BCP 47. An overview of these best practices is provided at the W3C Internationalization site. 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 Apple Music 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 storefront displays content only in a limited set of languages, as shown in the table below.
Languages | Storefront displays only these languages |
|---|---|
Afrikaans | af |
Arabic | ar |
Bengali | bn |
Bulgarian | bg |
Cantonese | yue-Hant |
Catalan | ca |
Chinese (Simplified) | zh-Hans |
Chinese (Traditional) | zh-Hant |
Croatian | hr |
Czech | cs |
Danish | da |
Dutch | nl |
English | en |
Estonian | et |
Finnish | fi |
French | fr |
German | de |
Greek | el |
Haitian | ht |
Hebrew | he |
Hindi | hi |
Hungarian | hu |
Icelandic | is |
Indonesian | id |
Irish | ga |
Italian | it |
Japanese | ja |
Kazakh | kk |
Korean | ko |
Lao | lo |
Latin | la |
Latvian | lv |
Lithuanian | lt |
Malay | ms |
Norwegian | no |
Persian | fa |
Polish | pl |
Portuguese | pt |
Punjabi | pa |
Romanian | ro |
Russian | ru |
Sanskrit | sa |
Slovak | sk |
Slovenian | sl |
Spanish | es |
Spanish (Latin America)* | es-419 |
Swedish | sv |
Tagalog | tl |
Tamil | ta |
Telugu | te |
Thai | th |
Turkish | tr |
Ukrainian | uk |
Urdu | ur |
Vietnamese | vi |
Zulu | zu |
* 419 is a UN M.49 region code. https://unstats.un.org/unsd/methodology/m49/
The SMPTE timecode format is expressed as: framerate/framerate multiplier/mode. The W3C standard for expressing the 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: |
| 00:55:13.124 (Note: |
NTSC Video |
|
| 00:55:09:20 |
NTSC Video |
|
| 00:55:13;00 (Note: Drop frame mode requires the use of the semicolon after the seconds.) |
NTSC Film (Imprecise) |
|
| 01:08:57:02 |
PAL |
|
| 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.
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?
W3Schools | XML: A Beginner’s Guide by Dave Mercer |
|---|---|
Some letters in XML have to be rewritten, what is that about? What’s wrong with my ampersand? My XML isn’t valid!
XML uses a small set of characters to denote structure in the document. If you need to use these characters within content in your XML file, you need to let the XML file know that the characters are not being used as structure by "escaping" them. For example the letters < and > designate an element tag marker, so if you have a value of "9 > 0" in your XML, you need to escape the greater than character with a set of characters called an entity. The entity for greater than ">" is ">", thus making your previous statement "9 > 0". If you cannot rewrite these characters, see the next section regarding using a Character Data (CDATA) block.
Here are the characters that need to be escaped, and their equivalent entities:
Character | Escaped Equivalent |
|---|---|
> | > |
< | < |
& | & |
I cannot rewrite my characters. Is there another option? What is CDATA?
XML does offer another solution when rewriting reserved characters is not possible. 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>
Both of these examples are correct and acceptable. For further explanation, see https://www.w3schools.com/xml/dom_cdatasection.asp. Note the characters must still be encoded in UTF-8.
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.
These products are neither endorsed nor supported by Apple.
XML Metadata Production |
|
|
Oxygen XML Editor Mac, Windows, Linux | Exchanger XML Editor Mac, Windows, Linux | Altova XML Spy Windows |
XML Debugging |
|
|
Firefox Mac, Windows, Linux | xmllint OS X (or later), BSD | |
MD5 Checksum |
|
|
md5 OS X (or later), BSD | md5sum Windows |
The following table lists the previously-released specifications and the revisions:
Date/Version | Summary |
|---|---|
July 2024 - Version 5.3.20 | Renamed this document. Added information on asset-only updates. Updated music profile information for primary status and secondary ISRC. Delivering song lyrics for music videos is not supported. Additional updates and clarifications. |
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. |
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 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 |
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: |
August 10, 2020 - Version 5.3.10 | Added “pre-add” albums. Added |
April 6, 2020 - Version 5.3.9 | Streaming tags ( |
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 |
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 |
October 24, 2018 - Version 5.3.5 | Added a new tag, Added a new Deprecated |
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 |
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 |
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 |
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 |
May 25, 2016 - Version 5.2.5 | Clarified |
January 29, 2016 - Version 5.2.4 | Added new tags to support improved sales reporting: |
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 |
September 29, 2014 - Version 5.2.1 | Added a new tag |
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 |
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 |
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 |
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 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 |
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 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 |
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. |
August 10, 2009 - Version 3.3.3 |
|
July 1, 2009 - Version 3.3.2 |
|
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 |
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 |
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. |
Title
Renamed this document to Apple Music Specification.
Music Profile: Asset-Only Updates
Added information on delivering asset-only updates. See Music Album Asset-Only Update Examples.
Music Profile: Primary Status
Updated the instructions on specifying primary status for album and track artists. See Basic Music Album Metadata Annotated.
Music Profile: Secondary ISRC
The secondary ISRC is required when you deliver an immersive audio recording. See Basic Music Album Metadata Annotated.
Song Lyrics for Music Videos
For music videos, delivering a song lyrics file (TTML file) is not supported.
General
Additional updates and clarifications.
Music Profile: Album and Track Flags
Updated the list of categories that can be specified for album and track flags. See Basic Music Album Metadata Annotated.
Immersive Audio Updates
Added information on removing immersive audio source assets. See Immersive Audio Updates.
General
Additional updates and clarifications.
Recommended Contributor Roles
A list of extended contributor roles is available in a separate document: Extended Contributor Roles.
General
Included minor updates and clarifications.
General
Corrections and clarifications.
Music Profile: Album Motion Art
Added information on how to specify album motion art. See the XML example in Basic Music Album Metadata Example and see the annotation information in Basic Music Album Metadata Annotated
General
Included minor updates and clarifications.
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.
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>
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.
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>.
Clarification
The link to a tool to verify md5sum was outdated and has been updated to: MD5 Win Verifier. See Helpful Tools.
Music Profile: Tag Changes
Added
<assets> block can be used to deliver track audio files
external_identifier.isrc as an attribute on a datafile
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 |
|---|---|---|
| Available for Fitness+ | Available for Fitness+. The |
| Not available for Fitness+. The | 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
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 |
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
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 |
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.
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.
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.
New lyrics delivery for multiple locales:
<lyrics_set> <lyrics_file> <file_name>pleasure.ttml</file_name> <size>993</size> <checksum type="md5">40619cd971b4d41987f7dd3c28738a9f</checksum> </lyrics_file> <lyrics_file locale="zh-Hans"> <file_name>pleasure_simplified_zh.ttml</file_name> <size>1067</size> <checksum type="md5">8738a9f9cd977f7d4d4106d311b98c24</checksum> </lyrics_file> <lyrics_file locale="zh-Hant"> <file_name>pleasure_traditional_zh.ttml</file_name> <size>1132</size> <checksum type="md5">19cd971b988738a9f7f7d44d4106d3c2</checksum> </lyrics_file></lyrics_set>Existing lyrics delivery (still supported):
<lyrics_file> <file_name>sample_lyrics.ttml</file_name> <size>993</size> <checksum type="md5">40619cd971b4d41987f7dd3c28738a9f</checksum></lyrics_file>Or,
<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.
New and updated Indian music genres:
Genre | Sub-Genre |
|---|---|
Indian Classical | Carnatic Classical Hindustani Classical |
Regional Indian | Assamese Bengali Bhojpuri Gujarati Haryanvi Kannada Malayalam Marathi Odia Punjabi Rajasthani Urdu |
Regional Indian | Bengali | Rabindra Sangeet |
Regional Indian | Punjabi | Punjabi Pop |
Music Profile: Roles
Added Anime Character to the list of vocal roles. See Recommended Contributor Roles.
Music Profile: Cleared for Ticketmaster
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>
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.
Music Video Profile: Screen Capture Art
The requirements for music video artwork have changed. Refer to the iTunes Video and Audio Asset Guide for details.
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.
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.
For XML examples, see HDR Dolby® Vision Metadata Example and HDR10 Metadata Example. For an XML example showing how to deliver HDR and SDR videos in the same delivery, see HDR and SDR Delivery.
Music Video Profile: 4K Video
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
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):
<package xmlns="http://apple.com/itunes/importer" version="music5.3">
Note that this information is for clarification purposes; the numbering schemes have not changed and do not affect the delivery process as long as you follow the numbering rules.
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
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:
<package xmlns="http://apple.com/itunes/importer" version="music5.3">
Music Profile: Music Video Crop Dimensions
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.
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.
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.
Music Profile: Content Updates
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.
Music Profile: Music Videos
The <title_version> tag can be delivered for music videos within the <locales> block. See Japanese Language Metadata Example for Music Video and Title and Artist Localizations Metadata Video Example for more information.
Music Profile: Corrections
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
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:
<previews> <preview timecode_format="qt_text" start_time="00:05:13.002" image_time="00:05:20.128"/> </previews>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
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):
Incorrect:
<publishers> <publisher>Apple Publishing/Acme Music/XYZ Songs</publisher></publishers>Correct:
<publishers> <publisher>Apple Publishing</publisher> <publisher>Acme Music</publisher> <publisher>XYZ Songs</publisher></publishers>Music Profile: Cleared for iTunes Radio
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:
<package xmlns="http://apple.com/itunes/importer" version="music4.7">
Music Profile: Tag Changes
Deprecated
<cleared_for_itunes_radio> (at both the album <product> or track <product> levels)
<cleared_for_itunes_radio_during_preorder>
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>
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>
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:
<preorder_sales_start_date>2014-12-16</preorder_sales_start_date>
<sales_start_date>2015-12-18</sales_start_date>
Music Profile: Role
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.
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.
Storefront Languages
Storefront languages for Russia and India have been added. See How Localized Content Displays on Apple Music for more information.
Read-Only Information
A new appendix describes read-only information that appears when you do a metadata lookup on an existing package. Read-only tags are shown in the returned metadata and are supplied by Apple to provide information about the package, such as the status of the content review and Apple IDs for 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
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:
<package xmlns="http://apple.com/itunes/importer" version="music5.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)
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>See Title and Artist Localizations Metadata Basic Example for how to use these tags.
Music Profile: Genres
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
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 |
|
Deprecated Method Using the Genre Label |
|
Acceptable Method Using Both the Genre Code and the Genre Label |
If you use this method, the genre identified by code and the genre identified by genre label must resolve to the same genre, for example, |
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 (https://tools.ietf.org/html/rfc5646), which is part of BCP 47. An overview of these best practices is provided here: https://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.
See the metadata example in Title and Artist Localizations Metadata Basic Example for how to use this tag.
Music Profile: Ringtones
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>
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
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.
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 (https://tools.ietf.org/html/rfc5646), which is part of BCP 47. An overview of these best practices is provided here: https://www.w3.org/International/articles/language-tags/.
iTunes Store: Localized Content
A new section has been added to explain how localized content displays on the iTunes Store. See How Localized Content Displays on Apple Music.
Music Profile: Cover Art
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>
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>
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
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.
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>
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.
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>
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.
<artist> <artist_name>Eminem</artist_name> <roles> <role>Featuring</role> </roles> <primary>false</primary></artist>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.
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.
Renamed (old tag = new tag)
<album_vendor_id> = <vendor_id>
<album_upc> = <upc>
<album_grid> = <grid>
<album_title> = <title>
<album_label_name> = <label_name>
<album_genres> = <genres>
<album_copyright_pline> = <copyright_pline>
<album_copyright_cline> = <copyright_cline>
<album_artwork_files> = <artwork_files>
<album_liner_notes> = <liner_notes>
<album_description_short> = <description_short>
<album_description_long> = <description_long>
<album_volume_count> = <volume_count>
<album_track_count> = <track_count>
<album_artists> = <artists>
<album_preorder_previews> = <preorder_previews>
<track_vendor_id> = <vendor_id>
<track_isrc> = <isrc>
<track_grid> = <grid>
<track_title> = <title>
<track_title_version> = <title_version>
<track_gapless_play> = <gapless_play>
<track_label_name> = <label_name>
<track_genres> = <genres>
<track_products> = <products>
<track_copyright_pline> = <copyright_pline>
<track_lyrics> = <lyrics>
<track_liner_notes> = <liner_notes>
<track_beats_per_minute> = <beats_per_minute>
<track_preview_start_index> = <preview_start_index>
<track_volume_number> = <volume_number>
<track_audio_file> = <audio_file>
<track_artists> = <artists>
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.
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.
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">
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.
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).
Music Profile: Tag Changes
Deprecated
<album_related_albums>
<album_release_date>
<artwork_files>
<preorder_only>
<track_track_number>
<track> (bonus material)
<volume> (bonus material)
Changed (new tag = old tag)
<album_title translation="phonetic"> = <album_title translation="pronunciation">
<album_title_version translation="phonetic"> = <album_title_version translation="pronunciation">
<asset type="artwork"> = <artwork_files>
<asset type="full"> = <data_file>
<name translation="phonetic"> = <name translation="pronunciation">
<original_release_date> = <album_release_date>
<preorder_type>preorder only</preorder_type> = <preorder_only>
<track_number> = <track_track_number>
<track_title translation="phonetic"> = <track_title translation="pronunciation">
<track_title_version translation="phonetic"> = <track_title_version translation="pronunciation">
Added
<cleared_for_ticketmaster>
<cleared_for_user_generated_ringtones>
<original_release_date>
<preorder_type>
<track_number>
<preview starttime="n"/> (video)
<wholesale_price_tier> (video)
Music Profile: Artists
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>
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>
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.
Music Profile: Element Changes
Deprecated
<album_explicit_lyrics>
<album_original_release_year>
<display_artist>
<track_cleared_for_sale>
<track_piece>
<url>
Renamed (new tag = old tag)
<products> = <track_products>
Added
<chapters>
<track_gapless_play>