Discord Music Bot for Navidrome (Subsonic API)

A lightweight, Discord-integrated music bot that interfaces with Navidrome (or any compatible Subsonic API server). It lets users search and play songs directly in a voice channel using natural commands and a responsive queue system.

Currently, the bot supports:

• Searching artists, albums, or tracks
• Playing and queuing music
• Shuffling and navigating the queue
• Volume and playback control
• Random playlist generation with filters
• Basic playlist save/load functionality

✅ Features

• 🎵 Full playback support: play, pause, resume, next, back, restart
• 🔍 Advanced search: fuzzy queries or structured key:value searches
• ➕ Dynamic queue control: add to front or back, shuffle, list, clear
• 📚 Library-aware: fetch and display detailed info on albums, artists
• 🎲 Random music: filterable random playlist creation (genre, year, etc.)
• 💬 Multiple prefixes: supports ~, /, hey bot, and hey bot,

---

🛠️ Setup

To run the bot, clone the repo and create a .env file in the root directory with the following:

TOKEN=<<DISCORD_TOKEN>>
NAVIDROME_URL=<<NAVIDROME_BASE_URL>>
NAVIDROME_USERNAME=<<USERNAME>>
NAVIDROME_PASSWORD=<<PASSWORD>>
NAVIDROME_VERSION=<<API_VERSION>>
NAVIDROME_CLIENT_ID=<<CLIENT_IDENTIFIER>>

Any music server supporting the Subsonic API should work.

Run the bot with:

cargo run

For the restart command to work the app needs a release build instead: cargo build / run -r

---

💬 Commands

Core Commands

Command	Description
/help	Show help text, or use ~help <command> for specific command help
/join	Join your current voice channel
/fuckoff	Leave the voice channel
/play	Start or resume playback
/pause	Pause the current playback
/next	Skip to the next track in queue. (/next n skips n)
/back	Replay the previous track or step back N tracks
/volume	Set playback volume (number or up / down)
/shuffle	Shuffle the current queue

Search & Selection

Command	Description
/search	Run a general search (songs, albums, artists). Use modifiers (see below)
/search2	Run a structured search with fields: artist, album, song, year
/info	Show details about a selected item
/page	Show the next page of search results (after /search, /search2)
/add	Add a result to the end of the queue (~add 2)
/add_front	Add a result to the front of the queue

Adding a new track / album / artist to the queue requires a search before. The results are presented with an index. This index is used by commands like info, add, add_front. If multiple result types are returned, the type needs to be specified with an additional Argument: track, album, artist

Queue Management

Command	Description
/list	Show current queue
/clear	Clear the queue
/playing	Show current playing track
/save_list	Save the current queue to a preset
/load_list	Load a previously saved queue

Random Playback

Command	Description
/play_random	Play a random selection. Supports filters: genre, fromYear, toYear, count

---

🔎 Search Tips

• Use t:<type> to narrow by type (song, album, or artist)
• Use c:<count> and p:<page> to control pagination
• Example:

~search t:song c:20 p:2 my favorite track

• Structured search (/search2) uses fielded queries:

~search2 artist:Tool year:1996

At least one of artist, album, or song is required.

If multiple types are returned (e.g. song & album), use the typ:<type> param in commands like add or info.

---

Settings

Key	Accepts	Description
loop_mode	off, one, all	Sets track loop behavior.
load_on_start	true / false	Load saved playlist on startup.
save_on_exit	true / false	Save playlist on shutdown.
save_type	playlist, static, append	Mode for saving track lists.
playlist	<file path>	Default playlist file.
keep_playing	true / false	Continue playback when switching channels.
all	(no value)	Show all current settings.
save	(no value)	Save settings to disk.
load	(no value)	Load settings from disk.

all setting commands can be called w / o an argument to just display the current value.

⚙️ Tech Stack

• Discord API (via serenity & poise)
• Navidrome + Subsonic API
• Audio playback powered by Songbird
• Written in Rust (async, tokio)

---

📌 Notes

• The search results rely on the Subsonic API and may return fuzzy matches across all fields.
• Discord messages are limited to 2000 characters, which caps the number of displayed results.
• Indexes from search results are used to identify selections in subsequent commands (~add 4).

---

🚧 Future Improvements

• Rewrite fuzzy search with better token weighting
• custom playlist beside the default one, with download option (as list)
• Customizable playback profiles that can be switched
• Navigation inside currently playing tracks

---