Native Mod & Theme Plugin System

[SuperSpacer54376]

Is there an existing issue for this?

• I have searched the existing issues

A lot of Spotube users genuinely love the app and want to customize it more: visuals, layouts, small quality-of-life features, and optional panels like lyrics or stats. Right now, there’s no official way to do that. This is one of the main reasons why I cannot make the full switch right now.

What this system should enable

In plain terms, a mod system would let users and contributors:

• Add optional UI pieces (side panels, overlays, widgets)

• Customize themes beyond basic light/dark (colors, opacity, blur)

• Listen to simple player events (track change, play/pause)

• Build small, optional feature add-ons (lyrics panels, stats, queue tools)

All of this would be opt-in, sandboxed, and controlled by the user.

---

What this system intentionally avoids

• Code injection or runtime patching

• Access to private or internal Spotube APIs

• Anything related to DRM, streaming internals, or Spotify logic

• UI overrides that could destabilize the app

---

High-level idea

At a high level, mods would be small Dart-based extensions that interact with Spotube through clearly defined public APIs, running in isolated environments so they can’t crash or compromise the app.

Spotube Core
 ├── ModManager
 │    ├── Discover / load mods
 │    ├── Enable / disable
 │    └── Permission & crash handling
 │
 ├── Public Mod API
 │    ├── ThemeController
 │    ├── PlayerEvents (read-only)
 │    ├── UI Extension Slots
 │    └── Storage API
 │
 └── Flutter UI
      ├── Sidebar slot
      ├── Bottom bar slot
      ├── Overlay slot
      └── Settings slot

Mods would only interact with what’s explicitly exposed and would run in Dart isolates to keep failures contained.

---

What a mod would look like

Manifest (mod.json)

Each mod would declare what it is and what permissions it needs:

{
  "id": "glass_ui",
  "name": "Glass UI",
  "version": "1.0.0",
  "author": "Community",
  "description": "Adds glassmorphism-style visuals",
  "permissions": ["theme", "ui.overlay"],
  "entry": "main.dart"
}

Entry file (main.dart)

void main(ModContext ctx) {
  ctx.onLoad(() {
    ctx.theme.setBlur(
      enabled: true,
      radius: 20,
      opacity: 0.65,
    );
  });
ctx.player.onTrackChange((track) {

ctx.logger.info("Now playing: ${track.title}");

});

}

Everything here goes through the public API

---

Theme customization (example)

ctx.theme.apply(

ThemeExtension(

backgroundOpacity: 0.8,

surfaceOpacity: 0.6,

blurRadius: 22,

accentColor: Color(0xFF8AB4F8),

)

);

Behind the scenes, this would:

• Use Flutter’s BackdropFilter

• Automatically disable blur where unsupported

• Respect platform performance limits

---

UI extension points

Mods could add widgets only to predefined, safe locations:

• Sidebar panels

• Bottom bar widgets

• Floating overlays

• A dedicated settings tab

Mods would not be allowed to replace navigation, override core playback UI, or directly change app state.

---

Security and stability

This system is designed to fail safely:

Measure	Why it matters
Dart isolates	A crashing mod doesn’t crash the app
Permission system	Users know what a mod can access
No reflection	Internal APIs stay protected
Read-only player data	Prevents abuse
Kill-switch	Misbehaving mods can be disabled automatically

Optional future ideas could include signed mods or an official registry, but those aren’t required upfront.

---

Mod management UI

From a user perspective, mods would be managed directly in Settings:

• Enable or disable mods

• View requested permissions

• See crash or error reports per mod

• Reload mods when safe

---

Suggested rollout (incremental)

/p>

Phase 1

• Theme extensions

• Read-only player events

• Basic mod manager

Phase 2

• UI extension slots

• Overlay support

• Simple storage API

Phase 3 (optional)

• Mod registry

• Signing / verification

• Developer documentation

Thank you for taking the time to read this.

Suggested solution

If this gets approved, I can build the mod system and do a pull request.

Useful resources

No response

Additional information

No response

Self grab

• I'm ready to work on this issue!