Bot Commands Reference

​

Available Commands

​

Command List

​

Music Playback Commands

​

!play

!play <song name or URL>

• search_query (required): Either a YouTube URL or a search term

• Accepts both direct YouTube URLs (starting with http:// or https://)
• For search queries, uses YouTube Data API v3 to find the first matching video
• Downloads audio in MP3 format at 192 kbps quality using yt-dlp
• Adds songs to a per-guild queue if something is already playing
• Automatically joins your voice channel if not already connected
• Uses per-guild caching (stored in music/<guild_id>/ directories)
• Skips download if the video is already cached

!play https://www.youtube.com/watch?v=dQw4w9WgXcQ
!play Never Gonna Give You Up
!play lofi hip hop

• Returns error if you’re not in a voice channel
• Returns error for region-locked, private, or deleted videos
• Shows “Searching for…” message during search operations
• Notifies when using cached versions of songs

​

!skip

!skip

• Stops current playback immediately
• Triggers the song_finished callback which plays the next queued song
• If queue is empty, playback stops
• Handles edge cases where playback stopped but state wasn’t cleared

!skip

​

Voice Channel Management

​

!leave

!leave

• Disconnects from the current voice channel
• Clears the entire song queue for the guild
• Resets playback state (current song, queue, timers)
• Cancels any active inactivity timers
• Deletes the entire guild cache directory (music/<guild_id>/)
• Removes all downloaded songs for that server

!leave

​

Utility Commands

​

!ping

!ping

• Measures round-trip latency to Discord voice server in milliseconds
• Only works when bot is connected to a voice channel
• Warns if latency exceeds 150ms

!ping

Voice connection latency for this server: 42.35 ms

​

!author

!author

• Shows bot creator information
• Displays Discord username and GitHub profile link

!author

This bot was made by spyflow (Discord: spyflow, GitHub: https://github.com/spyflow).

​

!clearcache

!clearcache

• Deletes the guild-specific music directory (music/<guild_id>/)
• Removes all cached MP3 files for that server
• Prevents clearing cache if a song from cache is currently playing
• Requires stopping playback first if songs are playing

!clearcache

• Bot prevents cache clearing during active playback
• Use !leave or skip all songs before clearing cache if needed

​

Command Prefix

bot = commands.Bot(command_prefix='!', intents=intents)

​

Per-Guild Isolation

• Separate queues for each server
• Independent voice connections
• Isolated cache directories
• Individual inactivity timers

​

Inactivity Timeout

inactive_time = 300  # Time in seconds before the bot disconnects

• A new song starts playing
• The !play command is used

​

Error Handling

• User not in voice channel
• Bot in different voice channel
• Invalid or unavailable videos
• Network/API errors
• File system errors
• yt-dlp download errors