What causes "状态栏歌词开启失败，请到手机系统设置打开悬浮窗权限" in maotoumao/MusicFree?

Guide the user to Settings → Apps → this app → 'Display over other apps' and enable it, then re-enable status bar lyric.

maotoumao/MusicFree · warning

状态栏歌词开启失败，请到手机系统设置打开悬浮窗权限

Error message

状态栏歌词开启失败，请到手机系统设置打开悬浮窗权限

What it means

showStatusBarLyric in src/native/lyricUtil/index.ts wraps the native call: when originalShowStatusBarLyric rejects, it logs, shows a warning toast telling the user to enable the floating-window (悬浮窗) permission in system settings, and auto-disables lyric.showStatusBarLyric in config. The thrown native error is about Android's overlay permission being missing.

Source

Thrown at src/native/lyricUtil/index.ts:59

    /** 检查权限 */
    checkSystemAlertPermission: () => Promise<boolean>;
    /** 请求悬浮窗 */
    requestSystemAlertPermission: () => Promise<boolean>;
}

const LyricUtil: ILyricUtil = NativeModules.LyricUtil;

const originalShowStatusBarLyric = LyricUtil.showStatusBarLyric;

const showStatusBarLyric: ILyricUtil["showStatusBarLyric"] = async (
    initLyric,
    config,
) => {
    try {
        await originalShowStatusBarLyric(initLyric, config);
    } catch (e) {
        errorLog("状态栏歌词开启失败", e);
        Toast.warn("状态栏歌词开启失败，请到手机系统设置打开悬浮窗权限");
        Config.setConfig("lyric.showStatusBarLyric", false);
    }
};

LyricUtil.showStatusBarLyric = showStatusBarLyric;

export default LyricUtil;

View on GitHub (pinned to d118b18b3d)

Solutions

Guide the user to Settings → Apps → this app → 'Display over other apps' and enable it, then re-enable status bar lyric.
Before calling, check/request overlay permission via the native module (e.g. checkPermission + jumpToSettings) instead of relying on the failure toast.
Note the config already auto-reverts (lyric.showStatusBarLyric=false); re-enable it after granting permission.

Defensive patterns

Strategy: try-catch

Validate before calling

const hasOverlay = await LyricUtil.checkPermission?.();
if (!hasOverlay) {
  LyricUtil.jumpToPermissionSettings?.();
  return; // don't attempt until granted
}

Try / catch

try {
  await LyricUtil.showStatusBarLyric(lyric, config);
} catch (e) {
  Config.setConfig('lyric.showStatusBarLyric', false);
  Toast.warn(t('lyric.overlayPermissionRequired'));
}

Prevention

Check/request SYSTEM_ALERT_WINDOW permission before enabling status bar lyric.
Provide a settings shortcut that opens the app's overlay permission page.
Remember the permission may be revoked by OEM ROMs after updates — re-check on app start.
Keep the auto-disable behavior so the app doesn't repeatedly fail.

When it happens

Trigger: Calling LyricUtil.showStatusBarLyric while the app lacks SYSTEM_ALERT_WINDOW / floating window permission on Android, so the native module rejects when trying to draw the status-bar lyric view.

Common situations: Fresh install where the user never granted 'display over other apps'; OEM ROMs (MIUI, EMUI) revoking overlay permission after updates; permission denied per-app in system settings; running on devices where the lyric service requires extra permission.

Related errors

AI-assisted analysis of maotoumao/MusicFree@d118b18b3d (2026-08-30). Data as JSON: /api/errors/9bed94fc1e09cd2b. Report an issue: GitHub.