A fast, modern, privacy-focused local music player
AMUS is built for people who own their music library. It runs completely offline, stays lightweight, and feels like a modern desktop app — not a web wrapper.
- Wide format support — MP3, FLAC, WAV, OGG, M4A, AAC, OPUS (via rodio)
- Advanced queue — play next, drag-and-drop reorder, shuffle, and repeat
- Auto-regeneration — when the queue runs dry, similar tracks are suggested from artist/album match, play count, and randomness
- Background playback — keeps playing from the system tray when the window is closed
- Mini player — compact always-available window with art, track info, and controls
- Stop / pause / seek — full transport controls plus stop
- Fast incremental scanning — metadata extraction and cover art on scan
- Real-time file watcher — picks up added, modified, and deleted files automatically
- Playlists — create, rename, delete; add/remove tracks; custom or auto-generated cover art; quick “Add more” search on the playlist page
- Favorites — one-click toggle per track
- Artist metadata — automatic profile and banner images (Bing / DuckDuckGo)
- In-memory library cache — library loads once at startup for snappy browsing and fewer IPC round-trips
- Fuzzy global search — client-side Fuse.js with extended search patterns
- Type filters —
/tracks,/artists,/albums,/playlistsslash commands - Context menus — right-click tracks for play, queue, playlist, favorite, and more
- Keyboard shortcuts — app-wide and optional global media shortcuts (customizable)
- Playback history & stats — play counts, listening time, streaks, library growth, format distribution, hourly/weekday heatmaps, favorite trends
- System tray — play/pause, previous/next, show/hide, quit
- Auto-updater — updates from GitHub Releases (passive install on Windows)
- OS media controls — integrate with system media keys (MPRIS/SMTC/Now Playing)
- File associations — open audio files directly with AMUS
- Modern UI — custom title bar, themes, and a responsive library layout
Open global search and type normally for fuzzy matching, or use these extended patterns to refine results (powered by Fuse.js extended search). You can combine them with type filters like /tracks belver or /artists ^Tu.
| Token | Match type | Description |
|---|---|---|
belver |
fuzzy-match | Items that fuzzy match belver (e.g. “Believer”) |
="Rebel" |
exact-match | Items that are exactly Rebel |
'lofi |
include-match | Items that include lofi |
!lofi |
inverse-exact-match | Items that do not include lofi |
^Tu |
prefix-exact-match | Items that start with Tu |
!^Tu |
inverse-prefix-exact-match | Items that do not start with Tu |
na$ |
suffix-exact-match | Items that end with na |
!na$ |
inverse-suffix-exact-match | Items that do not end with na |
Tips
- Whitespace-separated terms are AND’d together (all must match).
- Use
|for OR (e.g.'jazz | 'blues). - Prefix a query with a slash command to limit type:
/albums ^The,/tracks !live$. - Tab accepts the ghost suggestion when one is shown.
The amus binary doubles as a remote control for the running app. If AMUS isn't running, it's auto-started in the background. Use amus help to see everything, or amus <command> --help for details on a specific command.
| Command | Description |
|---|---|
play [paths...] |
Resume playback, or play files/folders/globs |
play -s <query> |
Play the top search result for a query |
pause |
Pause playback |
stop |
Stop playback |
toggle |
Toggle play/pause |
next |
Skip to the next track |
prev |
Go to the previous track |
seek <value> |
Seek to a position (e.g. 90) or by offset (+10, -5) |
volume <value> |
Set volume as a percent (e.g. 80) or adjust (+5, -10) |
mute |
Toggle mute |
status |
Show current track, playback state, and position |
queue add [paths...] |
Add files/folders/globs to the end of the queue |
queue add -s <query> |
Add search results to the queue |
queue clear |
Clear the user queue |
queue shuffle |
Toggle shuffle on/off |
queue show |
Print the current queue contents |
library rescan |
Rescan all library sources |
search [scope] <query> |
Search the library (artist:, album:, or bare track:) |
playlist [name] |
Show a playlist's contents (omit to list all) |
playlist create <name> |
Create a new playlist |
playlist play <name> |
Play a playlist |
playlist add <name> <path> |
Add a track to a playlist |
playlist remove <name> <path> |
Remove a track from a playlist |
playlist delete <name> |
Delete a playlist |
albums |
List all albums |
artists |
List all artists |
album <id_or_name> |
Show an album's track listing |
artist <id_or_name> |
Show an artist's track listing |
import <path> |
Import a folder as a library source and scan it |
info <path> |
Print local metadata for an audio file (no server needed) |
open |
Show and focus the main window |
hide |
Hide the main window |
close |
Close or hide the main window |
update |
Check for and install updates |
reset |
Reset all app data (DB, settings, cache) and restart |
reset --force |
Skip confirmation prompt |
version |
Print the AMUS version |
Examples
amus # start the GUI
amus ~/Music/album.flac ~/Downloads/track.mp3 # play specific files
amus ~/Music # play an entire folder
amus play -s "artist:Radiohead" # play the top artist match
amus next # skip to next track
amus seek +30 # jump forward 30 seconds
amus volume 60 # set volume to 60%
amus queue add ~/Music/New\ Albums/*.flac # glob and queue
amus queue show # see what's coming next
amus playlist create "Late Night" # new empty playlist
amus playlist add "Late Night" ~/Music/jazz.mp3 # add a track to it
amus playlist play "Late Night" # start playing it
amus albums # browse the library
amus search album "In Rainbows" # find an album
amus info ~/Downloads/unknown.flac # peek at metadata
Notes
- Paths accept glob patterns (
**/*.flac) and can be files or directories — everything is scanned recursively for audio. - The
-s/--searchflag is only available onplayandqueue add. For general lookups usesearch. - Seek and volume values prefixed with
+or-are treated as relative adjustments; bare numbers are absolute. - On first invocation of any command, AMUS launches in the background if it isn't already running.
Grab the latest build from Releases.
| Platform | Arch |
|---|---|
| Windows | x64 |
| Linux | x64 |
| macOS | Intel & Apple Silicon |
paru -S amus
# or
yay -S amus- Tauri v2 prerequisites (Rust, platform deps)
- Bun
git clone https://github.com/Naitik4516/AMUS.git
cd AMUS
bun install
bun tauri devProject layout (click to expand)
amus/
├── src/ # SvelteKit frontend (SPA, SSR off)
│ ├── lib/
│ │ ├── player.svelte.ts # PlayerState ($state runes) + event listener
│ │ ├── stores.svelte.ts # Library store (tracks/albums/artists/playlists)
│ │ ├── commands.svelte.ts # invoke() wrappers for Tauri commands
│ │ ├── settings.svelte.ts # tauri-plugin-store settings
│ │ ├── shortcuts.svelte.ts # App + global shortcut definitions
│ │ ├── stats.svelte.ts # Stats state
│ │ ├── update.svelte.ts # Auto-updater
│ │ ├── utils.ts # Image URLs, duration formatting, cn()
│ │ └── types.d.ts # Shared TS types
│ ├── components/ # UI (shadcn-svelte, menus, cards, stats)
│ ├── routes/
│ │ ├── (main)/ # Library, artists, albums, playlists, …
│ │ └── miniplayer/ # Separate mini-player window
│ └── styles/ # Tailwind v4 theme + fonts
├── src-tauri/ # Rust / Tauri backend
│ ├── migrations/ # SQLite migrations (rusqlite_migration)
│ └── src/
│ ├── lib.rs # App setup: plugins, DB, tray, player, commands
│ ├── commands.rs # Tauri command handlers
│ ├── db.rs # Schema, queries, stats
│ ├── player/ # Actor-based playback (rodio)
│ ├── scanner.rs # Parallel library scan (rayon + lofty)
│ ├── sync.rs # Startup scan + notify file watcher
│ └── artist_pic_fetcher.rs # Artist image scraping
├── static/ # Icons and static assets
└── package.json
How it fits together
- Player actor —
PlayerActorruns on its own thread; the UI talks to it via commands and listens onplayer://event. - SQLite library — pooled DB at app data (
music.db); WAL mode for concurrent reads. - Frontend store — library data is loaded once at startup into Svelte 5 state for fast UI and client-side search.
| Layer | Technology |
|---|---|
| Desktop shell | Tauri v2 |
| Frontend | SvelteKit 5 (SPA, SSR off), Svelte 5 runes |
| UI | shadcn-svelte, Tailwind CSS v4, Lucide |
| Search | Fuse.js (client-side fuzzy + extended search) |
| Backend | Rust — rodio, rusqlite, r2d2, lofty, rayon, notify |
| Artist images | primp + scraper (Bing / DuckDuckGo) |
| Audio formats | MP3, FLAC, WAV, OGG, M4A, AAC, OPUS |
- OS media controls
- Command-line interface for remote control
- File associations (open audio files with AMUS)
- Mini player with always-on-top option
- Fuzzy global search (Fuse.js + type filters)
- Global and local keyboard shortcuts
- Track context menus (right-click)
- Playlist cover art + quick "Add more" flow
- Startup library cache for snappier UI
- Comprehensive frontend test coverage (Vitest)
- Player subsystem refactor for better architecture
- Lyrics support
- Improved UI animations
- Better OS integration
- Smart playlists
- Music recommendations
- Gapless playback & silence skipping
- Crossfade
- Equalizer
- Audio normalization
- DSP effects
- Sleep timer
- Automatic metadata tagging
- Dynamic theming
- Auto-start and scheduled playback
- Video playback support
Is this a vibe-coded / fully AI-generated project?
No. AMUS is a personal project I designed and built. I use AI tools (including coding agents and autocomplete) for implementation help and boilerplate — especially while learning Rust or working through low-level pieces. Some areas (for example parts of the scanner and sync logic) had substantial AI assistance. Everything is reviewed, tested, and integrated by me; architecture, features, and maintenance are intentional human decisions.
If AMUS crashes or shows a blank window after launch:
- Try Again — restart the app from the error page
- Reset App Data — click the "Reset App Data" button on the error page, or run
amus reset --forcefrom a terminal. This clears your database, settings, session, and cached art, then restarts fresh. - Report the issue — open a GitHub issue and include any error details shown on the page
- Downgrade — install the previous stable version from the Releases page
If amus is not recognized in Command Prompt or PowerShell after installation, add the AMUS installation directory to your PATH manually, or reinstall using the NSIS installer (it now adds AMUS to PATH automatically).
Resets all app data and restarts the application. Useful for troubleshooting startup failures or data corruption.
amus reset # prompts for confirmation
amus reset --force # skip confirmation (useful in scripts)
Does it need the cloud or an account?
No. Your library stays on your machine. Artist image fetch is the only optional network use for metadata art.
Where is my data stored?
In the app data directory (SQLite library DB, cover art, settings). Nothing is uploaded for playback.