Customize the reference TV app

Live TV is a reference TV app designed for Android television devices. However, device manufacturers may want to add more product-specific functions, which are not covered by the default implementation of Live TV, such as picture adjustment, game mode, or 3D mode. To support these device-specific functions or options, Live TV supports these customizations:

• Enabling time-shifting mode, which allows users to pause, fast forward, and rewind. Configuring time-shifting mode to use external storage instead of internal storage.
• Adding options to the TV options row.
• Adding a custom row and adding options in it.

Note: Live Channels is Google's implementation of Live TV that can be used as is on devices with Google services. To customize Live Channels, replace com.android.tv.* with com.google.android.tv.* in these instructions.

Customize Live TV

To customize Live TV, the target Android TV device needs a customization package installed, which must be a prebuilt system app with the com.android.tv.permission.CUSTOMIZE_TV_APP permission.

Live TV searches for a system package with this permission, checks the resource files, and detects the package's Activities marked with specific categories to process customization.

Key point: Only one package can customize Live TV.

Configure time-shifting mode

Time-shifting (trickplay) allows Android television devices to pause, rewind, and fast forward channel playback. In the Live TV implementation, time-shifting can be used via the Play controls UI. Time-shifting is enabled by default in Live TV, but can be disabled. Time-shifting can also be configured to use external storage only.

To configure time-shifting, add the string resource trickplay_mode and set its value to one of these options:

• enabled: Enable time-shifting. This is the default value when no options are given.
• disabled: Disable time-shifting.
• use_external_storage_only: Configure time-shifting to use external storage.

<string name="trickplay_mode">use_external_storage_only</string>

Figure 1. Play controls UI is activated after pressing the D-pad center button.

Customize TV options

Device manufacturers can add custom options for Live TV settings to the existing TV options menu, such as adding a shortcut to the Sound Picture settings.

To indicate a custom option, declare an intent-filter that filters the category com.android.tv.category.OPTIONS_ROW in an activity. The custom feature is implemented by the device manufacturer in the activity. The activity launches if the option is clicked. The activity's title and icon are used for the option. Customized TV options should match the existing UI to provide the best user experience.

Note: An activity can only handle one option because Live TV cannot differentiate intent-filters in an activity with the same category due to the Android limitation. See Handle multiple options in an activity for a workaround.

Device manufacturers can also place a custom option before or after the existing options by defining android:priority in AndroidManifest.xml. An option with a defined priority value lower than 100 shows before the existing items and a value higher than 100 shows after. Multiple custom options (either before or after existing options) are sorted by their priority in ascending order. If options have the same priority, order among them is undefined.

In this example, the option appears first in the TV options row, and PictureSettingsActivity launches if the option is clicked.

<activity android:name=".PictureSettingsActivity"
    android:label="@string/activity_label_picture_settings"
          android:theme="@style/Theme.Panel">
    <intent-filter
        android:icon="@drawable/ic_tvoptions_brightness"
        android:label="@string/option_label_brightness"
        android:priority="0">
        <action android:name="android.intent.action.MAIN" />
        <category android:name="com.android.tv.category.OPTIONS_ROW" />
    </intent-filter>
</activity>

Figure 2. Sample customized TV options row (Brightness and Energy Saving).

Figure 3. Sample custom TV options.

Handle multiple options in an activity

An option maps to an activity's intent-filter and vice-versa. Because Android doesn't differentiate intent-filters with the same categories and actions, an activity only handles one option, even if multiple intent-filters are declared in it. To handle multiple options in an activity, use <activity-alias> in AndroidManifest.xml. In the activity, use getIntent().getComponent() to identify the clicked option.

<activity-alias android:name=".AnyUniqueName"
    android:targetActivity=".PictureSettingsActivity">
    <intent-filter
        android:icon="@drawable/ic_tvoptions_energy_saving"
        android:label="@string/option_label_energy_saving"
        android:priority="1">
        <action android:name="android.intent.action.MAIN" />
        <category android:name="com.android.tv.category.OPTIONS_ROW" />
    </intent-filter>
</activity-alias>

Create a custom row

Device manufacturers can add and customize a row above the TV options row. This custom row is optional.

Row title

Define a partner_row_title string in res/values/strings.xml. The string's value is used for the custom row title.

<string name="partner_row_title">Partner Row</string>

Custom options

To add custom options to the custom row, follow the process for adding options to the TV options menu, but change the category name to com.android.tv.category.PARTNER_ROW instead.

<activity android:name=".ThreeDimensionalSettingDialogActivity"
    android:label="@string/activity_label_3d"
    android:theme="@android:style/Theme.Material.Light.Dialog">
    <intent-filter
        android:icon="@drawable/ic_tvoptions_3d"
        android:priority="0">
        <action android:name="android.intent.action.MAIN" />
        <category android:name="com.android.tv.category.PARTNER_ROW" />
    </intent-filter>
</activity>

Figure 4. Sample optional custom row.

Figure 5. Sample custom option dialog.