Axion

An offline, production-quality desktop music player built with Electron + React + TypeScript.

• App: Axion
• Developer: almostkoi
• appId: com.almostkoi.axion

Features

• Auto-scan of the OS Music folder on every launch (~/Music, C:\Users\<user>\Music, or ~/Music)
• Live filesystem watching via chokidar — new files appear without restart
• Supported formats: MP3, FLAC, AAC, M4A, OGG, WAV, OPUS
• Full metadata extraction with embedded artwork, including ReplayGain and USLT/SYLT lyrics
• Local SQLite library (via better-sqlite3) with play counts, like status, listen history
• YouTube Music-styled dark UI (red accent, sidebar + bottom player bar)
• Home, Songs, Albums, Artists, Playlists, Search, Queue, Stats, Settings pages
• Full playback engine over the Web Audio API with:
  • Gapless preloading via dual <audio> elements
  • Configurable 0–12 s crossfade
  • ReplayGain (track + album) applied as gain adjustment
  • 10-band biquad EQ with built-in presets + custom presets + live curve visualization
  • Playback speed 0.5×–2.0× with pitch preservation
  • Selectable audio output device (setSinkId)
• Shuffle / repeat (off / all / one) / volume / mute
• Queue with drag-reorder, history, save-queue-as-playlist
• Liked songs auto-playlist, smart playlists (rule JSON), M3U import/export
• Real-time fuzzy search over title / artist / album / genre
• Lyrics view (embedded tags + .lrc sidecar with timestamp-sync highlight)
• Now Playing full-screen view with blurred-art background
• Mini player window (always-on-top, frameless)
• System tray with play / pause / next / prev / show / quit
• System media keys via Electron globalShortcut
• OS notifications on track change (with artwork)
• Track + bulk tag editor (writes ID3 tags for MP3 via node-id3; DB updated for all formats)
• Right-click context menus on every track
• Stats page: top songs/artists, genre pie chart, 180-day add heatmap, listening heatmap
• Five accent colors (Red, Blue, Green, Purple, Orange)

Getting Started

# 1) Install dependencies (also generates app icons and rebuilds native modules)
npm install

# 2) Compile TypeScript (main process + renderer bundle)
npm run build:ts
npm run build:renderer
# (Or combined:)
# npm run build:all

# 3) Launch Axion
npm start

Build installers

npm run build          # current platform
npm run build:win      # NSIS + portable EXE → release/Axion-Setup-1.0.0-*.exe
npm run build:mac      # DMG + ZIP
npm run build:linux    # AppImage + deb

Notes on native modules

better-sqlite3 is a native Node addon and must be compiled against Electron's exact V8 headers.

• This project runs electron-builder install-app-deps automatically via the postinstall script, which performs the rebuild for you.
• If you switch Electron versions or see a NODE_MODULE_VERSION mismatch, run:

  npm run rebuild

First launch

1. On first launch, Axion seeds its Settings with a single watched folder: your OS Music folder.
2. A background scan starts immediately. Album/song cards appear as tracks are parsed.
3. Add extra folders in Settings → Library → + Add folder.

Project layout

axion/
├── main.ts                 # Electron main process
├── preload.ts              # Secure contextBridge (exposes window.axion)
├── src/
│   ├── App.tsx             # Routing + modal host
│   ├── main.tsx            # Renderer entry
│   ├── index.html
│   ├── styles/global.css   # Tailwind + CSS variables
│   ├── types/
│   │   ├── index.ts        # Track, Album, Artist, Playlist, Settings, …
│   │   └── ipc.ts          # Typed IPC contract (AxionAPI)
│   ├── utils/
│   │   ├── db.ts           # better-sqlite3 queries   (main-only)
│   │   ├── scanner.ts      # walker + chokidar watcher (main-only)
│   │   ├── metadata.ts     # music-metadata + node-id3 (main-only)
│   │   └── format.ts       # Pure formatters (shared)
│   ├── store/useStore.ts   # Zustand global store
│   ├── hooks/
│   │   ├── useAudioEngine.ts
│   │   ├── useLibrary.ts
│   │   └── useKeyboard.ts
│   ├── components/ …        # Sidebar, PlayerBar, NowPlaying, TrackRow, …
│   └── pages/ …             # Home, Songs, Albums, Playlists, Stats, Settings …
├── scripts/
│   └── generate-assets.cjs # Creates assets/icon.png + tray-icon.png
└── assets/                 # Populated by postinstall

Keyboard shortcuts

Key	Action
Space	Play / Pause
Left	Previous (or seek back 5 s if > 3 s into track)
Right	Next
Up / Down	Volume ± 5 %
M	Mute toggle
S	Shuffle toggle
R	Cycle repeat mode
Ctrl / Cmd + L	Like current track
Ctrl / Cmd + K	Focus search
Ctrl / Cmd + M	Toggle mini player
Ctrl / Cmd + Q	Quit

Data locations

• Library database: <app userData>/axion.db (SQLite WAL)
  • macOS: ~/Library/Application Support/Axion/axion.db
  • Windows: %APPDATA%\Axion\axion.db
  • Linux: ~/.config/Axion/axion.db

License

Axion Source-Available License v1.0 © 2025 almostkoi See LICENSE for the full text.

In short:

• Personal & non-commercial use is free. Modify it, fork it, run it on your own devices.
• Public showcase (videos, streams, blog posts, screenshots, derivative apps) requires visible credit: name the project Axion, credit almostkoi, and link back to the source.
• Commercial use (selling, paid hosting, monetised tutorials whose primary subject is Axion, bundling into for-profit products, etc.) is not permitted without a separate written commercial license from the author. Contact koi@shusui.dev to discuss commercial licensing.

Third-party libraries bundled with Axion remain under their own licenses (MIT/Apache/BSD/etc.) and are unaffected by the terms above.