Python audio transitions for queues, bots, and streamers

Veloura Audio

A reusable audio engine for equal-power crossfades, beat-aware planning, AutoMix-style transitions, and Discord-independent PCM playback.

Install Listen PyPI

Queue Playback

Use PCMQueuePlayer for frame reads, snapshots, skips, and queue control outside Discord.

Smart Transitions

Trim silence, normalize loudness, and adapt crossfade timing to track duration and analysis results.

Lossless Renders

Render FLAC, WAV, ALAC, or AIFF transition files without lossy re-encoding.

0.6.3 Hardening

Bugfixes that make Veloura safer to ship.

This patch focuses on reliability: clearer failures, safer defaults, cross-platform runtime behavior, and file renders that match prepared transition settings more closely.

Runtime

Visible track errors

Bad sources now show up in queue snapshots instead of silently ending playback.

Doctor

Real FFmpeg checks

Configured FFmpeg paths are validated before the CLI reports a healthy setup.

Portable

Windows-safe reads

PCM streaming no longer depends on Unix-only pipe readiness behavior.

Audio

Short clip bounds

Crossfades are clamped for tiny tracks so transitions stay sane.

Render

Gain and tempo parity

Lossless file renders now apply prepared gain and tempo settings.

Cache

Bad cache ignored

Invalid cached transition values fall back to fresh safe planning.

Install

Small core, optional integrations.

The base install includes a bundled FFmpeg provider for decoding and analysis. Add stream resolution or Discord voice support when your product needs it.

pip install veloura-audio

pip install "veloura-audio[stream]"

pip install "veloura-audio[discord]"

python -c "import veloura; print(veloura.__version__)"

python -m veloura doctor

Player API

Build playback without inheriting a Discord bot shape.

Enqueue prepared tracks, read PCM frames, inspect snapshots, and prepare the next transition when both tracks are known.

from veloura.audio import AudioTrack, PCMQueuePlayer, transition_preset

config = transition_preset("automix")
player = PCMQueuePlayer(
    volume=0.65,
    crossfade_seconds=config.base_crossfade_seconds,
)

track = AudioTrack.from_source(
    "song-a.mp3",
    title="Song A",
    duration=180,
)

player.enqueue(track)
frame = player.read_frame()
snapshot = player.snapshot().to_dict()

Selected preset

Streamer

Balanced transitions for livestreams, Discord queues, and background music.

Crossfade: 8s
Analysis: Balanced
Best for: General queues

AutoMix

Pair-aware transitions with conservative fallbacks.

AutoMix analyzes current outro and next intro beat windows, then applies a pair-specific crossfade, intro trim, and small tempo nudge when confidence is high. If analysis is weak, it keeps the blend short.

Audio Demo

Listen to a rendered ending transition.

A short demo showing Veloura blending one CC0 music track into another. The clip was rendered with PCMQueuePlayer and bundled as a listenable example of real-time queue playback.

Veloura CC0 Music Transition

Two CC0 music excerpts blended with an equal-power ending transition.

Track A

Crossfade

Track B

Demo Sources

CC0 music sources, credited clearly.

The public demo is rendered from OpenGameArt tracks listed as CC0. Attribution is optional under CC0, but the sources are shown here for provenance.

Empacotatron

By Fupi. Listed as CC0 on OpenGameArt. View source.

Rhythm Garden

By congusbongus. Listed as CC0 on OpenGameArt. View source.

python examples/generate_transition_demo_audio.py

Discord Example

Run the slash-command example bot.

The reference bot in examples/discord_slash_bot.py uses Veloura for stream resolution, transition prep, and Discord voice playback. It includes /play, /queue, /now, /skip, /stop, and /volume. Public-bot guardrails include same-channel controls, optional DJ role checks, mention escaping, queue caps, cooldowns, resolver timeouts, and bounded cache storage. Invite it with the bot and applications.commands scopes, plus Connect/Speak voice permissions.

pip install "veloura-audio[all]"
export DISCORD_TOKEN="your-bot-token"
export DISCORD_GUILD_ID="your-test-server-id"
export VELOURA_DJ_ROLE_ID="your-dj-role-id"
python examples/discord_slash_bot.py

Playable Demo

Lossless transition render

The same CC0 excerpts rendered through veloura render-transition into FLAC and WAV files with no lossy output encode step.

Download FLAC Download WAV

CC0 Track A

Float Crossfade

CC0 Track B

Output: FLAC + WAV
Rate: 48 kHz stereo
Sources: CC0 music excerpts

Lossless Rendering

Render transitions without lossy re-encoding.

For local music apps, demos, and release-prep workflows, Veloura can decode sources to high-precision float PCM, apply an equal-power-style crossfade, and write FLAC, WAV, ALAC, or AIFF output.

python -m veloura render-transition \
  ./track-a.flac \
  ./track-b.flac \
  ./transition.flac \
  --crossfade 8

Lossless rendering means the transition output is written without MP3/AAC/Opus-style compression. The crossfade still creates a new waveform, so it is not bit-for-bit copying of the source files.

Troubleshooting

Fast checks when audio setup gets weird.

FFmpeg

Run python -m veloura doctor. Veloura uses bundled FFmpeg when system FFmpeg is missing.

Streams

Install veloura-audio[stream] when resolving YouTube URLs or search queries through yt-dlp.

Discord Voice

Install veloura-audio[discord] so discord.py and PyNaCl are available.

Public Bots

Use same-channel checks, cooldowns, queue caps, resolver timeouts, and permission checks before handing input to yt-dlp.

Use Cases

One engine, several product surfaces.

Discord Music Bots

Keep CrossfadeAudioSource as the Discord voice adapter while the package handles transition planning.

Radio Streams

Run prepared queues through PCM frame output for continuous livestream or station-style playback.

Music Apps

Use PCMQueuePlayer as the audio engine behind desktop, web, or mobile-style queue products.