Ytfzf - Search (With Thumbnails) And Play YouTube Videos From A Terminal
ytfzf is a script to search, download and play YouTube videos by making use of mpv and youtube-dl under the hood. It works on Linux and macOS. The command line script had its first stable (1.0.0) release last week.
Original story by Logix from the Linux Uprising Blog. Published 2020-05-07, Originally published 2020-05-05.
This work is available under the Creative Commons Attribution (CC BY) license.
ytfzf running in a terminal. Screenshot by Logix, licensed under the Creative Commons Attribution license.
ytfzf initially started as a single line script, but has since evolved, recently gaining the ability to show YouTube thumbnails in the terminal, along with other enhancements.
For each YouTube search query, a list of results in shown in the right-hand side pane. On the left-hand side you can see the selected video title, the channel that posted the video, the number of views, video duration, upload date, and the video thumbnail (which is optional).
Use the ↑ and ↓ arrow keys to navigate through the search results, and press the ↵ Enter key to play the video (or download it, it ytfzf was started with the -d command line parameter). The videos are played using mpv by default, but you can change this with another video player, as long as it has the ability to launch YouTube links.
The thumbnails are implemented using Überzug, a command line utility which allows drawing images on terminals by using child windows. Since Überzug only works on X11, the ytfzf video thumbnails feature is also tied to X11 sessions, and does not work on Wayland. Also, don't expect this to work in a tty - it obviously won't.
It's worth noting that the video thumbnails may sometimes be displayed outside the terminal window. In such cases you'll need to resize the terminal, then press the ↑ / ↓ arrow keys to select a different video, and it will use an updated thumbnail size.
Besides this, ytfzf also features support for video history, allows choosing the media format, and can queue multiple tracks (using fzf multi-selection). You can search for YouTube videos and play / download using fzf, dmenu or rofi.
Other features include the ability to play / download audio only, auto-play and repeat YouTube videos, play a random search result, and there's also an option to show available media formats before proceeding.
See the ytfzf --help for a complete list of options.
For future releases, the developer intends to implement support for YouTube playlists and comments. There's no timeline for when these features will be implemented though.
Configuring and using ytfzf[edit]
The ytfzf configuration can be set in the ~/.config/ytfzf/conf.sh file, or using environment variables. Let's use ~/.config/ytfzf/conf.sh to set everything up below. Create the ~/.config/ytfzf folder:
Now open ~/.config/ytfzf/conf.sh in a text editor (create it since it doesn't already exist), and paste the following:
YTFZF_HIST=1 # history is on by default it can be set to -> 0 history off, 1: history on
YTFZF_LOOP=0 # if set to 1 it is on but normally it is off by default. Can be turned on using option -l
YTFZF_PREF="bestvideo[height<=?1080]+bestaudio/best" # set the video format
YTFZF_ENABLE_FZF_DEFAULT_OPTS=1 # fzf colors are going to be the one from your fzf configuration
FZF_PLAYER="mpv" # sets the video player used by ytfzf (mpv by default), e.g. FZF_PLAYER="devour mpv"; you can also specify the YTFZF_PLAYER_FORMAT, e.g. YTFZF_PLAYER_FORMAT="devour mpv --ytdl-format="
This is an example configuration. You can change some of these settings, use them as they are, or uncomment them to use the defaults. You can find more configuration options here.
Using ytfzf is as easy as running:
ytfzf
After typing this command, you'll be prompted to enter the YouTube search query, like this:
$ ytfzf
Search Youtube:
The YouTube search results won't have thumbnails while using this though. To enable thumbnails, run ytfzf with the -t (or --thumbnails) command line parameter:
ytfzf -t
By default, ytfzf plays a video from your search results when you hit ↵ Enter. If you want to download the video instead of playing it, use the -d command line parameter:
ytfzf -d
Want to queue YouTube videos in ytfzf (and thus, in mpv)? Press Tab ↹ to select each video that's going to be added to the queue, to be played in mpv. Use > and < (so use ⇧ Shift+> and ⇧ Shift+<) to navigate through the queue to the next and previous videos.
For more details on configuring and using ytfzf, including how to use it with external menus such as dmenu or rofi, see its project page.
Install ytfzf[edit]
ytfzf can be installed from AUR on Arch Linux / Manjaro, and using the nitratesky overlay on Gentoo. You may also install it on macOS.
For other Linux distributions, installing ytfzf is fairly easy since it's just a script. You'll need to install its dependencies manually though: mpv, youtube-dl, fzf (optional, for menu), jq and ueberzug (optional, for video thumbnails; this too has some dependencies). We'll also need git to get the latest ytfzf.
Below you'll find step-by-step instructions for installing ytfzf on Debian / Ubuntu / Linux Mint / Pop!_OS and other Linux distributions based on Debian or Ubuntu, as well as for Fedora. You can install ytfzf on any other Linux distribution as explained below, but you'll need to figure out the dependency names for your Linux distribution yourself.
As a reminder, video thumbnails don't work on Wayland, so if you use Fedora or Ubuntu 21.04, which use Wayland by default, you can either use this without thumbnails, or switch from Wayland to the X11 session from the login screen.
1. Install the ytfzf dependencies, as well as the Üeberzug dependencies.
- Debian / Ubuntu / Linux Mint / Pop!_OS:
sudo apt install jq mpv fzf git python3-pip python3-wheel python3-dev python3-xlib libx11-dev libxext-dev make
- Fedora (also requires adding the RPMFusion repositories to install mpv):
sudo dnf install https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm
sudo dnf install jq mpv fzf git python3-pip python3-wheel python3-devel python3-xlib libX11-devel libXext-devel make
For any Linux distribution: Since youtube-dl is usually updated in the repositories (at least on Debian / Ubuntu), let's install it from PyPi. We'll also need to install ueberzu in the same way:
python3 -m pip install --user youtube-dl ueberzug
It's probably a good idea to remove the youtube-dl package if you've installed it from the repositories. You can later update youtube-dl using python3 -m pip install --user --upgrade youtube-dl
2. Get the ytfzf GitHub repository, and install ytfzf:
git clone https://github.com/pystardust/ytfzf
cd ytfzf
sudo make install
This installs the ytfzf script into /usr/local/bin, so make sure you have this directory in your PATH.
In case you later want to uninstall it, navigate to the ytfzf directory and run:
sudo make uninstall
You can use mpv alone to search YouTube and play the search results by running mpv ytdl://ytsearch[n]:keywords (replace [n], without brackets, with the number of search results you want added to the playlist) as long as you have youtube-dl installed. You can try mpv ytdl://ytsearch5:rockit\ little\ cat to enjoy a wonderful song by the South Korean duo Rockit Girl. However, mpv will just play the search results, it will not show any list of results you can easily choose songs or videos from. ytfzf can do that and a lot more. It is worth a look if you love using the terminal and you want to search and watch videos from there.
Enable comment auto-refresher