ytfzf(1)

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 <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)
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.

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

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) 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.

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.

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

To use an addon, use one of the options listed above, or add
load_interface <interface>
scrape=<scraper>
load_sort_name <sort-name>
load_thumbnail_viewer <viewer>
load_url_handler <url-handler>
load_extension <ext>
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
| -- <search>-<pid>
|  | -- 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:

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 <https://github.com/pystardust/ytfzf/issues>

SEE ALSO

ytfzf(5) youtube-dl(1), mpv(1) fzf(1) dmenu(1)

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