# How to Add Custom SponsorBlock Categories in SmartTube

> Learn how to add custom SponsorBlock categories in SmartTube via in-app settings or by modifying the source code. Enhance your ad-skipping experience today.

- Repository: [Yuriy L/SmartTube](https://github.com/yuliskov/SmartTube)
- Tags: how-to-guide
- Published: 2026-09-14

---

**You can add custom SponsorBlock categories in SmartTube either through the in-app settings menu (which stores them in SharedPreferences under `sb_custom_categories`) or by modifying the source code to declare new constants in [`SponsorBlockCategory.kt`](https://github.com/yuliskov/SmartTube/blob/main/SponsorBlockCategory.kt) and string resources in [`strings.xml`](https://github.com/yuliskov/SmartTube/blob/main/strings.xml).**

SmartTube, the advanced Android TV client for YouTube maintained by yuliskov/SmartTube, integrates the SponsorBlock service to skip unwanted video segments. While the app ships with standard categories like sponsor, intro, and outro, the codebase supports extending these with user-defined categories that map to specific SponsorBlock API keys.

## Understanding the Category Architecture

Before adding categories, you need to understand how SmartTube structures this data across three layers: the user-facing strings, the internal API constants, and the persistence mechanism.

### String Resources for Display Names

The human-readable labels that appear in the settings menu are defined in the common module's string resources. In [`common/src/main/res/values/strings.xml`](https://github.com/yuliskov/SmartTube/blob/main/common/src/main/res/values/strings.xml), you will find entries for built-in categories:

```xml
<string name="content_block_sponsor">Sponsor</string>
<string name="content_block_intro">Intro</string>
<string name="content_block_outro">Outro</string>

```

When adding a custom category through the UI, the display name you enter is saved alongside the technical configuration.

### Category Constants in SponsorBlockCategory.kt

The internal mapping between user selections and SponsorBlock API requests lives in [`smarttubetv/src/main/java/com/smarttube/sponsorblock/SponsorBlockCategory.kt`](https://github.com/yuliskov/SmartTube/blob/main/smarttubetv/src/main/java/com/smarttube/sponsorblock/SponsorBlockCategory.kt). This file contains constants representing the official SponsorBlock segment types:

```kotlin
object SponsorBlockCategory {
    const val SPONSOR = "sponsor"
    const val INTRO = "intro"
    const val OUTRO = "outro"
    const val INTERACTION = "interaction"
    // ... additional built-in categories
}

```

When the app constructs a request to the SponsorBlock server, it uses these string constants as category parameters.

### Persistence via SponsorBlockPreferences.kt

Custom categories created at runtime are serialized and stored by [`SponsorBlockPreferences.kt`](https://github.com/yuliskov/SmartTube/blob/main/SponsorBlockPreferences.kt). The class manages a `SharedPreferences` entry under the key `sb_custom_categories`, storing a JSON array of objects containing the display name, API key, and optional color code.

## Adding Categories Through the User Interface

The simplest method requires no source code modification and works on any installed release.

1. **Navigate to Settings** → **SponsorBlock** → **Manage Categories**.
2. Select **"Add Custom Category"**.
3. Enter the **Display Name** (e.g., *Product Placement*).
4. Enter the **API Key** exactly as recognized by SponsorBlock (e.g., `product_placement` or `selfpromo`).
5. Optionally, select a **Color** for the segment indicator.
6. Tap **Save**.

The `SponsorBlockPreferences` class immediately writes this entry to `SharedPreferences` under `sb_custom_categories`. The app merges this custom list with the built-in categories defined in [`SponsorBlockCategory.kt`](https://github.com/yuliskov/SmartTube/blob/main/SponsorBlockCategory.kt) on the next video load.

## Adding Categories via Source Code Modification

If you are building SmartTube from source and want to permanently bundle new categories into the APK, modify the following files before compilation.

### Step 1: Add String Resources

Add your category's display name to [`common/src/main/res/values/strings.xml`](https://github.com/yuliskov/SmartTube/blob/main/common/src/main/res/values/strings.xml):

```xml
<string name="content_block_product_placement">Product Placement</string>
<string name="content_block_custom_segment">Custom Segment</string>

```

### Step 2: Declare the Category Constant

Open [`smarttubetv/src/main/java/com/smarttube/sponsorblock/SponsorBlockCategory.kt`](https://github.com/yuliskov/SmartTube/blob/main/smarttubetv/src/main/java/com/smarttube/sponsorblock/SponsorBlockCategory.kt) and add your new constant:

```kotlin
object SponsorBlockCategory {
    // Existing categories
    const val SPONSOR = "sponsor"
    const val INTRO = "intro"
    
    // Your custom addition
    const val PRODUCT_PLACEMENT = "product_placement"
    const val CUSTOM_SEGMENT = "custom"
}

```

### Step 3: Update the Settings UI

Modify [`SponsorBlockSettingsFragment.kt`](https://github.com/yuliskov/SmartTube/blob/main/SponsorBlockSettingsFragment.kt) (or the equivalent settings presenter) to include your new category in the default array presented to users. This ensures the checkbox appears in the category management screen without requiring manual entry.

### Step 4: Rebuild and Deploy

Compile the project using the standard Gradle build process. Your new category will now appear as a toggleable option alongside the official SponsorBlock categories.

## Summary

- **String resources** in [`common/src/main/res/values/strings.xml`](https://github.com/yuliskov/SmartTube/blob/main/common/src/main/res/values/strings.xml) control what users see in menus.
- **API constants** in [`SponsorBlockCategory.kt`](https://github.com/yuliskov/SmartTube/blob/main/SponsorBlockCategory.kt) define the keys sent to SponsorBlock servers.
- **Runtime custom categories** are stored in `SharedPreferences` via [`SponsorBlockPreferences.kt`](https://github.com/yuliskov/SmartTube/blob/main/SponsorBlockPreferences.kt) using the key `sb_custom_categories`.
- **UI workflow**: Settings → SponsorBlock → Manage Categories → Add Custom Category.
- **Code workflow**: Add strings, add constants, update UI fragments, rebuild APK.

## Frequently Asked Questions

### How are custom SponsorBlock categories stored in SmartTube?

Custom categories are serialized as JSON and stored in Android `SharedPreferences` under the key `sb_custom_categories`, managed by the `SponsorBlockPreferences` class. This allows the app to persist your custom entries between sessions without modifying the source code.

### Can I use custom SponsorBlock categories without compiling the SmartTube APK?

Yes. Use the in-app settings menu at Settings → SponsorBlock → Manage Categories → Add Custom Category. This writes directly to the app's private preferences and requires no technical expertise or source code access.

### What is the difference between the Display Name and API Key when adding a category?

The **Display Name** is the user-facing label shown in SmartTube's settings and on-screen segment indicators. The **API Key** is the exact string identifier that SponsorBlock's database uses to classify segments (e.g., `sponsor`, `selfpromo`, `music_offtopic`). The API key must match SponsorBlock's expected values to retrieve segments correctly.

### Do custom SponsorBlock categories sync across my devices?

No. Because custom categories added via the UI are stored locally in `SharedPreferences` (`sb_custom_categories`), they do not sync through any cloud service. You must manually recreate them on each device, or build a custom APK with hardcoded categories if you want consistency across multiple installations.