veloura-audio 0.3.0__tar.gz

veloura_audio-0.3.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include tests *.py

veloura_audio-0.3.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: veloura-audio
+Version: 0.3.0
+Summary: Reusable Python audio engine with crossfade and beat-aware transition planning.
+Project-URL: Homepage, https://github.com/VelouraAudio/veloura-audio
+Project-URL: Repository, https://github.com/VelouraAudio/veloura-audio
+Project-URL: Issues, https://github.com/VelouraAudio/veloura-audio/issues
+Keywords: audio,crossfade,ffmpeg,music,streaming
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Sound/Audio :: Mixers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Provides-Extra: stream
+Requires-Dist: yt-dlp>=2026.3.17; extra == "stream"
+Provides-Extra: discord
+Requires-Dist: discord.py>=2.3.0; extra == "discord"
+Requires-Dist: PyNaCl>=1.5.0; extra == "discord"
+Provides-Extra: all
+Requires-Dist: discord.py>=2.3.0; extra == "all"
+Requires-Dist: PyNaCl>=1.5.0; extra == "all"
+Requires-Dist: yt-dlp>=2026.3.17; extra == "all"
+
+# Veloura
+
+Veloura is a reusable Python audio transition engine for smooth queue playback.
+It provides FFmpeg-backed PCM decoding, equal-power crossfades, transition
+analysis, beat-aware planning, and a small CLI for local inspection.
+
+Veloura is framework-agnostic. Use it in streamer tools, radio pipelines,
+desktop music apps, Discord/Twitch bots, or backend automation without tying
+your project to one bot implementation.
+
+## Features
+
+- Equal-power crossfade mixing for signed 16-bit PCM audio
+- Queue/session helpers for buffering, skip, and current-track snapshots
+- Smart transition planning based on track duration, silence trim, and loudness
+- Beat/BPM analysis with beat-aware transition plans
+- Project-local or user-cache transition analysis storage
+- Optional `yt-dlp` stream resolution for URLs and search queries
+- Optional Discord audio source compatibility
+- Pure-Python PCM fallback for Python builds without `audioop`
+
+## Requirements
+
+- Python 3.12 or newer
+- FFmpeg for decoding, playback, silence analysis, loudness analysis, and beat
+  analysis
+- `yt-dlp` only when resolving online stream/search inputs
+- `discord.py` and `PyNaCl` only when using the Discord audio source directly
+
+## Installation
+
+Install the core package:
+
+```bash
+pip install veloura-audio
+```
+
+Install stream resolution support:
+
+```bash
+pip install "veloura-audio[stream]"
+```
+
+Install Discord voice support:
+
+```bash
+pip install "veloura-audio[discord]"
+```
+
+Install every optional integration:
+
+```bash
+pip install "veloura-audio[all]"
+```
+
+## Quick Start
+
+```python
+from veloura.audio import AudioTrack, CrossfadeSession, transition_preset
+
+config = transition_preset("streamer")
+
+track = AudioTrack.from_source(
+    "/music/current-song.flac",
+    title="Artist - Current Song",
+    duration=184,
+)
+
+session = CrossfadeSession(volume=0.65, crossfade_seconds=config.base_crossfade_seconds)
+session.source.enqueue(track)
+```
+
+For online sources, install `veloura-audio[stream]` and resolve a playable stream:
+
+```python
+import asyncio
+
+from veloura.audio import resolve_stream_track, transition_preset
+
+
+async def main():
+    track = await resolve_stream_track(
+        "artist song official audio",
+        transition_config=transition_preset("streamer"),
+    )
+    print(track.title, track.stream_url)
+
+
+asyncio.run(main())
+```
+
+## CLI
+
+Veloura exposes the same core tools through `python -m veloura` or the
+`veloura` console script:
+
+```bash
+python -m veloura presets
+python -m veloura prepare ./song.mp3 --preset streamer
+python -m veloura analyze ./song.mp3
+python -m veloura plan ./current.mp3 ./next.mp3 --preset broadcast
+```
+
+For YouTube/search inputs, install `veloura-audio[stream]` and add `--resolve`:
+
+```bash
+python -m veloura plan "current song" "next song" --preset streamer --resolve
+```
+
+Transition analysis is cached under `~/.cache/veloura` by default, or under the
+directory set in `VELOURA_CACHE_DIR`. Use `--cache-dir` for a project-local
+cache, or `--no-cache` when comparing fresh analysis.
+
+## Presets
+
+- `streamer`: balanced transitions for livestream/background music
+- `broadcast`: longer, smoother radio-style blends
+- `low-latency`: shorter analysis windows for weaker machines or fast queues
+
+Aliases such as `streamer-safe`, `broadcast-smooth`, and `fast` are also
+available.
+
+## Standalone Example
+
+The example player resolves local files or stream queries, prepares transition
+analysis, mixes the queue, and pipes PCM into `ffplay`:
+
+```bash
+python examples/streamer_player.py ./song-a.mp3 ./song-b.mp3 --preset streamer
+python examples/streamer_player.py ./song-a.mp3 ./song-b.mp3 --cache-dir ./veloura-cache
+```
+
+## Public API
+
+Prefer these names for new projects:
+
+- `AudioTrack`
+- `CrossfadeSession`
+- `FileAnalysisCache`
+- `transition_preset`
+- `prepare_smart_transition`
+- `plan_beat_transition`
+- `resolve_stream_track`
+
+Compatibility names:
+
+- `MixerTrack`
+- `CrossfadeAudioSource`
+
+## Development Checks
+
+```bash
+python3 -m unittest discover -s tests
+python3 -m py_compile veloura/*.py veloura/audio/*.py examples/*.py
+```
+
+Before publishing publicly, confirm the package name on PyPI, add project URLs,
+choose the license/copyright owner, build the distribution, and publish to
+TestPyPI first.

