Troubleshooting

Keep Luma in the foreground during a large import. The screen stays on automatically. If you briefly switch to another app, the import keeps running for a while; if iOS eventually suspends the app, everything imported up to then is kept.

Then simply import the same folder again: songs that are already there are skipped, only the rest is added.

If the files are in iCloud Drive or another cloud storage, Luma has to download them first. On a slow connection that takes time; a stable Wi-Fi helps.

The file has an extension Luma doesn't play, for example .ogg, .wma or .ape. Supported are MP3, AAC, M4A, M4B, ALAC, FLAC, WAV, AIFF, CAF and Opus. Convert other formats on your computer, for example to FLAC (lossless) or AAC. See Formats.

The extension is right, but the content can't be read: the file is incompletely downloaded, damaged or copy-protected (DRM, for example from streaming apps). Check whether it plays on your computer, and import an intact copy.

Luma treats songs with the same title, artist, album, track number and length as identical, even if they sit in different folders or are in another format. That prevents duplicate entries. To keep another version of a song (such as a remaster), the tags have to differ, for example in the album name. Details and examples: Duplicate songs on import.

The songs have different album names or album artists. Align them with Edit Album Info. Step by step: An album shows up twice.

The files contain no tags. Luma then uses the file name. Fill in the info in Luma (Edit info) or tidy up the tags on your computer with a tagging program before importing.

Some covers have a border or text right up to the edge. Set Settings › Appearance › Cover corners to Square, and Luma shows artwork in full.

Your change is saved in Luma; only the file itself wasn't updated. That happens with unusually structured files; Luma would rather leave them unchanged than damage anything. You still see the new info in Luma.

Luma couldn't read the library data at launch, for example after a crash in the middle of saving, and reset it. A backup of the old data was created. Import your music again and read in your Luma Data backup. Please send us a short note in that case so we can look into the cause.

Turn on Settings › Playback › Normalize volume. Right after a large import, Luma is still measuring in the background; until then it estimates. You can see the progress below the switch. See Normalize volume.

Set Cross-Fade to 0 s. Luma then plays gapless, the way the songs flow into each other on the album.

The button only appears when the song has lyrics: in the file's lyrics tag, or as an .lrc file that sat next to it during a folder import. Luma doesn't download lyrics from the internet. See Lyrics.

That's intentional: when headphones disconnect, Luma pauses so the music doesn't suddenly come out of the speaker. Just press play again.

These songs are in the Not in Library section: they come from a playlist backup and aren't in your library yet, or their file is missing from your Mac's music folder. Import them and they move back into place automatically. Or remove them with Remove All. See Grey songs.

Title, artist or album differ too much from the backup, or Luma finds two fitting versions (such as studio and live) and would rather match neither. On the Mac, right-click and choose Match Song…. On the iPhone, remove the grey entry and add the song to the playlist again. Background: How Luma matches songs.

The file you picked isn't a backup from Luma or is damaged, for example after editing it by hand. Luma only reads its own JSON file, not .m3u or .m3u8 playlists. The structure of the file is described in How the JSON file is structured.

There was nothing new to take over from the backup, and some of its songs or albums are missing from your library. Stats and collections can only be matched to songs and albums that are already there. Import the music first, then read in the file again. See Restoring.

Every playlist and collection in the backup already exists with the same name, none of them is missing anything, and the stats are at least as high as in the file. So there's nothing to do. To rebuild a playlist in the backup's order, delete it first and then read in the backup again.