Create your Catalog File
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
- 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
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:
- 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.
- 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:
- Familiarize yourself with XML and its concepts, if you are not already comfortable working with XML.
- Download the CDF schema XSD file, which you can use as a template for your catalog file: CDF XSD file download.
- 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.
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:
||A theatrical or made-for-TV movie.|
||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|
||A sequential TV presentation, normally presented in episodes grouped by seasons|
||A single season of a TV show|
||A single episode in a single season of a TV show|
||A TV series consisting of a small number of sequential episodes|
||A single episode in a mini-series|
||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:
||The work is free to view at any time|
||The work requires a subscription to your service to view|
||The work requires a one-time payment, after which it can be viewed at any time|
||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_>
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
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
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 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.
- 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
- 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
Episodenumbers in your catalog. Instead, replace the
TvEpisodeentry 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
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.