Create your Catalog File
Step 1: Create Your Catalog File
In this step, you will create a catalog file that contains the metadata (title, length, release year, etc.) for your app's media content (movies, TV shows, specials, mini-series, and extras). The catalog file must follow the Catalog Data Format (CDF) schema, which requires you to follow a specific XML structure for describing your media.
- Creating Your Catalog File
- An Example Catalog File
- General Catalog File Structure
- Common Elements for All Works
- Elements Specific to the Work Type
- Tying Shows, Seasons, and Episodes Together
- Requirements for Box Art Images (ImageUrl)
- CDF FAQ
- Next Steps
Creating Your Catalog File
Use an automated process to create the file by developing programmatic scripts that pull the information from your database and transform the data to a CDF-compliant catalog file.
In general, to create the file, you will need to first familiarize yourself with XML and its concepts as they relate to the catalog XSL schema — see the CDF Overview. You'll then download the CDF schema XSD file to understand the logic and rules at a more granular level. You can also use the code samples shown in the Element web pages or the CDF examples ZIP as a starting point. As you create the file, consult the CDF reference documentation.
An Example Catalog File
The following example shows a simple catalog file that contains only one item (a movie), and uses only required elements.
<?xml version="1.0" encoding="utf-8" ?> <Catalog xmlns="http://www.amazon.com/FireTv/2014-04-11/ingestion" version="FireTv-v1.11"> <Partner>Everything Ever Made Filmworks</Partner> <Works> <Movie> <ID>MV-12345</ID> <Title locale="en-US">Edison Kinetoscopic Record of a Sneeze</Title> <Offers> <SubscriptionOffer> <Regions> <Country>US</Country> </Regions> </SubscriptionOffer> </Offers> </Movie> </Works> </Catalog>
General Catalog File Structure
This section provides an overview of the structure of the CDF schema and its elements. Readers should have a good understanding of XML.
The top-level outline of a catalog file can be represented as:
<Catalog> <Partner> ... </Partner> <Works> ... </Works> </Catalog>
Catalog (required) is the root element of all catalog files.
Partner (required) identifies you, the content provider.
Works (required) contains the bulk of the file: all of the movies and TV shows in your library, as much information as you choose to provide about each entry, and the offers that enable the user to view them.
Works element can contain any number of child elements, each representing an individual work such as a movie or a TV show. If the
Works element contains no child elements, we infer that all of your content is no longer available and we will remove it from our index.
The most common work type elements are as follows:
||Represents a feature-length film, but can also be used for short films.|
||A single episode of a
||One of the basic work types, a
||A televised series made up of seasons and episodes.|
||Televised events that don't belong to the traditional show-season-episode television hierarchy.|
||A clip or trailer that can be a standalone work or, more commonly, can be associated with another work (either external or in your catalog).|
Movies are standalone elements. TV shows, TV seasons, and TV episodes are separate elements that are tied together by IDs, as are mini-series and mini-series episodes. TV specials and extras can be standalone elements, but they can also be tied to other works. See Tying Shows, Seasons, and Episodes Together for details.
Common Elements for All Works
All of the work types listed above are built on a core of common elements, extended in each case with only 1-5 type-specific elements. Only a small subset of the common elements are required.
The outline of a work element can be represented as:
<_WorkType_> (such as <Movie> or <TvSeason>) <ID> <Title> <Offers> </_WorkType_>
ID (required) is an identifier of your choosing for the work. Each work's ID must be unique within your catalog and it should never change as long as you offer that work. The ID element is also used in associating work elements, for instance to specify a TV episode as part of a TV show and season.
Title (required) is, of course, the work's title. You can provide the title in multiple languages.
Offers (required) contains the methods through which the customer can view the work: for free or through subscription. Offers can be limited by time or by region. The
Offers element must contain at least one offer but can contain as many as necessary. There are four offer types:
||The work is free to view at any time, or optionally is free only during a given window.|
||The work can be watched by subscribers to the provider's service.|
The outline of an offer, including optional elements, can be represented as:
<_OfferType_> (such as <FreeOffer> or <SubscriptionOffer>) <Regions> <WindowStart> <WindowEnd> <LaunchDetails> <Price> (rental or purchase only) <Duration> (rental only) </_OfferType_>
LaunchDetails (optional) enables you to specify options for visual quality, audio language, and subtitles under this offer. It also allows you to define a special ID that can be used to directly launch a work with a predetermined configuration of those options.
If the availability of a given work changes, you must submit an updated catalog file with the new offer information.
The detail page for a movie, extra, or TV show displays all of the available offers and providers for that item. We display viewing options in this order (subject to change):
- Free offers
- Subscription content
- Fee-based content (purchase or rental)
Common Optional Elements for All Works
So far, we've discussed the common required elements and a handful of common optional elements. Using those alone, you have the knowledge to construct a valid catalog file.
However, those elements account for only about one-third of the total available to you. All the rest of the common elements are optional and are used to provide more information about the work.
For example, there are elements for genre, certification, cast and crew, plot description, studio, images, and customer rating. For a full list, see the Catalog Data Format (CDF) Schema.
A Note About Strings
Some string data in the CDF schema, such as a work's title and description, are defined as the custom
LocalizedString type. Localized strings allow you to provide the same content in different languages, to be used according to the user's device language setting. These strings have the required attribute
locale (of standard type
xsd:language). Here is an example:
<Title locale="en-US">Edison Kinetoscopic Record of a Sneeze</Title>
Localized strings also have an optional attribute
pronunciation (of standard type
xsd:string). This attribute is provided for Japanese catalog entries that specify string text in kanji. The expected sort order in Japanese is based on pronunciation (which cannot be determined from kanji) rather than characters. The
pronunciation attribute provides that information, typically using hiragana.
Elements Specific to the Work Type
In addition to the common elements, each work type has from one to five elements specific to that work type alone. In general, these elements have two uses: (1) to specify an original release or air date and (2) to tie works together, such as a TV episode to a TV show.
The elements that bundle shows, seasons, and episodes are required, and are discussed in more detail in the next section.
Refer to the Catalog Data Format (CDF) Schema for particulars on the type-specific elements.
Tying Shows, Seasons, and Episodes Together
TV episodes are aired during one season of a particular TV show. A mini-series is made up of individual episodes. An extra can provide a preview or behind-the-scenes information about a movie. A TV special might be related to a TV show, but be outside of that show's normal sequence.
The CDF provides elements that enable you to make those connections. When a Fire TV user browses to a TV show and sees the show organized by seasons with each episode shown sequentially in its season, that is the result of these elements.
In general, you can associate one work with another by either ID or title. An ID must match the ID of another work in your catalog. If that work is not in your catalog, you can use a title instead. The title isn't required to match anything in your catalog and is only used to group works.
The following table shows these elements for each work type:
|Work Type||Link Elements|
Rather than a title,
TvEpisode uses a number to specify a season not in your catalog and
Extra uses a link to an external ID scheme, such as IMDb. Also, while you can choose which to use, one in each element link pair is required for
MiniSeriesEpisode. The link value is optional for
Extra, which can be standalone works.
The following illustration shows how the various elements and values are matched for a TV show when using IDs.
For instance, if a
TvShow had an ID of
ShowID values in
TvSeason would also equal
TV-123456. Download the Catalog Data Format Examples to see fully implemented catalogs illustrating these concepts.
Requirements for Box Art Images (ImageUrl)
ImageUrl element, one of the optional elements common to all works, provides the URL of an image that represents the work, sometimes called the "box art." If you don't include
ImageUrl, we attempt to use art available from other sources such as IMDb, if we can make a match, or we might use a generic placeholder image.
|Type||JPG (preferred) or PNG||Other image types will not be used|
|Aspect Ratio||16 X 9||Images in your feed should follow the 16 x 9 aspect ratio.|
|Size||Height greater than 240px (480px preferred)||Images less than 480px in height generate a warning in the ingestion report, but those between 240px and 480px are accepted without counting toward the total number of invalid images. Images less than 240px in height will not be used. For optimal quality, we prefer large images (no image size is too big) that we can scale as needed.
Note: If we crop your image because of its aspect ratio, the cropped version must still meet this height requirement regardless of its original dimensions.
At a minimum, we recommend that your images meet the specifications described. Note that this refers to the box art image, not the work itself.
- Q: How do I create my catalog file?
- A: You create this file programmatically by exporting your metadata to an XML file that fits the CDF format.
- Q: I have a TV show with seasons and episodes. What content types should I use to categorize my show?
- A: Use
- Q: I have a TV show with episodes that are sequential, but that do not have seasons. What content type should I use?
- A: Use the
MiniSeriesEpisodetypes. You will need to specify values for
EpisodeInSeriesto represent the episode sequence.
- Q: I have a TV show with sequential episodes, but that don't have a sequence number. Instead of sequence number, these episodes are ordered by their air-date. Can I still use
MiniSeriesas my type? If not, which content type should I use?
- A: Use the
TvSpecialtypes. In the
TvSpecial, link it to the
ShowTitlefields, and include the mandatory air date.
- Q: I have a news-type content where the episodes do not have seasons but do have an air date. What content type should I use?
- A: Use the
TvSpecialtypes. In the
TvSpecial, link it to the
ShowTitlefields, and include the mandatory air date.
- Q: I have a show with seasons, but I do not have the actual values for the seasons. What should I do?
- A: You are required to include season values for a show with seasons, which prevents a bad user experience. To obtain season information, try looking at an authority catalog such as IMDb. Amazon usually recommends excluding season-based content that lacks season values, as opposed to trying to make the show fit into another content type. Omitting this content should help preserve a positive viewer experience for your users.
- Q: We don't have season or episode information for our series. What should I do? Should I just make up fake values?
- A: Do not provide fake
Seasonnumbers and episode numbers in your catalog. Instead, replace the
TvEpisodeentry type with
TvSpecial. Continue to map the entries (
TvSpecial) to the
TvShow, so that they are associated with one another through the
TvShow. However, note that in
OriginalAirDateis a required field. This allows us to better match (and use other sources to identify what the Season number and Episode number are) and to properly order the episodes in the
- Q: These all seem like an awful lot of rules to remember. How can I tell what to do without having to memorize every little nuance?
- A: Generally, go by what your customers would expect. For example, if you have a TV series that is a talk show that airs nightly, your customers probably will not tend to think of that series as having seasons. In this case, air date is more important. However, if you have a popular series that tends to be binge-watched by users, season and episode number will likely be much more important to that viewer base.
- Q: Ok, I've created my catalog file. Now what? Can I just upload it to AWS S3?
- A: Amazon strongly recommends validating the XML in your catalog file before uploading it to AWS S3. If your CDF contains any poorly formed or invalid XML, the file will be rejected by Amazon. See Step 2: Validate Your Catalog File for more details.
After you create your catalog file, move on to Step 2: Validate Your Catalog File.