veloura_audio-0.3.0/README.md

@@ -0,0 +1,159 @@
+# Veloura
+
+Veloura is a reusable Python audio transition engine for smooth queue playback.
+It provides FFmpeg-backed PCM decoding, equal-power crossfades, transition
+analysis, beat-aware planning, and a small CLI for local inspection.
+
+Veloura is framework-agnostic. Use it in streamer tools, radio pipelines,
+desktop music apps, Discord/Twitch bots, or backend automation without tying
+your project to one bot implementation.
+
+## Features
+
+- Equal-power crossfade mixing for signed 16-bit PCM audio
+- Queue/session helpers for buffering, skip, and current-track snapshots
+- Smart transition planning based on track duration, silence trim, and loudness
+- Beat/BPM analysis with beat-aware transition plans
+- Project-local or user-cache transition analysis storage
+- Optional `yt-dlp` stream resolution for URLs and search queries
+- Optional Discord audio source compatibility
+- Pure-Python PCM fallback for Python builds without `audioop`
+
+## Requirements
+
+- Python 3.12 or newer
+- FFmpeg for decoding, playback, silence analysis, loudness analysis, and beat
+  analysis
+- `yt-dlp` only when resolving online stream/search inputs
+- `discord.py` and `PyNaCl` only when using the Discord audio source directly
+
+## Installation
+
+Install the core package:
+
+```bash
+pip install veloura-audio
+```
+
+Install stream resolution support:
+
+```bash
+pip install "veloura-audio[stream]"
+```
+
+Install Discord voice support:
+
+```bash
+pip install "veloura-audio[discord]"
+```
+
+Install every optional integration:
+
+```bash
+pip install "veloura-audio[all]"
+```
+
+## Quick Start
+
+```python
+from veloura.audio import AudioTrack, CrossfadeSession, transition_preset
+
+config = transition_preset("streamer")
+
+track = AudioTrack.from_source(
+    "/music/current-song.flac",
+    title="Artist - Current Song",
+    duration=184,
+)
+
+session = CrossfadeSession(volume=0.65, crossfade_seconds=config.base_crossfade_seconds)
+session.source.enqueue(track)
+```
+
+For online sources, install `veloura-audio[stream]` and resolve a playable stream:
+
+```python
+import asyncio
+
+from veloura.audio import resolve_stream_track, transition_preset
+
+
+async def main():
+    track = await resolve_stream_track(
+        "artist song official audio",
+        transition_config=transition_preset("streamer"),
+    )
+    print(track.title, track.stream_url)
+
+
+asyncio.run(main())
+```
+
+## CLI
+
+Veloura exposes the same core tools through `python -m veloura` or the
+`veloura` console script:
+
+```bash
+python -m veloura presets
+python -m veloura prepare ./song.mp3 --preset streamer
+python -m veloura analyze ./song.mp3
+python -m veloura plan ./current.mp3 ./next.mp3 --preset broadcast
+```
+
+For YouTube/search inputs, install `veloura-audio[stream]` and add `--resolve`:
+
+```bash
+python -m veloura plan "current song" "next song" --preset streamer --resolve
+```
+
+Transition analysis is cached under `~/.cache/veloura` by default, or under the
+directory set in `VELOURA_CACHE_DIR`. Use `--cache-dir` for a project-local
+cache, or `--no-cache` when comparing fresh analysis.
+
+## Presets
+
+- `streamer`: balanced transitions for livestream/background music
+- `broadcast`: longer, smoother radio-style blends
+- `low-latency`: shorter analysis windows for weaker machines or fast queues
+
+Aliases such as `streamer-safe`, `broadcast-smooth`, and `fast` are also
+available.
+
+## Standalone Example
+
+The example player resolves local files or stream queries, prepares transition
+analysis, mixes the queue, and pipes PCM into `ffplay`:
+
+```bash
+python examples/streamer_player.py ./song-a.mp3 ./song-b.mp3 --preset streamer
+python examples/streamer_player.py ./song-a.mp3 ./song-b.mp3 --cache-dir ./veloura-cache
+```
+
+## Public API
+
+Prefer these names for new projects:
+
+- `AudioTrack`
+- `CrossfadeSession`
+- `FileAnalysisCache`
+- `transition_preset`
+- `prepare_smart_transition`
+- `plan_beat_transition`
+- `resolve_stream_track`
+
+Compatibility names:
+
+- `MixerTrack`
+- `CrossfadeAudioSource`
+
+## Development Checks
+
+```bash
+python3 -m unittest discover -s tests
+python3 -m py_compile veloura/*.py veloura/audio/*.py examples/*.py
+```
+
+Before publishing publicly, confirm the package name on PyPI, add project URLs,
+choose the license/copyright owner, build the distribution, and publish to
+TestPyPI first.

