YouTube in Your Terminal? Meet ytsurf

Let's be honest, sometimes you just want to watch a quick tutorial, catch a music video, or listen to a talk without falling into the YouTube rabbit hole. The endless stream of recommended videos, comments, and notifications can be a major distraction when you're trying to stay focused. What if you could strip all that away and get straight to the content?

Enter ytsurf, a neat little tool that brings YouTube right into your terminal. It's a clean, minimalist interface for watching videos without ever leaving your command line. For developers who live in their terminals, it's a surprisingly natural fit.

What It Does

ytsurf is a terminal-based YouTube client. You can search for videos, select from the results, and stream them directly in your terminal using ASCII graphics or Sixel graphics (if your terminal supports it). It uses mpv under the hood for playback, so you get a robust, familiar media player experience, just wrapped in a distraction-free, keyboard-driven interface.

Why It's Cool

The main appeal here is the sheer focus it forces. There are no thumbnails for other videos, no comment sections, and no algorithm trying to keep you watching. You search for what you want, you play it, and that's it. It turns YouTube into a utility rather than a time-sink.

From a technical perspective, it's a clever and practical use of existing tools. It leverages mpv for the heavy lifting of video decoding and streaming, and yt-dlp for fetching video data and streams, which is the modern, reliable successor to youtube-dl. The terminal UI is built with Textual, a Python framework for building TUI (Text User Interface) applications. This stack choice makes it both powerful and relatively straightforward to maintain.

It's perfect for:

• Quickly pulling up a programming conference talk while you code.
• Listening to music or a podcast in the background.
• Watching tutorials in a separate terminal pane without switching contexts to a browser.

How to Try It

Getting started is straightforward. You'll need Python and pip installed.

1. Install it:

   pip install ytsurf
   

2. Run it: Simply type ytsurf in your terminal. The first run will guide you through a quick setup to configure your video quality preference and terminal graphics mode.

3. Use it: Use the / key to start a search, type your query, and hit enter. Navigate the results with arrow keys, press enter to play a video, and use standard mpv keyboard controls (space for pause/play, q to quit, etc.) during playback.

For more details, configuration options, or to contribute, check out the project on GitHub: https://github.com/Stan-breaks/ytsurf

Final Thoughts

ytsurf won't replace your browser for every YouTube session—sometimes you want the comments and recommendations. But as a focused, developer-centric tool, it's brilliant. It solves a specific problem of distraction and context-switching in a very elegant way. It's one of those tools that feels obvious once you see it, and you'll probably find yourself using it more than you'd expect, especially during deep work sessions. Give it a spin and see if it changes how you use YouTube for work.

Follow us for more cool projects: @githubprojects