Basic Audiobook Metadata Annotated

Package Metadata Fields

<?xml version="1.0" encoding="UTF-8"?>

XML Declaration (required)

The character encoding of your document must be defined.

Apple Books 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 xmlns="http://apple.com/itunes/importer" version="music5.3">

Package Container (required)

The xmlns (for XML namespace) attribute is required and is needed for schema validation. It is used to declare the namespace (and associated schema) to which the tags in the XML are expected to conform. The namespace must be:

http://apple.com/itunes/importer

The version attribute is required. Packages created to this specification must indicate version="music5.3". The “music” portion of the attribute must be in lowercase letters.

<language>en</language>

Language (required)

The primary language of the metadata for this package. Fields such as title are expected to appear in this language.

As a best practice when specifying a language, use the region subtag (for example, the US of en-US) only when it conveys helpful information, such as spelling variations between countries. See Language Codes for more information.

The language codes are formatted according to the best practices recommended by the Internet Engineering Task Force (IETF) in a group of documents known collectively as BCP 47, and in particular, RFC 5646, which is part of BCP 47. For an overview of these best practices, see https://www.w3.org/International/articles/language-tags/.

Provider Metadata Fields

<provider>AppleseedBooks</provider>

Provider (required, Apple-supplied)

This value should be the Apple-defined provider name used for partner identification.

Album Metadata Fields

<album>

Album (required)

Begins the album block to describe the audiobook and its contents.

<album_type>audiobook</album_type>

Album Type (required)

Specifies that the “album” being delivered is an audiobook. You must indicate the type as audiobook to distinguish it from other content types.

<vendor_id>9781106701657</vendor_id>

Audiobook Vendor ID (required)

The permanent value that uniquely identifies this audiobook separately from any other audiobook given by the same provider. Apple strongly recommends using the audiobook 13-digit ISBN-13 identifier for easier content management. The <vendor_id> cannot be updated.

Important: If another form of vendor identifier is provided, it can only contain alphanumeric characters and underscores ("_"). Packages delivered with identifiers containing other characters are rejected.

<title>Dracula (Unabridged)</title>

Audiobook Title (required; can be updated, but may require a ticket; see Content Update Behavior)

The title of the audiobook in the primary language of the package (as delivered in the <language> tag).

If an audiobook has a title version, it should be included in the audiobook title in parentheses "( )." Generally, the title version is used to distinguish different versions of the same audiobook (for example, "Abridged," "Unabridged," or “Original Staging”). If the audiobook does not have a different version, do not include this information in the metadata.

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.

<original_release_date>2015-09-21</original_release_date>

Original Release Date (required; can be updated but may require a ticket; see Content Update Behavior)

The original date of the first consumer-available physical audiobook release (cassette, 8-track, CD, or other physical media). This is not the digital release date, unless this audiobook has not previously been released on any format. This is the field presented to the user on Apple Books.

This field is cosmetic only and does not impact "available date" or "street date" on Apple Books. For audiobooks that are re-releases (for example, re-mastered, or releases on new media types such as CD, digital, and so on), do not use the date of re-release.

This field must be in YYYY-MM-DD format. If the <original_release_date> is more than 90 days later than the earliest <sales_start_date>, the package is rejected.

<label_name>Apple Publishing Group</label_name>

Label Name (required; can be updated)

The name of the publisher that released the audiobook.

<genres>

<genre code="CLASSICS-00"/>

</genres>

Audiobook Genres (required; can be updated, but may require a ticket; see Content Update Behavior)

Genres to associate with the audiobook. Apple recommends defining at least one, but no more than two genres.

All audiobook genres have an Apple genre code, which is supplied using the attribute named code used with the <genre> tag. The code attribute is required. The genre must be specified using following format:

<genre code="CLASSICS-00"/>

See Audiobook Genres for a list of codes.

Important: Genre information may be reassigned at the discretion of Apple Books.

<copyright_pline>2008 Apple Publishing Group</copyright_pline>

Audiobook Copyright P-Line (optional; can be updated)

Performance copyright line for the audiobook. Must be in the form YYYY copyright info as in the example. Do not add the p-line symbol (℗) or “p”; it is added automatically. Some audiobooks don't have this P-line available. Remove this tag if this is the case.

<copyright_cline>2008 Apple Publishing Group</copyright_cline>