veloura_audio-0.3.0/docs/release_checklist.md

@@ -0,0 +1,53 @@
+# Veloura Public Release Checklist
+
+Use this checklist before publishing Veloura as a public/global Python package.
+
+## Identity
+
+- Confirm the public package name on PyPI: `veloura-audio`
+- Choose the legal license and add a `LICENSE` file
+- Decide the copyright owner or contributor line
+- Add official project URLs to `pyproject.toml`:
+  - Homepage
+  - Source repository
+  - Issue tracker
+  - Documentation
+
+## Package Metadata
+
+- Keep `veloura.__version__` and `pyproject.toml` version in sync
+- Confirm the Python version floor: currently `>=3.12`
+- Confirm optional extras:
+  - `stream` for `yt-dlp`
+  - `discord` for Discord voice support
+  - `all` for every optional integration
+- Recheck classifiers after choosing a license
+
+## Local Verification
+
+```bash
+python3 -m unittest discover -s tests
+python3 -m py_compile veloura/*.py veloura/audio/*.py examples/*.py
+python3 -m build
+python3 -m twine check dist/*
+```
+
+## Publishing Flow
+
+1. Build from a clean source tree.
+2. Upload to TestPyPI first.
+3. Install from TestPyPI in a fresh virtual environment.
+4. Run `python -m veloura presets`.
+5. Test `prepare`, `analyze`, and the streamer example with local files.
+6. Test stream resolution with `pip install "veloura-audio[stream]"`.
+7. Publish the same checked artifacts to PyPI.
+
+## Release Notes
+
+For each public release, include:
+
+- New features
+- Compatibility notes
+- Dependency or Python-version changes
+- Known limitations
+- Migration notes for renamed or deprecated public APIs

