Tips and special cases

Tips & troubleshooting, updated October 25, 2026

Workflows that have proven themselves, and answers for the cases that don't fit into every guide. The rules behind them are in How Luma recognizes and matches songs.

Before importing: get your tags in order

Luma sorts by the tags in your files and nothing else. Ten minutes with a tagging app on your computer (such as Mp3tag or MusicBrainz Picard) saves a lot of tidying up in the app later. A detailed field-by-field guide is on the blog: Make your metadata consistent.

Set the album artist: it keeps albums with guest appearances together and decides which artist an album is listed under.
Spell consistently: for albums the exact spelling counts. “AC/DC” and “ACDC” are two artists to Luma.
Fill in disc numbers: on double albums Luma sorts by disc first, then by track number.
Embed artwork: Luma takes the cover from the file. A loose cover.jpg in the folder isn't read.
Embed lyrics if you transfer with Luma Transfer (see below).

Compilations

On a compilation, every song has a different artist. Without a shared album artist, Luma turns it into many one-song albums. Give every song the same album artist, such as “Various Artists”. You can also do this afterwards in Luma with Edit Album Info, see Edit track and album info.

Two versions of the same song

Single and album: different album names, so two songs. Both are imported.
Remaster, live or demo version: usually the title or length differs, and all is well. If title, artist, album, number and length are identical, Luma takes the second file for a duplicate and skips it. Give it an addition then, such as “(2009 Remaster)”.
The same music as FLAC and MP3: if both versions have the same tags and the same length, Luma keeps only the one imported first. If you want the better quality, import the FLAC files first. If the MP3 is already in, delete the album in Luma and import the FLAC version.
In playlists: if two versions with similar titles sit on one album, Luma only matches a song from a playlist backup when the title fits exactly. Otherwise it stays grey, so the wrong version doesn't end up in the playlist.

Importing large collections

Keep Luma in the foreground. The screen stays on by itself during the import. A quick app switch is fine, long pauses in the background are not.
Going in stages is fine. Just import the same folder again. Whatever is already there is skipped, only the rest comes in. That also works after cancelling.
Cloud files take longer. If the collection is in iCloud Drive, Luma has to download every file first. Over Wi-Fi with the charger plugged in, that's most reliable.
From a Mac, Luma Transfer is fastest, especially over a USB cable. Feel free to drag in your whole collection: duplicates are sorted out beforehand.
Keep an eye on storage. Lossless formats need a lot of space. How much each album takes up is shown under Settings › Library & Storage › Storage Used.

The “Luma” folder in the Files app

The folder On My iPhone › Luma is an inbox, not your library. Whatever you put there, whether in the Files app, through the Finder over a cable or on iPad in Split View, Luma imports by itself the next time it opens and then removes it from the folder. Files Luma can't read end up in the Not Imported subfolder. A README.txt in the folder explains the same.

Don't put anything there that you want to keep as an original. And never choose this folder as the destination for Export Library; Luma doesn't allow it anyway.

Lyrics and Luma Transfer

Since version 1.1, Luma Transfer and Luma for Mac send lyrics along: if an .lrc, .elrc, .ttml or .txt file sits next to a song, it goes to the iPhone together with the song. If the song is already there and has no lyrics from a file yet, only the lyrics are added. The iPhone needs Luma 1.6 for this.

Older versions only send audio files, so the lyrics are missing on the iPhone. Two fixes:

Embed the lyrics: use a tagging app to write the lyrics into the file's lyrics tag. Embedded lyrics travel with the file everywhere.
Import through the Files app: put the folder including its .lrc files into iCloud Drive and bring it into Luma with Import Music. On a folder import, Luma reads the lyrics too.

Using Mac and iPhone together

Luma for Mac and Luma on the iPhone each have their own library. There's no automatic sync. This is how you keep both up to date anyway:

Music: send new albums from the Mac to the iPhone with Luma Transfer. You can always drag in your whole collection, only what's missing comes over.
Playlists and collections: on the Mac, File › Export Data… (⇧⌘E), save the file to iCloud Drive and read it in on the iPhone under Settings › Library & Storage › Backup › Import Data. Existing playlists and collections are only topped up, not created twice.
Likes and play counts are counted on each device separately. The same file carries them over: for every song Luma keeps the higher value and adds missing likes. Plays from both devices aren't added up, and likes you removed stay on the other device.

Moving from iPhone to Mac

Export the libraryOn the iPhone, Settings › Library & Storage › Export Library, and choose a folder in iCloud Drive or on a USB stick.
Get the folder onto the MacCopy the “Luma Mediathek …” folder to where your music should live for good, for example into “Music”.
Add it as a music folderIn Luma for Mac, File › Add Music Folder… (⌘O) and pick the folder.
Read in your dataWait until Luma has scanned the folder, then File › Import Data… (⇧⌘I) and pick Luma Daten.json from the export. Playlists, collections, likes and stats move along.

Reinstalling Luma safely

When you delete the app, iOS deletes the library too. If you want to reinstall Luma, back up two things first:

MusicOnly needed if you no longer have the original files elsewhere: Export Library.
Playlists, collections, likes and statsSettings › Library & Storage › Backup › Export Data. Already part of the library export as Luma Daten.json, as long as you have at least one playlist.
After reinstallingImport the music first, then the file with Import Data. That way Luma finds every song right away.

Without this file, likes and statistics start from zero after a reinstall. Without it, they're only kept when you restore from a device backup.

Music first, then playlists, or the other way round?

Both work. If you read in the playlists first, all songs are grey and move into place one by one as the music is imported. The other way round, the playlists are complete right away. With large collections, “music first” is clearer, because you see immediately which songs are really missing.

Before you delete songs

iPhone and iPad: a deleted song disappears from every playlist, along with its likes and play counts. A later import brings it back as a new song, but not into the playlists by itself.
Mac: Move to Trash moves the music file itself to the Trash. If a file is only missing because you moved it, Luma finds it again on the next scan.
Replacing an album (say MP3 with FLAC): export your playlists first. After replacing, read the backup in again. The missing songs are then added at the end of each playlist. If you want the old order back exactly, delete the affected playlist first and then read in the backup.

Still have a question or found a mistake? Email hello@suenavus.com.