GopherTube

🚧 Development Paused

Hey there 👋
This project is currently on hold while I focus on my exams.
Development will resume soon

Thanks for your patience!

~ @krishnassh

<p align="left"> <a href="https://discord.gg/TqYvzbGJzb" target="_blank"> <img src="https://invidget.switchblade.xyz/TqYvzbGJzb" alt="Join our Discord" /> </a> </p>

A simple terminal YouTube client for searching and watching videos using yt-dlp and mpv.

Overview
Features
Who is this Project for?
Prerequisites
Installation
Usage
- Keyboard Shortcuts
Configuration
- Configuration Options
Troubleshooting
FAQ
Roadmap
Star History
Contributing

Overview

GopherTube is a terminal-based YouTube client. It scrapes and parses the youtube website to search YouTube and uses mpv to play videos. The UI is built with Go and uses fzf, and is keyboard-driven.

Screenshots

<p align="left"> <img src=".assets/demo.png" alt="Additional Demo 2" style="width:100%;max-width:900px;min-width:300px;" /> <br><em>searching for videos</em> </p>

Demo Video
Watch the demo video here

Features

Fast YouTube search (scrapes YouTube directly, no API key needed)
Play videos with mpv
Minimal terminal UI (fzf)
Keyboard navigation (arrows, Enter, Tab, Esc)
TOML config
Download videos with quality selection (yt-dlp)
Downloads menu: browse and play downloaded videos
Thumbnail preview in downloads menu

Who is this Project for?

This Project is for everyone who enjoys Terminal apps
For Everyone Who respects thier Privacy and Freedom
Anyone who wants to watch videos while using as few system resources as possible — for example, if you have an older or low-spec machine that struggles to run YouTube in a full web browser, this project can help you cut down on resource usage.

Prerequisites

Go 1.21+
mpv (media player)
fzf (fuzzy finder)
chafa (terminal image preview)
yt-dlp (YouTube downloader)

Install dependencies:

# Ubuntu/Debian
sudo apt install mpv fzf chafa
pip install -U yt-dlp

# macOS
brew install mpv fzf chafa yt-dlp

# Arch Linux (Aur is having shasum issues install it from the script)
yay -S gophertube yt-dlp

Installation

Quick Install (One-liner):

curl -sSL https://raw.githubusercontent.com/KrishnaSSH/GopherTube/main/install.sh | bash

Package Managers

# Arch Linux (AUR)
yay -S gophertube

# macOS (Homebrew) - coming soon
# brew tap KrishnaSSH/tap
# brew install gophertube

Manual Installation:

git clone https://github.com/KrishnaSSH/GopherTube.git
cd GopherTube
go build -o gophertube
./gophertube

Usage

Start the app: ./gophertube
Type a search and press Enter (or press Escape to exit)
Use ↑/↓ to move, Enter to play, Tab to load more, Esc to go back to search
Thumbnails and video info are shown in the preview
mpv opens to play the selected video

Keyboard Shortcuts

| Key | Action | |----------|-------------------------| | Enter | Search / Play video | | ↑/↓ | Navigate video list | | Tab | Load more videos | | Esc | Go back / Quit |

Configuration

Create ~/.config/gophertube/gophertube.toml:

search_limit = 30
quality = "1080p"           # default: 1080p (options: 1080p, 720p, 480p, 360p, Audio)
downloads_path = "/home/$USER/Videos/GopherTube"  # where to save downloads

Configuration Options

| Key | Type | Default | Description | |------------------|--------|-------------------------------------------|----------------------------------------------| | search_limit | int | 30 | Max results to fetch per page/load more. | | quality | string | "1080p" | Preferred quality or Audio for audio-only. | | downloads_path | string | "$HOME/Videos/GopherTube" | Directory to save downloads. |

Troubleshooting

fzf not found: install fzf (see Prerequisites) and ensure it’s in PATH.
mpv not launching: verify mpv is installed and accessible from terminal.
No thumbnails: ensure chafa is installed; some terminals may not support images.
yt-dlp errors: update yt-dlp to the latest version.

FAQ

Does this use the YouTube API? No, it scrapes the website. No API key required.
Can I play audio only? Yes. Choose "Listen" or set quality to Audio.
Where are files downloaded? See downloads_path in config.

Roadmap

Configurable keybindings
Optional inline player controls
Windows support (best effort)
CI and release artifacts for more platforms

Star History

<div align="left"> <h3>💖 Support GopherTube</h3> <p>If you find this project useful, consider supporting its development with crypto:</p> <table> <tr> <td><img src="https://img.shields.io/badge/BTC-donate-orange?style=for-the-badge&logo=bitcoin&logoColor=white" alt="BTC" /></td> <td><code>bc1q78ymwmf33vr33ly8rpej7cqvr6cljjcdjf3g6p</code></td> </tr> <tr> <td><img src="https://img.shields.io/badge/LTC-donate-blue?style=for-the-badge&logo=litecoin&logoColor=white" alt="LTC" /></td> <td><code>ltc1qsfp4mdwwk3nppj278ayphqmkyf90xvysxp3des</code></td> </tr> <tr> <td><img src="https://img.shields.io/badge/ETH-donate-purple?style=for-the-badge&logo=ethereum&logoColor=white" alt="ETH" /></td> <td><code>0x6f786f482DDa360679791D90B7C8337655dC2199</code></td> </tr> </table> </div>

License

Contributing

PRs and issues welcome.

See CONTRIBUTING.md for guidelines.

Gophertube

Install / Use

README