Metadata-Version: 2.4
Name: gana-player
Version: 1.0.4
Summary: A Cyberpunk CLI Music Player for Hackers
Home-page: https://github.com/juniorsir/gana
Author: JuniorSir
Author-email: juniorsir011@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Android
Classifier: Environment :: Console
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: yt-dlp>=2023.10
Requires-Dist: requests
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 🌌 GANA PLAYER

> **The Ultimate Cyberpunk CLI Music Player for Hackers.**

[![PyPI version](https://badge.fury.io/py/gana-player.svg)](https://badge.fury.io/py/gana-player)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**GANA** is a high-performance, terminal-based YouTube music player designed for Linux and Termux.  
It features a 3D Hyperdrive UI, AI-powered recommendations, background playback with lock-screen controls, and automatic offline caching.

---

# 🚀 Quick Start

## 1️⃣ Install via Pip (Universal)

Works on any system with Python 3.8+.

```bash
pip install gana-player
```

Run it:

```bash
gana
# OR
gana-player
```

---

## 2️⃣ Install on Termux (Android)

For the full experience (hardware controls, notifications), install the API dependencies first.

```bash
pkg update
pkg install python mpv ffmpeg termux-api
pip install gana-player
gana
```

> ⚠️ You must install the **Termux:API** app (Play Store or F-Droid) for lock screen controls to work.

---

# 🎮 Controls & Hotkeys

## 🖥 Global CLI Commands

You don't need to open the UI to use GANA.

```bash
gana search "lofi hip hop"   # Jump straight to search results
gana play "starboy"          # Instantly auto-play best match
gana resume                  # Continue where you left off
gana history                 # View and manage playback history
gana help                    # Show the interactive manual
```

---

## 🎵 In-Player Hotkeys

| Key        | Action |
|------------|--------|
| `SPACE`    | Pause / Resume |
| `N / P`    | Next / Previous Song |
| `← / →`    | Seek -10s / +10s |
| `S`        | Open ✨ AI Recommendations HUD |
| `V`        | Open Queue Manager |
| `R`        | Toggle Loop (Sequence ➡ / One 🔂 / All 🔁) |
| `B`        | Background Mode (Keep playing while browsing menu) |
| `Q`        | Stop & Return to Menu |

---

## 📂 Queue Manager (Press `V`)

| Key     | Action |
|---------|--------|
| `ENTER` | Jump to selected song |
| `D`     | Delete song from queue |
| `R`     | Toggle Loop Mode |

---

# ✨ Features Breakdown

## 🌌 3D Hyperdrive UI

The interface reacts to your music.

- When playing → starfield accelerates into hyperdrive  
- When paused → starfield drifts slowly  
- A sine-wave rainbow visualizer dances above the seek bar  

---

## 🧠 AI Recommendations

Press `S` while playing any song.

GANA analyzes:
- Current track  
- Recent search history  

It generates **4 intelligent recommendations**.  
Select one to instantly queue it next.

---

## 📡 Offline Caching (Smart Data Mode)

- Every song is cached automatically to:
  ```
  ~/.gana/cache/
  ```
- Replaying a cached song uses **0 data**
- Auto-cleans cache (keeps last 5 songs)
- Works completely offline

### 🔌 Offline Mode

Turn off WiFi → Open History → Play cached songs instantly.

---

## 📱 Android Integration

- 🔒 **Lock Screen Support**
  - Song title
  - Album art
  - Offline Support 

- 🔔 **Notification Controls**
  - Tap notification to Pause/Play
  - Use Next / Prev buttons
  - Use Single tap to add sleep time

---

# 🛠 Troubleshooting

## ❌ "mpv not found"

GANA requires `mpv` to play audio.

**Linux:**
```bash
sudo apt install mpv
```

**Termux:**
```bash
pkg install mpv
```

---

## ❌ Notifications not showing on Android

- Ensure:
  ```bash
  pkg install termux-api
  ```
- Install **Termux:API** app
- Restart Termux

---

## ❌ Visualizer looks broken / text glitchy

Ensure your terminal supports 256 colors:

```bash
export TERM=xterm-256color
```

---

# 📦 Installation for Advanced Users

## Install via DEB (Debian / Ubuntu)

If a `.deb` release is provided:

```bash
sudo apt install ./gana_1.0.0_all.deb
```

---

## 🔨 Build from Source

```bash
git clone https://github.com/yourusername/gana
cd gana
pip install .
```

---

# ❤️ Made for the CLI Community

Built with love for hackers, developers, and terminal enthusiasts.

---

## 📄 License

MIT License © 2026

