Terminal-first streaming engine with smart autoplay radio.

---

Overview

Tuitify is a terminal-first music streaming application built for users who want a fast, keyboard-driven listening experience without leaving the command line. It combines YouTube-powered music discovery, seamless playback, and radio-style autoplay recommendations into a lightweight TUI (Text User Interface) that feels like a minimal Spotify for the terminal.

Users can search for music or podcasts, instantly stream audio using VLC-backed playback, and continue listening through an automatically generated recommendation queue based on the currently playing track. Album artwork, progress tracking, next-up previews, playback controls, and keyboard shortcuts make the experience smooth, responsive, and practical for daily use.

Why Tuitify?

Most terminal music players focus only on local files. Tuitify is built for streaming-first listening. Listen your favourite music and podcasts without leaving the terminal.

The goal is simple: minimal friction, continuous listening, and a terminal-native music experience, no more ads, no more interruptions, just the freedom to enjoy your music seamlessly from your command line.

As a contributor to SimpMusic, I’ve seen how a simple and seamless streaming experience can completely change the way people listen to music. Tuitify brings that same idea to the terminal-a lightweight, keyboard-first music player that keeps playback smooth, fast, and uninterrupted.

Features

• Global Search: Instantly find songs, albums, or podcasts.
• Smart Radio Engine: Automatically seeds recommendations based on your current track for non-stop playback.
• High-Quality Audio: Uses yt-dlp and vlc for reliable and high-quality streaming.
• Keyboard Centric: Optimized for efficiency with customizable keybindings.
• Album Art: Real-time display of track artwork in your terminal.

Support Matrix

Terminal	TGP support	Sixel support	Works with textual-image
Black Box	❌	✅	✅
foot	❌	✅	✅
GNOME Terminal	❌	❌
iTerm2	❌	✅	✅
kitty	✅	❌	✅
konsole	✅	✅	✅
tmux	❌	✅	✅
Visual Studio Code	❌	✅	✅
Warp	❌	❌	❌
wezterm	✅	✅	✅
Windows Console	❌	❌
Windows Terminal	❌	✅	✅
xterm	❌	✅	✅

✅ = Supported; ❌ = Not Supported

Getting Started

Prerequisites

• Python 3.12+
• VLC Media Player: Ensure VLC is installed on your system as it's the core playback engine.

Installation

1. Clone the repository:

   git clone https://github.com/Hemanth2332/tuitify.git
   cd tuitify

2. Install dependencies (using uv or pip):

   uv sync
   # or
   pip install .

Running the App

Simply run the main.py file:

uv run ./main.py

Controls

• i: Focus search input
• Enter: Search / Play selected track
• Space: Play / Pause
• n: Skip to next track
• tab: switch between panels
• ← / →: Seek backward/forward (10s)
• q: Quit Tuitify

Feel Free to change the keybindings to your own preference in src/tui/keybindings.py.

Project Structure

• src/tui/: Main TUI application logic and layout.
• src/youtube/: YouTube service, streaming player, and recommendation engine.
• src/search/: Search-specific wrappers.

Contribution

Tuitify is built to grow, and contributions are always welcome.

If you'd like to contribute:

1. Fork the repository
2. Create a new branch (feature/your-feature-name)
3. Commit your changes
4. Open a Pull Request

Ideas, discussions, and improvements are always appreciated.

License

This project is licensed under the MIT License - see the LICENSE file for details.