https://github.com/krishnassh/gophertube
A modern terminal user interface for searching and watching YouTube videos using mpv and chafa
https://github.com/krishnassh/gophertube
chafa go golang terminal-based terminal-ui youtube youtube-dl
Last synced: about 2 months ago
JSON representation
A modern terminal user interface for searching and watching YouTube videos using mpv and chafa
- Host: GitHub
- URL: https://github.com/krishnassh/gophertube
- Owner: KrishnaSSH
- License: gpl-3.0
- Created: 2025-07-12T07:51:28.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2026-04-12T00:57:50.000Z (2 months ago)
- Last Synced: 2026-04-12T02:25:31.823Z (2 months ago)
- Topics: chafa, go, golang, terminal-based, terminal-ui, youtube, youtube-dl
- Language: Go
- Homepage:
- Size: 3.52 MB
- Stars: 382
- Watchers: 4
- Forks: 19
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-cli-apps-in-a-csv - GopherTube - A terminal-based YouTube client that scrapes YouTube search results and uses mpv for video playback. (<a name="viewers"></a>Viewers)
- awesome-tuis - GopherTube - based YouTube client that scrapes YouTube search results and uses mpv for video playback (Table of Contents)
- awesome-cli-apps - GopherTube - A terminal-based YouTube client that scrapes YouTube search results and uses mpv for video playback. (<a name="viewers"></a>Viewers)
README
# GopherTube
[](https://golang.org/dl/)
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://github.com/KrishnaSSH/GopherTube)
[](https://github.com/KrishnaSSH/GopherTube/commits/main)
[](https://github.com/KrishnaSSH/GopherTube/graphs/contributors)
[](https://github.com/KrishnaSSH/GopherTube)
[](https://github.com/KrishnaSSH/GopherTube/issues)
[](https://github.com/KrishnaSSH/GopherTube/pulls)
[](https://github.com/KrishnaSSH/GopherTube/stargazers)
[](https://github.com/KrishnaSSH/GopherTube/releases)
[](https://github.com/KrishnaSSH/GopherTube/releases)
[](https://goreportcard.com/report/github.com/KrishnaSSH/GopherTube)
[](https://aur.archlinux.org/packages/gophertube)
A simple terminal YouTube client for searching and watching videos using [yt-dlp](https://github.com/yt-dlp/yt-dlp) and [mpv](https://mpv.io/).
---
## Table of Contents
- [Overview](#overview)
- [Features](#features)
- [Who is this Project for?](#who-is-this-project-for)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Quick Install](#installation)
- [Manual Installation](#installation)
- [Usage](#usage)
- [Keyboard Shortcuts](#keyboard-shortcuts)
- [Configuration](#configuration)
- [Configuration Options](#configuration-options)
- [Troubleshooting](#troubleshooting)
- [FAQ](#faq)
- [Roadmap](#roadmap)
- [Star History](#star-history)
- [Contributing](#contributing)
## Overview
GopherTube is a tui based youtube client. It scrapes and parses the youtube website to get the metadate and uses [mpv](https://mpv.io/) to play videos. The ui is built with bubbletea, and is keyboard driven.
**Screenshots**
main menu
searching for videos
video plays in mpv
**Demo Video**
[▶ Watch the demo video](https://github.com/user-attachments/assets/5b1a7f52-c5c3-405c-ae0a-7f113c3978b8)
## Features
- **Fast YouTube search** (scrapes YouTube directly, no API key needed)
- Play videos with [mpv](https://mpv.io/)
- Minimal terminal UI (fzf)
- Keyboard navigation (arrows, Enter, Tab, Esc)
- TOML config
- **Download videos** with quality selection ([yt-dlp](https://github.com/yt-dlp/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 tuis,
- anyone who wants to watch videos while using low system resources. for example if you have an older or lowspec machine that struggles to run youtube in full web browser this app might help you cut down recourse usage.
---
## Prerequisites
- [Go 1.21+](https://go.dev/dl/)
- [mpv](https://mpv.io/) (media player)
- [chafa](https://hpjansson.org/chafa/) (terminal image preview)
- [yt-dlp](https://github.com/yt-dlp/yt-dlp) (YouTube downloader)
Install dependencies:
```bash
# Ubuntu/Debian
sudo apt install mpv chafa
pip install -U yt-dlp
# macOS
brew install mpv chafa yt-dlp
# Arch Linux (Aur is having shasum issues install it from the script)
yay -S gophertube
or
yay -S gophertube-bin # for direct binary downloads
```
---
## Installation
**Quick Install (One-liner):**
```bash
curl -sSL https://raw.githubusercontent.com/KrishnaSSH/GopherTube/main/install.sh | bash
```
**Manual Installation:**
```bash
git clone https://github.com/KrishnaSSH/GopherTube.git
cd GopherTube
go build -o gophertube
./gophertube
```
---
## Usage
- Start the app: `gophertube`
- Select between Search Youtube, Search Downloads, Settings, Quit. and press enter.
- Use ↑/↓ or j/k to move, Enter to play, Tab to load more, Esc to go back to search
- mpv opens to play the selected video
---
## Configuration
Create `~/.config/gophertube/gophertube.toml`:
```toml
search_limit = 30
quality = "1080p" # default: 1080p (options: 1080p, 720p, 480p, 360p, Audio)
downloads_path = "/home/$USER/Videos/GopherTube" # where to save downloads
theme = "Minimal" # default: Minimal (options: Minimal, Gopher, Gruvbox, etc)
```
### 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. |
| theme | string | "Minimal" | Default application theme. |
---
## Troubleshooting
- __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. API key is not 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
- thumbnail support in the bubbletea rewrite
## Star History
---
💖 Support GopherTube
If you find this project useful, consider supporting its development with crypto:
bc1q78ymwmf33vr33ly8rpej7cqvr6cljjcdjf3g6p
ltc1qsfp4mdwwk3nppj278ayphqmkyf90xvysxp3des
0x6f786f482DDa360679791D90B7C8337655dC2199
## License
[](LICENSE)
---
## Contributing
PRs and issues welcome.
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
---