ytsurf: Watch YouTube Videos Without Leaving Your Terminal

Ever found yourself deep in a coding session, needing to quickly check a tutorial or listen to some background music, but dreading the context switch to your browser? I built ytsurf to solve exactly this problem.

What is ytsurf?

ytsurf is a lightweight shell script that brings YouTube search and playback directly to your terminal. No more alt-tabbing to your browser, getting distracted by recommendations, or losing your flow state.

Key Features

• Lightning-fast search: Search YouTube directly from your command line
• Interactive selection: Beautiful fzf interface with thumbnail previews via chafa
• Smart caching: Results cached for 10 minutes to speed up repeated searches
• Zero friction playback: Selected videos play instantly in mpv
• Distraction-free: No YouTube UI, no recommendations, just the content you want

How It Works

The magic happens through a combination of proven Unix tools:

• yt-dlp fetches video information and metadata
• jq parses the JSON responses
• fzf provides the interactive selection interface
• chafa displays thumbnail previews right in your terminal
• mpv handles the video playback

Installation

Arch Linux (Easy Mode)

yay -S ytsurf
# or
paru -S ytsurf

Manual Installation

mkdir -p ~/.local/bin
curl -o ~/.local/bin/ytsurf https://raw.githubusercontent.com/Stan-breaks/ytsurf/main/ytsurf.sh
chmod +x ~/.local/bin/ytsurf

Usage

It’s as simple as:

ytsurf "javascript async await tutorial"

Or run it without arguments for interactive mode:

ytsurf

You’ll get a beautiful fzf interface showing:

• Video titles (truncated for readability)
• Duration
• Channel name
• Live thumbnail previews as you navigate

Press Enter to start watching with mpv!

Why I Built This

As developers, we live in the terminal. Whether it’s running builds, managing git repos, or debugging issues, the command line is our home. But every time we needed to reference a video tutorial or wanted some background music, we had to break our flow by switching to a browser.

YouTube’s web interface, while great for casual browsing, can be a productivity killer with its recommendations and rabbit holes. ytsurf gives you the content you need without the distractions.

The Technical Details

The script leverages yt-dlp‘s search capabilities to fetch the top 10 results for any query. It then uses jq to parse and format the JSON response into a readable list. The thumbnail URLs are passed to chafa for in-terminal image display, creating a surprisingly rich browsing experience.

Caching is implemented using simple file timestamps – if a search was performed within the last 10 minutes, it uses the cached results instead of making a new API call.

Performance & Efficiency

• Cached searches: Sub-second response times for repeated queries
• Lightweight: Uses existing system tools, no heavy dependencies
• Bandwidth efficient: Only downloads thumbnails for viewed results
• Memory friendly: Minimal resource usage compared to browser tabs

Future Enhancements

I’m considering adding:

• Playlist support
• History tracking
• Custom mpv options
• Integration with other video platforms

Try It Out!

If you’re a terminal enthusiast who values productivity and minimal distractions, give ytsurf a try. It’s open source, lightweight, and designed by developers, for developers.

GitHub: Stan-breaks/ytsurf
AUR Package: ytsurf

What terminal tools have transformed your workflow? Drop a comment below – I’d love to hear about your favorite productivity hacks!