Python audio transitions for queues, bots, and streamers

Veloura Audio

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

Install Listen PyPI

Queue Playback

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

SLM Auto Timing

Let Veloura choose pair-specific crossfade seconds from duration, safety caps, and beat confidence.

Lossless Renders

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

0.6.5 SLM Auto Timing

Automatic transition timing, no manual guesswork.

This patch adds Veloura's public Small Listening Model planner: a local deterministic scorer that chooses crossfade duration for each pair before AutoMix refines the transition.

SLM

Auto crossfade timing

plan_slm_transition chooses transition seconds from pair-level audio signals.

AutoMix

SLM as base planner

AutoMix now starts from the SLM estimate before beat-aware refinement.

Preset

SLM aliases

slm and veloura-auto map to automatic pair planning.

API

QueuePlayer import

QueuePlayer is the friendly public name; PCMQueuePlayer remains supported.

Docs

Install versus import

Install veloura-audio, then import veloura in Python.

AutoMix

Clearer pair prep

Docs separate explicit track-pair preparation from the player queue helper.

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. Install the PyPI package as veloura-audio; import it in Python as veloura.

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

Small Listening Model

Automatic crossfade timing for each pair.

Veloura SLM is public, local, and deterministic. It does not call an external AI service. It scores the current and next track, then chooses practical crossfade seconds so users do not have to guess.

from veloura.audio import AudioTrack, plan_slm_transition, transition_preset

config = transition_preset("slm")
current = AudioTrack.from_source("track-a.flac", title="Track A", duration=184)
next_track = AudioTrack.from_source("track-b.flac", title="Track B", duration=196)

plan = plan_slm_transition(current, next_track, config)
print(plan.crossfade_seconds, plan.reason)

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, QueuePlayer, transition_preset

config = transition_preset("automix")
player = QueuePlayer(
    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 starts from the SLM crossfade estimate, analyzes current outro and next intro beat windows, then applies pair-specific timing, intro trim, and a 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 QueuePlayer and bundled as a listenable example of real-time queue playback.

Veloura CC0 Music Transition

One CC0 music excerpt blended into another 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 QueuePlayer as the audio engine behind desktop, web, or mobile-style queue products.