SuperLyric: a lyrics module for Android music apps

What SuperLyric is and how it talks to apps

SuperLyric is a lyrics getter, a module that other apps embed so they can display lyrics for whatever is playing.

The design decision the README leads with is the transport. It is a music software lyrics fetching and publishing module based on Binder data passing, and it explicitly abandons the traditional broadcast model in favour of higher-performance, lower-latency Binder cross-process capability.

That choice is the interesting part of the project. On Android, an app that wants information from another app's process usually broadcasts an intent, which any app can receive and which carries a payload with limited type support. Binder, the Android IPC primitive underneath all the system services, allows a defined interface between two processes with typed calls and lower overhead. A lyrics module that has to react to a song change the instant it happens cares about that difference: a broadcast is a fire-and-forget event with a queue and a scheduler in the way, while a Binder call is a direct request with a response.

The other half of the design is that lyric acquisition is separated from lyric publication. The module's job ends at obtaining the lyric text for the currently playing track and handing it to the host app; how the host app displays it is the host app's business.

The repository layout shows the split. There is a lyric-kernel/ directory, which is presumably the core lyric handling, and a processor/ directory, which is likely where the per-application adapters live, since each supported app needs its own way of getting at the lyric. The app/ directory holds the application itself, and build.gradle, settings.gradle and gradle.properties are the Gradle build files, with the gradlew wrapper committed so the build does not depend on a system Gradle.

The primary language is Kotlin, the licence is GPL-3.0, the default branch is master, and the recent releases are 4.1 from 2026-10-11, 3.3 from 2026-08-19 and 3.2 from 2026-06-15. The last push was on 2026-10-16, so the work is current.

There is a CLAUDE.md at the root of the repository, which suggests the project is developed with an AI coding assistant in the loop.

The three acquisition paths, and why an app lands on one of them

The supported-apps list is long, and every entry carries an acquisition method. The three methods are explained in the README, and the explanation is short enough to be worth quoting because each has a real operational consequence.

Hook 获取 means the module hooks the lyric model inside the host application. No extra setup is needed, and playback works normally. This is the path for apps where the lyric already exists as a parsed model in the app's own process, so reading it is a matter of intercepting the right call.

网络获取 means the lyrics are pulled online through the media session and the network stack, with a local cache, and the requirement is simply that the network stays up. This is the path for apps where the lyric is never materialised locally but the app's media session exposes enough metadata to identify the track, and the module looks the lyric up from a service.

Api 原生支持 means the host application integrates the SuperLyric API natively. For those apps the lyric is a first-class capability rather than something intercepted or looked up.

The current list covers Apple Music, Spotify, NetEase Cloud Music, QQ Music, Kugou and its Lite variant, Migu Music, Bodian Music, Salt Music, Flamingo and a player called 光锥音乐, with the last two on the native API path.

The three paths have quite different reliability profiles, and that is the practical fact to hold on to. A hooked app depends on the hook continuing to work when the host app updates its internals, which is the same fragility every Xposed-style module has. A network-fetched app depends on the media session exposing the track metadata and on the remote lyric service being reachable and up to date. A natively integrated app depends on the host app's developers choosing to keep it.

There is also a long list of applications in an HTML comment in the README that the maintainers have temporarily not adapted to the 4.0 unified architecture. That comment is a useful artefact, because it names roughly twenty more apps, including several that deliver lyrics over Bluetooth or to a desktop widget, and it tells you the adapter set is in flux.

Building the module and wiring it into a host app

There are no installation steps in the README, and that is not an omission so much as a statement about the shape of the project. SuperLyric is a module rather than a standalone application that a user installs and runs, so there is nothing to install before the lyrics appear.

What there is instead is a Gradle project you build and link. The repository carries build.gradle, settings.gradle and gradle.properties at the root, plus a gradle/ directory and the gradlew and gradlew.bat wrapper scripts, so the build does not depend on a Gradle installation being present on the machine.

The settings.gradle file is what tells you how the modules relate to each other, and the top-level directories give the shape: lyric-kernel/ holds the core lyric handling, processor/ holds the per-application adapters, and app/ is the application module that assembles them. A host app that wants to publish lyrics takes the kernel, supplies an adapter for the app it runs inside, and publishes through Binder.

The API counterpart is a separate repository, SuperLyricApi, The README links to it as the API project address without describing its use, so its operational shape is not something the README settles.

The first real use is therefore a test rather than an installation. Open one of the supported apps, start playback, and check whether the lyric appears. The three acquisition paths give three different symptoms when something is wrong. If a hook-path app shows no lyric, the adapter has stopped matching the host's internals. If a network-path app shows no lyric, the media session metadata may not be identifying the track, or the lyric service is unreachable, or the cache is serving an empty entry. If a natively integrated app shows no lyric, the host app's own integration is the place to look.

Distinguishing those three cases is the practical skill this module demands, and the supported-apps table is what makes it possible, because it tells you which path to expect before you start debugging.

What is not supported, and the API companion project

The unsupported section is short. YouTube Music is listed, and the README invites pull requests if you have a good adaptation method.

