Metadata-Version: 2.4
Name: cli-music-player-cthulhu
Version: 0.4.1
Summary: A lightweight terminal music player with a pulsing Cthulhu
Author-email: Thiago Mendonça <tfariamendonca@gmail.com>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pygame>=2.5.0
Requires-Dist: mutagen>=1.45.0
Requires-Dist: yt-dlp>=2023.0.0
Dynamic: license-file

# CLI Music Player

A lightweight, terminal-based music player written in Python, featuring a pulsing Cthulhu and online lyrics support.

![Demo](demo.gif)

## Features

- **Terminal User Interface (TUI):** Clean interface built with `curses`.
- **Online & Synced Lyrics:** Automatic lyrics fetching from `LRCLIB`, `Letras.mus.br`, and `Lyrics.ovh`.
- **File Browser:** Navigate directories to find your music.
- **Recursive Library Mode:** Scan all subdirectories and play your entire collection at once.
- **Shuffle Mode:** Randomized playback with a history-aware "Previous" function.
- **Audio Formats:** Supports mp3, wav, flac, ogg, m4a, wma, aac, opus.
- **Playback Controls:**
  - Play / Pause / Stop
  - Next / Previous Track
  - Volume Control
  - Progress Bar with Synced Lyrics highlighting.
- **Now Playing View:** Dedicated screen showing track info, progress, and Cthulhu/Lyrics.

## Requirements

- Python 3.8+
- Audio output device.

## Installation

### Via PIP (Recommended)

Install directly from PyPI:

```bash
pip install cli-music-player-cthulhu
```

### From Source

1. Clone the repository:
   ```bash
   git clone https://github.com/thiagofmendonca/cli-music-player.git
   cd cli-music-player
   ```

2. Install dependencies:
   ```bash
   pip install pygame mutagen
   ```

3. Run the script:
   ```bash
   python musicplayer.py
   ```

## Usage

Run the command from your terminal:

```bash
musicplayer
```

### Controls

| Key | Action |
| :--- | :--- |
| **Arrow Up/Down** | Navigate files / Scroll Lyrics |
| **Enter** | Play file / Open directory |
| **Space** | Play / Pause |
| **l** | Toggle Lyrics View |
| **n** | Next Track |
| **p** | Previous Track (History-aware) |
| **z** | Toggle Shuffle Mode |
| **R** | Load Recursive Library (all subfolders) |
| **B** | Return to Browser Mode |
| **+ / -** | Volume Up / Down |
| **Tab** | Toggle "Now Playing" View |
| **s** | Stop |
| **q** | Quit (or go back from Player View) |

## License

MIT
