# lenerd46/spotifyplus architecture

> Architecture diagram of the GitHub repository lenerd46/spotifyplus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lenerd46/spotifyplus
- Repository: https://github.com/lenerd46/spotifyplus

## Overview

Spotify Plus is an Xposed module that augments Spotify’s playback, lyrics, menus, and appearance while retaining Spotify’s native app as the user-facing surface. The main workflow is listening in Spotify, where hooks adapt playback and UI; for lyrics, the module parses and displays synchronized vocals, and users can open an in-app editor to create or submit sync data. The README documents additional theme, queue, timer, private-session, Last.fm, and scripting capabilities. Some feature implementations were not sampled, so those branches are documented capability links rather than inferred internal call chains.

Main entry points: [`app/src/main/java/com/lenerd46/spotifyplus/scripting/ScriptManager.java`](https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/scripting/ScriptManager.java) (Script manager), [`app/src/main/java/com/lenerd46/spotifyplus/hooks/NewContextMenuHook.java`](https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/hooks/NewContextMenuHook.java) (Context menus), [`app/src/main/java/com/lenerd46/spotifyplus/hooks/BeautifulLyricsHook.java`](https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/hooks/BeautifulLyricsHook.java) (Lyrics integration), [`app/src/main/java/com/lenerd46/spotifyplus/beautifullyrics/sync/LyricsSyncEditor.java`](https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/beautifullyrics/sync/LyricsSyncEditor.java) (Sync editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Spotify integration"]
  node_spotify["Spotify app"]
  node_hookbase["Hook framework<br/>[SpotifyHook.java]"]
  node_references["Runtime references<br/>[References.java]"]
  node_context_menu["Context menus"]
end

subgraph group_lyrics["Lyrics experience"]
  node_lyrics_hook["Lyrics integration"]
  node_lyrics_parser["Lyrics parser<br/>[LyricsParser.java]"]
  node_lyrics_data["Lyrics models"]
  node_lyrics_visual["Lyric animation"]
  node_lyrics_math["Curve interpolation"]
  node_sync_editor["Sync editor"]
  node_sync_draft["Sync draft"]
end

subgraph group_playback["Playback features"]
  node_playback_hooks["Playback hooks"]
  node_next_queue["Play Next queue<br/>[NextUpQueue.java]"]
end

subgraph group_customization["Customization"]
  node_theme_hook["Theme hooks<br/>[ThemeHook.java]"]
  node_theme_background["Animated backgrounds"]
end

subgraph group_scripting["Scripting"]
  node_scripting_manager["Script manager<br/>[ScriptManager.java]"]
  node_script_events["Script events<br/>[EventManager.java]"]
  node_script_storage["Script storage<br/>[StorageApi.java]"]
  node_script_ui["Script UI<br/>[UIManager.java]"]
end

node_listener(("Listener"))
node_lastfm["Last.fm"]

node_listener -->|"uses"| node_spotify
node_spotify -->|"enhanced by"| node_hookbase
node_hookbase -.->|"initializes"| node_lyrics_hook
node_lyrics_hook -->|"replaces lyrics"| node_spotify
node_lyrics_parser -->|"creates models"| node_lyrics_data
node_lyrics_visual -->|"uses curves"| node_lyrics_math
node_lyrics_hook -->|"opens editor"| node_sync_editor
node_sync_editor -.->|"edits draft"| node_sync_draft
node_listener -->|"syncs lyrics"| node_sync_editor
node_listener -->|"enables features"| node_playback_hooks
node_playback_hooks -->|"adds Play Next"| node_next_queue
node_listener -->|"opens menu"| node_context_menu
node_context_menu -->|"uses queue"| node_next_queue
node_context_menu -->|"opens track"| node_lastfm
node_listener -->|"customizes theme"| node_theme_hook
node_theme_hook -->|"configures"| node_theme_background
node_listener -.->|"loads scripts"| node_scripting_manager
node_scripting_manager -->|"registers events"| node_script_events
node_scripting_manager -->|"exposes API"| node_script_storage
node_scripting_manager -->|"exposes API"| node_script_ui
node_script_events -->|"gets scope"| node_scripting_manager
node_listener -.->|"runtime state"| node_references

click node_hookbase "https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/hooks/SpotifyHook.java"
click node_references "https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/References.java"
click node_lyrics_hook "https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/hooks/BeautifulLyricsHook.java"
click node_lyrics_parser "https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/beautifullyrics/entities/LyricsParser.java"
click node_lyrics_data "https://github.com/lenerd46/spotifyplus/tree/main/app/src/main/java/com/lenerd46/spotifyplus/beautifullyrics/entities/lyrics"
click node_lyrics_visual "https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/beautifullyrics/entities/interludes/InterludeVisual.java"
click node_lyrics_math "https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/beautifullyrics/curveinterpolator/AbstractCurveMapper.java"
click node_sync_editor "https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/beautifullyrics/sync/LyricsSyncEditor.java"
click node_sync_draft "https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/beautifullyrics/sync/LyricsSyncDraft.java"
click node_playback_hooks "https://github.com/lenerd46/spotifyplus/tree/main/app/src/main/java/com/lenerd46/spotifyplus/hooks"
click node_next_queue "https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/player/NextUpQueue.java"
click node_context_menu "https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/hooks/NewContextMenuHook.java"
click node_theme_hook "https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/hooks/ThemeHook.java"
click node_theme_background "https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/theme/AnimatedThemeBackground.java"
click node_scripting_manager "https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/scripting/ScriptManager.java"
click node_script_events "https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/scripting/EventManager.java"
click node_script_storage "https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/scripting/StorageApi.java"
click node_script_ui "https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/scripting/UIManager.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_spotify,node_hookbase,node_references,node_context_menu toneBlue
class node_lyrics_hook,node_lyrics_parser,node_lyrics_data,node_lyrics_visual,node_lyrics_math,node_sync_editor,node_sync_draft toneAmber
class node_playback_hooks,node_next_queue toneMint
class node_theme_hook,node_theme_background toneRose
class node_scripting_manager,node_script_events,node_script_storage,node_script_ui,node_listener,node_lastfm toneIndigo
```

## Components

### Spotify integration

- **Spotify app**
- [Hook framework](https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/hooks/SpotifyHook.java): `app/src/main/java/com/lenerd46/spotifyplus/hooks/SpotifyHook.java`
- [Runtime references](https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/References.java): `app/src/main/java/com/lenerd46/spotifyplus/References.java`
- [Context menus](https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/hooks/NewContextMenuHook.java): `app/src/main/java/com/lenerd46/spotifyplus/hooks/NewContextMenuHook.java`

### Lyrics experience

- [Lyrics integration](https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/hooks/BeautifulLyricsHook.java): `app/src/main/java/com/lenerd46/spotifyplus/hooks/BeautifulLyricsHook.java`
- [Lyrics parser](https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/beautifullyrics/entities/LyricsParser.java): `app/src/main/java/com/lenerd46/spotifyplus/beautifullyrics/entities/LyricsParser.java`
- [Lyrics models](https://github.com/lenerd46/spotifyplus/tree/main/app/src/main/java/com/lenerd46/spotifyplus/beautifullyrics/entities/lyrics): `app/src/main/java/com/lenerd46/spotifyplus/beautifullyrics/entities/lyrics`
- [Lyric animation](https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/beautifullyrics/entities/interludes/InterludeVisual.java): `app/src/main/java/com/lenerd46/spotifyplus/beautifullyrics/entities/interludes/InterludeVisual.java`
- [Curve interpolation](https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/beautifullyrics/curveinterpolator/AbstractCurveMapper.java): `app/src/main/java/com/lenerd46/spotifyplus/beautifullyrics/curveinterpolator/AbstractCurveMapper.java`
- [Sync editor](https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/beautifullyrics/sync/LyricsSyncEditor.java): `app/src/main/java/com/lenerd46/spotifyplus/beautifullyrics/sync/LyricsSyncEditor.java`
- [Sync draft](https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/beautifullyrics/sync/LyricsSyncDraft.java): `app/src/main/java/com/lenerd46/spotifyplus/beautifullyrics/sync/LyricsSyncDraft.java`

### Playback features

- [Playback hooks](https://github.com/lenerd46/spotifyplus/tree/main/app/src/main/java/com/lenerd46/spotifyplus/hooks): `app/src/main/java/com/lenerd46/spotifyplus/hooks`
- [Play Next queue](https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/player/NextUpQueue.java): `app/src/main/java/com/lenerd46/spotifyplus/player/NextUpQueue.java`

### Customization

- [Theme hooks](https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/hooks/ThemeHook.java): `app/src/main/java/com/lenerd46/spotifyplus/hooks/ThemeHook.java`
- [Animated backgrounds](https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/theme/AnimatedThemeBackground.java): `app/src/main/java/com/lenerd46/spotifyplus/theme/AnimatedThemeBackground.java`

### Scripting

- [Script manager](https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/scripting/ScriptManager.java): `app/src/main/java/com/lenerd46/spotifyplus/scripting/ScriptManager.java`
- [Script events](https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/scripting/EventManager.java): `app/src/main/java/com/lenerd46/spotifyplus/scripting/EventManager.java`
- [Script storage](https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/scripting/StorageApi.java): `app/src/main/java/com/lenerd46/spotifyplus/scripting/StorageApi.java`
- [Script UI](https://github.com/lenerd46/spotifyplus/blob/main/app/src/main/java/com/lenerd46/spotifyplus/scripting/UIManager.java): `app/src/main/java/com/lenerd46/spotifyplus/scripting/UIManager.java`

### Other components

- **Listener**
- **Last.fm**

## Connections

- Listener → Spotify app: uses
- Spotify app → Hook framework: enhanced by
- Hook framework → Lyrics integration: initializes (evidence: `app/src/main/java/com/lenerd46/spotifyplus/hooks/BeautifulLyricsHook.java`)
- Lyrics integration → Spotify app: replaces lyrics
- Lyrics parser → Lyrics models: creates models (evidence: `app/src/main/java/com/lenerd46/spotifyplus/beautifullyrics/entities/LyricsParser.java`)
- Lyric animation → Curve interpolation: uses curves (evidence: `app/src/main/java/com/lenerd46/spotifyplus/beautifullyrics/entities/interludes/InterludeVisual.java`)
- Lyrics integration → Sync editor: opens editor (evidence: `app/src/main/java/com/lenerd46/spotifyplus/hooks/BeautifulLyricsHook.java`)
- Sync editor → Sync draft: edits draft
- Listener → Sync editor: syncs lyrics
- Listener → Playback hooks: enables features
- Playback hooks → Play Next queue: adds Play Next (evidence: `app/src/main/java/com/lenerd46/spotifyplus/hooks/NewContextMenuHook.java`)
- Listener → Context menus: opens menu
- Context menus → Play Next queue: uses queue (evidence: `app/src/main/java/com/lenerd46/spotifyplus/hooks/NewContextMenuHook.java`)
- Context menus → Last.fm: opens track (evidence: `app/src/main/java/com/lenerd46/spotifyplus/hooks/NewContextMenuHook.java`)
- Listener → Theme hooks: customizes theme
- Theme hooks → Animated backgrounds: configures (evidence: `app/src/main/java/com/lenerd46/spotifyplus/theme/AnimatedThemeBackground.java`)
- Listener → Script manager: loads scripts
- Script manager → Script events: registers events (evidence: `app/src/main/java/com/lenerd46/spotifyplus/scripting/ScriptManager.java`)
- Script manager → Script storage: exposes API (evidence: `app/src/main/java/com/lenerd46/spotifyplus/scripting/ScriptManager.java`)
- Script manager → Script UI: exposes API (evidence: `app/src/main/java/com/lenerd46/spotifyplus/scripting/ScriptManager.java`)
- Script events → Script manager: gets scope (evidence: `app/src/main/java/com/lenerd46/spotifyplus/scripting/EventManager.java`)
- Listener → Runtime references: runtime state