That single entry is worth pausing on, because YouTube Music is the app most people would want lyrics for, and the fact that it is the one exclusion tells you something about why the other apps work.

The mechanism for each supported app is either hooking the app's internal lyric model or reading its media session. For a service that streams its catalogue and does not expose per-track lyric text in a form either path can reach, neither approach applies. The exclusions are therefore a direct consequence of the design rather than an arbitrary omission, and they will follow the same logic for other streaming-first apps.

The API side lives in a separate repository, SuperLyricApi, linked from the README. The separation is natural: the module handles acquisition and publication inside a host app on a device, while the API is a separate project for host applications that want to integrate natively. The native-API apps in the list, Flamingo and 光锥音乐, are the ones that integrate the API path directly.

So the shape for an adopter has two halves. The module is a library or application component you build and install, and SuperLyricApi is a separate project for host applications that integrate the native API path.

The project declaration section is also worth reading for the terms it sets. Using the module means accepting all consequences, derivative projects carry no responsibility from this project, and any project using the code should credit the author. That is a warning about the legal exposure of hooking other people's applications rather than about licensing, since the licence itself is GPL-3.0.

The README is bilingual, with an English version at README-en.md and the Chinese one at README.md, which is the one shown here.

Reading the supported-apps table as a compatibility contract

The list of supported software is the most operationally important part of the README, and it is worth reading as a contract rather than as a feature list.

Each line pairs a package identifier with a method. The identifiers are the Android application IDs, Apple Music as com.apple.android.music, NetEase Cloud Music as com.netease.cloudmusic, QQ Music as com.tencent.qqmusic, Kugou as com.kugou.android and the Lite version as com.kugou.android.lite, Migu Music as cmccwm.mobilemusic, Bodian Music as cn.wenyu.bodian, Salt Music as com.salt.music, Spotify as com.spotify.music, and the rest as listed.

The Flamingo entry is listed as unknown, which is a small detail with a real meaning: the maintainer knows the adapter works but does not have a stable package identifier for it, so detection has to work some other way.

What the identifiers give you is precision about what the module matches against. A module that identifies its host by package name does not care what the app is called on the launcher, and it means a fork or a repackaged app under a different identifier is not covered.

The same list also encodes the failure modes. The entries on the network path are NetEase Cloud Music, the two Kugou builds and Spotify, which are the streaming services where the lyric is a remote resource. The hook path covers the rest, which are the apps that bundle or fetch lyrics and expose them internally.

One line in the list is a genuine edge case and it sits in the commented-out block: Poweramp is annotated as only being able to obtain lyrics while the software lyric interface is displayed. That is a very different constraint from the others, since it means the lyric is only present at certain moments, so a module that reads it on song change would find nothing.

The commented block also shows the intended future directions, with several entries labelled for Meizu status bar lyrics, several for Bluetooth lyrics and a couple for desktop lyrics. That is a useful signal about where the module is heading, since a host app integrating a status bar or Bluetooth lyric needs a different publication surface from one showing lyrics in its own player UI.

Where SuperLyric is the wrong choice

There are three limits, and the first is inherent to the hooking approach.

The first is that a hook-based adapter is only correct until the host app changes. When Apple Music or QQ Music updates its internals, the module may stop finding the lyric model, and the failure is silent in the sense that playback continues and only the lyrics vanish. This is the standard maintenance cost of this class of module, and it is paid per app rather than once. The commented-out block of unadapted applications in the README is a visible record of that cost.

The second is the network path's dependency on someone else's lyrics. When the module fetches over the network, the correctness of the result depends on a remote service matching the track and returning the right text, and the local cache means a stale entry can be served. For a lyric display that is usually harmless. For anything that compares lyric content, it is not.

The third is that the project asks you to accept the consequences. The declaration says using the module means accepting all consequences and that derivative projects carry no responsibility from this project. Combined with the hooking technique and the GPL-3.0 licence, that means you are taking on the question of whether hooking a music application is permitted in your jurisdiction and acceptable under that application's terms of service, separately from whether the code works.

The honest alternative depends on what you actually want. If you want lyrics for one specific app that SuperLyric does not support, the app's own lyric feature is the thing to check first, since the app may display lyrics only when it can obtain them, and a network-fetching module for the same app is what you would build. If you want lyrics as a general capability across many players, a system-level feature such as the Android media session's metadata or a dedicated lyrics service used by several players covers more apps with no hooking at all, at the cost of not working for apps that keep their lyrics internal.

For developers of a music app, the third option is the one the native API path represents: integrate SuperLyricApi directly and get lyrics as a supported capability rather than an interception, which is what the Flamingo and 光锥音乐 entries do.

What SuperLyric offers over those options is breadth with no per-app setup for the user, and a contribution model where a missing adapter is a pull request.

Editorial conclusion

Adopt SuperLyric if you use one of the listed Android music apps and want lyrics for songs the app itself does not expose, since the module has per-app adapters and the network path works without extra setup. Do not adopt it for YouTube Music, which the README lists as unsupported. Before you install, check whether the specific app you care about uses the hook path or the network path, since the network path depends on the app's media session behaviour and on a reachable lyric service.

Frequently asked questions

Official sources

1. HChenX/SuperLyric on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases