Gracias por tu visita. Esta página solo está disponible en inglés.

Step 1: Create Your Catalog File

In this step, you will need to 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.

Options for Creating Your Catalog File

You have two options for creating your catalog file:

  • Automated: Use an automated process to create the file by exporting your data from a database; then transform that data to a CDF-compliant catalog file.
  • Manual: Manually create the catalog file.

Creating the Catalog file via Exporting and Transforming Your Data

Most apps that integrate with Fire TV will be able to use an automated process to create the catalog file for the app's catalog data.

To use an automated process to create your catalog file:

  1. Export your metadata from your app's database. If necessary, ask a database administrator or support person within your org for help exporting the data. The fields that you export should be roughly equivalent to those defined by the Catalog Data Format Schema Reference.
  2. Write an XSLT transform to copy the exported data into an XML file that conforms to the Catalog Data Format Schema Reference. Ask a developer for help, if necessary.

Manually Creating your Catalog file

If your content catalog's metadata is not stored in a database, or if for any reason, you cannot export and transform that data to an XML file, you will need to manually create your catalog file.

To manually create your catalog file:

  1. Familiarize yourself with XML and its concepts, if you are not already comfortable working with XML.
  2. Download the CDF schema XSD file, which you can use as a template for your catalog file: CDF XSD file download.
  3. Consulting the CDF documentation and using an XML editor (many are available for download from various sources), compose the catalog file for your app's catalog data.

An Example Catalog File

The following example shows a simple catalog file that contains only one item (a movie), and uses only required elements. We strongly recommend that you provide more details about each work than this, but this limited example is useful in showing the most basic catalog file structure. Download the cdf-examples.zip file for larger and more comprehensive examples.

<?xml version="1.0" encoding="utf-8" ?>
    <Catalog xmlns="http://www.amazon.com/FireTv/2014-04-11/ingestion" version="FireTv-v1.3">
        <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>
        <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.

The 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 available work type elements are:

Element Description
Movie A theatrical or made-for-TV movie.
TvSpecial A standalone TV show, which can be a special event or a show associated with a series but not part of its normal sequence of episodes
TvShow A sequential TV presentation, normally presented in episodes grouped by seasons
TvSeason A single season of a TV show
TvEpisode A single episode in a single season of a TV show
MiniSeries A TV series consisting of a small number of sequential episodes
MiniSeriesEpisode A single episode in a mini-series
Extra A clip or trailer, often related to another work

Movies are stand-alone elements. TV shows, seasons, and 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, by rental or purchase, 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:

Offer Type Description
FreeOffer The work is free to view at any time
SubscriptionOffer The work requires a subscription to your service to view
PurchaseOffer The work requires a one-time payment, after which it can be viewed at any time
RentalOffer The work requires a one-time payment and can be viewed for only a limited time after that

The outline of an offer, including optional elements, can be represented as:

<_OfferType_> (such as <FreeOffer> or <PurchaseOffer>)
    <Regions>
        <WindowStart>
            <WindowEnd>
                <LaunchDetails>
                    <Price> (rental or purchase only)
                        <Duration> (rental only)
</_OfferType_>

Regions (required) specifies the countries in which this offer is valid. Regions is required and must contain at least one Country.

WindowStart and WindowEnd (both optional) can be used together or separately to specify the time when this offer is valid. Before WindowStart and after WindowsEnd, the offer is not shown to the user.

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.

Price is the cost to rent or buy the work, and is required for RentalOffer and PurchaseOffer. It can be specified in one of four currencies: US dollar, British pound, Japanese yen, and euro.

Duration is the number of hours that a rental lasts, and is required for RentalOffer.

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.

Release dates are optional but recommended, and are specified by either a ReleaseDate (for movies, TV shows, or mini-series) or OriginalAirDate (for TV and mini-series episodes, and TV specials).

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
TvEpisode ShowID or ShowTitle
SeasonID or SeasonInShow
Note: TvEpisode also has a SeasonTitle element, but it is not used for grouping.
TvSeason ShowID</a> or ShowTitle</a>
TvShow None
TvSpecial ShowID or ShowTitle
MiniSeries None
MiniSeriesEpisode MiniSeriesID or MiniSeriesTitle
Extra RelatesToID or RelatesToExternalID
Movie None

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 TvEpisode, TvSeason, and MiniSeriesEpisode. The link value is optional for TvSpecial and 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.

Diagram showing the relations between the IDs of TV shows, seasons, episodes, and specials

For instance, if a TvShow had an ID of TV-123456, the ShowID values in TvEpisode and 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)

The 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.

Image requirements

Requirement Image Description
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 240 px (480 px preferred) Images less than 480 px in height generate a warning in the ingestion report, but those between 240 px and 480 px are accepted without counting toward the total number of invalid images. Images less than 240 px 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.

CDF FAQ

Q: How do I create my catalog file?
A: Ideally, you would 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 TVShow, TVSeason, and TVEpisode.
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 MiniSeries and MiniSeriesEpisode types. You will need to specify values for EpisodeInSeries to 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 MiniSeries as my type? If not, which content type should I use?
A: Use the TVShow and TVSpecial types. In the TVSpecial, link it to the TVShow using the ShowID or ShowTitle fields, 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 TVShow and TVSpecial types. In the TVSpecial, link it to the TVShow using the ShowID or ShowTitle fields, 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 Season numbers and Episode numbers in your catalog. Instead, replace the TvEpisode entry type with TvSpecial. Continue to map the entries (TvSpecials) to the TVShow, so that they are associated with one another through the TvShow. However, note that in TvSpecials, OriginalAirDate is 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 TvShow.
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.

Next Steps

After you create your catalog file, move on to Step 2: Validate Your Catalog File.