Copyright line for the audiobook. Must be in the form YYYY copyright info as in the example. Do not add the c-line symbol (©) or “c”; it is added automatically. Some audiobooks do not have this C-line available. Remove this tag if this is the case.

<artwork_files>

<file>

<file_name>cover.jpg</file_name>

<size>56723</size>

<checksum type="md5">58a9947e2e5de47bc3039092964ad3a3</checksum>

</file>

</artwork_files>

Audiobook Artwork (required; can be updated)

Audiobook artwork is required, and you must provide the <file_name>, <size>, and <checksum>. The file name can contain only alphanumeric characters (A-Z, a-z, 0-9) and these symbols: underscore ("_"), dash (“-”), and period (“.”). The file name must not start with an underscore, dash, or period and cannot contain spaces, other punctuation or symbols.

The artwork file must be minimum of 3000 by 3000 pixels. See Artwork Source Profile for complete file requirements.

Important: If providing a metadata-only update, the <artwork_files> block should be omitted.

Audiobook Description (required; can be updated; up to 4000 characters)

A description of the audiobook in the language specified in the <language> tag, up to a 4,000 character limit. The book description requires a minimum of 50 characters.

The format attribute identifies the format of the text sent in the <description> tag. The format can be HTML ("html") or the default text format, which is unformatted plain text ("plain"). Note that the <description> field is the only field for which HTML markup is supported.

The <description> tag holds the actual text. You can enclose the text in a special structure called a character data block CDATA. In a CDATA block, the <, >, [, ], and & characters are allowed. CDATA is only acceptable if those characters are not escaped or otherwise HTML encoded.

Note: Character counts are for standard 8-bit characters (such as those drawn from the ASCII character set). Fewer multiple-byte characters (for example, Japanese symbols) are allowed.

Audiobook Products Metadata Fields

<products>

<product>

Product (required; can be updated)

For each territory in which an audiobook is to be sold there must be a defined product, which supplies information such as salability, pricing, and sales start date. Product information can be updated by redelivering a metadata-only update.

<territory>AU</territory>

Audiobook Territory (required; can be updated)

The territory in which this audiobook is cleared for sale. Must be specified as an ISO 3166-1 alpha 2 country code. Some countries in the ISO 3166-1 alpha 2 country list contain other countries (for example, United States includes Puerto Rico).

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>3</wholesale_price_tier>

Wholesale Price Tier (required; can be updated)

The wholesale price tier for the audiobook. Must be a wholesale price tier number as specified in your contract with Apple.

Review your contract to verify the tiers available to you. If you provide an invalid price tier, Apple reserves the right to reject the package or to use default pricing. Contact your Technical Representative for more details.

<cleared_for_sale>true</cleared_for_sale>

Cleared for Sale (optional; can be updated)

Specifies whether the audiobook is cleared for sale in the territory for the product. Must be true or false. If not specified, the default is true.

<sales_start_date>2009-01-05</sales_start_date>

Sales Start Date (optional; can be updated)

The date that this audiobook is made available for sale to customers in the specified territory only. This is also known as the "street date" of the audiobook and is written in the format YYYY-MM-DD.

In this example, "2009-01-05" is the sales start date and the audiobook was made available for sale starting January 5, 2009.

Important: Omitting this tag on an initial upload makes the audiobook available for sale immediately after normal quality assurance processing.

</product>

</products>

<artists>

<artist>

<artist_name>Bram Stoker</artist_name>

<apple_id>2683478</apple_id>

<roles>

<role>Author</role>

</roles>

<primary>true</primary>

</artist>

<artist_name>Christopher Saul</artist_name>

<apple_id>301336965</apple_id>

<roles>

<role>Narrator</role>

</roles>

<primary>false</primary>

</artist>

</artists>

Audiobook Artists (required; can be updated, but may require a ticket; see Content Update Behavior)

Name, primary status, and roles for each artist. In this context, "artist" may be any contributor including the book author or narrator. Individual artists, such as co-authors, should be listed separately and not grouped together (for example, "Walter Isaacson", "Dylan Baker" should each have their own <artist> block instead of "Walter Isaacson and Dylan Baker" listed in one <artist> block).

Artist

