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.6 Reliability

Bounded stream resolution and safer releases.

Timed online lookups now run in an isolated process that Veloura can stop cleanly. Manual release checks no longer attempt to republish an existing PyPI version.

Resolver

Real timeout cleanup

Timed yt-dlp workers are terminated instead of continuing invisibly in a thread.

Cancel

Cancellation-aware

Cancelling a timed lookup also stops its worker process and releases its resources.

Release

Build-only manual runs

Manual Actions runs verify distributions without uploading duplicate files to PyPI.

API

Compatibility retained

Untimed resolution and the public resolver signature continue to work as before.

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]. Timed calls require JSON-compatible custom ydl_options.

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.