# 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](https://pypi.org/project/miniaudio/) (Low-latency C-level bindings)
* **UI Framework:** [Textual](https://textual.textualize.io/) (Async TUI with CSS support)
* **Build System:** [Poetry](https://python-poetry.org/)
* **Testing:** [Pytest](https://pytest.org/) & [Unittest.mock](https://docs.python.org/3/library/unittest.mock.html)

## Installation & Setup

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

### 1. Build and Install
```bash
# 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 
```Bash
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.

```Bash
poetry run pytest -v
```

## License 

[MIT license]()