veloura_audio-0.3.0/docs/veloura_scope.md

@@ -0,0 +1,86 @@
+# Veloura Scope
+
+Veloura is a reusable Python audio transition engine. The Discord bot is one
+consumer of the package, not the package's identity.
+
+## Target Use Cases
+
+- Streamer background music engines
+- 24/7 radio or livestream music pipelines
+- Discord, Twitch, or web music bots
+- Desktop music tools that need smooth queue playback
+- Audio automation scripts that need predictable fades and gain control
+
+## Core Package Owns
+
+- Audio track models
+- PCM helpers
+- FFmpeg-backed PCM decoding
+- Equal-power crossfade mixing
+- Queue/session buffering
+- Silence trim analysis
+- Loudness normalization
+- Beat/BPM analysis
+- Beat-aware transition planning
+- Stream URL resolution helpers
+- Presets for streamer, broadcast, and low-latency modes
+- File-based transition analysis cache
+- CLI tools for local analysis and transition planning
+
+## Core Package Does Not Own
+
+- Discord buttons, views, embeds, slash commands, or permissions
+- Lavalink nodes
+- Guild/server state
+- User playlists and saved songs
+- Spotify, Apple Music, Deezer, or Tidal scraping
+- Bot banners and presence
+- Database schemas for a specific app
+
+## Public API Direction
+
+Prefer these public names for new projects:
+
+- `AudioTrack`
+- `CrossfadeSession`
+- `FileAnalysisCache`
+- `transition_preset`
+- `prepare_smart_transition`
+- `plan_beat_transition`
+- `resolve_stream_track`
+
+Keep these names for compatibility:
+
+- `MixerTrack`
+- `CrossfadeAudioSource`
+
+## Release Milestones
+
+### 0.3
+
+- Generic `AudioTrack` public model
+- Streamer/broadcast/low-latency presets
+- `python -m veloura` CLI
+- File-based transition analysis cache
+- Generated audio tests for trim/loudness behavior
+- Docs for non-Discord use
+
+### 0.4
+
+- Example streamer player script
+- Cleaner status/snapshot model for external UIs
+- Optional playback adapters
+
+### 0.5
+
+- Stronger beat-aware planning
+- Better confidence scoring
+- Safer automatic fallback decisions
+- Transition preview/export helpers
+
+### 1.0
+
+- Stable typed API
+- Backward-compatible migration notes
+- Separate docs site/package README
+- Published package ready for public use

