NekoBeat is a real desktop app, not a website wrapped in Electron. Playback runs through GStreamer in Rust. The UI is React on Tauri v2. Search and stream from YouTube, SoundCloud, and Spotify in one place.
Features
Universal search and streaming
Search and stream from YouTube, SoundCloud, and Spotify in one UI. Streams are resolved with a custom scraping path and yt-dlp as fallback.
Offline library
Liked tracks are cached on disk so they keep playing when you are offline.
10-band equalizer
A GStreamer equalizer in the Rust audio pipeline: 10 bands from 31 Hz to 16 kHz, adjustable while music is playing.
Synchronized lyrics
Lyrics are fetched automatically (Genius and related sources). You can also upload .lrc / .srt / .vtt, tweak per-track timing offset, and keep them stored for later.
YouTube video sync
For YouTube tracks, the video can play in an embedded window in sync with the audio.
Discover (Listen Now)
Last.fm trending tracks show up on Listen. One click sends a title into search.
Discord Rich Presence
Title, artist, remaining time, and art show on your Discord profile. The Rust backend owns that path.
Auto-updater
In-app update check and install via the Tauri updater plugin and signed releases.
Picture-in-picture miniplayer
Small always-on-top player with art, track info, and controls. Drag by clicking anywhere. Shrink or expand with one click.
Media session integration
Windows SMTC and macOS Now Playing: play, pause, next, previous, seek.
Architecture
| Layer | Technology |
|---|
| Core | Rust |
| Framework | Tauri v2 |
| Frontend | React + TypeScript |
| Styling | Tailwind CSS |
| Animations | Framer Motion |
| Audio engine | GStreamer |
| Stream resolution | Custom scraping + yt-dlp fallback |
| Database | SQLite (rusqlite) |
| Lyrics | Genius API scraping |
Installation
Windows (recommended)
Install with winget for updates:
winget install NekoBeat
Or grab a build from Releases:
NekoBeat_x64-setup.exe (portable installer)NekoBeat_x64.msi (system-wide)
> The Windows installer already includes GStreamer. You do not need to install it yourself.
Other platforms
- macOS: download from Releases
- Linux:
.deb / AppImage from Releases
- Android: local Library, Liked, queue, lyrics, artwork, and MediaStyle controls are available. Online Listen/Browse remains off by default and can be enabled only when the installed APK passes its local streaming capability checks; Settings also provides an optional no-autoplay connectivity smoke test.
Build from source
CI / GitHub Actions
| Workflow | When | What |
|---|
| CI | push / PR to main | Frontend build + Linux cargo check |
| Build all platforms | push to main, or Actions → Run workflow | Windows / Linux / macOS installers + Android APK → Artifacts |
| Release | tag v* or Run workflow | Signed desktop + APK uploaded to a GitHub Release |
Secrets for signed releases: TAURI_SIGNING_PRIVATE_KEY, TAURI_SIGNING_PRIVATE_KEY_PASSWORD, optional ANDROID_KEYSTORE_*.
Do not commit: cookies.txt, .tauri/*.key, src-tauri/gstreamer/ (staged in CI), yt-dlp binaries, *.apk, or libnekobeat_lib.so.
Prerequisites:
git clone https://github.com/nishal21/NekoBeat.git
cd NekoBeat
npm install
npm run tauri dev
Build a release
# Signed Windows installer
.\scripts\build-release.ps1
That produces signed .exe and .msi installers plus .sig files for the auto-updater.
Project structure
nekobeat/
├── src/ # React frontend
│ ├── App.tsx # Main application
│ └── hooks.ts # Custom React hooks
├── src-tauri/
│ ├── src/
│ │ ├── main.rs # Entry point & GStreamer init
│ │ ├── lib.rs # Tauri command registration
│ │ ├── audio.rs # GStreamer playback engine
│ │ ├── aggregator/ # Search, resolve, Spotify, SoundCloud
│ │ ├── offline.rs # Local caching & liked songs
│ │ └── library.rs # SQLite database operations
│ ├── gstreamer/ # Bundled GStreamer runtime
│ └── binaries/ # External tools (spotiflac-cli)
└── scripts/
├── build-release.ps1 # Signed release builder
└── publish-update.ps1 # Update manifest generator
Acknowledgments
NekoBeat borrows ideas and patterns from these projects:
- Harmonoid — local library and lyrics UX patterns we studied early on
- Muffon — multi-source streaming client; aggregation shape
- Muffon API — backend patterns for multi-source search
- SpotiFLAC — optional desktop Spotify to lossless helper; Android uses NekoBeat's streaming resolver without a Go runtime
- Spotify Lyrics API — synced lyrics from Spotify
- MusicXMatch API — Musixmatch wrapper used during lyrics work
Thanks to everyone who maintains those projects.
Community and support
Star history
> If NekoBeat is useful to you, a star on the repo helps a lot.
License
NekoBeat is licensed under the PolyForm Noncommercial License 1.0.0 (SPDX: PolyForm-Noncommercial-1.0.0).
Required notice: Copyright (c) 2026 Nishal (https://github.com/nishal21)
In plain terms:
- You may use, study, fork, and change NekoBeat for personal and other noncommercial purposes.
- You may share forks and builds under the same terms.
- You may not use NekoBeat (or a modified version) for commercial purposes without a separate written license from the copyright holder.
- Commercial use includes selling the app, bundling it in a paid product, monetizing it with ads or subscriptions, or using it as part of a business offering.
Full text lives in LICENSE and at polyformproject.org.
Made with care by Nishal
"Music is the wine that fills the cup of silence."
