Discord Integration

Discord Integration

Discord is an adapter around Veloura, not the center of the package. The official example uses slash commands while keeping audio state and permission checks in the bot project.

Install

python3 -m pip install "veloura-audio[all]"

The discord extra installs discord.py and PyNaCl. The stream extra installs yt-dlp. The example needs both, so all is the simplest choice.

Discord application setup

In the Discord Developer Portal:

1. Create an application and bot.
2. Keep the bot token private.
3. Invite it with the bot and applications.commands scopes.
4. Grant View Channel, Connect, Speak, Send Messages, and Use Application Commands as appropriate for your server.
5. Do not grant Administrator unless your own product genuinely requires it.

Run the example from a clone of the repository:

export DISCORD_TOKEN="your-bot-token"
export DISCORD_GUILD_ID="your-test-server-id"
python3 examples/discord_slash_bot.py

DISCORD_GUILD_ID is optional. During development it syncs commands to one server, which is much faster than global command propagation.

Included slash commands

Command	Behavior
/play query	Resolve, prepare, enqueue, and start a track.
/queue	Show the current item, next items, and last audio warning.
/now	Show title, elapsed time, duration, and active crossfade.
/skip	Skip or promote the next prepared stream.
/stop	Stop, clear the queue, and disconnect.
/volume level	Set volume from 0.0 through 1.5.

Environment settings

Variable	Default	Purpose
DISCORD_TOKEN	required	Bot credential. Never commit it.
DISCORD_GUILD_ID	global sync	Development server for fast slash-command sync.
VELOURA_PRESET	streamer	Transition preset name.
VELOURA_VOLUME	0.65	Initial linear volume.
VELOURA_DJ_ROLE_ID	unrestricted	Role required for playback controls.
VELOURA_MAX_QUEUE_SIZE	50	Pending track limit per server.
VELOURA_PLAY_COOLDOWN_SECONDS	5	Per-user /play cooldown.
VELOURA_RESOLVE_TIMEOUT_SECONDS	35	Lookup and preparation time budget.
VELOURA_CACHE_MAX_ENTRIES	1000	Maximum transition cache files.
VELOURA_CACHE_TTL_SECONDS	604800	Cache lifetime, seven days.
VELOURA_CACHE_DIR	platform default	Override analysis cache location.

Minimal integration

from veloura.audio import (
    CrossfadeAudioSource,
    FileAnalysisCache,
    resolve_stream_track,
    transition_preset,
)

config = transition_preset("streamer")
cache = FileAnalysisCache(max_entries=1000, ttl_seconds=604800)
source = CrossfadeAudioSource(
    volume=0.65,
    crossfade_seconds=config.base_crossfade_seconds,
    max_queue_size=50,
)

track = await resolve_stream_track(
    query,
    requester_id=interaction.user.id,
    transition_config=config,
    analysis_cache=cache,
    timeout=35,
)

source.enqueue(track)

if not voice_client.is_playing():
    voice_client.play(source)

CrossfadeAudioSource.is_opus() returns False, so Discord treats its reads as PCM and performs the normal voice encoding.

State per server

Keep one queue source and one lock per Discord guild. Do not share a single CrossfadeAudioSource across servers. The example stores guild state in a dictionary; a production bot can place durable queue metadata in a database while keeping active FFmpeg streams in memory.

Public-bot guardrails

Before exposing /play publicly:

• Require the user to be in the bot's voice channel.
• Decide who can play, skip, stop, and change volume.
• Add per-user and per-server rate limits.
• Check the queue limit before starting expensive resolution.
• Set a resolver timeout.
• Limit concurrent lookups globally.
• Escape mentions and Markdown from resolved titles.
• Keep cache size and age bounded.
• Record the last decoder error without exposing secrets or signed media URLs.
• Handle voice disconnects and reconnects as normal failures.

The example demonstrates the first layer of these controls. Large public bots still need distributed rate limiting, observability, process supervision, and abuse handling in their own application.

Voice quality

Veloura can make the transition waveform smooth before Discord receives it. Discord still converts PCM to Opus for voice transport. Lossless input therefore does not create lossless Discord output.