Developer Console
Sign In
Sign In
Developer Console

Step 6 - Optional: Integrate Linear TV Data

 Catalog Ingestion

STEP 1:
Create your Catalog File
→
STEP 2:
Validate Your Catalog File
→
STEP 3:
Set Up Your AWS Account
→
STEP 4:
Upload Your Catalog File to Amazon
→
STEP 5:
Verify Your Uploaded Catalog File
→
STEP 6:
Optional: Integrate Linear TV Data
→
STEP 7:
Update your Catalog at Regular Intervals
 
Optional:
Use Page Collation

If you want your content to be more visible across the Live and Search tabs, and reduce the amount of data you send to individual customer devices, you can provide your programs, schedules, and stations to Amazon through catalog ingestion. With linear catalog ingestion, you can send a single metadata file and have it automatically sent to all customer devices with a lower latency than a Gracenote-based server integration.

If you already ingest a video-on-demand (VOD) catalog with Amazon through catalog ingestion, adding linear TV data is similar. The XML format has a similar structure but contains additional data like schedules and programs to surface content in the UI.

Considerations for adding a linear TV catalog:

  • Linear data integration is optional.
  • Although the file format complements the existing VOD format, there are additional steps to upload linear TV data. If you already have a catalog for VOD content, you must still create a separate catalog for linear TV.

 

Step 1: Prepare your linear catalog file

Preparing a linear catalog is similar to creating a VOD catalog file. The main differences are the additional elements unique to linear television.

  • Stations (Required): Corresponds to the channels you insert into Android's TV database that appear in the electronic program guide (EPG). Stations should contain a title, a time zone, and the following images:
    • stationCover: A JPEG or PNG with 16:9 aspect ratio and minimum resolution of 1920 x 1080px. The image contains station branding that is shown as a fallback when content-specific imagery is not provided.
    • stationHB: A PNG with 1:1 aspect ratio and a minimum resolution of 400 x 400px. Image has a transparent background and light-color station branding meant for darker backgrounds.
  • Lineups (Required): Scopes your station to a specific country. You must declare a lineup with a region to make sure your data shows only in the countries they are meant to show in.
  • Broadcasts (Required): Connects the stations with the lineups, allowing Amazon to determine what countries your stations should appear in.
  • Schedules (Required): Connects the Movie and Episode data you are providing in your linear catalog file with the station. This information appears in the EPG.
  • Movies, Episodes, and Seasons (Required): The core metadata that Fire TV displays in the EPG and elsewhere in Live and Search. Titling, descriptions, content ratings, and images are all included in this part of the catalog.

For more details, see Step 1: Create Your Catalog File.

Step 2: Validate your catalog file

After you create your catalog file, you must make sure that it is well-formed XML and validates against the CDF schema. An incorrectly formatted or invalid catalog file will be rejected by the catalog ingestion service. Validating your file locally can help catch errors that would prevent the file from being successfully ingested.

For more about validation, see Tools to Validate Your Catalog File.

Step 3: Set up your AWS account for linear catalog ingestion

Catalog ingestion uses Amazon Web Services (AWS) tools to upload your catalog and manage the users who have access to the tool used to store your catalog. Before uploading your catalog file, you must set up your AWS account and exchange account information with your Amazon representative.

Your Amazon representative creates your folder for linear catalog ingestion and provides you with access to your AWS S3 bucket. Because Amazon creates the S3 bucket, the bucket doesn't appear in your AWS S3 console. However, you can access the folder using the Command Line Interface (CLI), where you can view the folder's contents and upload files to the folder. The commands you can use to interact with your S3 folder are given in the next sections.

If you don't yet have an AWS account, follow the instructions in Step A: Sign In or Sign Up for an AWS Account (New AWS Users Only).

Step 4: Upload your linear catalog to Amazon

Upload your catalogs to the folder that your Amazon representative has given you, such as sample_application/.

