Lunar music

a discord music bot that plays from youtube, spotify, soundcloud, deezer, apple music, tidal, and more. built with discord.js and moonlink.js.

uses NodeLink/Lavalink for audio streaming - you have to host or supply the bot with a node yourself.

Bot's recommended for small/private instances (around 10 active servers). If you plan to scale beyond that, you'll need to modify the source code yourself to handle sharding and larger scale workloads.

Features

• multi-platform search - youtube, youtube music, soundcloud (default), spotify, deezer, apple music, tidal
• synced lyrics - synced lyrics powered by lrclib
• custom branding - customizable bot name & dynamic embed footer branding via .env
• audio effects - nightcore, vaporwave, tremolo, vibrato, rotation, lowpass, echo, karaoke
• queue management - paginated queue, loop (track/queue), skip, previous, back, clear
• now playing - embed with artwork, dominant color theming, duration, up next, artist info
• play stats - per-server and global leaderboards for most played tracks
• session summary - recap of songs played and total time when a session ends
• playback recovery - automatic stall detection and reconnection
• process supervisor - built-in child process launcher with crash detection, file logging, and restart rate limits
• voice channel status - shows the current track in the voice channel status bar

Setup

what you need

• node.js v20 or higher
• a discord bot token (create one here)
• a NodeLink/Lavalink node

install

git clone https://github.com/relentiousdragon/lunar-music.git
cd lunar-music
npm install

configure

copy the example env file and fill in your values:

cp .env.example .env

open .env and add:

node format:

identifier,host,port,password,secure

examples:

# single node
NODELINK_NODES=main,nodelink.example.com,3000,youshallnotpass,false

# multiple nodes (semicolon-separated)
NODELINK_NODES=main,nodelink.example.com,3000,password,false;backup,nodelink2.example.com,3000,password,false

Discord Activity setup

The optional Lunar Activity to control music, has a miniplayer, better synced lyrics, visualizer and some other cool stuff.

1. In the Discord Developer Portal for your APP, enable Activities and enable the platforms you want to test.
2. Under OAuth2, add the exact redirect URI used by ACTIVITY_REDIRECT_URI (for example, https://127.0.0.1).
3. Give the Activity a public HTTPS hostname you control, then add it under Activities -> URL Mappings. Map / to that hostname without a protocol. Discord proxies both the web app and WebSocket connection.
4. Either point ACTIVITY_TLS_KEY_PATH and ACTIVITY_TLS_CERT_PATH at the TLS key and certificate when the bot hosts HTTPS itself, or use a TLS-terminating reverse proxy/tunnel such as Cloudflare Tunnel. With a local Cloudflare Tunnel, set ACTIVITY_ALLOW_INSECURE_LOCAL=true, Cloudflare supplies public HTTPS/WSS and forwards it privately to local HTTP/WS.
5. The Activity automatically detects the text channel to use for now-playing embeds based on the voice channel's category. No manual configuration is needed.

For local development only, set ACTIVITY_ALLOW_INSECURE_LOCAL=true; it binds to 127.0.0.1, so use a secure tunnel such as Cloudflare Tunnel and map the resulting HTTPS hostname in the Developer Portal.

run

npm start

for development with auto-restart on file changes:

npm run dev

Commmands

Commands are available through both Discord slash commands and the configured prefix (default: l. or ln.). Set DISCORD_GUILD_ID while developing to register slash commands to one guild immediately; omit it for global registration.

playback

queue

effects

stats

search flags

use these with the play command to search on a specific platform:

other

structure

lunar-music/
├── assets/                   <- image assets
├── bot.js                    <- process supervisor (crash detection, restarts & logging)
├── src/
│   ├── index.js              <- bot main entry point
│   ├── client.js             <- discord client
│   ├── manager.js            <- moonlink manager + node config
│   ├── state.js              <- shared runtime state
│   ├── events/
│   │   ├── ready.js           <- startup, presence, watchdog
│   │   ├── messageCreate.js   <- command routing
│   │   └── voiceStateUpdate.js
│   ├── commands/
│   │   ├── play.js
│   │   ├── queue.js
│   │   ├── skip.js            <- skip, previous, back
│   │   ├── playback.js        <- pause, resume, stop, seek, loop, clear, restart
│   │   ├── filters.js         <- all audio effects
│   │   ├── stats.js           <- top, global
│   │   ├── help.js
│   │   └── system.js          <- bot process restart
│   ├── handlers/
│   │   ├── trackStart.js      <- now playing embed
│   │   ├── trackEnd.js        <- session tracking, breaks
│   │   ├── trackError.js
│   │   └── playerEvents.js    <- queue end, stuck, destroy, disconnect
│   └── utils/
│       ├── branding.js        <- bot footer & name helpers
│       ├── embeds.js
│       ├── emojis.js          <- custom emoji registry & permission fallback
│       ├── format.js
│       ├── color.js
│       ├── lyrics.js
│       ├── metadata.js
│       ├── stats.js
│       ├── search.js
│       ├── voice.js
│       └── filters.js
├── .env.example
├── .gitignore
├── package.json
├── LICENSE
└── README.md

notes

• use source <platform> (or /source) to set a per-server default search source; use source auto to restore automatic fallback.
• process supervisor (bot.js): the bot runs as a child process managed by bot.js. executing l.sr by a configured developer, or encountering an unexpected crash, causes bot.js to automatically restart the bot child process. restart/fix only restarts the current guild's player.
• crash logging & limits: crash trace logs are automatically written to logs/error.log. automatic restarts are limited to a maximum of 10 restarts per hour to prevent infinite crash loops.
• synced lyrics are powered by lrclib.net - a free, open-source lyrics api. the MAX_SYNCED_LYRICS_PLAYERS setting limits how many guilds can have live lyrics at the same time to avoid hitting rate limits.
• the bot takes a 60-second connection break every hour of continuous playback to keep the audio stream stable.
• if the player gets stuck, the watchdog will automatically detect it and try to recover.

License

GPL-3.0