Tulip guide

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 2). Tulip 2 is a new app, rebuilt from the ground up.

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.
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.
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: one word for the library (excellent, good, fair or needs attention) and a tile per issue.
• 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.
• Dead tracks relinked from folders you choose, stray files, albums split in two, and playlist tidying.
• Replace a cloud song or a broken entry with a better file on your Mac, keeping its plays, rating and place in your playlists (Pro).

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. In beta 2 it's about six times faster than in beta 1; on a 20,000-song library, listening takes about three and a half hours.

• Health › Overview shows each step's progress and the time left, for example "1,240 of 23,025 songs · About 3 h left". The jobs list shows the time left too.
• 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.

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.

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 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.
• 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 and in the privacy policy.

Keyboard shortcuts#

Press ? in Tulip to see them all.

In Review:

In a set of duplicates:

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 the Dead tracks tile and choose the folders where the files might be; Tulip suggests the relinks it can match.

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.

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 or with Lost your license? in Settings › License, or sign in to your account.

Something else? Visit Support or email support@lonelyduck.io. Help › Export Diagnostics… saves a file you can attach. Refunds follow the refund policy.