Harmony

Description

Harmony is a music manager designed specifically for old-school DJs. It allows you to organize and manage your music collection efficiently.

Features

• 🎵 Easy music management with automated tasks
• 📋 Playlist creation and organization
• ⚡ High-performance drag & drop - Instant track reordering (< 10ms) and adding tracks to sidebar playlists
• 🎨 Custom drag ghost showing track information
• 🔄 Automatic background synchronization
• 🔗 Track URLs - Store and access track pages from Beatport, Traxsource, and Bandcamp
• 🎧 Intuitive interface designed for DJs
• 🎹 OpenKey Harmonic Mixing - Track keys are automatically formatted and visually color-coded according to the OpenKey standard for seamless harmonic mixing

Recent Updates (v0.32.1)

• 🐛 Pre-Cue Playback Fix - Resolved an issue where playback would skip incorrectly by properly applying the pre-cue position dynamically and cleaning up event listeners to prevent memory leaks.

Screenshots

📸 Click to view screenshots

Main Library View

Manage your entire music collection with powerful search and filtering capabilities.

Track Detail View

Edit track metadata, find tag candidates from Beatport/Traxsource/Bandcamp, replace files, and manage ratings.

Duplicate Finder

Identify and manage duplicate tracks in your collection with advanced comparison tools.

Beatport Recommendations

Get track recommendations from Beatport

Tech Stack

• Desktop Framework: Electron with TypeScript
• Frontend: React 18 + Vite + Mantine UI
• State Management: Zustand
• Database: Drizzle ORM + SQLite (better-sqlite3)
• Build Tools: electron-vite, electron-builder
• Package Manager: pnpm

Recommended IDE Setup

• VSCode + ESLint + Prettier

Project Setup

Install

pnpm install

Development

pnpm run dev             # Start development mode with hot reload
pnpm start               # Preview built app

Build

# For windows
pnpm run build:win

# For macOS
pnpm run build:mac

# For Linux
pnpm run build:linux

# Current platform
pnpm run build

# Production release
pnpm run release

Code Quality

pnpm run lint            # ESLint with auto-fix
pnpm run format          # Prettier auto-format all files
pnpm run typecheck       # Run both node + web type checks

Testing

pnpm test                # Run tests in watch mode
pnpm run test:run        # Run all tests once (CI mode)
pnpm run test:ui         # Open Vitest UI
pnpm run test:coverage   # Run tests with coverage report

Documentation

• AGENTS.md - Complete project documentation, code style, architecture, available skills
• .agents/skills/ - Specialized AI skills for Electron, React, Mantine, Zustand, code review, and more

Contributing

If you would like to contribute to Harmony, please follow these steps:

1. Fork the repository
2. Create a new branch (git checkout -b feature-branch)
3. Read AGENTS.md for code style guidelines, architecture notes, and best practices
4. Make your changes following the project conventions
5. Run pnpm run lint and pnpm run typecheck before committing
6. Commit your changes (git commit -m 'Add new feature')
7. Push to the branch (git push origin feature-branch)
8. Open a pull request

Code Style

• Import organization: Node/Electron built-ins → External packages → Internal modules → Relative imports
• Formatting: Run pnpm run format (Prettier with single quotes, 120 line width)
• TypeScript: Use interfaces for objects, type aliases for unions, avoid any
• Logging: Use electron-log in main/preload (never console.*)
• Error handling: Always log errors, use try-catch for async operations

See AGENTS.md for complete guidelines.

License

This project is licensed under the MIT License. See the LICENSE file for details.