--- name: "ytfzf" section: "1" platform: "linux" package: "ytfzf" version: "2.6.2-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/ytfzf" --- # ytfzf(1) search and play videos ## NAME ytfzf - search and play videos ## SYNOPSIS **ytfzf** \[*options*\] \[*search-query*\] **ytfzf** \[*options*\] - ## DESCRIPTION **ytfzf** is a POSIX script that helps you find videos from Youtube, Peertube or Odysee (without API) and opens/downloads them using mpv/youtube-dl. ## SEARCH OPERATORS Search operators are special search queries. Standard search operators include: - *:help* Prints a possibly brief description of how to use the scraper. Addon scrapers may have more or less search operators ## SHORTCUTS These shortcuts will apply in any menu that supports it.\ The only menu that currently supports it is fzf.\ Shortcuts starting with alt, will exit the menu, shortcuts starting with ctrl will not.\ To change any of the defaults set the corresponding variable in your configuration file. - **download** alt-d (download\_shortcut) - **watch video** alt-v (video\_shortcut) - **audio only** alt-m (audio\_shortcut) - **detatch** alt-e (detach\_shortcut) - **print link** alt-l (print\_link\_shortcut) - **show formats** alt-f (show\_formats\_shortcut) - **show all info** alt-i (info\_shortcut) - **new search** alt-s (search\_again\_shortcut) - **scrape next page** ctrl-p (next\_page\_action\_shortcut) ## OPTIONS Information - **-h**, **--help** Show help text. - **--version** Show ytfzf's version. How to play the selected videos. - **-d**, **--download** Download the selected videos. This can also be set in the config file with **is\_download**. - **-m**, **--audio-only** Play audio only. This can also be set in the config file with **is\_audio\_only**. - **-f**, **--formats** Show available formats before proceeding. - **--format-selection=*screen*** The format selection screen type to use. Types: - *normal* - *simple* This can also be set in the config file with **format\_selection\_screen**. - **--format-sort=*sort*** The --format-sort to use in ytdl. This can also be set in the config file with **format\_selection\_sort**. - **--video-pref=pref** Set the ytdl video format to pref. This can also be set in the config file with **video\_pref**. - **--audio-pref=pref** Set the ytdl audio format to pref. This can also be set in the config file with **audio\_pref**. - **--ytdl-pref=pref** Set the ytdl format to pref. This can also be set in the config file with **ytdl\_pref**. - **--detach** Detach the video player from the terminal. This can also be set in the config file with **is\_detach**. - **-u**, **--url-handler=handler** The function/program to use as a url handler. This can also be set in the config file by adding **load\_url\_handler** \**.** - **-I** *option* Instead of playing the selected videos, get information about them in the selected format. The available options are: - *L*\|*l*\|*link* Prints the URL of the selected videos. - *VJ*\|*vj*\|*video-json* Prints the json of the selected videos. - *J*\|*j*\|*json* Prints the json of all the videos in the search results. - *F*\|*f*\|*format* Prints the video format being used. - *R*\|*r*\|*raw* Prints the data of the selected videos, as appears in the menu. - **-L** Alias for -I L - **--info-action=Iaction** The action to do when --info-wait is 1. **info\_wait\_action**. - **--info-wait=*number*** Whether or not to wait after printing info requested with -I or -L. This can also be set in the config file with **info\_wait**. - **--url-handler-opts=opts** Opts to pass to the url handler, by default this will pass extra opts to mpv. This can also be set in the config file with **url\_handler\_opts**. Menu options - **-l**, **--loop** Reopen the menu when the video stops playing. This can also be set in the config file with **is\_loop**. - **-s**, **--search-again** After closing fzf make another search. This can also be set in the config file with **search\_again**. - **-t**, **--show-thumbnails** Show thumbnails. Doesn't work with **-D** or **-H**. This can also be set in the config file with **show\_thumbnails**. - **--async-thumbnails** Whether or not to download thumbnails asynchronously.\ Downloading asynchronously will open the menu before all thumbnails are downloaded. This can also be set in the config file with **async\_thumbnails**. - **--skip-thumb-download** Whether or not to skip the thumbnail download. This is used if you want to not have thumbnails, or use custom thumbnails in $YTFZF\_CUSTOM\_THUMBNAILS\_DIR.\ For more info see CUSTOM THUMBNAILS in [ytfzf(5)](/ytfzf/5.md)\ This can also be set in the config file with **skip\_thumb\_download**. - **--notify-playing** Show notifications when a video is about to be played, and other notifications relating to playing videos. This can also be set in the config file with **notify\_playing**. - **--preview-side=side** The preview side in fzf.\ Options: - *left* - *right* - *up* - *down* This can also be changed in the config file with **fzf\_preview\_side**. - **-T**, **--thumb-viewer=program** Use program for displaying thumbnails.\ Built-in programs: - *chafa,*chafa-16,*chafa-tty* chafa, chafa with 16 colors, chafa with 4 colors. - *catimg,*catimg-256 catimg, catimg with 256 colors. - *imv* Good with tiling window managers. - *mpv* Similar to imv. - *swayimg* Only works on the sway wayland compositor. - *swayimg-hyprland* Only works on the hyprland compositor. Uses swayimg to render an image. - *\* Additional viewers can be put into $YTFZF\_THUMBNAIL\_VIEWERS\_DIR. This can also be changed in the config file by adding\ **load\_thumbnail\_viewer** \**.** - **-D**, **--external-menu** Use an external menu instead of fzf. The default is *dmenu*. This can also be set in the config file with **interface="ext"**. - **-i**, **--interface=interface** Use a custom interface script, which would be in $YTFZF\_CUSTOM\_INTERFACES\_DIR. This can also be set in the config file by adding **load\_interface** \**.** - **--sort** Sorts videos (after scraping) by upload date. This can also be set in the config file by adding **is\_sort**. - **--sort-name=name** Calls a function set in $YTFZF\_CONFIG\_FILE. Or sources a script in $YTFZF\_SORT\_NAMES\_DIR (if it exists). See SORT NAMES in [ytfzf(5)](/ytfzf/5.md) for more information. - **--fancy-subs** Whether or not to have a separator between each subscription. When this option is used it automatically disables --sort as it will mess up this option.\ This can also be set in the config file with **fancy\_subs**. - **--disable-back** Whether or not to disable the back button in submenus.\ This can also be set in the config file with **enable\_back\_button**. **--disable-actions** Whether or not to disable actions such as submenus and the back button.\ This can also be set in the config file with **enable\_actions**. - **--disable-submenus** Whether or not to disable submenus.\ Submenus are the menus that happen after a playlist or channel (currently only supported by youtube/invidious) is selected\ This can also be set in the config file with **enable\_submenus**. - **--keep-vars** Whether or not options passed into ytfzf also get passed into submenus. This can also be set in the config file with **keep\_vars**. - **--submenu-opts=opts** The opts to use in the submenu.\ This can also be set in the config file with **submenu\_opts**. - **--submenu-scraping-opts=opts** **DEPRECATED (use --submenu-opts instead)** Does the same thing as --submenu-opts.\ This can also be set in the config file with **submenu\_scraping\_opts**. Auto selecting - **-a**, **--auto-select** Auto-play the first result. - **-A**, **--select-all** Select all results. - **-r**, **--random-select** Auto-play a random result. - **-S** *sed address***,** --select=*sed address* Auto-play a specific video. Examples: - *2* Select the second video - *$* Select the last video - */^h/* Select all videos starting with h - **-n** *number***,** --link-count=*number* The *number* of videos to select with **-a** or **-r**. Scrapers - **-c** *scrapers***,** *--scrape=scrapers* Set which scraper to use. Multiple scrapers can be separated by comma (,). The currently supported builtin scrapers are: - *youtube*\|*Y* Scrapes invidious' api with a search query - *youtube-channel* Scrapes a youtube channel with youtube - *invidious-channel* Scrapes a youtube channel with $invidious\_instance\ When this scrape is active the search query is the link to a channel. - *video-recommended*\|*R* Scrapes recommended videos from an invidious video link - *youtube-playlist*\|*invidious-playlist* Scrapes a youtube playlist\ When this scrape is active the search query is the link to a playlist. - *youtube-trending*\|*T* Scrapes invidious' api to get youtube trending.\ When this scrape is active the search query is the tab of trending to scrape. - *from-cache* Scrapes a previous scrape that happened using --keep-cache from the saved cache. - *M*\|*multi* Uses ytfzf recursively to scrape multiple things with multiple different options\ See *ytfzf -c M :help* for more info\ Tabs: - *gaming* - *music* - *movies* - *youtube-subscriptions*\|*S*\|*SI* *SI* Scrapes invidious for channels instead of youtube. Scraping youtube may result in rate limiting. - *scrape-list*\|*SL* uses your $YTFZF\_SCRAPELIST\_FILE as scrape and search input. See "scrape lists" [ytfzf(5)](/ytfzf/5.md) for more information. - *peertube*\|*P* - *odysee*\|*lbry*\|*O* - *history*\|*H* (Only if $enable\_hist is enabled) - *url*\|*U* Opens the url in the video player and exits - *u* Treats the url as an item, and will open fzf, or the external menu. - *comments* Scrapes the comments of a video link from youtube - **-H**, **--history** Alias for -c H.\ Scrapes history file. - **--scrape+=scrapers** Same as -c, but keeps the default scrape as well. - **--scraper-=scrapers** Removes scraper from list of scrapers to use - **--multi-search** Whether or not to use multi search.\ To use multi search, separate each search with a comma, this works well when using multiple scrapers.\ This can also be set in the config file with **multi\_search**. - **--force-youtube** When using the *youtube* scraper, convert the invidious links to youtube links before playing/downloading. - **--force-invidious** When using the *youtube* scraper, use whatever invidious instance was chosen instead of converting to youtube links. Scraper Options Currently, --video-duration, --type, --thumbnail-quality, and --features only applies to the scrape: youtube/Y - **--pages=amount** Amount of pages to scrape on youtube/invidious, and the comments scraper. This can also be set in the config file with **pages\_to\_scrape**. - **--pages-start=page** The page to start on. This can also be set in the config file with **pages\_start**. - **--max-threads=amount** Amount of threads that can be used to scrape youtube search, playlists, and channels. (this does not apply to the subscription scraper).\ This can also be set in the config file with **max\_thread\_count**. - **--single-threaded** Set the max\_thread\_count to 1, this has the same effect as making everything single threaded. (this does not apply to the subscription scraper).\ This can also bet set in the config file with **max\_thread\_count=1**. - **--odysee-video-count=amount** Amount of videos to scrape on odysee. This can also be set in the config file with **odysee\_video\_search\_count**. - **--nsfw** Whether or not to search for nsfw videos.\ Only works with odysee/O This can also be set in the config file with **nsfw**. - **--sort-by=sort** Works with youtube/Y and odysee/O.\ To use a different sort for each scrape, use comma (,) to separate the sorts.\ As apposed to --sort, this happens during the search, not after. Results should sort by: - *relevance* - *rating* (youtube only) - *upload\_date* - *oldest\_first* (odysee only) - *view\_count* (youtube only) - **--upload-date=time-frame** Works with youtube/Y and odysee/O\ To use a different sort for each scrape, use comma (,) to separate the dates.\ Search for videos within the last: - *hour* - *today* - *week* - *month* - *year* - **--video-duration=duration** Whether or not to search for long or short videos. Possible options: - *short* - *long* - **--type=type** The type of results to get. - *video* - *playlist* - *channel* - *all* - **--thumbnail-quality=***quality* Select the quality of the thumbnails. Available options: - *maxres* - *maxresdefault* - *sddefault* - *high* (default) - *medium* - *default* - *start* The first frame of the video (low quality) - *middle* The middle frame of the video (low quality) - *end* The end frame of the video (low quality) - **--features=features** The features to have on a video (comma separated). - *hd* - *subtitles* - *creative\_commons* - *3d* - *live* - *4k* - *360* - *location* - *hdr* - **--region** The region (country code) to search.\ Supported by the scrapes youtube/Y and youtube-trending/T Miscellaneous - **--ii=instance***,***--invidious-instance=instance** Use a different invidious instance. - **--rii***,***--refresh-inv-instance** If this flag is provided, refresh instance cache with healthy instances using Invidious API - **--available-inv-instances** Prints the invidious instances that may be used and exits. - **--channel-link=link** Converts channel links from 'https://youtube.com/c/name' to 'https://youtube.com/channel/id' - **-q** Use search history instead of a search. This can also be set in the config file with **search\_source=hist**. - **--search-source** The source to use for the search query. Valid values include: - args Use commandline arguments as the search (default) - prompt Ask for a search via a prompt - hist Use search history. - next Used internally to use the next search in the list when **multi\_search** is enabled. - fn-args Used internally to use the function arguments passed to the function as the source. - \ A custom search source may be used if a function called get\_search\_from\_\ exists. The function must set the \_search variable to a search. - **-x**, **--history-clear=\** Clear search and watch history (if -x or --history-clear is used)\ To specify either search or watch history use --history-clear=\ - **--keep-cache** Whether or not to keep cache after *ytfzf* exists. This can also be set in the config file with **keep\_cache**. - **--ytdl-opts=***option* Pass command-line options to youtube-dl when downloading. ``` example: --ytdl-opts= ``` - **--ytdl-path=***path* Specify the path to youtube-dl or a fork of youtube-dl for downloading.\ This can also be set in the config file with **ytdl\_path**. - **-e***,* **--ext=extension** Load an extension.\ You may also add *load\_extension extension* to your config file. - **--list-addons** Lists all addons and exits. - **--thumbnail-log** Sets the file to log thumbnail debug info to. This can also be set in the config file with **thumbnail\_debug\_log**. ## CONFIGURATION The default behaviour of **ytfzf** can be changed by modifying the config file. See [**ytfzf**(5)](/ytfzf/5.md) for more information. ## ADDONS There are a few types of addons,\ **interfaces (-i, --interface)**\ **scrapers (-c, --scrape)**\ **sort-names (--sort-name)**\ **thumbnail-viewers (-T, --thumb-viewer)**\ **url-handlers (-u, --url\_handler)**\ **extensions (-e, --ext)** To install an addon, place the addon in *$YTFZF\_SYSTEM\_ADDON\_DIR/\/addon-name* To use an addon, use one of the options listed above, or add\ **load\_interface \**\ **scrape=\**\ **load\_sort\_name \**\ **load\_thumbnail\_viewer \**\ **load\_url\_handler \**\ **load\_extension \**\ In your configuration file ## EXIT CODES - **0** Success - **1** General error - **2** Invalid --option, option value, or configuration error. - **3** Missing dependency - **5** Empty search ## ENVIRONMENT - **$YTFZF\_CONFIG\_DIR** The directory to store config files. The default is *$XDG\_CONFIG\_HOME/ytfzf (or ~/.config/ytfzf)* - **$YTFZF\_CONFIG\_FILE** The configuration file to use. The default is *$YTFZF\_CONFIG\_DIR/conf.sh* - **$YTFZF\_SUBSCRIPTIONS\_FILE** The subscriptions file to use. The default is *$YTFZF\_CONFIG\_DIR/subscriptions* - **$YTFZF\_SCRAPELIST\_FILE** The scrapelist file to use. The default is *$YTFZF\_CONFIG\_DIR/scrapelist* - **$YTFZF\_THUMBNAIL\_VIEWERS\_DIR** The directory to keep additional thumbnail viewers. The default is *$YTFZF\_CONFIG\_DIR/thumbnail-viewers* - **$YTFZF\_CUSTOM\_SCRAPERS\_DIR** The directory to store custom scraper scripts in The default is *$YTFZF\_CONFIG\_DIR/scrapers* - **$YTFZF\_CUSTOM\_INTERFACES\_DIR** The directory to store custom interface scripts in the default is *$YTFZF\_CONFIG\_DIR/interfaces* - **$YTFZF\_SORT\_NAMES\_DIR** The directory to store custom sort-name scripts in the default is *$YTFZF\_CONFIG\_DIR/sort-names* - **$YTFZF\_URL\_HANDLERS\_DIR** The directory to store custom url handlers in the default is *$YTFZF\_CONFIG\_DIR/url-handlers* - **$YTFZF\_CUSTOM\_THUMBNAILS\_DIR** The directory to store custom thumbnails the default is *$YTFZF\_CONFIG\_DIR/thumbnails* - **$YTFZF\_EXTENSIONS\_DIR** The directory to store extensions the default is *$YTFZF\_CONFIG\_DIR/extensions* - **$YTFZF\_SYSTEM\_ADDON\_DIR** The directory to store system installed addons. The default may vary depending on how you installed ytfzf. - **$YTFZF\_CHECK\_VARS\_EXISTS** Whether or not to check if variables are set in the environment before setting default values. The default is *1* - **$YTFZF\_TEMP\_DIR** The temporary directory The default is is *$TMPDIR/ytfzf-$user-id.*\ If $TMPDIR is not defined it will use /tmp ## FILES - *~/.config/ytfzf/conf.sh* The configuration file. If submenu-conf.sh does not exist, this will also be used as the config in submenus - *~/.config/ytfzf/submenu-conf.sh* The submenu configuration file - *~/.config/ytfzf/subscriptions* The subscriptions file. ## CACHE Each instance of ytfzf has its own directory in $YTFZF\_TEMP\_DIR, if $keep\_cache is enabled, it uses $cache\_dir instead.\ The structure of each instance folder looks like this: (\<\> represents a placeholder, ? means optional)\ If an addon scraper is used, it may use undocumented files. ``` $cache_dir | -- watch_hist | -- - | | -- created-at | | -- searches.list | | -- post-scrape | | -- -? | | -- thumbnails? | | -- environment | | -- tmp | | | -- curl_config | | | -- .html | | | -- .json | | | -- .json.final? | | | -- menu_keypress | | | -- all-ids.list | | | -- downloaded-ids.list | | -- ids | | -- videos_json ``` An explanation of each directory/file: - *created-at* Contains the unix timestamp when the folder was created - *searches.list* A list of all searches\ If --multi-search is enabled, each search is separated by a new line - *watch\_hist* The watch history file. - *\-\* An instance's parent folder.\ If no search was given it uses the name "SCRAPE-\-\" instead. - *post-scrape* A folder that contains files relating to the scraping of a selected result. - *\-\* Created when a submenu is opened (eg: when a channel/playlist is selected). - *thumbnails* Stores the thumbnails for the instance (only with -t). - *environment* Every variable that is set and it's value, in that instance of ytfzf - *tmp* Stores less important temporarily used files. - *curl\_config* The configuration file for curl for downloading thumbnails (only with -t). - *\.html* For scrapers that need to scrape websites, this is the output of curl. - *\.json* The json scraped from a website. - *\.json.final* The final json scraped from a website. (Is used when multiple threads are used for scraping) - *menu\_keypress* The key pressed in fzf. - *all-ids.json* File that contains all scraped ids. Mainly to compare against downloaded-ids.json - *downloaded-ids.json* File that contains which thumbnails have been downloaded - *ids* The file that stores the id of each selected video. - *videos\_json* The file that stores a json of all videos displayed in fzf.\ This file is very helpful for making playlists as it is in the same format. ## AUTHOR Originally written by pystardust. *\<*https://github.com/pystardust*\>* ## BUGS Report bugs on github *\<*https://github.com/pystardust/ytfzf/issues*\>* ## SEE ALSO [**ytfzf**(5)](/ytfzf/5.md) [**youtube-dl**(1)](/youtube-dl/1.md), [**mpv**(1)](/mpv/1.md) [**fzf**(1)](/fzf/1.md) [**dmenu**(1)](/dmenu/1.md) ## COPYRIGHT **ytfzf** is free software: you can redistribute it and/or modify it under the terms of the *GNU General Public License version 3* as published by the Free Software Foundation. **ytfzf** is distributed in the hope that it will be useful but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with **ytfzf**. If not, see *\<*https://www.gnu.org/licenses/*\>.*