# Tulip guide > How to set up Tulip 2 for the Music app on your Mac: permissions, review, hold, apply and undo, the library tools, license and Macs, updates and troubleshooting. Applies to Tulip 2.0 beta 3 · Updated Oct 21, 2026 · https://lonelyduck.io/docs/tulip Tulip looks after the library you keep in the Music app on your Mac: duplicates, missing artwork and lyrics, songs whose file went missing, messy tags, listening history and smart playlists. It never changes anything until you approve it, and anything it changes can be undone for 30 days. This guide is for **Tulip 2**, which is in beta (2.0 beta 3). Tulip 2 is a new app, rebuilt from the ground up. > **Note:** **Still on Tulip 1.0?** Tulip 1.0 is still the stable version, at [lonelyduck.io/download](https://lonelyduck.io/download). If you bought it, your key works in Tulip 2 on up to 3 Macs at no cost, and Tulip 2 never writes Tulip 1.0's files. See [Older apps](https://lonelyduck.io/docs/older-apps#tulip-10). ## Getting started ### What you need - A Mac with Apple silicon (M1 or later). Tulip 2 doesn't run on Intel Macs. - macOS 14 Sonoma or later. Measuring BPM and key needs macOS 27. - English or Korean: Tulip follows your Mac's language, or choose one in **Settings › General › Language**. - The Music app with your library in it. Your own files are enough; an Apple Music subscription only matters for adding catalog songs to your library. ### Install 1. Download the Tulip 2 beta from the [Tulip page](https://lonelyduck.io/tulip#download). 2. Open the disk image and drag Tulip to Applications. 3. Open Tulip from Applications. ### The first run A short setup sheet walks through: 1. **Where your music lives.** Tulip works with the library the Music app keeps on your Mac. (Folders of music files aren't supported yet.) 2. **Permission to control Music.** macOS asks once; see [Permissions](https://lonelyduck.io/docs/tulip#permissions). 3. **Reading your library.** Tulip reads the library into its own index on your Mac. You can carry on while it reads. 4. **A first check.** A quick check runs now and only reads: tags, lyrics, artwork and iCloud status. The deep audio check (duplicates by sound, loudness and quality, plus lyrics and artwork looked up online) can run now, tonight when your Mac is idle, or later when you start it. 5. **License.** Start the 14-day Pro trial, enter a license, or choose Later. The trial starts only when you start it. You land on **Health › Overview**, which sums up what the check found. ## Permissions ### Automation: let Tulip control Music Tulip reads a few things only Music knows (favourites, cloud status, lyrics) and writes the changes you apply through Apple Events, so macOS asks whether Tulip may control Music. Choose **Allow**. If you chose Don't Allow: open **System Settings › Privacy & Security › Automation**, find Tulip and turn on Music. Tulip notices the change and carries on. ### Media & Apple Music macOS may also ask to let Tulip access your music library and Apple Music. Tulip uses it to read the library quickly and, if you subscribe, to add catalog songs. Change it any time in **System Settings › Privacy & Security › Media & Apple Music**. ## Review, hold, apply, undo Every change Tulip can make goes through the same four steps. ### 1. Review What a check finds becomes a suggestion in **Health › Review**, with every field shown before and after. Press `1` or `A` to hold, `2` or `R` to dismiss (Tulip remembers dismissals), or `3` when two songs aren't duplicates. Untick a field to leave it as it is. ### 2. Hold Held fixes wait in the amber **held** capsule in the toolbar. Click it to see them all. Keep browsing; nothing is written yet, and the values from before are saved first. ### 3. Apply Press **Apply** (or `⌘↩`). Tulip counts down five seconds first ("Applying 3 fixes in 5…"), with **Undo**. Right before each write, Tulip reads the song from Music again and skips it if it changed since you held it; History shows what was skipped. Applying is a Pro feature, or part of the 14-day trial. ### 4. Undo Every write is recorded with what was there before. **Health › History** reverts a whole batch or a single change for 30 days, and puts back exactly what Music had. Files Tulip removes go to Tulip Trash for 30 days first. There's no redo for a change you applied: to change it back, revert it in History. `⌘Z` undoes the last change; `⇧⌘Z` only redoes typing in a text field. ## What Tulip does The sidebar has Library, Health, Discover, Make and Insights. ### Your library - Songs, albums, artists and playlists from a live index that follows the changes you make in Music. Search in English or Korean, sort and filter any column, and see a song's file, tags and pending fixes in the inspector (`⌘I`). - **Cloud only** lists the songs that live in iCloud with no file on your Mac. - **Export** songs, with their play counts, as CSV or JSON: `⌘K` › **Export songs as CSV…** or **Export songs as JSON…** for the list you're looking at, or select songs and use **Export Selection as CSV…** in the menu bar. CSV files open in Numbers and Excel with Korean intact. ### Clean - **Health › Overview**: a score out of 100 and one word for the library (excellent, good, fair or needs attention), then a list of areas with the one that matters most at the top. Select an area to see its problems and a button that shows exactly those songs or suggestions; **How it's scored** explains each area's share. - Duplicates by tags, ISRC and sound, with a keeper rule you can read; the plays, ratings and playlists of the other copies move to the one you keep. - Stray files, albums split in two, and playlist tidying. Songs whose file is gone get it back in Find Files, below. - **Health › Find Files** gives a song a file from your own folders: songs only in iCloud, songs whose file is missing, and better copies of songs you have. Choose where Tulip looks, check the matches, and replace; each song keeps its plays, rating and place in your playlists (Pro). Replacing a song that's only in iCloud removes the iCloud copy, so that can't be undone. ### Enrich - Lyrics from LRCLIB, matched by length. Synced lyrics are kept by Tulip; plain lyrics are written to Music. - Artwork from Apple's catalog and the Cover Art Archive, compared side by side. Missing art and art under 600 px is flagged. - Tag rules: title case, "feat." moved out of titles, a genre map, sort fields. - Loudness measured on your Mac, and a check for files that look like lossy copies. ### The deep check The deep audio check listens to every song: duplicates by sound, loudness and quality. On a 20,000-song library, listening takes about three and a half hours. - **Health › Overview** shows the deep check under the score: each step's progress and the time left, for example "1,240 of 23,025 songs · About 3 h left", and a step that stopped has its own **Continue** or **Try again**. The jobs list shows the time left too. - If the lyrics service is busy, Tulip waits and carries on; what it found so far is kept, and the next check asks only about new and changed songs. - Listening, finding lyrics and finding artwork run at the same time. - Duplicate and loudness suggestions appear while the deep check is still listening, a few dozen songs at a time. - A quick check can run while the deep check is going, so **Check again** always works. ### BPM and key Tulip measures each song's BPM and key only while you're away from your Mac, a few seconds a song, and stops as soon as you're back. **Health › Overview** shows how many songs have been measured, and you can turn it off there. It needs macOS 27 or later. ### Insights - **Listening**: import your history from ListenBrainz (your user name) or Last.fm (your own API key and user name), then see charts by week, month, year and all time, a listening calendar of plays per day, your top songs, artists and albums, and **comebacks**, the songs you returned to after a long break. - **Play counts**: bring Music's play counts and last-played dates up to date from your listening history. Each update waits in Review like any other change (Pro to apply). - **Year in review**: the story of your year in music, with your top song, artist and album, your busiest month and longest streak, and what you fixed with Tulip this year. **Save picture** shares it as an image, in Story (1080 × 1920) or Wide (1200 × 630). ### Discover - **Catalog**: search the catalog with your library in mind; songs you already own are marked. Until Tulip is activated with a license on your Mac (the trial doesn't count), Discover searches the **iTunes Store**: you can preview songs and open them in Music. Once activated, it searches Apple Music. - Add songs, albums or playlists to your library or a playlist with an Apple Music subscription (Pro, once activated); otherwise open them in Music. - **For you**: albums you're missing and new releases from your artists (MusicBrainz), and artists like the ones you play (ListenBrainz). ### Make - **Smart playlists** with rules, nested groups and limits, kept as ordinary Music playlists and refreshed daily or weekly (Pro), so Vox and other players see them. - **From a sentence**: describe a playlist, such as "2000s Korean indie I haven't played in a year, about 2 hours", and Tulip builds it from your library, using Apple's on-device model when your Mac has it. ### Labs: Sounds like this An experiment that runs on your Mac: find songs in your library that sound alike, or describe a sound in words. Turn it on in **Settings › Advanced › Labs**, download the sound model (about 207 MB, from Hugging Face; nothing about your music is sent), and build the index now or while your Mac is idle on power. Then use **Sounds like this** in a song's inspector, or `⌘K` › **Describe a sound (Labs)**. ## License and your Macs ### Free, trial and Pro Browsing, checks, Review, insights and catalog search are free. Applying changes, replacing songs, kept smart playlists, adding from the catalog and play-count sync are Pro. Pro is a one-time purchase for 1 or 3 Macs, with every Pro feature in every version. See [pricing](https://lonelyduck.io/tulip#pricing). Every Mac gets a 14-day Pro trial, with no account and no card. **It starts only when you start it**: in setup's License step, on the Pro sheet the first time you press Apply, or in **Settings › License**. Until then, the Mac is on Free. After the trial, browsing, checking and reviewing stay free. ### Activate a Mac 1. Open the license email on the Mac and click the activate link. Tulip opens and asks "Activate Tulip Pro on this Mac?"; nothing is activated until you confirm. 2. Or paste the license (it starts with `tulip-license-v1…`), or the whole email, in **Settings › License**. Lost the email? Use **Lost your license?** in **Settings › License**, or **Email my license** on [the activate page](https://lonelyduck.io/tulip/activate). ### Your Macs A license covers 1 or 3 Macs. **Settings › License › Your Macs** lists the Macs using it. To move Pro to a new Mac when every place is taken, release a Mac you no longer use there, then activate the new one. Nothing on a released Mac is deleted. ### Offline Tulip renews its license quietly, about twice a week, when your Mac is online. Pro keeps working for up to 30 days without a connection; with fewer than 5 days left, Tulip asks you to connect once. [Licenses and your Macs](https://lonelyduck.io/docs/general/licenses) covers what Tulip and Canto share. ### Bought Tulip 1.0? Your Tulip 1.0 key works in Tulip 2 on up to 3 Macs, at no cost. On a Mac where Tulip 1.0 was activated, Tulip 2 finds the saved key the first time it opens and offers **Upgrade for free**. On another Mac, paste the key from your purchase email in **Settings › License**. ## Updates - About every 6 hours, Tulip checks lonelyduck.io for a newer version and tells you when one is ready. It downloads an update only when you press **Download**, then **Restart to update** installs it. - After updating, What's New lists the changes. Every version's notes are on [lonelyduck.io/tulip/changelog](https://lonelyduck.io/tulip/changelog). - **Settings › General › Updates › Releases**: **Automatic** follows betas while you run a beta and stable releases otherwise; **Beta** or **Stable** pick one. Tulip never moves to an older version. ## Privacy Your library and your music files never leave your Mac. Tulip contacts LonelyDuck for the license and updates (and, once activated, for Apple's developer token for catalog search), and the lyrics, artwork, listening, catalog and Labs services only when you use those features. There are no IP or location lookups. **Settings › Sources › What leaves this Mac** lists every service with what it sends. The full list of hosts is also on the [Tulip page](https://lonelyduck.io/tulip#privacy) and in the [privacy policy](https://lonelyduck.io/legal/privacy#tulip). ## Keyboard shortcuts Press `?` in Tulip to see them all. | Keys | Does | |---|---| | `⌘K` | Commands | | `⌘F` | Search and filter | | `⌘1` to `⌘6` | Go to a section | | `⌘,` | Settings | | `?` | All shortcuts | | `Esc` | Close a sheet, popover or search | | `⌘I` | Show or hide details (the inspector) | | `⌃⌘S` | Show or hide the sidebar | | `⌘R` | Read the library again | | `⌘.` | Cancel the running job | | `J` / `K` | Move down or up | | `X` | Select a row | | `⌘A` | Select everything filtered | | `Space` | Peek and play | **In Review:** | Keys | Does | |---|---| | `1` or `A` | Hold | | `2` or `R` | Dismiss | | `E` | Edit | | `←` / `→` | Previous or next candidate | | `⌘↩` | Apply held changes | | `⌘Z` | Undo the last change | | `⇧⌘Z` | Redo typing in a text field (there's no redo for an applied change) | **In a set of duplicates:** | Keys | Does | |---|---| | `P` | Keep this copy | | `M` | Merge or keep this copy separate | | `←` / `→` | Previous or next copy | | `⇧1` to `⇧8` | Listen to copy 1 to 8 | | `J` / `K` | Next or previous set | | `3` | Not a duplicate | ## Troubleshooting **"Tulip can't control Music."** Automation is off for Tulip. Turn it on in **System Settings › Privacy & Security › Automation › Tulip › Music**. **A change was skipped.** The song changed in Music after you held the fix, so Tulip left it alone. Run the check again for a fresh suggestion. **Songs show as dead tracks.** Their files moved or were deleted. Open **Health › Find Files**, choose **File missing**, and add the folders where the files might be; Tulip matches what it finds for you to check. **I want to undo something.** Open **Health › History** and revert the batch or the single change, for up to 30 days. **The deep check is taking a long time.** On a big library it takes hours; **Health › Overview** shows the time left. You can keep using Tulip, and quick checks still run meanwhile. **Discover only shows iTunes Store results.** Apple Music search starts once this Mac is activated with a license; the trial doesn't count. See [Discover](https://lonelyduck.io/docs/tulip#discover). **Every Mac on my license is taken.** Release a Mac you no longer use in **Settings › License › Your Macs**, then activate the new one. **I can't find my license email.** Ask for it again on [the activate page](https://lonelyduck.io/tulip/activate) or with **Lost your license?** in **Settings › License**, or sign in to [your account](https://lonelyduck.io/account). **Something else?** Visit [Support](https://lonelyduck.io/support) or email support@lonelyduck.io. **Help › Export Diagnostics…** saves a file you can attach. Refunds follow the [refund policy](https://lonelyduck.io/legal/refunds).