You can refer to the artist by Apple identifier (using the <apple_id> tag) or by name (using the <artist_name> tag). Apple assigns every artist a unique Apple identifier. Apple recommends that artists be delivered with the Apple identifier to avoid the ambiguity in cases where audiobook artists share the same name as other authors, music artists, actors, or crew members. You can supply the <apple_id>, the <artist_name>, or both the <apple_id> and <artist_name>. If you supply both tags, the <artist_name> tag is ignored in favor of the Apple identifier. If you do not know the audiobook artist's Apple identifier, you can do a metadata lookup on an existing audiobook 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.

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

The following roles are required for audiobooks:

Author
Narrator

Other roles may be provided if appropriate. See Contributor Roles for a complete list of accepted roles.

Apple strongly recommends that you list the authors before the narrators in the metadata.

Note: Supplying the narrator role is optional during the pre-order period. Once assets have been supplied, it is required.

The role names must be in English in order to be imported into Apple Books. But the names are localized if needed when displayed on Apple Books.

Primary Status

Primary status indicates whether the audiobook appears on the artist’s page in Apple Books. Typically, there are one or two primary (lead) artists (such as the author or co-authors). For audiobooks without an author (for example, a book that has an editor or translator instead of an author), the primary status should be set to true (<primary>true</primary>) for that contributor.

Artist names appear in the order in which they are specified in the provided metadata.

Note: The primary status for the narrator role should be set to false (<primary>false</primary>).

Audiobook Track Metadata Fields

<tracks>

<track>

Audiobook Track (required)

Begins the <tracks> block. Within the <tracks> block, each track audio file is specified using its own <track> tag. An individual track can be up to 23 hours long.

Apple recommends that you use as few <track> tags as possible. If a track audio file becomes over 23 hours, then split the audiobook by adding another <track>. See Audiobook Example with Multiple Tracks for an example XML delivery.

Note: A track audio file does not equal a chapter. Each track audio file can have several chapters.

<type>audiobook</type>

Audiobook Track Type (required)

Specifies the track as an audiobook as opposed to a regular song or ringtone.

<vendor_id>9781106701657_1</vendor_id>

Audiobook Track Vendor Identifier (required)

The permanent value that uniquely identifies this track audio file separately from any other track audio file given by the same provider. Apple recommends using the audiobook 13-digit ISBN-13 identifier for easier content management. For multi-track audiobooks, keep in mind that each track’s vendor identifier must be unique. For example, the vendor identifier for this first track is the ISBN-13 identifier, followed by an underscore and the number 1.

The <vendor_id> cannot be updated.

<title>Dracula Track 1 (Unabridged)</title>

Audiobook Track Title (required; can be updated, but may require a ticket; see Content Update Behavior)

The title of the track audio file in the primary language of the package (as delivered in the <language> tag). Note that this is the name of the track, not a chapter title. Chapter titles are delivered within the <chapter> block (see below).

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.

<label_name>Apple Publishing Group</label_name>

Audiobook Track Label Name (optional; can be updated)

The name of the publisher that released the audiobook. If not specified, the <label_name> from the <album> level is used

<explicit_content>none</explicit_content>

Audiobook Track Parental Advisory (optional; can be updated)

Denotes whether a track audio file contains explicit content. The value can be clean, explicit, or none. If omitted, none (that is, a track for which neither a clean or explicit version exists) is assumed.

Important: A track must only be marked clean if it is an edited version of the original explicit form of the track.

<track_number>1</track_number>

Audiobook Track Number (required)

The track number, used to order tracks within an audiobook. Must be a positive integer. The track number must be unique across all tracks in an audiobook.

<audio_file>

Audiobook Track Audio File (required; can be updated)

Begins the <audio_file> block for specifying the track audio file asset file. You must provide the <file_name>, <size>, and <checksum>.

See Audio Source Profile for complete audio asset file requirements.

See Concatenating MP3 Files to learn how to combine multiple audiobook MP3 files into a single track audio file.

<file_name>9781106701657_1.wav</file_name>

Audio File Name (required)

