veridis 0.1.1

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

Veridis: High-Performance CLI Audio Engine

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

Technical Architecture

Veridis 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: Uses Python generators to index libraries, which keeps memory use at O(1) while traversing the filesystem. This makes sure that boot times are almost instant, even with libraries that have more than 10,000 files.
• Reactive Design System: Made with the Textual framework and a custom CSS-in-TUI design system. It uses dynamic layout reflows to change the way it looks based on the size of the terminal without messing up the visual hierarchy.

Tech Stack

• Core: Python 3.13+
• Audio Engine: Miniaudio
• UI Framework: Textual
• Build System: Poetry
• Testing: Pytest & Unittest.mock

Installation & Setup

Veridis is packaged as a standard Python module.

1.System Dependencies

Depending on your OS, you may need the following audio developement headers:

Linux(Debian/Ubuntu/EndeavourOS)

# Debian/Ubuntu
sudo apt-get install python3-dev libasound2-dev build-essential

#Arch/EndeavourOS
sudo pacman -S alsa-lib base-devel

MacOS(untested)

brew install pkg-config

Windows(untested)

# Install via Chocolatey
# Requires C++ build tools for miniaudio compilation
choco install visualcpp-build-tools

2. Option A: Quick install (via PyPI)

pip install veridis

3. Option B: Build and Install

Ensure you have Poetry installed.

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

# Install dependencies using poetry
poetry install

4. Execution

poetry run veridis

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