Skip to main content
Learn how to build SmartTube from source for development, testing, or customization.
IMPORTANT: OpenJDK 14 or older is required! Newer JDK versions could cause app crashes. Make sure you have the correct Java version before building.

​
Prerequisites

Before building SmartTube, you’ll need:
1

Install Java Development Kit

Install OpenJDK 14 or older (not newer!)
# Check your Java version
java -version
The output should show version 14 or lower.
2

Install Android SDK

Download and install Android Studio or the Android command-line tools
3

Install Git

Install Git for cloning the repository and managing submodules
4

Set up ADB (optional)

Set up Android Debug Bridge for installing builds directly to your device

​
Building SmartTube

​
Clone the Repository

Clone SmartTube with submodules: 
git clone https://github.com/yuliskov/SmartTube.git
cd SmartTube
git submodule update --init
The git submodule update --init command is essential - it pulls in required dependencies that are managed as Git submodules.

​
Build and Install

To build and install the debug version: 
# Connect to your Android TV device
adb connect <device_ip_address>

# Build and install the stable debug flavor
gradlew clean installStstableDebug
Replace <device_ip_address> with your Android TV’s IP address (found in Settings > Network). Make sure ADB debugging is enabled on your device.

​
Build Flavors

SmartTube has three product flavors, each with its own package ID:

Beta

Application ID: org.smarttube.betaLatest features and bug fixes. Recommended for most users.
gradlew installStbetaDebug

Stable

Application ID: org.smarttube.stableMore tested and stable releases.
gradlew installStstableDebug

F-Droid

Application ID: app.smarttube.fdroidF-Droid compatible build.
gradlew installStfdroidDebug

​
Build Types

Each flavor can be built in two configurations:
  • Debug: Unsigned build with debugging enabled
    • Command: gradlew install<Flavor>Debug
    • Example: gradlew installStbetaDebug
  • Release: Optimized and signed build (requires keystore)
    • Command: gradlew install<Flavor>Release
    • Example: gradlew installStbetaRelease

​
ADB Connection

Connect to your Android TV device over the network:

​
Enable ADB Debugging

1

Enable Developer Options

Go to Settings > About and click on Build repeatedly until developer mode is activated
2

Enable ADB Debugging

Go to Settings > Developer Options and enable ADB debugging and Network debugging
3

Find your device IP

Go to Settings > Network to find your device’s IP address
4

Connect via ADB

adb connect 192.168.1.100:5555
Replace with your device’s actual IP address

​
Verify Connection

# List connected devices
adb devices

# Should show something like:
# 192.168.1.100:5555    device
The first time you connect, you’ll need to accept the connection on your TV. A prompt will appear asking to allow USB debugging.

​
Development Setup

​
Open in Android Studio

  1. Launch Android Studio
  2. Click Open and select the SmartTube directory
  3. Wait for Gradle sync to complete
  4. Select your build flavor from the Build Variants panel
  • Compile SDK Version: 31 (or as specified in build.gradle)
  • Build Tools Version: As specified in build.gradle
  • Min SDK: 19 (Android 4.4 KitKat)
  • Target SDK: As specified in build.gradle

​
Architecture Information

SmartTube supports multiple CPU architectures:
  • armeabi-v7a: 32-bit ARM (most Android TV devices)
  • arm64-v8a: 64-bit ARM (newer devices, Pixel Tablet)
  • x86: 32-bit x86 (for WSL and some TV boxes)
The build generates a universal APK that includes all architectures, plus separate APKs for each architecture. The universal APK is larger but works on all supported devices.

​
Common Build Issues

​
JDK Version Error

Problem: App crashes or build fails Solution: Verify you’re using OpenJDK 14 or older 
java -version
# Should show version 14 or lower

​
Submodule Not Initialized

Problem: Build fails with missing dependencies Solution: Initialize submodules 
git submodule update --init

​
ADB Connection Failed

Problem: Can’t connect to Android TV device Solution:
  • Ensure both devices are on the same network
  • Check that ADB debugging is enabled
  • Try restarting ADB: adb kill-server && adb start-server

​
Out of Memory

Problem: Gradle build runs out of memory Solution: Increase Gradle memory in gradle.properties 
org.gradle.jvmargs=-Xmx4096m

​
Building Release APKs

To build signed release APKs:
  1. Create a keystore.properties file in the project root:
storeFile=/path/to/your/keystore.jks
storePassword=your_store_password
keyAlias=your_key_alias
keyPassword=your_key_password
  1. Build the release version:
gradlew assembleStbetaRelease
  1. Find the APK in smarttubetv/build/outputs/apk/stbeta/release/
Never commit your keystore.properties file to version control! Add it to .gitignore.

​
Additional Resources

​
Contributing Your Build

Built something interesting? See the Contributing Guide to learn how to submit your changes back to the project.

Build docs developers (and LLMs) love

Get started for freeTalk to us