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
How It Works
The magic happens through a combination of proven Unix tools:
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/St...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:
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
Future Enhancements
I'm considering adding:
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!
More...
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/St...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!
More...