Metadata-Version: 2.4
Name: riff-player
Version: 2.0.0
Summary: Terminal media player - play music and video from your terminal
Author: Sapnoneel Barik
License: MIT
Project-URL: Homepage, https://github.com/Sapnoneel/Riff
Project-URL: Repository, https://github.com/Sapnoneel/Riff
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mutagen>=1.47.0
Requires-Dist: yt-dlp>=2024.1.0
Requires-Dist: textual>=0.47.0
Requires-Dist: rich>=13.0.0
Requires-Dist: spotipy>=2.23.0
Requires-Dist: ytmusicapi>=1.3.0
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file
Dynamic: requires-python

# 🎵 Riff — Terminal Media Player

<div align="center">

![Python](https://img.shields.io/badge/Python-3.11+-3776AB?style=flat-square&logo=python&logoColor=white)
![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS-informational?style=flat-square)
![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)
![Status](https://img.shields.io/badge/Status-Active-brightgreen?style=flat-square)

**Play music and video from your terminal. Local files or the entire internet.**

</div>

---

Riff is a cross-platform terminal media player built in Python. Search your local storage with fuzzy-find, stream from YouTube and 1000+ sites, and control everything without ever leaving the terminal.

---

## ✨ Features

| Feature | Description |
|---|---|
| 🎵 **Local Playback** | Searches your Music, Videos, and Downloads folders automatically |
| 🌐 **Internet Streaming** | Powered by yt-dlp — YouTube, SoundCloud, and 1000+ sites |
| 📺 **Video Support** | Stream or play video files from the terminal |
| 🔍 **Fuzzy Search** | Interactive file picker via fzf |
| 🖥️ **TUI Interface** | Beautiful full-screen terminal UI via Textual |
| 💿 **Metadata Display** | Shows title, artist, album from ID3 tags |
| 🪟 **Cross-Platform** | Windows, Linux, and macOS |

---

## 📦 Installation

### Step 1 — Install mpv and fzf

**Windows (PowerShell):**
```powershell
winget install shinchiro.mpv
winget install fzf
```

**Linux (Ubuntu / Debian):**
```bash
sudo apt install mpv fzf
```

**macOS:**
```bash
brew install mpv fzf
```

### Step 2 — Clone the repo

```bash
git clone https://github.com/Sapnoneel/Riff.git
cd Riff
```

### Step 3 — Install Python dependencies

```bash
pip install -r requirements.txt
```

### Step 4 — Verify everything is set up

```bash
python riff.py info
```

You should see green checkmarks next to `mpv`, `yt-dlp`, and `fzf`.

---

## 🚀 Usage

```bash
# Show help
python riff.py

# Check dependency status
python riff.py info

# Play a local file directly
python riff.py play "C:/Music/song.mp3"

# Search your local library (interactive fuzzy picker)
python riff.py search "bohemian rhapsody"

# Search for audio files only
python riff.py search "adele" --audio

# Browse your entire media library
python riff.py browse

# Stream audio from YouTube / internet
python riff.py stream "lofi hip hop"
python riff.py stream "https://youtu.be/dQw4w9WgXcQ"

# Stream video
python riff.py video "big buck bunny"

# Queue and shuffle all search results
python riff.py search "pink floyd" --queue --shuffle

# Launch the full TUI interface
python riff.py tui
```

---

## ⌨️ Playback Controls

These controls work inside mpv during playback:

| Key | Action |
|-----|--------|
| `Space` | Pause / Resume |
| `←` / `→` | Seek 5 seconds |
| `↑` / `↓` | Seek 1 minute |
| `9` / `0` | Volume down / up |
| `m` | Mute |
| `f` | Toggle fullscreen (video) |
| `q` | Quit |

### TUI Controls

| Key | Action |
|-----|--------|
| `L` | Browse local library |
| `S` | Focus search bar |
| `I` | Stream audio from internet |
| `V` | Stream video from internet |
| `Enter` | Play selected file |
| `Q` | Quit |

---

## 🗂️ Project Structure

```
Riff/
├── riff.py                  # Entry point
├── riff/
│   ├── __init__.py          # Package metadata
│   ├── cli.py               # Argument parsing & command dispatch
│   ├── player.py            # mpv wrapper for local playback
│   ├── search.py            # Local file search + fzf picker
│   ├── stream.py            # Internet streaming via yt-dlp
│   ├── meta.py              # Metadata reader (mutagen)
│   ├── tui.py               # Textual TUI interface
│   └── utils.py             # Cross-platform helpers
├── tests/
│   └── __init__.py
├── requirements.txt
├── setup.py
├── .gitignore
└── README.md
```

---

## 🔧 Dependencies

| Package | Version | Purpose |
|---------|---------|---------|
| [mpv](https://mpv.io) | latest | Media engine for audio and video |
| [yt-dlp](https://github.com/yt-dlp/yt-dlp) | ≥ 2024.1.0 | Internet streaming from 1000+ sites |
| [fzf](https://github.com/junegunn/fzf) | latest | Interactive fuzzy file picker |
| [mutagen](https://mutagen.readthedocs.io) | ≥ 1.47.0 | Audio metadata / ID3 tag reading |
| [textual](https://textual.textualize.io) | ≥ 0.47.0 | Full-screen TUI framework |
| [rich](https://rich.readthedocs.io) | ≥ 13.0.0 | Terminal text formatting |

> **Note:** `mpv` and `fzf` are system binaries installed separately (see Installation above).
> All Python packages are installed via `pip install -r requirements.txt`.

---

## 🖥️ Platform Notes

### Windows
- Use **Windows Terminal** (from Microsoft Store) for the best TUI experience
- `mpv` must be installed via `winget install shinchiro.mpv`
- Video plays in a floating mpv window launched from the terminal

### Linux
- Video-in-terminal works best with the **kitty** terminal (`mpv --vo=kitty`)
- All other terminals fall back to a floating mpv window

### macOS
- Video-in-terminal works with **iTerm2**
- Install dependencies via Homebrew

---

## 🤝 Contributing

Contributions are welcome! Here's how:

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/my-feature`
3. Commit your changes: `git commit -m "Add my feature"`
4. Push to your branch: `git push origin feature/my-feature`
5. Open a Pull Request

Please open an issue first for major changes so we can discuss the direction.

---

## 📄 License

MIT © [Sapnoneel Barik](https://github.com/Sapnoneel)

---

<div align="center">
Made with ♪ and Python
</div>