veloura_audio-0.3.0/examples/streamer_player.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""Minimal standalone streamer player powered by Veloura.
+
+This example does not import the Discord bot. It resolves each argument into an
+audio track, applies Veloura transition analysis, then pipes mixed PCM into
+``ffplay``.
+
+Example:
+
+    python examples/streamer_player.py "./song-a.mp3" "./song-b.mp3"
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from veloura.audio import (
+    CHANNELS,
+    FRAME_RATE,
+    AudioTrack,
+    CrossfadeSession,
+    FileAnalysisCache,
+    prepare_smart_transition,
+    resolve_stream_track,
+    transition_preset,
+)
+
+
+def probe_duration(source: str) -> float:
+    ffprobe = shutil.which("ffprobe")
+    if not ffprobe:
+        return 0.0
+    result = subprocess.run(
+        [
+            ffprobe,
+            "-v",
+            "error",
+            "-show_entries",
+            "format=duration",
+            "-of",
+            "default=noprint_wrappers=1:nokey=1",
+            source,
+        ],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.DEVNULL,
+        text=True,
+        check=False,
+    )
+    try:
+        return float((result.stdout or "0").strip() or 0.0)
+    except ValueError:
+        return 0.0
+
+
+async def build_track(source: str, *, preset: str, cache: FileAnalysisCache | None) -> AudioTrack:
+    config = transition_preset(preset)
+    if Path(source).exists():
+        track = AudioTrack.from_source(
+            source,
+            title=Path(source).stem,
+            duration=probe_duration(source),
+        )
+        if cache:
+            return await asyncio.to_thread(cache.prepare_transition, track, config)
+        return await asyncio.to_thread(prepare_smart_transition, track, config)
+    return await resolve_stream_track(source, transition_config=config, analysis_cache=cache)
+
+
+async def build_tracks(
+    sources: list[str],
+    *,
+    preset: str,
+    cache: FileAnalysisCache | None,
+) -> list[AudioTrack]:
+    return [await build_track(source, preset=preset, cache=cache) for source in sources]
+
+
+def open_ffplay() -> subprocess.Popen:
+    ffplay = shutil.which("ffplay")
+    if not ffplay:
+        raise RuntimeError("ffplay was not found. Install FFmpeg with ffplay to run this example.")
+    return subprocess.Popen(
+        [
+            ffplay,
+            "-nodisp",
+            "-autoexit",
+            "-loglevel",
+            "warning",
+            "-f",
+            "s16le",
+            "-ar",
+            str(FRAME_RATE),
+            "-ac",
+            str(CHANNELS),
+            "-i",
+            "pipe:0",
+        ],
+        stdin=subprocess.PIPE,
+    )
+
+
+def play_tracks(tracks: list[AudioTrack], *, volume: float, crossfade: float):
+    session = CrossfadeSession(volume=volume, crossfade_seconds=crossfade)
+    for track in tracks:
+        session.source.enqueue(track)
+
+    player = open_ffplay()
+    try:
+        while True:
+            frame = session.source.read()
+            if not frame:
+                break
+            if not player.stdin:
+                break
+            player.stdin.write(frame)
+    finally:
+        session.stop()
+        if player.stdin:
+            player.stdin.close()
+        player.wait(timeout=5)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Play a Veloura-powered streamer queue.")
+    parser.add_argument("sources", nargs="+", help="Local files, stream URLs, or yt-dlp search queries.")
+    parser.add_argument("--preset", default="streamer")
+    parser.add_argument("--volume", type=float, default=0.65)
+    parser.add_argument("--crossfade", type=float, default=8.0)
+    parser.add_argument("--cache-dir")
+    parser.add_argument("--no-cache", action="store_true")
+    args = parser.parse_args(argv)
+
+    cache = None if args.no_cache else FileAnalysisCache(args.cache_dir)
+    tracks = asyncio.run(build_tracks(args.sources, preset=args.preset, cache=cache))
+    play_tracks(tracks, volume=args.volume, crossfade=args.crossfade)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

veloura_audio-0.3.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "veloura-audio"
+version = "0.3.0"
+description = "Reusable Python audio engine with crossfade and beat-aware transition planning."
+readme = "README.md"
+requires-python = ">=3.12"
+keywords = [
+    "audio",
+    "crossfade",
+    "ffmpeg",
+    "music",
+    "streaming",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio",
+    "Topic :: Multimedia :: Sound/Audio :: Mixers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.scripts]
+veloura = "veloura.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/VelouraAudio/veloura-audio"
+Repository = "https://github.com/VelouraAudio/veloura-audio"
+Issues = "https://github.com/VelouraAudio/veloura-audio/issues"
+
+[project.optional-dependencies]
+stream = [
+    "yt-dlp>=2026.3.17",
+]
+discord = [
+    "discord.py>=2.3.0",
+    "PyNaCl>=1.5.0",
+]
+all = [
+    "discord.py>=2.3.0",
+    "PyNaCl>=1.5.0",
+    "yt-dlp>=2026.3.17",
+]
+
+[tool.setuptools.packages.find]
+include = ["veloura*"]
+
+[tool.setuptools.package-data]
+veloura = ["py.typed"]

veloura_audio-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+