咲く, Let your music bloom

A web based audio player with AutoEq compatible 10 band parametric equalizer, built with ReactJS.

Audio Player	Playlist

Live Demo

I move between multiple development environments and rotate through different headphones, which means every listening session wants a new parametric EQ workflow. On Windows I rely on Equalizer APO. On macOS I juggle BlackHole and host AU. When I fall back to DAC control panels like Qudelix or FiiO I lose the moment I leave that hardware behind. The constant swapping wastes time and fractures the experience.

Saku Audio Player is born to scratch that itch for me. I wanted something that never asks for an installer, a login, or a network round trip. My music library is synced on NAS and accessible for me in my machines, or in a usb drive, and Saku lets me bring my own music, process everything with client side tools, and keep every decibel adjustment private to the browser.

Building it showed another gap as well. The npm ecosystem still lacks a light 10-band PEQ library, so this project is the path toward modularizing the equalizer and packaging it for others. The same code will power a browser extension that can import AutoEQ ParametricEQ presets and apply a real 10-band curve anywhere.

In a world where access keeps drifting toward subscriptions and remote servers, I would rather keep the listening chain local. Saku is a bring your own music solution that puts control of the audio stack back in the listener’s hands.

• Now support all 8,850 AutoEq Parametric EQ presets search and download via Github API! No longer have to parse through the AutoEq Github repository manually.
• Directory drag and drop addition support added.

• High-quality audio playback with Web Audio API
• Support for MP3, FLAC, M4A, WAV, AAC, OGG formats
• Drag and drop audio file import
• Waveform visualization with scrubbing
• Volume control with mute functionality
• Track navigation and playlist management

• 10-band parametric EQ with real-time processing
• Professional frequency response visualization
• Auto-preamp calculation to prevent clipping
• Real-time clipping monitor with visual feedback
• EQ bypass toggle for A/B comparison

• Comprehensive preset library system
• AutoEQ compatibility with ParametricEQ.txt import/export
• Multiple export formats: JSON, AutoEQ text, PowerAmp XML, Qudelix JSON
• Local storage persistence
• Preset deletion with confirmation dialogs

• Responsive design with modal interfaces
• Dual theme system (light for playlist, dark for EQ)
• Comprehensive keyboard shortcuts for power users
• Mobile-friendly touch controls
• Accessibility compliant interface

• UI Clean up and Consistency

  • Font consistency
  • PEQ Panel theme consistency and font consistency
  • Playlist margin and track item handling

• UX Revamp for more consistent experience on both Mobile and Browser

  • playlist responsive
  • PEQ responsive
  • Keyboard shortcut modal
  • Player responsive (vertical)

• Playlist management enhancements

  • remove individual track
  • drag and move track order
  • Repeat modes (currently repeat all by default)
  • Drag and Drop directory addition for tracks

• Consolidate PEQ import

• AutoEq Search Integration I went through with general AutoEq Github API integration. Initially was going to use full tree scan for the AutoEq directory, but instead just went with local index generation with spare cloned repo, and only use the API for import/download.

• Mobile Support

• PEQ modularization

  • Extract PEQ to a separate library
  • Typescript support

• Electron App for Desktop usage

• Arrow Left: Skip backward 10 seconds
• Arrow Right: Skip forward 10 seconds
• Arrow Up/Down: Volume up/down
• A: Add track to playlist
• B: Previous track
• N: Next track
• M: Mute/unmute (preserves volume level)
• Space: Play/pause
• E: Open/close EQ panel
• P: Open/close playlist panel

• Shift + Arrow Keys: Navigate EQ presets
• T: Toggle EQ bypass
• R: Reset EQ to flat response
• Esc: Close modals (save preset, keyboard shortcuts)

1. Clone the repository

git clone https://github.com/seungkilee-cs/saku-audio-player.git
cd saku-audio-player

2. Install dependencies

npm install

3. Start development server

npm run dev

4. Open http://localhost:5173 in your browser

npm run build

The built files will be in the dist directory.

npm run deploy

Deploys to GitHub Pages using the configured homepage URL.

Refer to the full regression strategy in docs/test/regression-testing.md.

npm run test

Runs Vitest/Jest-based suites (React Testing Library, MSW mocks). Use npm run test -- --watch for incremental feedback.

npx playwright test

Executes Playwright scenarios across Chromium and Firefox. Ensure the dev server is running (npm run dev) or configure the Playwright webServer setting.

Add GitHub Actions workflow steps to execute both commands above (npm run test, npx playwright test) on each pull request for regression coverage.

1. Drag audio files onto the player or use the playlist modal to add tracks
2. Use playback controls or keyboard shortcuts to control audio
3. Adjust volume with the volume slider or arrow keys

1. Press E or click the EQ button to open the parametric equalizer
2. Adjust frequency bands by dragging sliders or entering precise values
3. Use presets from the dropdown or import your own AutoEQ files
4. Toggle bypass with T key to compare processed vs unprocessed audio
5. Monitor the clipping indicator to avoid distortion

1. Open the EQ modal and click Import
2. Select files in supported formats:
   • AutoEQ ParametricEQ.txt files
   • JSON preset files
   • PowerAmp XML files
   • Qudelix JSON files
3. Presets are automatically saved to your local library

AutoEQ provides scientifically measured EQ presets for thousands of headphones and earphones. Here's how to get them:

1. Visit the AutoEQ Results Repository
2. Navigate to your headphone manufacturer folder
3. Find your specific headphone model
4. Download the ParametricEQ.txt file from the model folder
5. Import the file directly into Saku Audio Player

1. Go to AutoEQ.app (if available)
2. Search for your headphone model
3. Download the parametric EQ file in json
4. Import into Saku Audio Player

1. Install AutoEQ: pip install autoeq
2. Obtain frequency response measurements for your headphones
3. Run AutoEQ to generate compensation curve:

   python -m autoeq --input_dir=measurements --output_dir=results

4. Use the generated ParametricEQ.txt file

AutoEQ ParametricEQ.txt files should contain lines like:

Filter 1: ON PK Fc 105 Hz Gain -2.1 dB Q 0.7
Filter 2: ON PK Fc 2300 Hz Gain -1.8 dB Q 2.0
Preamp: -2.1 dB

Saku Audio Player automatically parses these files and converts them to the internal format.

1. Configure your desired EQ settings
2. Click Export in the EQ modal
3. Choose your preferred format
4. Save the file for use in other applications

• Built with React 19 and Vite
• Web Audio API for real-time audio processing
• Context-based state management
• Local storage for preset persistence

• 10-band parametric EQ using BiquadFilterNode
• Real-time frequency response calculation
• Automatic preamp adjustment to prevent clipping
• AnalyserNode-based clipping detection

• Chrome 66+ (recommended)
• Firefox 60+
• Safari 14+
• Edge 79+

• Less than 1% CPU overhead for EQ processing
• Responsive design for Web and mobile view
• Efficient memory usage with cleanup on component unmount

GPL3 License. See the repository for license details.

• AutoEQ project for headphone measurement data compatibility
• PowerAmp android app for the inspiration
• Web Audio API community for technical guidance