Home
This guide will help you get started with setting up Petrichor!
- Petrichor
- macOS 14.0 (Sonoma) or later
- Apple Silicon (M series chips) or Intel processor
- Go to Releases and download the latest
.dmg. - Open it and drag the app icon into the Applications folder.
- In Applications, right-click Petrichor > Open.
brew install --cask petrichor
Petrichor supports 20+ audio file formats — MP3, AAC/M4A, ALAC, FLAC, WAV, AIFF, Ogg Vorbis, Opus, Monkey's Audio (APE), Musepack, WavPack, DSD, and more — and should handle most of your audio files without problems.
When you launch Petrichor for the first time, you'll be presented with a view to add Folders to your library using the Add Music Folder button.
Once the folder(s) are added, the app will start scanning your folders where it;
- Scans through all the available tracks, identifying supported ones
- Extracts metadata including title, artist, album, genre, year, and album artwork
- Sets up the music database with the extracted information
- Loads up your music library at the end of scanning
Starting from v1.4, the initial scan runs in the background so the app is ready to use almost immediately on first launch — your library will keep growing as more tracks are processed.
In case your folders include files that are not yet supported by Petrichor or some tracks failed to scan, the app will notify you about it at the end of scanning.
Once you're presented with your music library at the end of scanning your folders, you'll see the app window that includes various elements.
The Home tab is your music dashboard, featuring:
- Discover — A rotating set of tracks you've never played (or played a long time ago). You can refresh this list manually any time using the refresh icon next to the section title, or rely on the automatic refresh interval set in Library settings.
- Tracks — A list of all the tracks present in your library
- Artists — A flat listing of every artist
- Albums — A flat listing of every album
- Pinned items — Anything you've pinned to Home. By default you'll see some of the playlists pinned here, but you can pin individual artists, albums, decades, genres, or playlists from their context menus.
The Library tab provides an organized view of your music. Here you have more granular access to your tracks by categorizing them using one of the following:
- Artists — All artists in your library
- Albums — Complete album listing, with sorting by year or date added
- Genres — Music organized by genre
- Years — Browse by release year
- Decades — Group by decade
- Composers — Classical music organization
Switch between categories using the picker in the top-left of the sidebar. You can filter the list of items, or pin them to Home by right-clicking any item in the sidebar.
The Playlists tab lets you create and manage your own playlists. Out of the box, it includes three specialized smart playlists:
- Favorites — Tracks you've marked with a ⭐
- Top 25 Most Played — Your most frequently played songs
- Top 25 Recently Played — Songs you've played in the last week
To create a custom playlist:
- Click the "+" button in the Playlists section
- Provide a playlist name in the dialog that shows up
- Click
Add songsand search for tracks you want to add — you can add multiple tracks by searching using various keywords and adding them one by one
Petrichor can import and export .m3u / .m3u8 playlists. The actions are available from the File menu, and from the … (more) menu next to a custom playlist in the sidebar. Imported playlists with relative track paths are resolved against your watched library folders.
If your music files are organized in a specific folder structure and you'd prefer to browse them that way, you can do so from the Folders tab.
Note: The Folders tab can be hidden via Settings → General → Show folders tab in main window if you prefer a cleaner toolbar.
Your added folders are directly accessible from the sidebar and can be expanded on click. When a folder includes tracks directly, they show up when that folder is selected.
The player bar at the bottom provides traditional playback controls along with the ability to:
- View track information by clicking the album art (opens the Track Info & Lyrics sidebar)
- Toggle favorite for the playing track by clicking the ⭐
- Open the current playback queue
- Toggle shuffle and repeat (off / repeat one / repeat all)
Clicking the album art on the player bar — or Show Info from a track's context menu — opens the Track Info sidebar. It surfaces metadata like album, album artist, track number, disc number, genre, composer, release date, lossless format details, and your favorite state. If the playing track has lyrics — either embedded in the file or available as a sidecar .lrc / .srt file — they show up in this sidebar as well, and synchronized lyrics scroll along with playback.
Starting from v1.4, Petrichor can also fetch lyrics from the internet automatically when none are embedded. Toggle this from Online settings.
| Track Information | Lyrics |
|---|---|
 |
 |
