Music Commands — Lavalink Playback with Queue & Controls

Niko’s music system uses wavelink — a Python Lavalink client — for high-quality, gap-free audio playback. Music commands require both the bot and you to be in a voice channel. /play is available as both a prefix command (e.g. .play) and a slash command (e.g. /play). All other music commands are prefix-only (e.g. .skip, .stop).

Music playback requires a running Lavalink node. Without one, all music commands will be unavailable. See the Lavalink Setup section below for instructions.

YouTube (search queries and URLs), Spotify (track, album, and playlist URLs via the Spotify Web API), SoundCloud (sc:<query> prefix), and direct audio URLs are all supported sources.

Playback Commands

Command	Aliases	Description
`/play <query or URL>`	`.p`	Search and play a track, or add it to the queue
`.nowplaying`	`.np`	Display the live now-playing card with controls
`.queue`	`.q`	Show the full playback queue
`.skip`	`.sk`	Skip the current track
`.stop`	—	Stop playback and clear the queue
`.pause`	—	Pause the currently playing track
`.resume`	—	Resume a paused track
`.disconnect`	`.dc`, `.leave`	Disconnect Niko from the voice channel

`/play <query or URL>`

Searches for and plays a track, or adds it to the queue if something is already playing. The /play slash command includes live YouTube autocomplete — as you type, Niko suggests matching tracks by querying Lavalink in real time. Supported input formats:

Input	Behaviour
`song name`	YouTube text search
`yt:<query>`	Explicit YouTube search
`sc:<query>`	SoundCloud search
`https://youtube.com/watch?v=...`	Direct YouTube URL
`https://open.spotify.com/track/...`	Spotify track → resolved to YouTube
`https://open.spotify.com/album/...`	Spotify album → all tracks queued
`https://open.spotify.com/playlist/...`	Spotify playlist → up to 50 tracks queued
`https://...` (other URL)	Played directly as a raw audio URL

Spotify support requires SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET to be set in your .env file. When those variables are absent, Spotify URLs are silently rejected.

`.nowplaying`

Sends (or refreshes) the now-playing control panel. The card displays:

Track title, artist name, and source (YouTube / SoundCloud)
A text progress bar showing elapsed and total duration (e.g. [████████░░░░░░] 2:14 / 3:47)
Current volume percentage and active loop / autoplay state
Album artwork rendered via Discord’s Media Gallery component (when available)
An Open Track link button pointing to the original source URL

The card includes two rows of interactive buttons:

Button	Action
⏮ Prev	Replay the previous track from history (disabled when history is empty)
⏸/▶ Pause / Resume	Toggle playback pause
⏭ Skip	Skip to the next queued track
⏹ Stop	Stop playback, clear the queue, and disable loop
🔁 Loop	Toggle loop mode (repeats the current track)
📻 Autoplay	Toggle Last.fm autoplay (greyed out if not configured)
🔉 Vol −	Decrease volume by 10%
🔊 Vol +	Increase volume by 10%

`.queue`

Displays the current playback queue in a formatted list. Shows up to 10 tracks with their position number, title, artist, and duration. If there are more than 10 tracks, a summary line indicates how many remain.

`.skip`

Immediately skips the currently playing track and begins playing the next item in the queue. If the queue is empty, the player enters an idle state and will disconnect after 5 minutes.

`.stop`

Stops the current track, clears the entire queue, and disables loop mode. The bot remains in the voice channel until the idle timeout (5 minutes) triggers automatic disconnection.

`.pause` and `.resume`

.pause pauses the current track mid-playback; .resume continues from where it left off. Pause and resume can also be toggled via the Pause / Resume button on the now-playing control panel.

Queue Management

Command	Description
`.stop`	Clears the full queue and stops playback

The source code uses player.queue.clear() via wavelink. Individual track removal and shuffle are not available as standalone commands in the current implementation.

Volume & Audio

Command	Aliases	Range	Description
`.volume <level>`	`.vol`	0 – 100	Set playback volume (`100` = default)

Volume can also be adjusted live using the Vol − and Vol + buttons on the now-playing card (each step changes volume by 10%).

Loop Mode

Command	Aliases	Description
`.loop`	`.repeat`	Toggle loop on/off for the current track