The name of the track audio file included in this delivery package. The name should be relative to the package (containing no path reference; neither "C:\" nor "/Macintosh HD/" should appear in this path) and it must contain the filename extension (".wav" in this example). The file name can contain only alphanumeric characters (A-Z, a-z, 0-9) and these symbols: underscore ("_"), dash (“-”), and period (“.”). The file name must not start with an underscore, dash, or period and cannot contain spaces, other punctuation or symbols. See Audio Source Profile for more information.

Important: Filenames are case-sensitive.

<size>172149800</size>

Audio File Size (required)

Size in bytes of the provided audio file for the track.

<checksum type="md5">2e669877c1913f59c6686a86b4d84d1d</checksum>

Audio File Checksum (required)

The MD5 checksum of the data file. See Checksums for more information.

</audio_file>

<audio_language>en</audio_language>

Track Audio Language (required)

Use the <audio_language> tag to specify the language of audio on the track audio file. It is especially important to include this information for audio performed in languages other than English.

The language codes are formatted according to the best practices recommended by the Internet Engineering Task Force (IETF) in a group of documents known collectively as BCP 47, and in particular, RFC 5646, which is part of BCP 47. An overview of these best practices is provided here: https://www.w3.org/International/articles/language-tags/.

Note: The language specified in the <audio_language> tag must not contain script information. For example, the language for Mandarin audio must be cmn, not 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 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.

<preview_start_index>240</preview_start_index>

Audiobook Track Preview Start (optional; can be updated)

Specifies a custom start time for the preview audio. The <preview_start_index> tag should be specified in seconds from the track start.

Important: If not specified, the default is 90 seconds for content over 180 seconds in duration and progressively earlier for shorter content.

<artists>

<artist>

<artist_name>Bram Stoker</artist_name>

<apple_id>2683478</apple_id>

<roles>

<role>Author</role>

</roles>

<primary>true</primary>

</artist>

<artist_name>Christopher Saul</artist_name>

<apple_id>301336965</apple_id>

<roles>

<role>Narrator</role>

</roles>

<primary>false</primary>

</artist>

</artists>

Audiobook Track Artists (required; can be updated, but may require a ticket; see Content Update Behavior)

Artist

Role

The following roles are required for audiobooks:

Author
Narrator

Other roles may be provided if appropriate. See Contributor Roles for a complete list of accepted roles.

Apple strongly recommends that you list the authors before the narrators in the metadata.

Note: Supplying the narrator role is optional during the pre-order period. Once assets have been supplied, it is required.

The role names must be in English in order to be imported. But the names are localized if needed when displayed on Apple Books.

Primary Status

Artist names appear in the order in which they are specified in the provided metadata.

Note: The primary status for the narrator role should be set to false (<primary>false</primary>).

<chapters>

<chapter>

<chapter_start_time>00:00:00.000</chapter_start_time>

<chapter_title>Chapter 1 - Jonathan Harker’s Journal</chapter_title>

</chapter>

<chapter>

<chapter_start_time>02:00:08.567</chapter_start_time>

<chapter_title>Chapter 2 - Jonathan Harker’s Journal Continued</chapter_title>

</chapter>

</chapters>

Audiobook Track Chaptering (required; can be updated)

Defines chapters within a given track audio file. Both <chapter_start_time> and <chapter_title> are required.

Chapter start time is in HH:MM:SS.sss format (hour, minute, second, milliseconds) and end time is inferred from the start time of the next defined chapter, or the track’s end time. Supplying the decimal point and milliseconds is optional.

Important: A chapter start time should not exceed the audio file duration. For example, if the delivered audio file is 18:43 minutes long, and you specify a chapter start time of 37:22:00, delivery fails.

Note: If you are concatenating files, and introducing chapter marks at points that were formerly boundaries between those files, be aware that regardless of whether you are specifying milliseconds in your chapter points, you must still track the precise cumulative duration of the files. You may choose to round to the nearest second in specifying the chapter marks. But you should use sub-second precision in tracking the cumulative length of the concatenated files. Otherwise, your chapter points gradually become more inaccurate further into the track as the imprecision is compounded.

For chapter titles, use customer-friendly naming conventions if possible, and stay as close as possible to the chapter names of the printed book. If chapters are named in the book, list the chapter number and then the chapter title, for example:

Chapter 1 - From the Beginning
Chapter 2 - The Next Day

Keep in mind that chapters and track audio files are not the same thing, and the chapter titles should not reflect the track numbers or titles at all. For example, do not include words such as "Track 1", "Track 2" in the chapter titles. Do not restate the title of the book in the chapter titles. If you include chapter numbers in chapter titles, do not restart the chapter numbering with each track audio file in a multiple-track delivery.

There is no limit to the total number of chapters specified, but generally chapters should follow the physical product chapter structure.

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.

</track>

</tracks>

</album>

</package>