Frequently Asked Questions

Petrichor is sandboxed and notarized by Apple, so it installs and opens without warnings. Download the DMG and drag it to Applications, or install it with Homebrew. Older guides floating around mention clearing quarantine flags with xattr, but that has not been necessary since the app was notarized.

Being sandboxed means the app holds only two permissions:

• Read and write access to the files and folders you pick. The write half is used for exactly one thing: exporting M3U playlist files.
• Network access, to check for updates, to stream Internet Radio when you play a station, and for the online extras that stay off until you turn them on: artist images and bios, lyrics downloads, Last.fm scrobbling, and reporting a problem from Help > Report a Problem.

Everything else stays on your Mac. Your library data is always offline, your audio files and folder structure are never touched, and there are no analytics on how you use the app. There never will be. If you do connect Last.fm, Petrichor never sees your password: you sign in on Last.fm’s own site, and all it gets back is a session key, kept in your Keychain if you allow it.

Never. It reads your files and writes nothing back: no tags, no artwork, no rearranging folders. The only time it writes anything at all is when you export a playlist as an M3U file. Your favorites, play counts, and playlists live in Petrichor’s own database.

Yes. They live in Petrichor’s database, separate from your audio files, and updates leave them alone. One thing that surprises people: a track only counts as played once it has played through in full, and Top 25 Most Played only lists tracks played more than five times.

Petrichor reads the metadata embedded in your files, so anything missing from the tags is missing from the library. When a track shows up blank, its tags are usually empty rather than unread. Turn on the Filename column by right-clicking any column header to work out which tracks they are, then fix the tags with an editor like Mp3tag. Once the tags are in place, force a refresh (using ⌘ + Click on Refresh button) and Petrichor will pick them up.

A normal refresh only looks for tracks that were added or removed, which is why edited tags do not show up. For a full metadata rescan, go to Settings → Library and hold ⌘ while clicking Refresh on a folder to reveal the force refresh option. Your playlists, play counts, and pinned items are all kept.

Yes. Album artists are available from the Library tab, and albums fall back to the track artist when the album artist tag is missing, which is usually what splits a compilation apart in the first place. If one still fragments, it is almost always the tags. Tracks under an artist, album artist, or composer are grouped by album as of 1.7, and you can sort those groups by name, year, or the date they were added.

No, and that is deliberate. Editing tags across forty-odd formats is a project in its own right, and there are already excellent tools that do it well. Mp3tag is a good place to start. Petrichor reads your tags and leaves your files alone.

Version 1.7 hands playback and metadata reading entirely to CrescendoKit, which took format support from around twenty up to 46 file extensions, but it does not decode tracker modules. MOD, IT, S3M, and XM played in 1.6.x and no longer do, so those files are skipped on import. Everything else that worked before still works, alongside plenty that did not, like WMA, TAK, Shorten, AC-3, DTS, and Matroska audio. DRM-protected files, audiobook containers, RealAudio, and MIDI are not supported either.

Tens of thousands of tracks. It is developed against a 10,000-track library for stress testing, and people run collections of 30,000 and more. Browsing reads from a local database rather than your disk, so the library stays responsive as it grows, and your drive is only touched when a track actually plays.

It works, with one caveat worth knowing. Petrichor is built for music stored locally on your Mac. Browsing stays fast because it reads from the database, but the initial scan across a network drive can be slow, and the Folders tab reads from the drive live. If your collection lives on a NAS, expect the first scan to take a while.

Petrichor builds your library from track metadata, which is what lets you browse by artist, album, genre, and year no matter how the files are arranged on disk. If you would rather browse the way your folders are laid out, the Folders tab does exactly that, and you can show or hide it from Settings → Appearance → Visibility (or by going to View menu of the app).

Search matches from the start of a title, album, or artist rather than anywhere inside it, and it needs at least two characters. That comes from the full-text search engine underneath, which is what keeps search quick across a large library. Matching from anywhere would mean giving that speed up. Search always covers your whole library, not just the folder you are looking at.

Right-click any column header to show or hide columns, and drag them to reorder. Sorting works on one column at a time by design: Albums, Playlists, and Artists already carry a sensible order of their own, so the other views are kept simple.

Not today. Petrichor plays music you already have on your Mac, and that focus is what keeps the library fast and the app entirely offline. Subsonic and Navidrome support is something I am exploring, but it is not trivial given how the app is built, and there is still plenty I want to implement for local playback first. Internet Radio is the one exception and it shipped in 1.7: add stations by URL, or pick from thousands of popular ones.

Yes, and it stays off until you connect to your Last.fm account. Petrichor never sees your Last.fm credentials: you authorize it on Last.fm’s own site and the app only keeps the session key. You can mirror your favorites as Loved tracks too. For ListenBrainz, connecting it to your Last.fm account works today, but supporting every scrobbling service separately is not something I want to take on.

Not yet. The Mac app has a long list of things I want to finish first, but most of Petrichor’s internals are not Mac-specific, so a port is something I genuinely want to do. I miss these features on my phone as well. No timeline to offer.

Staying off the App Store is a deliberate choice. It lets me decide which APIs to use and how the app should behave, rather than shaping releases around review rules. Petrichor does not, and never will, misuse platform APIs. I may reconsider one day if there is enough interest and it does not mean maintaining two codebases.

Use Help > Report a Problem in the app. Describe what happened and send it. An email address is required, since it is the only way I can follow up with questions, and it is used for that and nothing else.

Attaching diagnostics is optional, and the window shows you exactly what will be sent before you send it: your app and macOS version, the kind of Mac you are on, and a summary of your library and settings. Nothing in there identifies you or your Mac, and reports are deleted after 30 days. If you would rather not give an email address at all, there is a “Report on GitHub instead” link that opens a pre-filled public issue, though you will need a GitHub account for that.

There are no ETAs. Petrichor is a hobby project I work on in my spare time, so things land when they land. What is being considered lives in the issue tracker, and the changelog has everything that has shipped so far.