ytfzf

Search for videos on YouTube with thumbnail previews

$ ytfzf --show-thumbnails [search_pattern]

$ ytfzf --audio-only --auto-select --loop [search_pattern]

$ ytfzf --download --choose-from-history

$ ytfzf --audio-only --select-all [search_pattern]

$ ytfzf --trending --ext-menu [search_pattern]

$ ytfzf --peertube [search_pattern]

ytfzf [OPTIONS] [SEARCH_QUERY | YOUTUBE_URL]

-t
    Perform a search for the given query.

-L
    List trending videos.

-H
    List videos from a specific YouTube channel URL.

-h
    Display help message and exit.

-m
    Play video only (no audio).

-a
    Play audio only.

-i
    Enable interactive mode (default for searches).

-s
    Perform a strict search without using fzf for selection.

-D
    Download the selected video instead of playing it.

-u
    Update the ytfzf script to the latest version.

-o
    Pass additional options directly to mpv (or the configured player).

-f
    Specify the video/audio format code to download/play (e.g., bestaudio, bestvideo[height<=720]).

-l
    Loop the selected video indefinitely.

-c
    Clear ytfzf's cache.

-C
    Specify a custom directory for ytfzf's cache.

-x
    Open the selected video in the default web browser instead of playing it in mpv.

-p
    Search within a specific YouTube playlist URL.

-S
    Sort search results. Common values include date, rating, relevance, views.

-U
    Use an unofficial YouTube API for search.

-M
    Use minimal output for fzf (show only titles).

-v
    Enable verbose output for debugging.

--proxy
    Use a proxy for network requests.

--version
    Display the version of ytfzf and exit.

ytfzf is a powerful command-line utility that brings the YouTube experience to your terminal. It leverages fzf for interactive fuzzy searching of YouTube videos and uses youtube-dl or yt-dlp to fetch video information, with mpv for playback. Users can quickly search for videos, browse trending content, or access channel videos directly from their shell, then play them, download them, or even extract just the audio. Its interactive nature, powered by fzf, allows for efficient navigation and selection of results, making it a favorite for those who prefer a keyboard-driven workflow. ytfzf abstracts away the complexities of underlying command-line arguments, providing a streamlined interface.

ytfzf relies on several external dependencies to function correctly:
- fzf: For interactive fuzzy searching. Without it, only strict search (-s) is possible.
- mpv (or an alternative video player): For playing videos.
- youtube-dl or yt-dlp: For fetching video information and streams from YouTube.
Ensure these dependencies are installed and accessible in your system's PATH. Performance may vary based on network speed and API rate limits.

ytfzf requires fzf, mpv (or an alternative player like vlc), and youtube-dl or yt-dlp to be installed on your system. It will typically check for yt-dlp first, then youtube-dl.

Users can customize ytfzf's behavior through environment variables or by editing the script directly. For instance, YTFZF_DEFAULT_PLAYER can be set to use a player other than mpv.

The typical workflow involves running ytfzf -t "your search query", which presents a fzf interface of results. You can then fuzzy-find, select a video (often by pressing Enter), and ytfzf will launch mpv to play it.

ytfzf emerged from the desire for a more interactive and terminal-centric way to browse and play YouTube videos, leveraging the power of fzf for a superior user experience compared to directly piping youtube-dl output. It's an open-source project, primarily developed on GitHub, and benefits from community contributions, continually adding new features and improving compatibility with YouTube's evolving platform and youtube-dl/yt-dlp updates. Its development reflects the Linux community's preference for lightweight, modular tools that can be composed to achieve complex workflows.

fzf(1), mpv(1), youtube-dl(1), yt-dlp(1)