Troubleshooting

Cause: the APK is corrupt, or was built for a CPU architecture your phone doesn't support.
Fix: re-download the universal build from GitHub Releases. If it still fails, your Android version is likely below 8.0 (API 26), which Interlude does not support.

Cause: a build from another fork (Metrolist, SimpMusic, InnerTune) or a really old version of Interlude is already installed with the same package name but a different signing key. Android refuses to overwrite an app with a differently-signed one.
Fix: back up your playlists and downloads, uninstall the other app, then install Interlude. This is also why you must uninstall Interlude itself before installing a debug build produced by Android Studio.

Cause: Play Protect blocks all apps it hasn't seen before, not just malicious ones. Every sideloaded app triggers this the first time.
Fix: tap More details → Install anyway. If you never see the "More details" option, tap the small arrow next to the warning first.

Cause: the app you're installing from (browser, file manager) doesn't have "Install unknown apps" permission.
Fix: Settings → Apps → Special access → Install unknown apps, then enable it for the specific app you're using to open the APK.

Cause: your phone's battery optimization is killing the playback service when the app goes to background.
Fix: Settings → Apps → Interlude → Battery → Unrestricted. On Samsung devices this is under Allow background activity; on Xiaomi/HyperOS you also need to lock the app in the recents list.

Cause: usually a network problem on streamed tracks, or an extremely aggressive power-saving mode.
Fix: try a downloaded track — if it plays cleanly, the issue is network-side. If downloads also stutter, disable the equalizer as a test (a very high preamp setting can clip the output). If that fixes it, reduce preamp gain to 0 and re-enable.

Cause: Smooth Skip has strict preconditions and deliberately does nothing when they aren't met.
Fix: see the list of trigger conditions. The most common reasons are same-album tracks in gapless mode, manual skip within two seconds, and tracks without a detectable BPM.

Cause: the current queue has no next or previous track.
Fix: check the queue (swipe up on the mini player). If the queue looks correct but buttons don't respond, force-stop the app and reopen — this is a rare state-desync bug that a clean restart resolves.

Cause: no provider has synchronized lyrics for that track.
Fix: from the player overflow menu, try each provider (SimpMusic, BetterLyrics, Musixmatch) individually. If none produce results, the song genuinely lacks a synchronized transcript. You can leave the app in automatic mode and it will fall back to plain lyrics if any provider has them.

Cause: provider timestamps and the streamed audio differ in where they consider the start of the track, usually because of an intro that some providers include in their timing data.
Fix: try a different provider for that song. Per-song overrides persist until you reset them to automatic. OR Decrease or Increase the Lyrics offset in the lyrics menu

Cause: usually storage-side — the target folder is full, or has insufficient write permission.
Fix: check available storage. If you chose a custom download folder, ensure Android has granted write access to that folder (re-select it in Settings → Downloads → Folder). The app's private folder requires no permission and is the safest choice.

Cause: Smooth Skip's tempo analysis, live lyrics, or Discord Rich Presence are the usual suspects.
Fix: disable Smooth Skip in Settings → Player and Audio if you don't need it. Disable live lyrics animation in Settings → Content → Lyrics. Disable Discord Rich Presence if you're not using it. Each is a measurable improvement on a mid-range device.