{"id":47240492,"url":"https://github.com/johnnyshankman/hihat","last_synced_at":"2026-05-09T01:14:32.674Z","repository":{"id":205540380,"uuid":"713249729","full_name":"johnnyshankman/hihat","owner":"johnnyshankman","description":"hihat is a free, open-source, and minimalist music player for macOS. It plays every major audio format with true gapless playback, manages local libraries of any size, all bundled in a sleek interface. No ads, no accounts, no internet required — just your music.","archived":false,"fork":false,"pushed_at":"2026-05-05T04:34:25.000Z","size":128063,"stargazers_count":18,"open_issues_count":7,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-05T04:35:39.147Z","etag":null,"topics":["audio-player","audiophile","electron","mac-app","material-ui","minimalist-design","music-player","react","tailwindcss","tanstack-table","typescript","zustand"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johnnyshankman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"custom":["https://www.paypal.com/ncp/payment/MUPN9Y2G7XN7C"]}},"created_at":"2023-11-02T06:15:51.000Z","updated_at":"2026-05-05T04:34:27.000Z","dependencies_parsed_at":"2023-12-30T19:21:05.666Z","dependency_job_id":"8049a691-6199-4cbc-9fff-46fb351ec8a9","html_url":"https://github.com/johnnyshankman/hihat","commit_stats":null,"previous_names":["johnnyshankman/hihat"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/johnnyshankman/hihat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnnyshankman%2Fhihat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnnyshankman%2Fhihat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnnyshankman%2Fhihat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnnyshankman%2Fhihat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johnnyshankman","download_url":"https://codeload.github.com/johnnyshankman/hihat/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnnyshankman%2Fhihat/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32803665,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"ssl_error","status_checked_at":"2026-05-08T08:22:45.650Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio-player","audiophile","electron","mac-app","material-ui","minimalist-design","music-player","react","tailwindcss","tanstack-table","typescript","zustand"],"created_at":"2026-03-14T02:18:33.919Z","updated_at":"2026-05-09T01:14:32.667Z","avatar_url":"https://github.com/johnnyshankman.png","language":"TypeScript","funding_links":["https://www.paypal.com/ncp/payment/MUPN9Y2G7XN7C"],"categories":[],"sub_categories":[],"readme":"\u003ca name=\"readme-top\"\u003e\u003c/a\u003e\n\n\u003cbr /\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/johnnyshankman/hihat\"\u003e\n    \u003cimg src=\"assets/icon.png\" alt=\"Logo\" width=\"80\" height=\"80\"\u003e\n  \u003c/a\u003e\n\n  \u003ch3 align=\"center\"\u003ehihat\u003c/h3\u003e\n\n  \u003cp align=\"center\"\u003e\n    The minimalist offline music player for macOS\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"https://github.com/johnnyshankman/hihat/releases/latest\"\u003eDownload\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/johnnyshankman/hihat/issues\"\u003eReport Bug\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/johnnyshankman/hihat/issues\"\u003eRequest Feature\u003c/a\u003e\n  \u003c/p\u003e\n  \u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://github.com/johnnyshankman/hihat/actions/workflows/build.yml/badge.svg\" alt=\"Build status\" width=\"105\" height=\"20\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/v/release/johnnyshankman/hihat?label=release\u0026color=success\" alt=\"Latest release\" height=\"20\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/downloads/johnnyshankman/hihat/total?label=downloads\u0026color=blue\" alt=\"Total downloads\" height=\"20\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/johnnyshankman/hihat?color=lightgrey\" alt=\"License\" height=\"20\"\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n![hihat main window showing dark-themed music library with sidebar, track list, and player bar](screenshots/hero-main-window.png)\n\n## Table of Contents\n\n1. [About The Project](#about-the-project)\n2. [Getting Started](#getting-started)\n    - [Installing hihat](#installing-hihat)\n    - [First Time Setup](#first-time-setup)\n    - [Updating hihat](#updating-hihat)\n3. [Features](#features)\n4. [Supported Audio Formats](#supported-audio-formats)\n5. [User Guide](#user-guide)\n6. [Roadmap](#roadmap)\n7. [Built With](#built-with)\n8. [Contributing](#contributing)\n9. [Getting Started as a Contributor](#getting-started-as-a-contributor)\n10. [License](#license)\n11. [Contact](#contact)\n\n## About The Project\n\n**hihat** is a free, minimalist, open-source music player for macOS. It plays every major audio format with true gapless playback, manages libraries of any size, and comes with a sleek responsive interface.\n\nNo ads, no accounts, no internet — just your music.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n## Getting Started\n\n### Installing hihat\n\n1. Download the `.dmg` file from the [Latest Release](https://github.com/johnnyshankman/hihat/releases/latest)\n2. Double-click the `.dmg` to open it, then drag **hihat** into your Applications folder\n\nThat's it — hihat is now installed and ready to use.\n\n\u003e **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.\n\n### First Time Setup\n\n1. Open hihat\n2. Click the **Settings** icon (gear) in the top-right corner of the sidebar\n3. Under **Music Folder**, click the folder icon to select the folder where you store your music\n4. Confirm you want to scan the folder\n5. Wait for the import to complete (about 1 minute per 10,000 songs)\n6. Your library is ready — start playing!\n\n![hihat first-time setup showing the Settings drawer with Library Location folder picker](screenshots/setup-library-location.png)\n\n### Updating hihat\n\nTo check whether a newer version is available, open the **hihat** menu in the macOS menu bar and choose **check for updates**. hihat will tell you if you're already on the latest version or point you to the new release.\n\nTo install an update:\n\n1. Download the latest `.dmg` from the [Releases](https://github.com/johnnyshankman/hihat/releases/latest) page\n2. Drag the new **hihat** into your Applications folder and confirm the replacement\n3. Open hihat — your library, playlists, play counts, and settings are all preserved\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n## Features\n\n**Library Management**\n* Import any folder structure — hihat finds all music files recursively\n* Smart deduplication on import (prefers higher-quality files)\n* Fast library scanning (~1 minute per 10,000 songs)\n* Edit metadata for any track — changes are written back to the audio file tags\n* Library stats: total songs, size in GB, total plays, and total hours (via the hihat menu)\n* Incremental library backup to any external drive\n\n**Playback**\n* True gapless playback\n* Shuffle with navigable history (up to 100 tracks)\n* Repeat modes: off, single track, or all\n* Play count tracking with duration-based threshold\n* Last Played date tracking\n\n**Organization**\n* User-created playlists — create, rename, delete, and add or remove tracks\n* Smart playlists: Recently Added, Recently Played, and Most Played (top 50 each, updated automatically)\n* Browser panel for filtering by album artist and album\n* Sort by any column\n* Quick search bar — filter by title, artist, album, or genre\n* Customizable column visibility — right-click any column header\n* Drag-and-drop column reordering\n* Drag and drop tracks to sidebar playlists\n* Per-view search filters preserved across navigation\n* Persistent sorting preferences per playlist\n* Persistent column widths\n\n**Interface**\n* Dark and Light themes\n* Mini Player mode — a floating window with album art\n* Frameless macOS-native window with traffic light controls\n* Collapsible sidebar navigation\n* Multi-select with bulk operations (Cmd+Click, Shift+Click)\n* Scrolling marquee for long track and artist names\n* Responsive design down to 540px\n\n**Integration**\n* macOS media keys, keyboard, and Bluetooth headphone support\n* macOS menu bar with playback controls and keyboard shortcuts\n* macOS Now Playing widget integration\n* Find on Spotify, Apple Music, and Tidal in one click\n* Download album art from any track\n* Show any track's file in Finder\n\n![hihat in light theme with Browser panel open at the top](screenshots/features-light-theme-artist-browser.png)\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n## Supported Audio Formats\n\nAlmost every format under the sun is supported, and they can all be mixed together in the same library:\n\n* MP3\n* MP4/M4A\n* AAC\n* WAV\n* FLAC\n* ALAC\n* Opus\n* Ogg Vorbis\n* PCM\n\nFor detailed format information, see:\n* [The Chromium Project](https://www.chromium.org/audio-video/) for supported audio formats\n* [Music Metadata](https://github.com/borewit/music-metadata#features) for supported metadata formats\n\n#### Limitations\n* hihat does not play online streams\n* hihat does not play protected content (M4P, AAX)\n* hihat does not display album art for formats that do not embed it (WAV)\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n## User Guide\n\nA full walkthrough of hihat's features — playback, playlists, browsing and search, the Mini Player, metadata editing, right-click actions, settings, keyboard shortcuts, and tips — lives in a separate document so this README stays focused on getting you up and running.\n\n**See the [hihat User Guide](USER_GUIDE.md)** for everything you can do once the app is open.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n## Roadmap\n\n- [x] Edit song metadata\n- [ ] Queue a next-up song\n- [ ] Ability to Change Audio Outputs\n\nSee the [open issues](https://github.com/johnnyshankman/hihat/issues) for a full list of proposed features and known issues.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n## Built With\n\n* [![Electron][Electron.js]][Electron-url]\n* [![React][React.js]][React-url]\n* [![Typescript][Typescript.js]][Typescript-url]\n* [![Google Material UI][MaterialUI.js]][MaterialUI-url]\n* [![zustand][zustand.js]][zustand-url]\n* [![TanStack Query][TanStackQuery.js]][TanStackQuery-url]\n* [![TanStack Table][TanStackTable.js]][TanStackTable-url]\n* [![Music Metadata][MusicMetadata.js]][MusicMetadata-url]\n* [![Gapless 5][Gapless5.js]][Gapless5-url]\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n## Contributing\n\nContributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.\n\nIf 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\".\nDon't forget to give the project a star! Thanks again!\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the Branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n## Getting Started as a Contributor\n\n### Prerequisites\n\n* Node v22+\n  ```sh\n  brew install nvm\n  nvm install 22\n  nvm use 22\n  ```\n\n* npm v10+\n  ```sh\n  npm install npm@latest -g\n  ```\n\n### Installation\n\n1. Clone the repo\n   ```sh\n   git clone https://github.com/johnnyshankman/hihat.git\n   ```\n2. Install dependencies\n   ```sh\n   npm install\n   ```\n\n### Available Scripts\n\n```sh\nnpm run start          # Dev mode with hot reload\nnpm run build          # Production build (main + renderer)\nnpm run lint           # ESLint check\nnpm run lint:fix       # ESLint auto-fix\nnpm run typecheck      # TypeScript type checking\nnpm run test           # Jest unit tests\nnpm run test:e2e       # Playwright E2E tests\nnpm run package        # Build + package Electron app\n```\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n## License\n\nDistributed under the MIT License. See `LICENSE` for more information.\n\n## Contact\n\nJohnny aka White Lights - [@iamwhitelights](https://twitter.com/iamwhitelights)\n\nProject Link: [https://github.com/johnnyshankman/hihat](https://github.com/johnnyshankman/hihat)\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- MARKDOWN LINKS \u0026 IMAGES --\u003e\n[contributors-shield]: https://img.shields.io/github/contributors/johnnyshankman/hihat.svg?style=for-the-badge\n[contributors-url]: https://github.com/johnnyshankman/hihat/graphs/contributors\n[forks-shield]: https://img.shields.io/github/forks/johnnyshankman/hihat.svg?style=for-the-badge\n[forks-url]: https://github.com/johnnyshankman/hihat/network/members\n[stars-shield]: https://img.shields.io/github/stars/johnnyshankman/hihat.svg?style=for-the-badge\n[stars-url]: https://github.com/johnnyshankman/hihat/stargazers\n[issues-shield]: https://img.shields.io/github/issues/johnnyshankman/hihat.svg?style=for-the-badge\n[issues-url]: https://github.com/johnnyshankman/hihat/issues\n[license-shield]: https://img.shields.io/github/license/johnnyshankman/hihat.svg?style=for-the-badge\n[license-url]: https://github.com/johnnyshankman/hihat/blob/master/LICENSE\n[React.js]: https://img.shields.io/badge/React-20232A?style=for-the-badge\u0026logo=react\u0026logoColor=61DAFB\n[React-url]: https://reactjs.org/\n[Electron.js]: https://img.shields.io/badge/Electron-20232A?style=for-the-badge\u0026logo=electron\u0026logoColor=61DAFB\n[Electron-url]: https://www.electronjs.org/\n[ElectronReactBoilerplate.js]: https://img.shields.io/badge/ElectronReactBoilerplate-20232A?style=for-the-badge\u0026logo=react\u0026logoColor=61DAFB\n[ElectronReactBoilerplate-url]: https://electron-react-boilerplate.js.org/\n[MusicMetadata.js]: https://img.shields.io/badge/MusicMetadata-20232A?style=for-the-badge\u0026logo=javascript\u0026logoColor=61DAFB\n[MusicMetadata-url]: https://github.com/borewit/music-metadata\n[MaterialUI.js]: https://img.shields.io/badge/MaterialUI-20232A?style=for-the-badge\u0026logo=mui\u0026logoColor=61DAFB\n[MaterialUI-url]: https://mui.com/material-ui/\n[Typescript.js]: https://img.shields.io/badge/Typescript-20232A?style=for-the-badge\u0026logo=typescript\u0026logoColor=007ACC\n[Typescript-url]: https://typescriptlang.org\n[zustand.js]: https://img.shields.io/badge/Zustand-20232A?style=for-the-badge\u0026logo=javascript\u0026logoColor=007ACC\n[zustand-url]: https://github.com/pmndrs/zustand\n[TanStackQuery.js]: https://img.shields.io/badge/TanStack_Query-20232A?style=for-the-badge\u0026logo=reactquery\u0026logoColor=FF4154\n[TanStackQuery-url]: https://tanstack.com/query\n[TanStackTable.js]: https://img.shields.io/badge/TanStack_Table-20232A?style=for-the-badge\u0026logo=javascript\u0026logoColor=007ACC\n[TanStackTable-url]: https://tanstack.com/table\n[Gapless5.js]: https://img.shields.io/badge/Gapless5-20232A?style=for-the-badge\u0026logo=javascript\u0026logoColor=007ACC\n[Gapless5-url]: https://github.com/regosen/Gapless-5\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnnyshankman%2Fhihat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnnyshankman%2Fhihat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnnyshankman%2Fhihat/lists"}