SmartTube Leanback UI Customization: A Complete Guide for Android TV Developers

You can fully customize SmartTube's Android TV interface by modifying theme resources in styles.xml, extending the LeanbackActivity base class, and overriding Leanback library attributes such as imageCardViewStyle and primaryColor.

SmartTube builds its 10-foot user interface on the Android Leanback support library, providing a TV-optimized experience through the yuliskov/SmartTube repository. The architecture relies on a centralized theming system where XML resources and Java base classes work together to render browsing, playback, and guided-step screens. Mastering SmartTube Leanback UI customization requires understanding how LeanbackActivity orchestrates background managers, adapters, and theme attributes across the application.

Core Architecture and Base Classes

The LeanbackActivity Foundation

At the heart of every screen lies LeanbackActivity.java, located in smarttubetv/src/main/java/com/liskovsoft/smartyoutubetv2/tv/ui/common/LeanbackActivity.java. This abstract base class initializes essential Leanback components including the BackgroundManager for wallpaper switching and the LeanbackPlayerAdapter for media controls.

Any activity extending this class automatically inherits the default Leanback theming structure. For example, PlaybackActivity, SearchTagsActivity, and WebBrowserActivity all derive from LeanbackActivity, ensuring consistent navigation patterns and visual styling across the app.

Theme Inheritance and Color Palettes

SmartTube defines its visual identity through a hierarchy of XML themes extending standard Leanback parents. The core themes include:

• App.Theme.Leanback.Player – Controls the playback overlay UI
• App.Theme.Leanback.Browse – Governs the content browsing grids and headers
• App.Theme.Leanback.GuidedStep – Styles the wizard-like configuration screens

Specific color variants such as Blue, Red, DarkGrey, and OLED inherit from these base themes and override attributes like background, primaryColor, and preferenceTheme to create distinct visual modes.

Customizing Visual Styles

Modifying Color Schemes in styles.xml

To change the global color palette, edit smarttubetv/src/main/res/values/styles.xml. Locate the theme definition you wish to modify—such as App.Theme.Leanback.Blue—and override the color attributes:

<style name="App.Theme.Leanback.Blue" parent="Theme.Leanback.Browse">
    <item name="primaryColor">@color/teal_200</item>
    <item name="background">@color/teal_900</item>
    <item name="preferenceTheme">@style/App.Preference.Theme</item>
</style>

These changes propagate immediately to all fragments because the LeanbackActivity inflates views using these theme resources at runtime.

Creating Custom Card Layouts

Video cards, tag cards, and loading cards obtain their styling from LeanbackTheme attributes. The system retrieves the active style programmatically using the TypedArray pattern found in VideoCardView.java:

TypedArray a = context.obtainStyledAttributes(R.styleable.LeanbackTheme);
int styleRes = a.getResourceId(R.styleable.LeanbackTheme_imageCardViewStyle, 0);
a.recycle();

To apply a custom card appearance, define a new style in smarttubetv/src/main/res/values/themes.xml (or themes_old.xml) and reference it in your main theme:

<style name="Widget.Custom.VideoCard" parent="Widget.Leanback.ImageCardView">
    <item name="cardBackgroundColor">@color/dark_gray</item>
    <item name="titleTextAppearance">@style/TextAppearance.Custom.CardTitle</item>
</style>

<style name="App.Theme.Leanback.Browse">
    <item name="leanbackTheme_imageCardViewStyle">@style/Widget.Custom.VideoCard</item>
</style>

For granular layout control, modify the XML files in smarttubetv/src/main/res/layout/, such as text_badge_image_view.xml, which defines how text badges render on image cards using TextAppearance.Leanback.ImageCardView.Content.

Runtime UI Modifications

Switching Themes Programmatically

SmartTube supports dynamic theme changes without recompiling the application. To switch themes at runtime based on user preferences, call setTheme() before recreate():

public void switchToDarkTheme() {
    setTheme(R.style.App_Theme_Leanback_OLED_Browse);
    recreate(); // Forces Activity reload with new resources
}

This pattern works because LeanbackActivity re-inflates all UI components using the newly set theme resources, including the GuidedStepFragment styles defined in layouts like guidedstep_second_guidance.xml.

Customizing Playback Components

The playback interface relies on PlaybackFragment.java located in smarttubetv/src/main/java/com/liskovsoft/smartyoutubetv2/tv/ui/playback/. To override subtitle rendering or control positioning, access the view hierarchy after the fragment creates its Leanback player adapter:

// In PlaybackFragment.java
mLeanbackSubtitles = root.findViewById(R.id.my_custom_subtitles);

You can also customize the guided-step icons by modifying the Widget.Example.Leanback.*GuidanceIconStyle styles referenced in guidedstep_second_guidance.xml and related layout files.

Key Files for UI Customization

Understanding the location of critical resources accelerates the customization workflow:

• LeanbackActivity.java – Base activity supplying BackgroundManager and LeanbackPlayerAdapter
• styles.xml – Primary theme definitions and color palette variants
• themes_old.xml – Custom widget styles for titles, rows, and guidance icons
• VideoCardView.java – Card view implementation that consumes LeanbackTheme attributes
• PlaybackFragment.java – Playback UI integration point for subtitles and controls
• guidedstep_second_guidance.xml – Layout template for guided-step icon styling
• text_badge_image_view.xml – Badge text appearance configuration

Summary

• SmartTube implements its Android TV interface through the Leanback library, centered around the LeanbackActivity base class located in smarttubetv/src/main/java/com/liskovsoft/smartyoutubetv2/tv/ui/common/LeanbackActivity.java.
• Visual customization occurs primarily in smarttubetv/src/main/res/values/styles.xml by overriding theme attributes like primaryColor and background.
• Card appearances are controlled through LeanbackTheme attributes such as imageCardViewStyle, which are resolved at runtime via TypedArray lookups.
• Runtime theme switching is achieved by calling setTheme() followed by recreate() in activities extending LeanbackActivity.
• Playback components can be modified through PlaybackFragment.java and associated layout files for subtitles and control overlays.

Frequently Asked Questions

How does SmartTube implement the Leanback library for Android TV?

SmartTube extends the Android Support Leanback library through the LeanbackActivity base class, which provides essential infrastructure including BackgroundManager for wallpaper handling, LeanbackPlayerAdapter for media playback controls, and standardized fragment management for browsing and guided steps. This architecture ensures all TV-specific activities share consistent navigation and theming behavior.

Where are the color themes defined in the SmartTube source code?

Color themes are defined in smarttubetv/src/main/res/values/styles.xml, where variants like App.Theme.Leanback.Blue, App.Theme.Leanback.Red, and App.Theme.Leanback.OLED extend Theme.Leanback.Browse or related parents. These definitions override specific attributes such as primaryColor and background to create distinct visual schemes that apply across the entire application interface.

Can I change the UI theme while the app is running on an Android TV device?

Yes, SmartTube supports runtime theme switching programmatically. By calling setTheme(R.style.App_Theme_Leanback_OLED_Browse) followed by recreate() within any activity extending LeanbackActivity, the application reloads with the new resource set. This pattern allows users to switch between light, dark, and OLED modes without requiring an application restart.

How do I customize the appearance of video cards in the SmartTube browse interface?

Video card styling is controlled through the leanbackTheme_imageCardViewStyle attribute. Define a custom style extending Widget.Leanback.ImageCardView in your theme resources, then reference it in your main theme. The VideoCardView class retrieves this style at initialization using context.obtainStyledAttributes(R.styleable.LeanbackTheme), ensuring all cards render with your custom background colors, typography, and badges.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}