Psychotoxical-psysonic/README.md

Psysonic

A modern, gorgeous, and blazing fast desktop client for Subsonic API compatible music servers (Navidrome, Gonic, etc.).

---

Psysonic is a beautiful desktop music player built completely from the ground up for the modern era. Utilizing Tauri v2 and React, it offers a native-feeling, lightweight, and incredibly fast experience with a stunning UI inspired by the Catppuccin and Nord aesthetics.

Designed specifically for users hosting their own music via Navidrome or other Subsonic API servers, Psysonic aims to be the best way to interact with your personal library.

✨ Features

• 🎨 Gorgeous UI: 21 deeply integrated themes — Catppuccin, Nord, Retro (Gruvbox), Tokyo Night, and Psysonic originals (Classic Winamp, Poison, Nucleo, Psychowave) — with smooth glassmorphism effects and micro-animations.
• ⚡ Blazing Fast: Built with Rust & Tauri — native audio engine (rodio), minimal RAM usage compared to typical Electron apps.
• 🌍 Internationalization (i18n): Fully translated into English, German, French, and Dutch.
• 📻 Live "Now Playing": See what other users on your server are currently listening to in real-time.
• 🎵 Last.fm Integration (Beta): Direct scrobbling, Now Playing updates, love/unlove, Similar Artists, and top stats — no Navidrome configuration required.
• 💾 IndexedDB Caching: Ultra-fast loading times with persistent IndexedDB image caching for cover art and artist images.
• 📀 Album Downloads: Support for downloading entire albums directly to your local machine.
• 💿 Album & Artist Views: Beautiful grid displays and detailed artist pages with related albums and color-coded initial avatars for fast browsing.
• 〰️ Waveform Seekbar: Canvas-based waveform with a blue-to-mauve gradient and glow effect — click or drag anywhere to seek.
• 🌊 MilkDrop Visualizer: Full-screen Butterchurn/MilkDrop visualizer in the Ambient Stage with hundreds of presets and smooth transitions.
• 🎛️ Queue Management: Drag & drop reordering, shuffle, playlist saving/loading, and server-side queue synchronization.
• 🎼 Random Mix: Generate a random playlist from your entire library. Filter by keyword or pick a Super Genre (Metal, Rock, Electronic, Jazz…) for a focused mix with progressive loading.
• 🔄 Update Notifications: Built-in update checker (on startup + every 10 minutes) that notifies you when a new version is available on GitHub.
• 🖥️ Cross-Platform: Available natively for Windows, macOS, and Linux (including Wayland support).

🗺️ Roadmap

✅ Completed

• Native Rust/rodio audio engine (replaces Howler.js)
• 10-band graphic EQ with built-in and custom presets
• Crossfade between tracks
• Replay Gain (track + album mode)
• Gapless playback (experimental)
• MilkDrop/Butterchurn visualizer
• Waveform seekbar
• Last.fm scrobbling, Now Playing & love/unlove (beta)
• Similar Artists via Last.fm, filtered to library
• Statistics — Last.fm top charts & recent scrobbles
• Multi-server support
• IndexedDB image caching
• Random Mix with keyword filter & Super Genre mix
• 21 themes: Catppuccin, Nord, Retro (Gruvbox), Tokyo Night, Psysonic originals (Classic Winamp, Poison, Nucleo, Psychowave)
• Internationalization (English, German, French, Dutch)
• AUR package (Arch / CachyOS)

🚧 In Progress

• Last.fm integration — stabilising, moving out of beta
• Gapless playback — edge case stabilisation
• Crossfade — stability improvements

📋 Planned

• FLAC seeking fix
• General UI polish & visual refinement
• More languages

---

● Known Limitations

• Linux (drag & drop cursor feedback): Due to a WebKitGTK limitation, the drag cursor does not reflect the drop operation type — it may appear as a "forbidden" symbol or show no indicator at all, depending on the desktop environment. Drag and drop itself works correctly.
• FLAC seeking: Jumping to a position in a FLAC file via the waveform seekbar currently does not work. Seeking in MP3, OGG, and other formats is unaffected. This is a known issue and will be investigated.

📥 Installation

Navigate to the Releases page and download the installer for your operating system.

• Windows: .exe or .msi
• macOS: .dmg (Universal or Apple Silicon)
• Linux (Ubuntu/Debian): .deb from GitHub Releases
• Linux (Fedora/RHEL): .rpm from GitHub Releases
• Linux (Arch/CachyOS): AUR — yay -S psysonic or paru -S psysonic

The AUR package builds from source using your system's own WebKitGTK — no bundled libs, no EGL/Mesa compatibility issues.

🚀 Getting Started

1. Download and install Psysonic.
2. Open the app and enter your Subsonic/Navidrome server details (URL, Username, Password).
3. If applicable, you can provide both an external URL and a local LAN IP. Psysonic allows you to quickly toggle between them in the Settings.
4. Enjoy your music!

🛠️ Development

If you want to build Psysonic from source or contribute to the project:

Prerequisites

• Node.js (v18+)
• Rust (v1.75+)
• OS-specific build dependencies for Tauri (see the Tauri prerequisites guide).

Setup

# Clone the repository
git clone https://github.com/Psychotoxical/psysonic.git
cd psysonic

# Install node dependencies
npm install

# Run in development mode
npm run tauri:dev

# Build for production
npm run tauri:build

🤝 Contributing

Contributions are completely welcome! Whether it is translating the app into a new language, fixing a bug, or proposing a new feature.

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

📄 License

Distributed under the GNU General Public License v3.0. See LICENSE for more information.

This means: you are free to use, study, and modify Psysonic. If you distribute a modified version, you must release it under the same GPL v3 license and keep the original copyright notice intact. You may not incorporate this code into proprietary software.