riff-player 2.0.0

Terminal media player - play music and video from your terminal

🎵 Riff — Terminal Media Player

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

---

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):

winget install shinchiro.mpv
winget install fzf

Linux (Ubuntu / Debian):

sudo apt install mpv fzf

macOS:

brew install mpv fzf

Step 2 — Clone the repo

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

Step 3 — Install Python dependencies

pip install -r requirements.txt

Step 4 — Verify everything is set up

python riff.py info

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

---

🚀 Usage

# 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	latest	Media engine for audio and video
yt-dlp	≥ 2024.1.0	Internet streaming from 1000+ sites
fzf	latest	Interactive fuzzy file picker
mutagen	≥ 1.47.0	Audio metadata / ID3 tag reading
textual	≥ 0.47.0	Full-screen TUI framework
rich	≥ 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

---

Made with ♪ and Python