When loop is on, the currently playing track repeats indefinitely until loop is toggled off, the track is skipped, or playback is stopped.

Last.fm Autoplay

When the queue runs out of tracks, Niko can automatically fetch and queue similar tracks to keep the music flowing continuously. How it works:

When the queue is exhausted, Niko calls the Last.fm track.getSimilar API using the artist and title of the last played track.
Up to 10 similar tracks are returned, ordered by similarity score.
Niko searches YouTube for each similar track (ytsearch: <artist> - <title>) and plays the first match.
If no similar track resolves, the player enters the idle grace period and disconnects.

Toggle autoplay:

Command	Aliases	Description
`.autoplay`	`.ap`	Toggle Last.fm autoplay on/off

Last.fm autoplay requires a LASTFM_API_KEY in your .env file. Without it, the autoplay button on the now-playing card is shown as disabled, and the .autoplay command returns an unavailability message.

Music Status

Command	Description
`.musicstatus`	Check whether Niko is connected to a Lavalink node, and whether Spotify and Last.fm integrations are active

Lavalink Setup

Niko automatically discovers public Lavalink v4 nodes from the DarrenOfficial/lavalink-list GitHub repository at startup, probes them for latency, and connects to the fastest responsive node. A built-in fallback list of well-known public nodes is used if the upstream list is unavailable. To use your own private Lavalink node instead:

Download and run Lavalink

Download the latest Lavalink server jar from lavalink.dev and run it:

java -jar Lavalink.jar

By default, Lavalink listens on port 2333 with the password youshallnotpass.

Configure your node credentials

Note your Lavalink server’s host, port, password, and whether TLS/SSL is enabled. These are defined in application.yml inside the Lavalink server directory.

Point Niko at your node

Open src/cogs/music/cog.py and locate the startup_connect method. The node list is fetched via _fetch_node_list(), which first tries the DarrenOfficial list, then falls back to _FALLBACK_NODES. To hard-code your own node, add an entry to _FALLBACK_NODES:

_FALLBACK_NODES = [
    {
        "host": "your.lavalink.host",
        "port": 2333,
        "password": "youshallnotpass",
        "secure": False,
        "version": "v4",
    },
]

Niko will attempt to connect to nodes in order of measured latency.

Restart Niko

Restart the bot. The music cog calls wavelink.Pool.connect() on startup via bot.loop.create_task(self.startup_connect()). A successful connection is logged as:

[Lavalink] Connected to your.lavalink.host:2333 (SSL=False)

If the connection fails, Niko retries automatically every 10 seconds after a node disconnect event.

Environment Variables

Variable	Required	Description
`SPOTIFY_CLIENT_ID`	Optional	Spotify Web API client ID (enables Spotify URL resolution)
`SPOTIFY_CLIENT_SECRET`	Optional	Spotify Web API client secret
`LASTFM_API_KEY`	Optional	Last.fm API key (enables autoplay via similar tracks)

All music-related integrations degrade gracefully — the core YouTube/SoundCloud playback works without any of these keys.

AI & Chat

Economy & Casino

Moderation & Server

Entertainment

Music Commands — Lavalink Playback with Queue & Controls

Playback Commands

`/play <query or URL>`

`.nowplaying`

`.queue`

`.skip`

`.stop`

`.pause` and `.resume`

Queue Management

Volume & Audio

Loop Mode

Last.fm Autoplay

Music Status

Lavalink Setup

Environment Variables

Build docs developers (and LLMs) love

AI & Chat

Economy & Casino

Moderation & Server

Entertainment

Documentation Index

​Playback Commands

​/play <query or URL>

​.nowplaying

​.queue

​.skip

​.stop

​.pause and .resume

​Queue Management

​Volume & Audio

​Loop Mode

​Last.fm Autoplay

​Music Status

​Lavalink Setup

​Environment Variables

Build docs developers (and LLMs) love

Playback Commands

`/play <query or URL>`

`.nowplaying`

`.queue`

`.skip`

`.stop`

`.pause` and `.resume`

Queue Management

Volume & Audio

Loop Mode

Last.fm Autoplay

Music Status

Lavalink Setup

Environment Variables