hihat

The minimalist offline music player for audiophiles on OSX

Report Bug · Request Feature · Downloads

Table of Contents

1. About The Project
   • Core Features
   • Supported Audio and Metadata Formats
2. Usage
   • Installing hihat
   • First Time Setup
   • Playing Songs
   • Importing Songs
   • Rescanning Your Library
   • Filtering Your Library
   • Sorting Your Library
   • Tips
3. Updating hihat to latest version
4. Feature Roadmap
5. Contributing
6. License
7. Contact

About The Project

hihat was born out of frustration with the lackluster offline music players available for OSX today.

Ever tried Cog, Swinsian, Plexamp, DeaDBeeF VLC, etc? They're okay... but they're all missing key features & don't nail the sleek feel of iTunes circa 2002.

That's why I decided to create hihat - a free, open-source music player that ditches ads, respects your privacy, and works perfectly without an internet connection.

All wrapped up in a minimalist dark-mode design that's easy on the eyes during late night listening sessions.

(back to top)

Core Features

hihat core features:

• 100% offline
• free
• dark mode
• audiophile fidelity (supports all codecs)
• mix 'n match file types in one library
• limitless library size
• responsive design
• true gapless playback
• iTunes-like Browser and Library Explorer
• smart sort by song, artist, and album
• fast imports
• song shuffle
• song repeat
• media key/keyboard integration
• OSX menu bar integration
• bluetooth headphone integration
• playcount tracking
• quick library search
• library stats
• simple album art download
• smart library deduplicator
• nested folder support (finds all music files)
• legacy iTunes library importing
• find on Apple Music and Spotify in one click
• backup your library to anywhere

(back to top)

Supported Audio and Metadata Formats

Almost every format under the sun is supported, and they can all be mixed together into the same library seamlessly.

Just to name a few:

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

Audio files which cannot contain album art metadata will not display album art (such as WAV). Video files and AAX audiobooks are not supported.

If you'd like to see more detailed information, check out:

• The Chromium Project for info on supported audio formats.
• Music Metadata library for supported metadata formats.

Don't know where to download files of your favorite albums and tracks? I suggest:

• tidal-media-downloader (Works with Tidal)
• spotify-downloader (Works with Spotify and Youtube Music)

(back to top)

Usage

Installing hihat

1. Download the .dmg file of your choosing from our Latest Release
2. Double click it to open the contents, then drag the hihat application into your Apps folder

You are now all set.

Warning: The first time you open hihat OSX will warn you that it's from an unidentified developer and ask you to confirm you want to open hihat. Confirm. This warning is why the application is free, I do not pay for a BS Apple Developer License just to remove this dialog.

First Time Setup

1. Click the "Select Library Folder" button.
2. Choose the folder on your computer where you store your music library.
3. Wait for the import process to complete (about 1 minute per 10,000 songs).
4. You're all set! Your music library is now ready to use.

Playing Songs

• Double click on a song to play it
• Use the playback controls at the bottom of the app to pause, skip, adjust volume, shuffle, or enable song-repeat.

Importing Songs

1. Click the "+" icon in the top right corner of hihat.
2. Select the songs or folders of songs you want to add.
3. hihat will copy these files into your library folder (and intelligently ignore all non-music files)

Rescanning Your Library

If you've added songs to your library manually, hihat will not see them. To scan them in:

1. Go to the hihat menu.
2. Select "Rescan Library Folder".
3. hihat will update its database with any new songs while preserving play counts and dates for existing tracks.

Filtering Your Library

There is a search bar in the top right for searching through your library.

Sorting Your Library

By clicking on the table headers of your library, you can sort by:

• Song
• Album Artist
• Album
• Duration
• Date Added
• Playcount

Using the Media Session

OSX has a built in player for quickly accessing the play, pause, skip, and previous functions of hihat. You can access it via the play button icon in the top bar of OSX, or the side panel in OSX.

Alternatively, you can use any keyboard or bluetooth headphones to access these controls. hihat should respond to media commands just like any other native OSX application does!

Tips

• Right-click on a song for more options, like lookup on Spotify and Delete
• Right-click on the album art for more options, like Download or Copy to Clipboard
• Explore the hihat menu for features like backing up your library or deduplicating your library
• Click on the song name in the player to scroll back to the current song
• Click on the album art to scroll back to the current song
• Try resizing the window, it fits all sorts of sizes!

(back to top)

Updating hihat to latest version

Updating hihat is simple and ensures that you keep your library and all your settings intact. Follow these steps to update hihat:

1. Download the Latest Version:

   • Visit our Releases page and download the latest version of the .dmg file for hihat.

2. Mount the DMG File:

   • Double-click the downloaded .dmg file to open it. This will mount the disk image on your Mac.

3. Replace the Existing App:

   • In the opened window, drag and drop the hihat icon into the /Applications folder. If prompted, confirm to replace the existing application.

4. Launch the Updated App:

   • Go to your /Applications folder and run hihat. Your settings and configurations from previous versions will remain intact.

Important Note

• Preserved Settings: Your library and all your settings are stored in a separate directory from the application itself, and therefore will not be affected by the update process!

If you encounter any issues during the update process, please refer to our Issues page for assistance.

Built With

This project was built with the following technologies:

• 
• 
• 
• 
• 
• 
• 
• 
• 

(back to top)

Feature Roadmap

• Autoplay Next Song
• Virtualized Lists for opitmal rendering
• Cache imported songs from previous session
• Minimalist search/filter solution
• Recursive file finding for itunes-like libraries with nested folders
• Update/import skips pre-existing files
• On reboot, scroll to last played song, queue it up as well
• Shuffle songs
• Repeat song
• Resort by column
• When deleting/hiding a song don't lose user's place
• Support keyboard previous/next
• Fix the player UX on thin windows (400px)
• OSX song info in the menu bar tray thing
• Copy album art for sharing
• Download album art for sharing
• Ability to "open in finder" so you can see the song file
• Redo player UX on small screens, it's function over fashion atm
• Insert new songs or albums without reimporting the whole library
• Click on song info to scroll back to it
• Shareable Spotify search links
• Shareable Apple Music search links
• Sort by date added
• Playcount tracking and sort by playcount
• Ability to "hide" songs you don't want to see, with or without deleting their file in filesystem
• Ability to deduplicate identical songs in library easily
• Ability to delete entire albums of songs from library and filestystem
• Adjustable column widths for songname, artist, and album
• Sort by albumartist not the plain old artist, pretty much only used by rap albums with features (2Pac - All Eyez On Me)
• Adjustable album art size
• Shuffle "history" for hitting previous
• Mute and max buttons
• Show stats about your library somewhere, like GB and # of songs
• iTunes-like browser with list of artist and album filters
• Quiet mode creating bg music to a video/audiobook/podcast in another app
• True gapless playback
• Edit song metadata
• Hide/show columns in the Library List
• Queue a next-up song
• Smart playlists (Top 50, Recently Played, Recently Added)
• User defined playlists

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

(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

Follow the steps below to install the local development environment and serve the development application locally.

Prerequisites

• node v20

  brew install nvm
  nvm install v20
  nvm use v20

• npm v10 or higher

  npm install npm@latest -g

Installation

1. Clone the repo

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

2. Install NPM packages

   npm install

Running Local App

1. Run the app in development with hot reloading

   npm run start

(back to top)

License

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

(back to top)

Contact

Johnny aka White Lights - @iamwhitelights

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

(back to top)