veridis 0.1.0

A fast, lightweight CLI music player built with miniaudio and Textual

Gamma: High-Performance CLI Audio Engine

Gamma is a fast, lightweight Terminal User Interface (TUI) music player designed for low-latency audio playback and flexible resource management.

Technical Architecture

Gamma has a separate, multi-threaded structure. This design keeps the user interface responsive while delivering high-quality audio output:

• Concurrency Model: It uses a dual-thread architecture. A background daemon thread manages the C-bound Miniaudio backend. The main event loop handles the reactive TUI. This setup prevents UI jerkiness during hardware-intensive playback.
• Memory Optimization: Leverages Python generators for library indexing, achieving O(1) memory complexity during filesystem traversal. This ensures near-instant boot times even with libraries exceeding 10,000+ files.
• Reactive Design System: Built using the Textual framework with a custom CSS-in-TUI design system. It utilizes dynamic layout reflows to adapt to varying terminal dimensions without breaking the visual hierarchy.
• Standardized Packaging: Follows the src-layout convention and utilizes Poetry for deterministic dependency resolution, ensuring 100% reproducible development environments.

Tech Stack

• Core: Python 3.13+
• Audio Engine: Miniaudio (Low-latency C-level bindings)
• UI Framework: Textual (Async TUI with CSS support)
• Build System: Poetry
• Testing: Pytest & Unittest.mock

Installation & Setup

Gamma is packaged as a standard Python module. Ensure you have Poetry installed.

1. Build and Install

# Clone the repository
git clone [https://github.com/Vaibhavtripathi7/py-cli-music-player.git](https://github.com/Vaibhavtripathi7/py-cli-music-player.git)
cd py-cli-music-player

# Install dependencies and link the 'gamma' executable
poetry install

2. Execution

poetry run gamma

Control Interface

Key	Function
Space	Play/Pause
N	Increment to Next Track
Enter	Select Directory/Initialize Playback
D	Toggle Dark/Light mode
Q	Shutdown

Verification(Unit testing)

We use Mocking to simulate the audio engine, allowing tests to run in headless CI environments.

poetry run pytest -v

License

MIT license