YTFZF(1)

📦
version 2.6.2 · 2 versions
  • 2.6.2 · alpine 3.24, arch rolling, debian trixie, nixos 26.05, nixpkgs unstable, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
  • 2.5.4 · debian bookworm
, in alpine 3.24, arch rolling, debian trixie, nixos 26.05, nixpkgs unstable, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 YTFZF(1) — the ytfzf manual, bestie edition 💖

General Commands Manual ✨ welcome to the ytfzf page, we're so glad you're here 🫶

🌸 NAME 🌸

ytfzf — search and play videos. that's it. that's the whole vibe. 💅

✨ SYNOPSIS ✨

ytfzf [options] [search-query]
ytfzf [options] -

like. you give it options, you give it a search query, and it does the thing. iconic behaviour fr fr 🔥

🦋 DESCRIPTION 🦋

ytfzf is a POSIX script that helps you find videos from Youtube, Peertube or Odysee (no API needed, we're just built different 😌) and then opens/downloads them using mpv/youtube-dl.

no cap. that's the whole point of her. she's a little script with main character energy. 👑

🔍 SEARCH OPERATORS 🔍

so search operators are these special little search queries, okay? like magic words you type instead of a normal search. ✨

Standard search operators include:

  • :help — prints a possibly brief description of how to use the scraper. (possibly brief. she's not gonna write you an essay, bestie 😭)

Addon scrapers may have more or less search operators. so it's giving "your mileage may vary" energy 🧚

🎀 SHORTCUTS 🎀

okay so these shortcuts will apply in any menu that supports it. and the only menu that currently supports it is fzf. (she's the chosen one, iykyk 💅)

the way the rules work: shortcuts starting with alt will exit the menu, and shortcuts starting with ctrl will not exit the menu. crucial distinction, don't skip it. ⭐

to change any of the defaults, set the corresponding variable in your configuration file. (yes, the variable names are right there in the parentheses, go wild 🍓)

  • download — alt-d (download_shortcut)
  • watch video — alt-v (video_shortcut)
  • audio only — alt-m (audio_shortcut)
  • detatch — alt-e (detach_shortcut) (yes it's spelled "detatch" in the original and we respect her spelling choices 🫶)
  • 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. she'll tell you how to use her. 💖
  • --version — show ytfzf's version. the numbers. the lore. 🌈

🎬 How to play the selected videos.

okay this is the big section, hydrate before you read it. 🧚

  • -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. like a little menu of options, very demure ✨
  • --format-selection=screen — the format selection screen type to use. this can also be set in the config file with format_selection_screen.

Types:

  • normal
  • simple
  • --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. she's leaving the group chat to go do her own thing 🦋
  • -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 <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. short queen behaviour 👑
  • --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.
  • -l, --loop — reopen the menu when the video stops playing. this can also be set in the config file with is_loop. she's persistent. she's committed. 💫
  • -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.
⚠️ not me reminding you: this does NOT work with -D or -H. she said what she said. 💀
  • --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).

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.
  • <custom> — additional viewers can be put into $YTFZF_THUMBNAIL_VIEWERS_DIR.

this can also be changed in the config file by adding load_thumbnail_viewer <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 <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) 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.
⚠️ fr fr, using this turns off --sort for you. they do not coexist. periodt. 💅
  • --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.
💀 she's deprecated bestie, don't build your whole personality on her. use --submenu-opts.

🎯 Auto selecting

  • -a, --auto-select — auto-play the first result. no thinking required, she's got it 🫶
  • -A, --select-all — select all results. all of them. every single one. 👑
  • -r, --random-select — auto-play a random result. chaos mode activated 🎲
  • -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.

(part 1 of 3 — more coming, don't go anywhere bestie 🦋)

  • video-recommended, R — scrapes the recommended videos off an invidious video link ✨
  • youtube-playlist, invidious-playlist — scrapes a youtube playlist. When this scrape is the one active, your search query is the link to the playlist, periodt.
  • youtube-trending, T — scrapes invidious' api to grab youtube trending 🎀. When this scrape is active, your search query is the tab of trending you wanna scrape.
  • from-cache — scrapes a previous scrape that happened using --keep-cache, pulling it back out of the saved cache 🫶
  • M, multi — uses ytfzf recursively to scrape a bunch of things with a bunch of different options at once. See ytfzf -c M :help for more info, bestie. Tabs:
    • gaming
    • music
    • movies
  • youtube-subscriptions, S, SI — SI scrapes invidious for channels instead of youtube. Scraping youtube directly may result in rate limiting 😭 so like, be aware.
  • scrape-list, SL — uses your $YTFZF_SCRAPELIST_FILE as the scrape and search input. See "scrape lists" in ytfzf(5) for the full tea.
  • peertube, P
  • odysee, lbry, O
  • history, H — (only if $enable_hist is enabled)
  • url, U — opens the url in the video player and exits. bye 👋
  • 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 the history file.
  • --scrape+=scrapers — same as -c, but keeps the default scrape as well (so you're adding, not replacing, queen 💅).
  • --scraper-=scrapers — removes a scraper from the 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 so well when you're 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 🎀

Heads up bestie: currently, --video-duration, --type, --thumbnail-quality, and --features only apply to the scrape youtube/Y. iykyk.

  • --pages=amount — the amount of pages to scrape on youtube/invidious, and for 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 — the 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 — sets the max_thread_count to 1, which has the same effect as making everything single threaded. (this does not apply to the subscription scraper). This can also be set in the config file with max_thread_count=1.
  • --odysee-video-count=amount — the 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 a comma (,) to separate the sorts. As opposed 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 date for each scrape, use a 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 the instance cache with healthy instances using the 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.
    • <custom> — a custom search source may be used if a function called get_search_from_<source> exists. The function must set the _search variable to a search.
  • -x, --history-clear=<search|watch> — clear search and watch history (if -x or --history-clear is used). To specify either search or watch history, use --history-clear=<search|watch>.
  • --keep-cache — whether or not to keep the cache after ytfzf exits. 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) for more information.

🧚 ADDONS 🧚

There are a few types of addons, bestie:

  • 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-type>/addon-name

To use an addon, use one of the options listed above, or add this to your configuration file:

load_interface <interface>
scrape=<scraper>
load_sort_name <sort-name>
load_thumbnail_viewer <viewer>
load_url_handler <url-handler>
load_extension <ext>

⭐ EXIT CODES ⭐

  • 0 — Success 🎉
  • 1 — General error
  • 2 — Invalid --option, option value, or configuration error.
  • 3 — Missing dependency
  • 5 — Empty search

🌸 ENVIRONMENT 🌸

okay bestie so these are the environment variables that ytfzf reads, and every single one of them is lowkey a little dial you can turn. go off 💅

  • $YTFZF_CONFIG_DIR — the directory where config files live. the default is $XDG_CONFIG_HOME/ytfzf (or ~/.config/ytfzf if that's not a thing you set) 🎀
  • $YTFZF_CONFIG_FILE — the config file to use. default is $YTFZF_CONFIG_DIR/conf.sh ✨
  • $YTFZF_SUBSCRIPTIONS_FILE — the subscriptions file to use. default is $YTFZF_CONFIG_DIR/subscriptions 💖
  • $YTFZF_SCRAPELIST_FILE — the scrapelist file to use. default is $YTFZF_CONFIG_DIR/scrapelist 🦋
  • $YTFZF_THUMBNAIL_VIEWERS_DIR — the directory that keeps your additional thumbnail viewers. default is $YTFZF_CONFIG_DIR/thumbnail-viewers 🫶
  • $YTFZF_CUSTOM_SCRAPERS_DIR — the directory where custom scraper scripts go. the default is $YTFZF_CONFIG_DIR/scrapers 🔥
  • $YTFZF_CUSTOM_INTERFACES_DIR — the directory where custom interface scripts go. the default is $YTFZF_CONFIG_DIR/interfaces 🌈
  • $YTFZF_SORT_NAMES_DIR — the directory where custom sort-name scripts go. the default is $YTFZF_CONFIG_DIR/sort-names ⭐
  • $YTFZF_URL_HANDLERS_DIR — the directory where custom url handlers go. the default is $YTFZF_CONFIG_DIR/url-handlers 💜
  • $YTFZF_CUSTOM_THUMBNAILS_DIR — the directory where custom thumbnails go. the default is $YTFZF_CONFIG_DIR/thumbnails 🎀
  • $YTFZF_EXTENSIONS_DIR — the directory where extensions go. the default is $YTFZF_CONFIG_DIR/extensions 🧚
  • $YTFZF_SYSTEM_ADDON_DIR — the directory where system installed addons live. the default may vary depending on how you installed ytfzf, so like… it's giving mystery, it's giving depends ✨
  • $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 $TMPDIR/ytfzf-$user-id. if $TMPDIR is not defined it will use /tmp 💅

📁 FILES 📁

the little guys that live on your disk, bestie:

  • ~/.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 💾

okay so every single instance of ytfzf gets its own little directory inside $YTFZF_TEMP_DIR. but if $keep_cache is enabled, it uses $cache_dir instead. keeping receipts, periodt 🔥

the structure of each instance folder looks like this: (<> represents a placeholder, and ? means optional)

heads up bestie: if an addon scraper is used, it may use undocumented files. so like… there might be extra stuff in there, iykyk 🙈
$cache_dir
| -- watch_hist
| -- <search>-<pid>
|  | -- created-at
|  | -- searches.list
|  | -- post-scrape
|  | -- <submenu-search>-<submenu-pid>?
|  | -- thumbnails?
|  | -- environment
|  | -- tmp
|  |  | -- curl_config
|  |  | -- <scrape>.html
|  |  | -- <scrape>.json
|  |  | -- <scrape>.json.final?
|  |  | -- menu_keypress
|  |  | -- all-ids.list
|  |  | -- downloaded-ids.list
|  | -- ids
|  | -- videos_json

🫶 an explanation of each directory/file 🫶

so you're not out here squinting at filenames like 👁️👄👁️ — here's what each one actually is:

  • 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 👀
  • <search>-<pid> an instance's parent folder. if no search was given it uses the name "SCRAPE-<scrape>-<pid>" instead 🎀
  • post-scrape a folder that contains files relating to the scraping of a selected result 🦋
  • <submenu-search>-<submenu-pid> 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) 🔥
  • <scrape>.html for scrapers that need to scrape websites, this is the output of curl 🌸
  • <scrape>.json the json scraped from a website 💅
  • <scrape>.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 at <https://github.com/pystardust/ytfzf/issues> — go tell them, bestie, they wanna know 🙈

👀 SEE ALSO 👀

ytfzf(5) youtube-dl(1), mpv(1) fzf(1) dmenu(1) — the whole friend group, fr fr 🫶

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/>. ✨

and that's the whole page, bestie 💅 this was ytfzf 2.0, dated 2021 September, aka YTFZF(1) — go forth and scrape iconically 🌸✨🎀

📦 where this page comes from