This document specifies how to create and manage an artist through the artist feed, in which you deliver the <artist> tag at the top level (directly under <package>). Using the artist feed provides an efficient way to focus on artist management, including:
Creating a new artist
Adding localizations for artist name
Adding an artist’s photo (sometimes referred to as a "hero image")
iTunes assigns every artist a unique Apple ID. To deliver an artist image, the artist must have an Apple ID. There are two methods to find out an artist’s Apple ID:
Through a metadata lookup on an album that returns the metadata for the album (see Use Lookup Metadata Mode in the iTunes Store Transporter User Guide for information on how to do a metadata lookup).
Through an artist lookup that returns the artist name, genre, locale, and Apple ID (see Use Artist Lookup Mode in the iTunes Store Transporter User Guide for information on how to do an artist lookup).
For a new artist, you can use the artist feed to create the artist and generate an Apple ID.
You can also use a metadata lookup to review the current hero image data for an existing artist by looking up the metadata based on the artist’s Apple ID. (See Use Lookup Metadata Mode in the iTunes Store Transporter User Guide for information on how to do a metadata lookup.)
Note: Providers must have the rights to “claim” an artist in order to manage an artist’s hero image. You can claim an artist if the artist has not already been claimed and you meet one of the following:
You have delivered all of the artist’s albums
You have delivered at least one album for the artist within the last 12 months or the last album (if longer than 12 months)
If you do not have the rights, you may see an error message.
About this Release
Date/Version
Changes Made
March 15, 2017 - Version 5.3
First general release of the spec.
November 10, 2015 — Version 5.2
Limited release draft.
What’s in iTunes Package Artist Specification 5.3?
Music Profile: Artist Feed
A new <artist> feed allows you to manage information about an existing artist, including creating a new artist, adding artist name localizations, and adding a hero image.
Music Profile: Artist Photo
iTunes provides support for adding a photo of the artist for use on the artist page and Apple Music.
Music Profile: Element Changes
Added
<hero_image>
<hero_image_file>
Changed
<artist> can now be used directly under <package>
Delivery & Formatting Guidelines
Images
Image assets (the hero image photo) must meet the following requirements.
JPEG with .jpg extension (quality unconstrained) or PNG with .png extension
Color space: RGB (screens standard)
Must be square
Minimum size 2400 x 2400 pixels
Note: Do not increase the size of a smaller image to meet the minimum size standard. Excessively blurry or pixelated images will be rejected. Images with alpha channels will also be rejected.
Package Format
All delivered metadata and asset files must be delivered in the iTunes package format.
The name for the package directory can match the artist’s Apple ID and follow the format apple_id.itmsp. However, if you do not know the artist’s Apple ID, you can use any filename as long as it contains only alphanumeric characters and the underscore mark ("_"); the filenames cannot contain spaces, other punctuation or symbols, and must not start with an underscore. The filename is case-sensitive.
An iTunes Package contains:
an XML file named metadata.xml that describes the delivered content using the structure documented in this specification
associated image file
For example, a package for an artist with a hero image (the artist’s Apple ID is 20044) could be sent in a package named "20044.itmsp" and contain the following files:
metadata.xml
20044_hero_image.png
The metadata XML file must be immediately (at the top level) within the package directory.
Metadata Details
Character Encoding
All metadata files must use UTF-8 Unicode character encoding. UTF-8 efficiently encodes non-Roman characters and helps to ensure that metadata displayed in the store is the same as was intended by the repertoire owner. Your metadata file should not contain a byte-order mark (BOM) as it is not necessary for UTF-8 encoded data files nor is it supported by iTunes 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 in the iTunes Store.
Checksums
All content files delivered to iTunes must include an industry-standard MD5 checksum, a measure that helps to guarantee that the asset files received by iTunes 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 iTunes. If any differences are detected, the asset file and the entire corresponding package are rejected. See the Helpful Tools section of this document for tools that can generate MD5 checksums for your content.
XML Formatting
There should be no null data or empty tags in the XML (except where specifically mentioned in the annotations). The XML must be formatted to use line breaks and indentations as demonstrated in the examples included in this document. xmllint is a Unix command line tool that may be helpful to ensure that the provided XML is correctly formatted. Read the iTunes Schema Validation Guide for more information.
How Localized Content Displays on the Store
In general, users can configure their OS to prefer one language or another for displaying localized text. For example, a user in France is likely to have their OS configured to prefer French. Additionally, the iTunes Store has a default language configured for each storefront, based on the country of that storefront. Each storefront also has a list of additional languages it supports. For example, the US store has English as its default language, but also supports Spanish. A user who signs into the US iTunes Store with their OS language set to English will see the store's UI in English; a user who signs into the US iTunes Store with their OS language set to Spanish will see the store's UI in Spanish. Whichever language is chosen to display the store's UI for a given user is called the user's storefront language.
When content such as an album or song title is displayed in the iTunes Store, the Store 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
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
Artist Profile
Artist Profile
The Artist profile is used for the delivery of artist information, including localizations and a hero image.
Each package represents a single artist on the iTunes Store. It includes metadata about the artist and the optional image file.
For questions regarding this document, contact your iTunes Technical Representative.
Managing Artists
Managing Artists Overview
You can use the <artist> feed to manage information about an existing artist and to create a new artist. When managing an existing artist, you can do a metadata lookup for an artist lookup to retrieve the Apple ID of the artist and use the returned <apple_id> in a metadata update delivery.
You can also use the metadata lookup or artist lookup feature to see if the artist already exists before you decide if you need to create a new artist. See the sections that follow for more information.
Looking Up an Artist
To facilitate managing artists, a lookup mode has been added to Transporter to query for artists by artist name. The command is:
-m lookupArtist
For example, the following returns all music artists named Johnny Appleseed, along with genre information, the primary locale, and the Apple ID:
$ iTMSTransporter -m lookupArtist -u username -p password -n "Johnny Appleseed" -v off -outputFormat XML
You can review the returned metadata and decide what your next steps should be:
If the artist does not exist: you can create a new artist. See Creating a New Artist
If the artist already exists and matches the genre and locale: you can then reference the artist by Apple ID in metadata updates. See Updating an Existing Artist for an example.
If another artist already exists with the same name as the one you want to create, but the genre or locale do not match the artist you want to create: you can create a new artist and specify that an existing artist has the same name. See Creating a New Artist with the Same Name as an Existing Artist and use the allow_duplicate_name attribute.
If the metadata lookup returns one or more artists with the same name: you can check the genre and locale to ensure you are referencing the correct artist by using the Apple ID associated with the correct artist.
After doing a lookup to find if the artist already exists, you can create a new artist if:
Artist lookup did not return an artist.
Artist lookup returned an artist with the same name, but the genre and/or locale do not match your artist.
For each artist returned in an artist lookup, you’ll see the artist name, genre, locale, and an Apple ID listed. iTunes assigns every artist a unique Apple ID and an artist must have an Apple ID before the artist photo can be delivered. To see a complete example of metadata returned, refer to Lookup Artist Mode in the Transporter User Guide.
Creating a New Artist
If the artist lookup did not return an artist, you can use the artist feed to create the artist. You could also provide an optional image in the same delivery, but that is not necessary. To create a new artist, use the <apple_id> tag with the generate=“true" attribute:
<apple_id generate=“true"/>
Later, you can do an artist lookup to retrieve the Apple ID for use when you need to reference the artist in subsequent metadata updates. The following XML example shows how to create a new artist and deliver a hero image (see Managing an Artist Image for image requirements and a complete example with annotations):
Use the generate="true" attribute with the <apple_id> tag to create an artist who does not yet exist in iTunes. In general, an artist must have an Apple ID before the artist photo can be delivered, however, this attribute allows you to create the artist and add an image in the same XML delivery.
Later, you can do an artist lookup and look for the <appleId> tag.
Note: If you use generate="true" and also supply an Apple ID (for example: <apple_id generate="true">123456</apple_id>), the delivery will fail.
Creating a New Artist with the Same Name as an Existing Artist
If the artist lookup returned an artist with the same name (but not the same genre and/or locale), you can use the artist feed to create the artist and indicate that the artist you are creating has the same name as an existing artist. Use the <apple_id> tag with the generate=“true" and allow_duplicate_name attributes:
Use the generate="true" attribute with the <apple_id> tag to create an artist who does not yet exist in iTunes. In general, an artist must have an Apple ID before the artist photo can be delivered. This attribute allows you to create the artist and add images in the same XML delivery. Use the optional allow_duplicate_name="true" attribute if the artist has the same name as an existing artist.
Notes:
If you use generate="true" and also supply an Apple ID (for example: <apple_id generate="true">123456</apple_id>), the delivery will fail.
If you use allow_duplicate_name attribute set to true, the generate attribute must also be set to true. Later, you can do an artist lookup on the artist and look for the <appleId> tag.
Updating an Existing Artist
The artist feed using the <artist> tag at the top level allows you to add localizations for an existing artist without having to do a full metadata update on an album (using the <album> tag), making it quicker and more efficient.
Note: When updating an existing artist, iTunes identifies the artist to update by the supplied <apple_id>, not by the <artist_name>, so you can omit the <artist_name> tag.
Artist Name Localizations (optional; can be added but not changed)
Provides a mechanism to specify localizations for the artist name. In this example, Japanese localizations are being delivered. Note that localizations will not be added if the artist you are updating already has the localizations in the same language.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for artist names. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
For written Mandarin Chinese, you must supply the script subtag. For example, if the name is written in traditional characters, the language subtag (cmn) indicates Mandarin Chinese and the script subtag (Hant) indicates that the language is written in traditional characters (as opposed to simplified).
Acceptable locales for Chinese written language include:
cmn-Hant (Mandarin Chinese traditional script)
cmn-Hans (Mandarin Chinese simplified script)
The <phonetic_name> tag (optional) should only be used where the language is Japanese, Chinese, Korean, Thai, Russian, Bulgarian, or Ukrainian. For Japanese, the tag provides the reading (furigana) of the artist in full-width Hiragana or Katakana. If any meaningful separation units exist they should be delimited using a space character. Providing the phonetic name provides a better search experience for the user.
See the Language Codes appendix of the iTunes Package Music Specification for accepted codes and links to detailed information.
Managing Artist Images
Managing an Artist Image
An artist image is a photo for your artists that appear in the iTunes library if a customer owns the artist’s music. Photos are also visible in the iTunes Store and in Apple Music whenever the artists and their music are shown.
Artist photos can be delivered using the new artist feed for an artist who has been assigned an Apple ID. (See Creating a New Artist on how to generate a new artist who does not have an Apple ID.)
Image Asset Requirements
Image assets must meet the following requirements.
Photo for artist (hero image):
JPEG with .jpg extension (quality unconstrained) or PNG with .png extension
Color space: RGB (screens standard)
Must be square
Minimum size 2400 x 2400 pixels
Note: Do not increase the size of a smaller image to meet the minimum size standard. Excessively blurry or pixelated images will be rejected. Images with alpha channels will also be rejected.
Adding an Image Metadata Example
The metadata example below shows only the tags relevant to artist images support under the <artist> tag. Refer to the iTunes Package Music Specification for annotations on the remaining tags.
<?xml version="1.0" encoding="UTF-8"?><package xmlns="http://apple.com/itunes/importer" version="music5.3"> <language>en</language> <provider>Universal</provider> <artist> <apple_id>20044</apple_id> <!-- The tag below can be omitted when updating --> <artist_name>Madonna</artist_name> <!-- Add optional localizations --> <locales> <locale name="ja"> <artist_name>マドンナ</artist_name> <!-- Optional phonetic_name --> <phonetic_name>まどんな</phonetic_name> </locale> </locales> <hero_image> <vendor_id>MADONNA_HERO_IMAGE</vendor_id> <hero_image_file> <file_name>MADONNA_HERO_IMAGE.png</file_name> <checksum type="md5">736a64333baa8266c26aa87d882da05a</checksum> <size>384675</size> </hero_image_file> </hero_image> </artist></package>
Adding an Image Metadata Annotations
Only the tags relevant to artist images support are described. Refer to the iTunes Package Music Specification for annotations on the remaining tags.
<artist>
Artist (required; cannot be updated)
Begins the <artist> block.
<apple_id>20044</apple_id>
Artist Apple ID (required)
Each artist must have an Apple ID before you can deliver the artist photo. (For new artists without an Apple ID, see Creating a New Artist.) If you do not know the artist's Apple ID, you can do an artist lookup and look for the <appleId> tag (refer to Lookup Artist Mode in the Transporter User Guide).
<artist_name>Madonna</artist_name>
Artist Name (optional when updating an artist)
Name of the artist.
Note that artist roles or primary status are not specified in this context (when <artist> appears directly under <package>).
<locales>
<locale name="ja">
<artist_name>マドンナ</artist_name>
<!-- Optional phonetic_name -->
<phonetic_name>まどんな</phonetic_name>
</locale>
</locales>
Artist Name Localizations (optional; can be added but not changed)
Provides a mechanism to specify localizations for the artist name. In this example, Japanese localizations are being delivered. Note that localizations will not be added if the artist you are updating already has the localizations in the same language.
For single-byte characters (such as those drawn from the ASCII character set), there is a limit of 256 characters for artist names. For multiple-byte characters (for example, Japanese), the limit is 1024 bytes, which can equate to as many as 256 characters.
For written Mandarin Chinese, you must supply the script subtag. For example, if the name is written in traditional characters, the language subtag (cmn) indicates Mandarin Chinese and the script subtag (Hant) indicates that the language is written in traditional characters (as opposed to simplified).
Acceptable locales for Chinese written language include:
cmn-Hant (Mandarin Chinese traditional script)
cmn-Hans (Mandarin Chinese simplified script)
The <phonetic_name> tag (optional) should only be used where the language is Japanese, Chinese, Korean, Thai, Russian, Bulgarian, or Ukrainian. For Japanese, the tag provides the reading (furigana) of the artist in full-width Hiragana or Katakana. If any meaningful separation units exist they should be delimited using a space character. Providing the phonetic name provides a better search experience for the user.
See the Language Codes appendix of the iTunes Package Music Specification for accepted codes and links to detailed information.
<hero_image>
Artist Photo (optional, can be updated)
Begins the <hero_image> block.
Note that only one photo can be delivered for an artist.
<vendor_id>MADONNA_HERO_IMAGE</vendor_id>
Artist Photo Vendor ID (required)
The vendor ID of the artist photo, which uniquely identifies the image. 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 ID 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 IDs have a limit of 100 bytes.
Artist Photo Asset File (required; can be updated)
The photo asset file is required, and you must provide the <file_name>, <size>,and <checksum>. The asset file must be square and be a minimum of 2400 by 2400 pixels. See Image Asset Requirements for complete file requirements.
</hero_image>
Frequently Encountered Issues
Accented characters such as é and ü don’t appear correctly in my titles and descriptions.
Make sure you are correctly encoding your metadata in UTF-8. You can use one of the XML Metadata Production tools listed in the Helpful Tools chapter. There is an XML tool called xmllint that will help identify problems with your XML encodings. You can also try previewing your XML in a browser that renders XML trees such as Firefox.
How do I create a checksum for my files?
Apple accepts file checksums using the industry standard MD5 message digest. There are a variety of tools available to produce an MD5 checksum. See the tools listed in Helpful Tools.
I’m not familiar with XML. Where can I find a general tutorial for XML?
Some letters in XML have to be rewritten, what is that about? What’s wrong with my ampersand? My XML isn’t valid!
XML uses a small set of characters to denote structure in the document. If you need to use these characters within content in your XML file, you need to let the XML file know that the characters are not being used as structure by "escaping" them. For example the letters < and > designate an element tag marker, so if you have a value of "9 > 0" in your XML, you need to escape the greater than character with a set of characters called an entity. The entity for greater than ">" is ">", thus making your previous statement "9 > 0". If you cannot rewrite these characters, see the next section regarding using a Character Data (CDATA) block.
Here are the characters that need to be escaped, and their equivalent entities:
Character
Escaped Equivalent
>
>
<
<
&
&
I cannot rewrite my characters. Is there another option? What is CDATA?
XML does offer another solution when rewriting reserved characters is not possible. Tag text may be enclosed in a special structure called a character data block CDATA. In a CDATA block, the <, >, and & characters are allowed; the only thing not allowed is the CDATA block closing sequence “]]>” which is unlikely to occur in your text.
Here’s an example using entity escaping:
<description>If 9 > 0, then take 0 & 9.</description>
And here is an example using a CDATA block:
<description><![CDATA[if 9 > 0, then take 0 & 9. ]]></description>
I don’t have a value for a tag that is shown in the XML.
For tags marked optional for which you have no value, Apple requires that you remove the tag entirely from the XML rather than leaving the tag empty. If the tag is marked required, you may not omit the tag.
Helpful Tools
These products are neither endorsed nor supported by Apple.
