# limczhh/hyperlyric architecture

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

- Interactive diagram: https://gitdiagram.com/limczhh/hyperlyric
- Repository: https://github.com/limczhh/hyperlyric

## Overview

HyperLyric is an Android Xposed module for adding lyrics and media-card enhancements to Xiaomi HyperOS, with a separate notification-based lyric mode. The principal flow is player lyric or metadata input → selected lyric source and shared lyric state → lyric rendering → SystemUI island presentation. The README also documents online lyric sources, AI translation, configurable island and media-card styling, gesture controls, and system-limit bypasses. Paths and calls are based on the supplied tree and excerpts; some documented subsystems were not sampled, so their internal wiring is intentionally left broad.

Main entry points: [`app/src/main/java/com/lidesheng/hyperlyric/lyric/source/SourceManager.kt`](https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/lyric/source/SourceManager.kt) (Source manager), [`app/src/main/java/com/lidesheng/hyperlyric/root/island/hooks/SystemUIHookRegistry.kt`](https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/root/island/hooks/SystemUIHookRegistry.kt) (SystemUI hooks), [`app/src/main/java/com/lidesheng/hyperlyric/common/PreferenceKeys.kt`](https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/common/PreferenceKeys.kt) (User preferences), [`app/src/main/java/com/lidesheng/hyperlyric/service/LiveLyricService.kt`](https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/service/LiveLyricService.kt) (Live lyric service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sources["Lyrics and sources"]
  node_lyricon["Lyricon provider<br/>[SourceManager.kt]"]
  node_superlyric["SuperLyric source<br/>[SourceManager.kt]"]
  node_lyricinfo["LyricInfo metadata<br/>[SourceManager.kt]"]
  node_source_manager["Source manager<br/>[SourceManager.kt]"]
  node_lyric_models["Lyric models<br/>[Song.kt]"]
  node_online_lookup["Online lyric lookup"]
  node_ai_enhancement["AI lyric enhancement"]
end

subgraph group_presentation["Island presentation"]
  node_lyric_renderer["Lyric renderer<br/>[LyricRenderer.kt]"]
  node_island_content["Island content"]
  node_island_hooks["SystemUI hooks"]
end

subgraph group_media["Media enhancements"]
  node_media_cards["Media card styling"]
  node_expanded_media["Expanded island card"]
end

subgraph group_runtime["Android runtime"]
  node_hook_entry["Hook runtime<br/>[HookEntry.kt]"]
  node_live_service["Live lyric service"]
  node_metadata_source["Media metadata source"]
  node_notification_sink["Notification lyric output"]
  node_tile["Quick settings tile"]
end

subgraph group_settings["Configuration and limits"]
  node_preferences[("User preferences<br/>[PreferenceKeys.kt]")]
  node_limit_bypass["System limit bypass"]
end

node_player(("Music player"))
node_online_services(("Lyric services"))
node_ai_service(("OpenAI-compatible API"))
node_systemui(("HyperOS SystemUI"))
node_shizuku(("Shizuku service"))

node_player -->|"provides lyrics"| node_source_manager
node_lyricon -->|"selected source"| node_source_manager
node_superlyric -->|"selected source"| node_source_manager
node_lyricinfo -->|"provides metadata"| node_source_manager
node_source_manager -->|"dispatches data"| node_lyric_models
node_online_lookup -->|"queries"| node_online_services
node_ai_enhancement -.->|"requests translation"| node_ai_service
node_lyric_models -->|"renders lyrics"| node_lyric_renderer
node_lyric_renderer -->|"supplies content"| node_island_content
node_island_hooks -->|"updates content"| node_island_content
node_hook_entry -->|"registers hooks"| node_island_hooks
node_island_hooks -->|"hooks UI"| node_systemui
node_media_cards -->|"customizes cards"| node_systemui
node_expanded_media -->|"changes layout"| node_systemui
node_player -->|"publishes metadata"| node_metadata_source
node_metadata_source -->|"emits updates"| node_live_service
node_live_service -->|"updates notifications"| node_notification_sink
node_preferences -->|"selects source"| node_source_manager
node_preferences -->|"configures styling"| node_media_cards
node_limit_bypass -->|"alters restrictions"| node_systemui
node_limit_bypass -.->|"requests privileges"| node_shizuku
node_tile -->|"toggles listening"| node_preferences
node_tile -->|"rebinds service"| node_live_service

click node_lyricon "https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/lyric/source/SourceManager.kt"
click node_superlyric "https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/lyric/source/SourceManager.kt"
click node_lyricinfo "https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/lyric/source/SourceManager.kt"
click node_source_manager "https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/lyric/source/SourceManager.kt"
click node_lyric_models "https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/lyric/model/Song.kt"
click node_online_lookup "https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/online/LyricApiProvider.kt"
click node_ai_enhancement "https://github.com/limczhh/hyperlyric/tree/main/app/src/main/java/com/lidesheng/hyperlyric/root/lyricenhancement"
click node_lyric_renderer "https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/root/island/renderer/LyricRenderer.kt"
click node_island_content "https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/root/island/content/IslandSlotContentFacade.kt"
click node_island_hooks "https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/root/island/hooks/SystemUIHookRegistry.kt"
click node_media_cards "https://github.com/limczhh/hyperlyric/tree/main/app/src/main/java/com/lidesheng/hyperlyric/root/mediacard"
click node_expanded_media "https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/root/mediacard/island/IslandExpandedMediaElementController.kt"
click node_hook_entry "https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/root/HookEntry.kt"
click node_live_service "https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/service/LiveLyricService.kt"
click node_metadata_source "https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/service/LiveLyricService.kt"
click node_notification_sink "https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/service/LiveLyricService.kt"
click node_preferences "https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/common/PreferenceKeys.kt"
click node_limit_bypass "https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/root/UnlockFocusWhitelist.kt"
click node_tile "https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/service/LyricTileService.kt"

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_lyricon,node_superlyric,node_lyricinfo,node_source_manager,node_lyric_models,node_online_lookup,node_ai_enhancement,node_systemui toneBlue
class node_lyric_renderer,node_island_content,node_island_hooks toneAmber
class node_media_cards,node_expanded_media,node_ai_service toneMint
class node_hook_entry,node_live_service,node_metadata_source,node_notification_sink,node_tile toneRose
class node_preferences,node_limit_bypass,node_player,node_online_services,node_shizuku toneIndigo
```

## Components

### Lyrics and sources

- [Lyricon provider](https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/lyric/source/SourceManager.kt): `app/src/main/java/com/lidesheng/hyperlyric/lyric/source/SourceManager.kt`
- [SuperLyric source](https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/lyric/source/SourceManager.kt): `app/src/main/java/com/lidesheng/hyperlyric/lyric/source/SourceManager.kt`
- [LyricInfo metadata](https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/lyric/source/SourceManager.kt): `app/src/main/java/com/lidesheng/hyperlyric/lyric/source/SourceManager.kt`
- [Source manager](https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/lyric/source/SourceManager.kt): `app/src/main/java/com/lidesheng/hyperlyric/lyric/source/SourceManager.kt`
- [Lyric models](https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/lyric/model/Song.kt): `app/src/main/java/com/lidesheng/hyperlyric/lyric/model/Song.kt`
- [Online lyric lookup](https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/online/LyricApiProvider.kt): `app/src/main/java/com/lidesheng/hyperlyric/online/LyricApiProvider.kt`
- [AI lyric enhancement](https://github.com/limczhh/hyperlyric/tree/main/app/src/main/java/com/lidesheng/hyperlyric/root/lyricenhancement): `app/src/main/java/com/lidesheng/hyperlyric/root/lyricenhancement`

### Island presentation

- [Lyric renderer](https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/root/island/renderer/LyricRenderer.kt): `app/src/main/java/com/lidesheng/hyperlyric/root/island/renderer/LyricRenderer.kt`
- [Island content](https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/root/island/content/IslandSlotContentFacade.kt): `app/src/main/java/com/lidesheng/hyperlyric/root/island/content/IslandSlotContentFacade.kt`
- [SystemUI hooks](https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/root/island/hooks/SystemUIHookRegistry.kt): `app/src/main/java/com/lidesheng/hyperlyric/root/island/hooks/SystemUIHookRegistry.kt`

### Media enhancements

- [Media card styling](https://github.com/limczhh/hyperlyric/tree/main/app/src/main/java/com/lidesheng/hyperlyric/root/mediacard): `app/src/main/java/com/lidesheng/hyperlyric/root/mediacard`
- [Expanded island card](https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/root/mediacard/island/IslandExpandedMediaElementController.kt): `app/src/main/java/com/lidesheng/hyperlyric/root/mediacard/island/IslandExpandedMediaElementController.kt`

### Android runtime

- [Hook runtime](https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/root/HookEntry.kt): `app/src/main/java/com/lidesheng/hyperlyric/root/HookEntry.kt`
- [Live lyric service](https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/service/LiveLyricService.kt): `app/src/main/java/com/lidesheng/hyperlyric/service/LiveLyricService.kt`
- [Media metadata source](https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/service/LiveLyricService.kt): `app/src/main/java/com/lidesheng/hyperlyric/service/LiveLyricService.kt`
- [Notification lyric output](https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/service/LiveLyricService.kt): `app/src/main/java/com/lidesheng/hyperlyric/service/LiveLyricService.kt`
- [Quick settings tile](https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/service/LyricTileService.kt): `app/src/main/java/com/lidesheng/hyperlyric/service/LyricTileService.kt`

### Configuration and limits

- [User preferences](https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/common/PreferenceKeys.kt): `app/src/main/java/com/lidesheng/hyperlyric/common/PreferenceKeys.kt`
- [System limit bypass](https://github.com/limczhh/hyperlyric/blob/main/app/src/main/java/com/lidesheng/hyperlyric/root/UnlockFocusWhitelist.kt): `app/src/main/java/com/lidesheng/hyperlyric/root/UnlockFocusWhitelist.kt`

### Other components

- **Music player**
- **Lyric services**
- **OpenAI-compatible API**
- **HyperOS SystemUI**
- **Shizuku service**

## Connections

- Music player → Source manager: provides lyrics
- Lyricon provider → Source manager: selected source
- SuperLyric source → Source manager: selected source
- LyricInfo metadata → Source manager: provides metadata
- Source manager → Lyric models: dispatches data
- Online lyric lookup → Lyric services: queries
- AI lyric enhancement → OpenAI-compatible API: requests translation
- Lyric models → Lyric renderer: renders lyrics
- Lyric renderer → Island content: supplies content
- SystemUI hooks → Island content: updates content
- Hook runtime → SystemUI hooks: registers hooks
- SystemUI hooks → HyperOS SystemUI: hooks UI
- Media card styling → HyperOS SystemUI: customizes cards
- Expanded island card → HyperOS SystemUI: changes layout
- Music player → Media metadata source: publishes metadata
- Media metadata source → Live lyric service: emits updates
- Live lyric service → Notification lyric output: updates notifications
- User preferences → Source manager: selects source
- User preferences → Media card styling: configures styling
- System limit bypass → HyperOS SystemUI: alters restrictions
- System limit bypass → Shizuku service: requests privileges
- Quick settings tile → User preferences: toggles listening
- Quick settings tile → Live lyric service: rebinds service