Audio effects are controlled from the Equalizer, which can be opened from the Window menu or via ⌘+⌥+E.
The Equalizer includes:
- An adjustable Preamp
- A 10-band parametric EQ (32 Hz – 16 kHz)
- A Stereo Widening effect
- 23 built-in presets
Beyond the presets, you can save and tweak a custom configuration of gains. Petrichor remembers whether the EQ was enabled across app relaunches.
You can hide or show columns by right-clicking the column headers, and rearrange columns by dragging them around. Available columns include #, ★ (favorite), Disc, Filename, Title, Artist, Genre, Album, Year, Composer, Date Added, and Duration.
The sort/display button on the top-right of the tracks header lets you change how the list is sorted (by title, artist, album, year, duration, date added, favorite, etc.), the sort order (ascending or descending), and the row size (Expanded — with album art — or Compact).
Right-click any track to access:
- Play — Play the track immediately
- Play Next — Queue the track right after the currently playing one
- Add to Queue — Add to the end of the playback queue
- Show Info — View track details in the sidebar
- Reveal in Finder — Open Finder and select the track file
- Go to — Jump to the selected track in the Library tab based on chosen context (artist, album, etc.)
- Add to Playlist — Add the track to a selected playlist
- Add to Favorites / Remove from Favorites — Toggle favorite state
You can multi-select tracks in any list (with ⌘+click for individual selection or ⇧+click for range selection) and apply actions like adding to playlists, queueing, or favoriting in bulk via the right-click menu.
Access settings via Petrichor → Settings… or ⌘+,
-
Behavior
- Start at login — Start Petrichor when macOS starts
- Keep running in menubar on close — Keep Petrichor running in the background even when the app window is closed
- Hide duplicate songs — Prevent duplicate tracks from showing up in the library (requires app relaunch)
- Check for updates automatically — Keep Petrichor up-to-date with new releases
-
Appearance
- Color mode — Light, Dark, or Auto (follows system)
- Show folders tab in main window — Show or hide the Folders tab in the toolbar
- Use album artwork colors in backgrounds — Tint backgrounds (e.g. playlist headers, the player bar) with colors derived from the active album artwork
-
Discover & Scanning
- Refresh added folders for changes — How often Petrichor re-scans watched folders for new/changed files (e.g. on app launch, every hour, daily, manually)
- Refresh Discover tracks — How often the Discover list rotates
- Number of Discover tracks — Total tracks to include in the Discover section
-
Watched Folders
- Refresh added library folders for updates — Manually trigger a rescan of all watched folders. Hold ⌘ while clicking Refresh on an individual folder to force a full metadata rescan.
- Optimize library database — Compact and re-index the underlying database for faster queries
- Folders (n) — Expand to see and manage every watched folder. Use Add Folder to add a new one, or use the row-level controls to refresh or remove a single folder.
- Reset all library data — Wipe the library database and start over
-
Last.fm
- Connect your Last.fm account to enable scrobbling
- Enable scrobbling — Submit plays to Last.fm as you listen
- Sync favorites as Loved tracks — Mirror Petrichor's favorites with Last.fm "Loved" status
-
Lyrics & Metadata
- Fetch lyrics from internet when unavailable — Automatically download lyrics for tracks that don't have embedded or sidecar lyrics
- Fetch artist image and bio from internet — Pull artist artwork and biographies for richer artist views
View app information:
- Current version and build
- Library statistics (folders, tracks, artists, albums, total duration)
- Useful links — Website, Help, License, App Data, Acknowledgements
Playback can be controlled via these keyboard shortcuts (also discoverable in the Playback menu):
- Space — Play / Pause
- ⌘+→ — Next track
- ⌘+← — Previous track
- ⇧+⌘+→ — Seek forward
- ⇧+⌘+← — Seek backward
- ⌘+↑ — Increase volume
- ⌘+↓ — Decrease volume
- ⌘+⌥+E — Open Equalizer
- ⌘+, — Open Settings
- ⌘+W — Close window (app keeps running in the menubar if enabled)
- GitHub Issues — Report bugs or request features
- Discussions — Join the community conversation or ask questions about the app
Last updated for Petrichor version 1.5