Type the following command, substituting your catalog file name for <catalog_file_name.xml> and S3 folder name for <s3_folder_name>. The --acl bucket-owner-full-control option is required so that Amazon can read the file that you upload and ingest your catalog.

$ aws s3api put-object --body <catalog_file_name.xml> --bucket cdf2-amazon-firetv --key <s3_folder_name>/catalog.xml --region us-east-1 --acl bucket-owner-full-control

This command successfully uploads files up to 2 GB in size. If successful, the AWS CLI displays a set of tags for the VersionID, ETag, and Expiration for the file.

You receive an email after the catalog has ingested.

Step 5: Connect your app with your linear catalog

Now that you've successfully sent your linear catalog to Amazon, it's time to connect your app with the stations that you declared in your catalog file.

The external ID type that the following code refers to is the S3 folder name from steps 3 and 4 in the previous sections. For example, if your Amazon representative assigns you a folder named sample_application, your external ID type would be "sample_application".

The external ID value that the following code refers to corresponds to the ID of the station you sent in your linear catalog file. For example, if you declared a station with an ID of abc123, then the external ID value is "abc123".

Example code

/**
 * Variable to store the type of external ID, which is used for the matching service metadata. Valid types are
 * defined below as constants with prefix "EXTERNAL_ID_TYPE_"
 * Null or invalid data will result in failed service match of metadata
 */
private final static String EXTERNAL_ID_TYPE = "externalIdType";

/**
 * Variable to store the value of external ID, which is used for the matching service metadata.
 * Null or invalid data will result in failed service match of metadata
 */
private final static String EXTERNAL_ID_VALUE = "externalIdValue";

public void fillStationId(ContentValues values) {
   try {
        String jsonString = new JSONObject()
            .put(EXTERNAL_ID_TYPE, "#Actual Id Type#") // replace with unique namespace of your Amazon catalog e.g., "test_cdf2"
            .put(EXTERNAL_ID_VALUE, "#Actual Id Value#") // replace with unique CDF Station ID associated with channel e.g., "station-001", "station-child-001", "station-002", "station-child-002", "station-003", "station-child-003"
            .toString();
    
        // Add JSON string into the Channel contentValues 
        values.put(TvContract.Channels.COLUMN_INTERNAL_PROVIDER_DATA, jsonString.getBytes());
    } catch (JSONException e) {
        Log.e(TAG, "Error when adding data to blob " + e);
    }
}

public fun fillStationId(values: ContentValues) {
    try {
       val jsonString =  JSONObject()
        .put(
            EXTERNAL_ID_TYPE,
            "#Actual Id Type#"
        ) // replace with unique namespace of your Amazon catalog e.g., "test_cdf2"
        .put(
            EXTERNAL_ID_VALUE,
            "#Actual Id Value#"
        ) // replace with unique CDF Station ID associated with channel e.g., "station-001", "station-child-001", "station-002", "station-child-002", "station-003", "station-child-003"
        .toString()
    
        // Add JSON string into the Channel contentValues 
        values.put(TvContract.Channels.COLUMN_INTERNAL_PROVIDER_DATA, jsonString.toByteArray())
    } catch (JSONException e) {
        Log.e(TAG, "Error when adding data to blob " + e)
    }
}

companion object {
    /**
    * Variable to store the type of external ID, which is used for the matching service metadata. Valid types are
    * defined below as constants with prefix "EXTERNAL_ID_TYPE_"
    * Null or invalid data will result in failed service match of metadata
    */
    private const val EXTERNAL_ID_TYPE: String = "externalIdType"
    
    /**
    * Variable to store the value of external ID, which is used for the matching service metadata.
    * Null or invalid data will result in failed service match of metadata
    */
    private const val EXTERNAL_ID_VALUE: String = "externalIdValue"
}

For more details, see Insert CDF Station ID.

Next steps

After you follow these steps, you should be able to see your channel. Follow the instructions in Checkpoint: Display One Channel on Fire TV's UI.

Last updated: May 05, 2025