hihat

The minimalist offline music player for macOS

Download · Report Bug · Request Feature

Table of Contents

1. About The Project
2. Getting Started
   • Installing hihat
   • First Time Setup
   • Updating hihat
3. Features
4. Supported Audio Formats
5. Using hihat
   • Playing Music
   • Sidebar and Navigation
   • Playlists
   • Browsing and Filtering
   • Notifications
   • Mini Player
   • Editing Metadata
   • Right-Click Actions
   • Settings and Preferences
   • Keyboard Shortcuts
6. Tips
7. Roadmap
8. Built With
9. Contributing
10. Getting Started as a Contributor
11. Looking for Something Like WinAmp?
12. License
13. Contact

About The Project

hihat is a free, open-source music player for macOS built for people who keep a local music library. It plays every major audio format with true gapless playback, manages libraries of any size, and stays out of your way with a clean dark-mode interface. No ads, no accounts, no internet required — just your music.

(back to top)

Getting Started

Installing hihat

1. Download the .dmg file from the Latest Release
2. Double-click the .dmg to open it, then drag hihat into your Applications folder

That's it — hihat is now installed and ready to use.

Note: The first time you open hihat, macOS will warn you it's from an unidentified developer and ask you to confirm. This is expected — hihat is free and does not pay for an Apple Developer License to suppress this dialog.

First Time Setup

1. Open hihat
2. Click the Settings icon (gear) in the top-right corner of the sidebar
3. Under Music Folder, click the folder icon to select the folder where you store your music
4. Confirm you want to scan the folder
5. Wait for the import to complete (about 1 minute per 10,000 songs)
6. Your library is ready — start playing!

Updating hihat

1. Download the latest .dmg from the Releases page
2. Drag the new hihat into your Applications folder and confirm the replacement
3. Open hihat — your library, playlists, play counts, and settings are all preserved

(back to top)

Features

Library Management

• Import any folder structure — hihat finds all music files recursively
• Smart deduplication on import (prefers higher-quality files)
• Fast library scanning (~1 minute per 10,000 songs)
• Edit metadata for any track — changes are written back to the audio file tags
• Library stats: total songs, size in GB, total plays, and total hours (via the hihat menu)
• Incremental library backup to any external drive

Playback

• True gapless playback
• Shuffle with navigable history (up to 100 tracks)
• Repeat modes: off, single track, or all
• Play count tracking with duration-based threshold
• Last Played date tracking

Organization

• User-created playlists — create, rename, delete, and add or remove tracks
• Smart playlists: Recently Added, Recently Played, and Most Played (top 50 each, updated automatically)
• Browser panel for filtering by album artist and album
• Sort by any column
• Quick search bar — filter by title, artist, album, or genre
• Customizable column visibility — right-click any column header
• Drag-and-drop column reordering
• Drag and drop tracks to sidebar playlists
• Per-view search filters preserved across navigation
• Persistent sorting preferences per playlist
• Persistent column widths

Interface

• Dark and Light themes
• Mini Player mode — a floating window with album art
• Frameless macOS-native window with traffic light controls
• Collapsible sidebar navigation
• Multi-select with bulk operations (Cmd+Click, Shift+Click)
• Scrolling marquee for long track and artist names
• Responsive design down to 540px

Integration

• macOS media keys, keyboard, and Bluetooth headphone support
• macOS menu bar with playback controls and keyboard shortcuts
• macOS Now Playing widget integration
• Find on Spotify, Apple Music, and Tidal in one click
• Download album art from any track
• Show any track's file in Finder

(back to top)

Supported Audio Formats

Almost every format under the sun is supported, and they can all be mixed together in the same library:

• MP3
• MP4/M4A
• AAC
• WAV
• FLAC
• ALAC
• Opus
• Ogg Vorbis
• PCM

For detailed format information, see:

• The Chromium Project for supported audio formats
• Music Metadata for supported metadata formats

Limitations

• hihat does not play online streams
• hihat does not play protected content (M4P, AAX)
• hihat does not display album art for formats that do not embed it (WAV)

(back to top)

Using hihat

Playing Music

Double-click any track in the library to start playing. The player bar at the bottom of the window shows:

• Album art on the left (click to open the Mini Player)
• Track title and artist next to the album art (click the title to scroll back to the current song)
• Playback controls in the center: shuffle, previous, play/pause, next, and repeat
• Seek slider with elapsed and remaining time below the playback controls
• Volume slider and mute button on the right

Sidebar and Navigation

The sidebar on the left is your main navigation:

• All — click to view your entire music library
• Playlists — your user-created playlists and smart playlists (marked with a sparkle icon)
• Settings icon (gear) — opens the Settings drawer
• Toggle — collapse or expand the sidebar with the toggle button, or press Cmd+S

Playlists

Creating a playlist: Click the + icon next to the "Playlists" header in the sidebar, type a name, and hit Create.

Adding tracks to a playlist: Right-click any track and select Add to Playlist, then choose which playlist. You can also multi-select tracks (Cmd+Click or Shift+Click), right-click, and choose Add All to Playlist. Alternatively, drag and drop tracks directly onto any playlist in the sidebar.

Smart playlists: Three built-in smart playlists update automatically:

• Recently Added — your 50 most recently imported tracks
• Recently Played — your 50 most recently played tracks
• Most Played — your 50 most played tracks

Managing playlists: Right-click any user-created playlist in the sidebar to Rename or Delete it.

Browsing and Filtering

