Skip to content

Home

Jump to bottom
manish singh edited this page Jul 25, 2026 · 2 revisions

Veloura Audio

Veloura is a Python audio transition engine. It helps one track hand off to the next with predictable PCM decoding, equal-power crossfades, optional transition analysis, beat-aware planning, and lossless file rendering.

It is deliberately framework-independent. A Discord bot can use it, but so can a desktop player, radio service, livestream tool, or your own music application. Veloura owns the audio transition. Your application still owns its users, playlists, permissions, database, interface, and product rules.

This wiki follows Veloura Audio 0.6.6. Install the distribution as veloura-audio and import it in Python as veloura.

Start here

python3 -m pip install veloura-audio
python3 -m veloura doctor
from veloura.audio import AudioTrack, QueuePlayer

player = QueuePlayer(volume=0.65, crossfade_seconds=5.0)
player.enqueue(AudioTrack.from_source("./track-a.flac", duration=180))
player.enqueue(AudioTrack.from_source("./track-b.flac", duration=195))

while player.is_active():
    pcm_frame = player.read_frame()
    if not pcm_frame:
        break
    # Send pcm_frame to your audio device, encoder, voice adapter, or pipeline.

The output is 48 kHz stereo signed 16-bit PCM. QueuePlayer does not choose an audio device for you; that is what keeps it usable in different products.

Choose your path

Goal Read
Install Veloura and play a first queue Getting Started
Understand the package before integrating it Architecture
Build a player around PCM frames Queue Playback
Trim silence and normalize track loudness Smart Transitions
Let Veloura choose pair-specific transition timing SLM and AutoMix
Resolve URLs and search queries Stream Resolution
Add it to a Discord slash-command bot Discord Integration
Produce FLAC, WAV, ALAC, or AIFF output Lossless Rendering
Use terminal commands CLI Reference
Operate a public or long-running service Caching and Operations

What Veloura does

  • Decodes local files and direct streams through FFmpeg.
  • Produces stable PCM frames for application-controlled playback.
  • Mixes adjacent tracks with an equal-power crossfade.
  • Measures silence and mean volume before playback when requested.
  • Estimates BPM and beat timing from audio energy.
  • Plans conservative pair-specific transitions with SLM and AutoMix.
  • Renders transitions to lossless output formats.
  • Provides optional adapters for yt-dlp and Discord voice.

What Veloura does not do

  • It is not a music catalogue, recommendation service, or rights-management system.
  • It does not make Discord voice lossless. Discord still encodes voice as Opus.
  • It cannot guarantee that vocals will never overlap. Veloura 0.6.6 does not include lyric transcription or vocal-stem separation.
  • The public SLM is a deterministic local scorer, not a hosted language model and not a claim of human-DJ judgment.
  • It does not turn lossy MP3 or AAC input back into original lossless audio.
  • It does not silently download online media into your library.

Those boundaries are intentional. They keep the core small enough to inspect, test, and embed without forcing one product design on everyone.

Project links

Veloura Audio · MIT licensed · Documentation for the 0.6.x API

Veloura Audio

PyPI · GitHub · Issues

Clone this wiki locally