Development

Development

Clone and install

git clone https://github.com/VelouraAudio/veloura-audio.git
cd veloura-audio
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -e .

Install optional integrations only when working on them:

python3 -m pip install -e ".[stream]"
python3 -m pip install -e ".[discord]"
python3 -m pip install -e ".[all]"

Run the standard checks

python3 -m unittest discover -s tests -v
python3 -m compileall -q veloura examples
python3 -m html.parser docs/index.html
python3 -m veloura doctor
python3 -m build
python3 -m twine check dist/*

CI runs tests, runtime checks, compilation, build, and Twine validation on Ubuntu, macOS, and Windows with Python 3.12 and 3.13.

Test philosophy

• Pure planning logic should use deterministic unit tests.
• PCM math needs boundary and clipping tests.
• FFmpeg tests should generate tiny local fixtures instead of downloading media.
• Network resolver tests should isolate protocol and timeout behavior.
• Every fixed regression should receive a focused test.
• Cross-platform behavior belongs in CI, not an assumption based on one laptop.

Repository structure

veloura/
  cli.py
  audio/
    models.py
    player.py
    crossfade.py
    ffmpeg_stream.py
    transition.py
    beat.py
    slm.py
    automix.py
    resolver.py
    lossless.py
    cache.py
examples/
tests/
docs/
.github/workflows/

Contribution scope

Keep the core focused on reusable audio behavior. Platform-specific commands, databases, recommendation systems, and UI frameworks usually belong in examples or companion packages.

Before adding an abstraction, show the repeated complexity it removes. Before adding a dependency, explain why the standard library or existing FFmpeg boundary is insufficient.

Compatibility

• AudioTrack is the public name; MixerTrack remains an alias.
• QueuePlayer is the friendly public name; PCMQueuePlayer remains an alias.
• Preset aliases remain accepted, but documentation should teach canonical names first.
• New fields on public dataclasses should have defaults when possible.
• Behavioral changes require release notes and tests.

Documentation style

• Say exactly what the feature does.
• State important limitations beside the feature.
• Prefer complete runnable examples.
• Do not call deterministic rules “AI” without explaining the implementation.
• Do not claim lossless transport when only file output is lossless.
• Keep package name and import name explicit.