The toolbar at the top of the track list holds all the tools for finding and organizing music: a search button, a browser button, and a notification button, all grouped at the right edge of the toolbar.

Search: Click the search button in the toolbar (or just start typing when focused on the library) to filter tracks by title, artist, album, or genre.

Browser: Click the browser button in the toolbar (next to search) to open the Browser panel at the top of the track list. It has two columns — Album Artist and Album — so you can drill down by artist and then by album. Click any item to filter; click it again to deselect.

Sorting: Click any column header to sort ascending or descending.

Column visibility: Right-click any column header to show or hide columns (Title, Artist, Album, Album Artist, Genre, Time, Play Count, Date Added, Last Played).

Notifications

hihat shows quick, in-app notifications when things happen in the background — for example, when a track is added to a playlist, when metadata is saved, or when a file can't be written.

Click the bell button in the toolbar (at the far right, next to the browser button) to open the notification panel. A small badge appears on the bell whenever there are unread notifications. From the panel you can review recent notifications, dismiss them one by one, or clear them all at once. Click the bell again to close the panel.

Mini Player

Click the album art in the player bar to open the Mini Player — a compact floating window that stays on top of other apps. It displays the album art as a full background with playback controls overlaid at the bottom. All controls work: play/pause, skip, previous, seek, volume, shuffle, and repeat.

Editing Metadata

Right-click any track and select Edit Metadata to open the metadata editor. You can edit 13 fields:

• Title, Artist, Album, Album Artist, Genre
• Track Number, Total Tracks, Disc Number, Total Discs
• Year, BPM, Composer, Comment

When you click Save, hihat updates both its database and the actual audio file tags. This means your edits persist even if you re-scan your library or use the files in another music player.

Supported formats for file tag writing: MP3 (ID3), M4A/AAC (MP4 atoms), FLAC (Vorbis Comment), and OGG. Album art and any tags you don't edit are always preserved.

Note: If hihat cannot write to the file (e.g. the file is on a read-only drive, or is in an unsupported format like WAV), your edits are still saved to the hihat database. You'll see a warning notification letting you know the file tags could not be updated.

Right-Click Actions

Right-click any track to access:

• Play — play this track immediately
• Add to Playlist — add to any of your playlists
• Edit Metadata — edit track metadata and write changes back to the audio file
• Show in Finder — reveal the audio file in macOS Finder
• Find on Spotify — search for this track on Spotify
• Find on Apple Music — search for this track on Apple Music
• Find on Tidal — search for this track on Tidal
• Download Album Art — save the embedded album art as an image
• Remove from Library — remove the track from hihat and move the file to Trash

When viewing a playlist, the delete option becomes Remove from Playlist (the file stays in your library).

When multiple tracks are selected (Cmd+Click or Shift+Click), right-click to:

• Add All to Playlist — bulk add selected tracks
• Remove from Library — bulk remove selected tracks

Settings and Preferences

Click the gear icon in the sidebar to open the Settings drawer:

• Music Folder — change where hihat looks for your music (triggers a full rescan)
• Import Music — add new songs or folders to your library
• Rescan Library — scan your existing library folder for new or changed files
• Backup Library — incremental backup to any external drive (only copies new and changed files)
• Appearance — toggle between Dark and Light themes
• Column Visibility — show or hide table columns (also available by right-clicking any column header)
• Reset — start fresh by clearing play counts, playlists, and settings. Your music files are never touched.

Keyboard Shortcuts

Action	Shortcut
Next Track	Cmd+Right
Previous Track	Cmd+Left
Volume Up	Cmd+Up
Volume Down	Cmd+Down
Toggle Shuffle	Cmd+=
Toggle Repeat	Cmd+R
Toggle Sidebar	Cmd+S
Toggle Full Screen	Ctrl+Cmd+F

hihat also responds to media keys on your keyboard and Bluetooth headphones, and integrates with the macOS Now Playing widget for play/pause, skip, and previous controls.

(back to top)

Tips

• Click the song name in the player bar to scroll back to the currently playing track
• Try resizing the window — hihat adapts to all sorts of sizes, including a compact view at narrow widths
• Use Cmd+Click or Shift+Click to select multiple tracks for bulk operations
• Check the hihat menu in the menu bar for library stats

(back to top)

Roadmap

• Edit song metadata
• Queue a next-up song
• Ability to Change Audio Outputs

See the open issues for a full list of proposed features and known issues.

(back to top)

Built With

• 
• 
• 
• 
• 
• 
• 
• 
• 

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

Getting Started as a Contributor

Prerequisites

• Node v22+

  brew install nvm
  nvm install 22
  nvm use 22

• npm v10+

  npm install npm@latest -g

Installation

1. Clone the repo

   git clone https://github.com/johnnyshankman/hihat.git

2. Install dependencies

   npm install

Available Scripts

npm run start          # Dev mode with hot reload
npm run build          # Production build (main + renderer)
npm run lint           # ESLint check
npm run lint:fix       # ESLint auto-fix
npm run typecheck      # TypeScript type checking
npm run test           # Jest unit tests
npm run test:e2e       # Playwright E2E tests
npm run package        # Build + package Electron app

(back to top)

Looking for Something Like WinAmp?

I highly suggest Aural for that experience! It's no longer in development but works perfectly.

Looking for Windows support?

How'd you end up here? MusicBee is great and free but is not open source.

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Johnny aka White Lights - @iamwhitelights

Project Link: https://github.com/johnnyshankman/hihat

(back to top)