Provided by: ytfzf_2.6.1-1_all 
NAME
ytfzf - the configuration file for ytfzf.
SYNOPSIS
~/.config/ytfzf/conf.sh
DESCRIPTION
The configuration file is a .sh file and can be used as such. The file can be completely
empty and ytfzf will still work with the default settings. The options should be set as
environment variables and functions.
CONFIGURATION FILES
Configuration files are stored in $XDG_CONFIG_HOME/ytfzf (or $HOME/.config/ytfzf).
conf.sh
A shell script that gets sourced into ytfzf when ytfzf is run.
subscriptions
A file that is a list of links to youtube channel's video page, such as:
https://www.youtube.com/channel/UCtMVHI3AJD4Qk4hcbZnI9ZQ
Each link should be separated by a new line.
If a channel appears similar to "https://www.youtube.com/c/SomeOrdinaryGamers", run
ytfzf --channel-link="https://www.youtube.com/c/SomeOrdinaryGamers"
Before adding it to your subscriptions file
A comment can be created by having '#comment' on its own line or after a link. For
example:
link-to-channel
#comment
link-to-channel #best channel
scrapers
A folder that contains executable files that scrape websites See CUSTOM SCRAPERS for more
information
CONFIGURATION OPTIONS
VARIABLES
conf.sh is used mainly for setting variables for ytfzf. If a variable has no default,
that means it is set to an empty string.
To set a variable in conf.sh be sure to use
variable_name="value"
leave out the $ at the start of the variable name.
Files and directories
$cache_dir
The directory to store cache files in.
It is highly recommended to only change this if $__is_submenu is 0, or funky
things could happen
default: $XDG_CACHE_HOME/ytfzf (or $HOME/.cache/ytfzf)
$hist_file
The file to write watch history to if $enable_hist is 1
It is highly recommended to only change this if $__is_submenu is 0, or funky
things could happen
default: $cache_dir/watch_hist
$search_hist_file
The file to write search history to if $enable_search_hist is 1
default: $cache_dir/search_hist
How to play the selected videos.
$is_detach
Whether or not to detach the video player from the terminal.
default: 0
$is_audio_only
Whether or not to only play audio.
default: 0
$url_handler
The function/programs to handle the selected videos
It is recommended to not set this variable directly, but rather to use the
command load_url_handler
See URL handlers for a list of built-in url handlers default:
multimedia_player
$yt_video_link_domain
The domain to play youtube videos from (does not apply to odysee and
peertube or youtube playlists)
If left blank, the value will be whatever invidious instance ytfzf chose
default: https://www.youtube.com
$info_to_print
The information to print instead of playing a video. The available options
for this variable are:
L | l | link
Print 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.
$info_wait_action
The action to do when $info_wait is 1.
Valid actions:
q quit (will go back to menu, if $is_loop is 1).
Q quit regardless if loop is enabled or not.
m return to menu.
default: q
$info_wait
Whether or not to wait for input after printing info.
default: 0
$video_pref
The video preference to use for youtube-dl in mpv.
default: bestvideo
$audio_pref
The audio preference to use for youtube-dl in mpv.
default: bestaudio
$ytdl_pref
The preference to use for youtube-dl in mpv.
default: $video_pref+$audio_pref/best/$video_pref/$audio_pref
$url_handler_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
$interface
The interface/menu to use.
It is recommended to not use this variable directly, instead use
load_interface interface-name
Valid options.
ext same as -D
scripting
is applied when -a, -r, or -A is used
'' default
$external_menu_len
The amount of cols in interface_ext, (-D)
default: 210
$fzf_preview_side
The side to show the preview in fzf.
Valid options:
left
right
up
down
default: left
$thumbnail_viewer
The program to display images for thumbnail previews
It is recommended to not use this variable directly, instead use
load_thumbnail_viewer viewer
Valid options:
sixel
iterm2
kitty
sway
wayland
ueberzug
chafa
chafa-16
Uses chafa with 16 colors
chafa-tty
Uses chafa with 4 colors
catimg
catimg-256
Uses catimg with 256 colors
mpv Uses the mpv player to display the images
Works well with tiling window managers.
imv Similar to mpv, but is a dedicated image viewer
swayimg
Only works on the sway wayland compositor
swayimg-hyprland
Only works on the hyprland compositor. Uses swayimg to render
images.
default: ueberzug
$show_formats
Whether or not to bring up the format selection menu.
default: 0
$format_selection_screen
The format that selection screen will use. Types:
simple normal
default: simple
$format_selection_sort
The --format-sort to use in ytdl.
default: height
$enable_submenus
Whether or not to enable submenus,
A submenu is a menu that appears after a playlist or channel is selected.
(Currently only supported with youtube/invidious scraper) default: 1
$enable_actions
Whether or not to enable actions such as submenus, and the back button.
default: 1
$keep_vars
Whether or not options passed into ytfzf also get passed into submenus
$enable_back_button
Whether or not to enable back button in submenus. default: 1
$submenu_opts
Options to use in submenus. default:
$submenu_scraping_opts
DEPRECATED (use submenu_opts instead) Does the same thing as $submenu_opts
default:
$is_sort
Whether or not to sort scraped videos by date in the menu default: 0
$fancy_subs
Whether or not to have a separator between each subscription default: 0
$fancy_subs_left
The text to display on the left of the channel name when fancy_subs is 1.
default: -------------
$fancy_subs_right
The text to display on the right of the channel name when fancy_subs is 1.
default: $fancy_subs_left
$show_thumbnails
Whether or not to show thumbnails in fzf.
default: 0
$async_thumbnails Whether or not to download thumbnails asynchronously.
Downloading asynchronously will open the menu before all thumbnails are
downloaded. default: 0
$skip_thumb_download
Whether or not to skip thumbnail download.
default: 0
$thumbnail_quality
Select the quality of the thumbnails. Currently only supports youtube (uses
invidious api).
This does not work for the '-cS' scraper as it scrapes youtube not invidious
(use 'SI' instead).
For lower internet speeds it is recommended to use default.
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)
$notify_playing
Whether or not to send a notification when a video is about to be played.
default: 0
$is_loop
Whether or not to show the menu after the selected videos have stopped
playing.
default: 0
$search_again
Whether or not to make another search after fzf is closed.
default: 0
$download_shortcut
The shortcut to download the selected videos.
default: alt-d
$video_shortcut
The shortcut to watch the selected videos.
default: alt-v
$audio_shortcut
The shortcut to listen to the selected videos.
default: alt-m
$detach_shortcut
The shortcut to use the detach player.
default: alt-e
$print_link_shortcut
The shortcut to use to print the link.
default: alt-l
$show_formats_shortcut
The shortcut to show formats before playing the video.
default: alt-f
$info_shortcut
The shortcut to get all info about the selected video.
default: alt-i
$search_again_shortcut
The shortcut to make another search.
default: alt-s
$shortcut_binds
The keys to listen for in fzf.
default: Enter,double-click,$download_shortcut,
$video_shortcut,$detach_shortcut,$print_link_shortcut,$show_formats_shortcut,
$info_shortcut,$search_again_shortcut,$custom_shortcut_binds"
next_page_action_shortcut
The shortcut to scrape the next page.
default: ctrl-p
$custom_shortcut_binds
The custom shortcut keys. Automatically appended to $shortcut_binds
If $shortcut_binds is set manually, this must also manually be appended.
Auto selecting
$is_auto_select
Whether or not to auto select the first -n videos. (only works if
$interface=scripting)
default: 0
$is_random_select
Whether or not to randomly select -n videos. (only works if
$interface=scripting)
default: 0
$is_specific_select
Whether or not to select a specific video (use $ scripting_video_count to
specify which) (only works if $interface=scripting)
default: 0
$scripting_video_count
The amount of videos to get with -a or -r.
default: 1
Scrapers
$scrape
The website to scrape by default. The currently supported options are:
youtube,
youtube-trending,
youtube-subscriptions,
peertube,
odysee/lbry.
youtube-playlist,
youtube-channel,
invidious-channel,
video-recommended,
playlist/json-file,
The search will be a path to a json file laid out as described in VIDEO JSON
FORMAT
history,
url/U,
u,
M/multi,
comments
default: youtube
$multi_search
Whether or not to enable multi search. default: 0
$search_sort_by
The attribute to sort by when searching.
relevance (default)
rating (youtube only)
upload_date
oldest_first (odysee only)
view_count (youtube only)
$search_upload_date
Search for videos within the last:
hour
today
week
month
year
$search_video_duration
Whether or not to search for long or short videos. Possible options:
short
long
$search_result_type
The type of results to get.
video (default)
playlist
channel
all (may not work on some instances)
$nsfw Whether or not to search for nsfw videos in odysee/O.
default: false
$search_result_features
The features to have on a video (comma separated).
hd
subtitles
creative_commons
3d
live
4k
360
location
hdr
$search_region
The region (country code) to search. default: US
$invidious_instance
The instance of invidious to use.
default: https://vid.puffyan.us
$pages_to_scrape
The amount of pages to scrape on youtube/invidious.
default: 1
$pages_start
The starting page to scrape.
default: 1
$max_thread_count
The amount of threads that can be used while scraping youtube search,
playlists, and channels. (this does not apply to the subscription scraper)
default: 20
$odysee_video_search_count
The amount of videos to scrape on odysee.
default: 30
$sub_link_count
The amount of videos to scrape per channel when getting subscriptions.
default: 2
Misc
$scrape_search_exclude
The scrapers to not ask for a search query.
Be sure to have a space at the end and beginning of the string.
default: youtube-subscriptions S SI T youtube-trending H history
$custom_scrape_search_exclude
Extra scrapers to not ask for a search query.
This will automatically be appended to $ scrape_search_exclude.
In addition, you do not need spaces at the start, and end, only between
scrapers. default:
$gap_space
A number of spaces equal to half the width of your terminal
default: 115 spaces
$enable_hist
Whether or not to keep track of history
default: 1
$enable_search_hist
Whether or not to keep track of search history
default: 1
$search_source
How to get the search query. The builtin values for this are:
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.
$log_level
How much debug information to log.
2 Log everything
1 Log only warnings and errors
0 Log only errors
default: 2
$thumbnail_debug_log
The log file for thumbnail debug information. default:/dev/null
$useragent
The useragent to use when scraping websites.
default: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like
Gecko) Chrome/88.0.4324.152 Safari/537.36"
$ytdl_opts
The command-line options to pass to youtube-dl when downloading.
$ytdl_path
Path to youtube-dl or a fork of youtube-dl for downloading.
If yt-dlp is installed that will be preferred over youtube-dl
default: youtube-dl
Option Parsing
$long_opt_char
The char to use for long opts.
default: -
$optstring
The string of options to use for the getopts function.
It is highly unrecommended to change this variable, unless you know what you
are doing.
default: ac:de:fhi:lmn:qrstu:xADHI:LS:T:W:$long_opt_char:
$YTFZF_CHECK_VARS_EXISTS
Whether or not to check if variables in the environment already exist when
setting default options.
This option can not be set in the config, it must be set in your startup
shell with export, or before running ytfzf such as:
YTFZF_CHECK_VARS_EXISTS=0 ytfzf ...
default:1
State
State values are NOT meant to be modified by the user.
$__is_submenu
Whether or not the script is in a submenu.
$__is_fzf_preview
Whether or not the script is running to display an fzf preview
__scrape_count
The current scrape count starting at 1.
FUNCTIONS
Sometimes a variable is not good enough, instead functions should be defined. To find the
default value of these, check the source code by searching for function_exists
"<function_you_are_looking_for>".
Menu related functions
external_menu()
When $interface is ext_menu, call this function instead of fzf.
This function takes 1 argument, a prompt string.
get_sort_by()
This function is called to get the value to sort by when $is_sort is 1.
This function takes in a line in the form of "title |channel |duration
|views |date |id".
data_sort_fn()
This function sorts the data that is being piped into it.
This function takes no arguments, all data is piped into it.
custom_info_wait_action_<text>()
This function is called if an unknown $info_wait_action is given or read.
<text> should be replaced with the text wanted from $info_wait_action, eg:
custom_info_wait_e.
This function takes no arguments.
video_info_text()
This function prints the text for the selection menu.
Must end with a new line,
The url must be the last thing printed.
This function takes no arguments, the relevant variables are listed here:
title
channel
duration
views
date
url
It is recommended to check the script to see how each thing is printed.
thumbnail_video_info_text()
This function prints text in the preview area of fzf when thumbnails are
enabled.
Everything can be printed however you like.
This function takes no arguments, the relevant variables are listed here:
title
channel
duration
views
date
url
thumbnail_video_info_text_<scraper>()
This function is the same as thumbnail_video_info_text() for the scraper
specified.
on_no_thumbnail()
This function is run when no thumbnail is found
get_ueberzug_positioning_left()
This function sets the variables, $width, $height, $x, and $y. $x, and $y,
should represent cols and lines not pixels.
These variables will be used to position and size the image in the fzf
preview when $fzf_preview_side is left.
This function takes 2 arguments:
max_width
max_height
get_ueberzug_positioning_right()
This function sets the variables, $width, $height, $x, and $y.
$x, and $y, should represent cols and lines not pixels.
These variables will be used to position and size the image in the fzf preview when $fzf_preview_side is right.
This function takes 2 arguments:
max_width
max_height
get_ueberzug_positioning_up()
This function sets the variables, $width, $height, $x, and $y.
$x, and $y, should represent cols and lines not pixels.
These variables will be used to position and size the image in the fzf preview when $fzf_preview_side is up.
This function takes 2 arguments:
max_width
max_height
get_ueberzug_positioning_down()
This function sets the variables, $width, $height, $x, and $y.
$x, and $y, should represent cols and lines not pixels.
These variables will be used to position and size the image in the fzf preview when $fzf_preview_side is down.
This function takes 2 arguments:
max_width
max_height
get_swayimg_positioning_left()
This function sets the variables, $x, $y, $img_w, and $img_h.
$x, and $y, should represent pixels.
These variables will be used to position and size the image in the fzf preview when $fzf_preview_side is left.
This function takes 8 arguments:
img_w
img_h
max_width
max_height
max_height
term_x
term_y
col_px_width
line_px_height
get_swayimg_positioning_right()
This function sets the variables, $x, $y, $img_w, and $img_h.
$x, and $y, should represent pixels.
These variables will be used to position and size the image in the fzf preview when $fzf_preview_side is right.
This function takes 8 arguments:
img_w
img_h
max_width
max_height
max_height
term_x
term_y
col_px_width
line_px_height
get_swayimg_positioning_up()
This function sets the variables, $x, $y, $img_w, and $img_h.
$x, and $y, should represent pixels.
These variables will be used to position and size the image in the fzf preview when $fzf_preview_side is up.
This function takes 8 arguments:
img_w
img_h
max_width
max_height
max_height
term_x
term_y
col_px_width
line_px_height
get_swayimg_positioning_down()
This function sets the variables, $x, $y, $img_w, and $img_h.
$x, and $y, should represent pixels.
These variables will be used to position and size the image in the fzf preview when $fzf_preview_side is down.
This function takes 8 arguments:
img_w
img_h
max_width
max_height
max_height
term_x
term_y
col_px_width
line_px_height
search_prompt_menu()
This function asks the user to make a search query, and sets the variable $_search to the query.
This function is called if ytfzf is started without a search. (and is using the default interface)
This function takes no arguments.
search_prompt_ext()
This function asks the user to make a search query, and sets the variable $_search to the query.
This function is called if ytfzf is started without a search. (and is using the -D flag)
This function takes no arguments.
quick_menu()
This function should take user input and echo it back
This function is called with -f, and -q. Or any other time a generic menu is needed. (and the default interface is being used)
This function takes 1 argument, and takes input from stdin
1: The prompt to use.
stdin: the items to choose from (separated by new lines)
quick_menu_ext()
This function should do the same thing as quick_menu()
This function is called when quick_menu() would be called, but when -D is enabled.
This function takes 1 argument, and takes input from stdin
1: The prompt to use.
stdin: the items to choose from (separated by new lines)
info_wait_prompt()
The prompt to use when info_wait is enabled.
This function takes no arguments.
info_wait_prompt_ext()
Same as info_wait_prompt() when -D is used.
This function takes no arguments.
info_wait_prompt_wrapper()
Call info_wait_prompt_<interface_name>
This function takes no arguments.
display_text()
Print text to standard out.
This function takes an unlimited number of arguments to print.
display_text_ext()
Print text to standard out.
This function takes an unlimited number of arguments to print.
display_text_wrapper()
Call display_text_<interface_name>
This function takes an unlimited number of arguments to print.
URL handlers
A URL handler is a function that handles the urls given,
URL handlers should take into account these modifier values,
$video_pref ,
$is_audio_only ,
and
$is_detach
Modifier variables will be piped into a URL handler to allow for URL handlers to be written in any language.
They will be piped in the order shown above separated by spaces.
multimedia_player()
The handler that is called by default.
This function opens either video_player() or audio_player() depending on whether or not
$is_audio_only (-m) is enabled.
This function takes in an unlimited amount of arguments, each of which is a link to a video.
video_player()
Plays the urls with a video player
This function takes in an unlimited amount of arguments, each of which is a link to a video.
audio_player()
Plays the urls with an audio player
This function takes in an unlimited amount of arguments, each of which is a link to a video.
downloader()
Downloads the urls
This function takes in an unlimited amount of arguments, each of which is a link to a video.
get_video_format_<name>()
A custom format selection screen
<name> should be the the wanted value of $format_selection_screen
This function should set ytdl_pref
This function takes all urls as separate arguments.
on_open_url_handler_<ext>()
This function is run when open_url_handler is called, but before the url handler is actually opened.
This function takes an unlimited number of arguments, each argument is a url that was opened.
close_url_handler_<name>
<name> should be the name of the url handler with - replaced with _.
A function that happens after the url handler has finished playing.
The point of this function is to clean up anything that the url handler did.
after_close_url_handler_<ext>
A function that happens after the url handler has finished playing, and after
close_url_handler_<name>
has happened.
If
is_detach
is
1
this function may be called immediately after
url_handler
opens.
Search History
handle_search_history()
This function handles appending the search to the given search file.
This function takes 2 arguments:
1 The search to write
2 The file to append to.
parse_search_hist_file()
This function should parse the search history file, and print out each search separated by new lines.
The search history file will be fed through stdin.
get_search_from_<src>()
If search_source is set to <src> this function will be called.
This function is expected to set the variable _search to a search query.
This function takes no arguments.
on_search()
This function gets called each time a website is scraped.
This function takes 2 arguments:
1
The search query
2
The current scrape
on_search_<search_query>()
This function gets called each time a website is scraped if the current
search matches <search_query>.
This function takes 1 argument.
1 The current scrape
Misc
get_requested_info_<name>()
If <name> is in info_to_print this function will be run.
This function takes no arguments.
handle_playing_notifications()
This function sends a notification for the videos that are about to be
played.
This function takes an unknown amount of urls as arguments.
post_scrape()
This function happens after all scraping is complete
post_scrape_<extension-name>()
Same as post_scrape() but for each extension
on_opt_parse()
This function gets called after an option is parsed, and sets variables
based the options passed into it. A non 0 exit code will override the
default behavior of a specific option.
This function takes 4 arguments:
1
The current option being parsed
2
The current option argument being parsed
3
The unmodified option being parsed.
For an option such as -a, this value will be the same as $1.
However, for every --long-option this value will be "-".
4
The unmodified option argument being parsed.
For an option such as -c S, this value will be the same as $2.
However, for every --long-option=value, this value will be -long-option=value.
on_opt_parse_<opt_name>()
This function gets called before an option is parsed. A non 0 exit code
will override the default behavior of a specific option.
This function takes 3 arguments:
1 The the optarg
2 The raw opt
3 The raw optarg
on_post_set_vars()
This function gets called after all vars are set, and all opts are parsed.
This function takes no arguments.
on_clean_up()
This function is called when the script is cleaning up files from the
search, or when the script exits.
This function takes no arguments.
usage()
This function calls the print_help_<ext> for each loaded extension.
This function takes no arguments.
handle_custom_keypresses()
This function gets called in the internal handle_keypress() function. This
function should return 0 to not override the default handle_keypress()
function.
This function takes 1 argument:
1
The key pressed.
handle_custom_post_keypresses()
This function gets called in the internal handle_post_keypress() function,
this function should return 0 to not override the default
handle_post_keypress() function.
The job of this function is to undo the changes of the last keypress.
This function takes no arguments, it must get the keypress from
$keypress_file
handle_keypress_*()
The name of this function should replace the "*" with the name of the
shortcut, eg: alt_d
in addition replace any "-" with "_".
This function is called after handle_custom_keypresses() if it returned 0,
and the shortcut is not a built-in shortcut.
This function takes 0 arguments.
handle_post_keypress_*()
The name of this function should replace the "*" with the name of the
shortcut, eg: alt_d
in addition replace any "-" with "_".
This function is called after handle_custom_post_keypresses() if it returned
0, and the shortcut is not a built-in shortcut.
this function takes 0 arguments.
handle_custom_action()
This function is called when an unknown action (as described in VIDEO JSON
FORMAT) is given.
This function takes 1 argument:
The action.
Exit Codes:
1 go back to menu
2 exit
CUSTOM THUMBNAILS
Custom thumbnails are located in $YTFZF_CUSTOM_THUMBNAILS_DIR. The name of the image must
be <video-id>.jpg
To see an example, make a search with ytfzf and locate the thumbnails folder in
$cache_dir/search
Custom thumbnails are going to try to be loaded before the official thumbnail.
If a custom thumbnail, and the official thumbnail doesn't exist, ytfzf will try to use
$YTFZF_CUSTOM_THUMBNAILS_DIR/YTFZF:DEFAULT.jpg .
VIDEO JSON FORMAT
This is the format used for playlists, and custom scrapers.
Videos should be objects in a list.
Required object keys:
ID (string): a unique id to the video
url (string): the url to the video
title (string): the title of the video
scraper (string): The scraper that created the json (used for thumbnails)
thumbs (string): a url to a thumbnail/image
channel (string): the channel name
duration (string): length of the video (standard: [HH:]MM:SS)
views (string): amount of views a video has
date (string): upload date (standard: date is relative to current day, eg: 3 days ago)
action (string): an action in the format of "action [key=value key2=value2...]"
Example JSON:
[
{
"ID": "dQw4w9WgXcQ",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"title": "definitely not never gonna give you up"
}
]
PLAYLISTS
A playlist is a json file in the format of VIDEO JSON FORMAT, To easily get the formatted
json for a video, run ytfzf -I VJ <search
SORT NAMES
A sort name is a function in your config file, or a shell script in $YTFZF_SORT_NAMES_DIR
that defines the following functions:
data_sort_fn()
get_sort_by()
CUSTOM SCRAPERS
Custom scrapers shell scripts located in $YTFZF_CUSTOM_SCRAPERS_DIR.
A scraper is responsible for scraping videos from a website and APPENDING them to
"$ytfzf_video_json_file".
The shell script must be the same shell as your /bin/sh.
Other functions this script may define:
on_startup_<name_of_scraper>
This function will be called when the scraper is sourced (which is when the user
asks for it).
This function takes no arguments.
thumbnail_video_info_text_<name_of_scraper>
This function shall print information for the thumbnails interface.
This function is effectively the same as thumbnail_video_info_text().
scrape_next_page_<scraper>
This function shall scrape more videos from <scraper>.
In order for this function to be called properly with alt-p, or ctrl-p, the page it
left off on must be written to ${session_cache_dir}/<scraper>-current-page.
Where scraper is the name of the scraper with _ instead of -
<scraper> should be the name put in the "scraper" attribute in VIDEO JSON FORMAT
This function will happen if the user presses alt-p in fzf.
This function takes no arguments.
handle_custom_action_<action_name>
This function shall handle a custom action.
<action_name> should be the name of the action replacing any "-" with "_".
This function takes 1 argument.
1 The action arguments
Exit Codes:
1 go back to menu
2 exit
CUSTOM INTERFACES
Custom interfaces are shell scripts located in $YTFZF_CUSTOM_INTERFACES_DIR.
An interface is responsible for letting the user pick a video from
"$ytfzf_video_json_file", then writing the url(s) to "$ytfzf_selected_urls"
The shell script must be the same shell as your /bin/sh.
In addition, the script must also define the function interface_<name_of_interface>
With _ replacing -.
This function could handle everything itself, or call another program written in any
language to handle it.
interface_<name_of_interface> will take a path to the json file holding all data about all
the videos as the first argument.
The second argument will be a path to a file to store the selected url in, separated by
new lines.
Other functions the scraper may define:
search_prompt_menu_<name_of_interface>()
This function should do the same thing as search_prompt_menu(). This function
takes no arguments.
If this function is not defined, search_prompt_menu_ext() will be called instead.
quick_menu_<name_of_interface>()
This function should do the same thing as quick_menu(). This function takes no
arguments.
If this function is not defined, quick_menu_ext() will be called instead.
display_text_<name_of_interface>()
This function should display text in a way that is copy and pasteable. This
function takes an unlimited number of arguments.
... The text to display
info_wait_prompt_<name_of_interface>()
This function should ask the user to pick an info_wait_action option. It should
then set the variable info_wait_action equal to the user's choice. This function
takes no arguments.
THUMBNAIL VIEWERS
Custom thumbnail viewers are programs in $YTFZF_THUMBNAIL_VIEWERS_DIR. Arguments:
1 An action, there are 3 actions, start, stop, view, no-img
2 The path to the thumbnail.
3 x position (in columns) of the image
4 y position (in lines) of the image
5 width of image (in columns)
6 height of image (in lines)
7 max width of image (in columns) (width already accounts for this)
8 max height of image (in lines) (height already accounts for this)
9 side of the terminal to display the image (x, y, width, height already
account for this)
this will be either up down left right
EXTENSIONS
Extensions are essentially extra config files that you can load in your own config file.
Extensions should either be in $YTFZF_EXTENSIONS_DIR or $YTFZF_SYSTEM_ADDON_DIR/extensions
An extension can do anything a config file can, this includes modifying the default
utility functions in ytfzf (which could break the script)
Extensions will be given a variable called $__loaded_path which is the full path to the
extension that is loaded.
This is helpful when needing to determine the current runtime path for the extension.
To load an extension add load_extension name-of-extension to $YTFZF_CONFIG_FILE
There are two automatically loaded extensions, __ytfzf__ and __ytfzf_multisearch__
__ytfzf_multisearch__ is only loaded if $multi_search is 1
Functions for extensions, where <ext> is replaced with the name of the extension, and all
- are replaced with _.
on_clean_up_<ext>()
Runs when the script exits. This function takes no arguments.
on_no_thumbnail_<ext>()
Runs when no thumbnail is found. This function takes no arguments.
after_close_url_handler_<ext>()
Runs after the url handler is closed. This function takes no arguments.
on_post_set_vars_<ext_name>()
Replace ext_name with the name of an extension (with - replaced with _). This
function is the same as on_post_set_vars
ext_on_search_<ext>()
Runs for before the website is scraped, for every search query. This function
takes two arguments.
1 The current search
2 The current scrape type
post_scrape_<ext>()
Runs after scraping is complete. This function takes no arguments.
on_init_search_<ext>()
Runs when the search is being initialized. This function takes one argument.
1 The search
UTILITY FUNCTIONS
A utility function is any function that can be used in configuration files, extensions,
thumbnail viewers, interfaces, search-names,
refresh_inv_instances()
This function writes the response from
"https://api.invidious.io/instances.json?sort_by=type,health,api" to
$cache_dir/instances.json. This function takes no arguments.
get_invidious_instances()
This function grabs invidious instances that have an api and prints them separated
by a new line. This function takes no arguments.
create_sorted_video_data()
This function prints a sorted jsonl string of the scraped videos that can be used
in an interface This function takes no arguments.
run_interface()
Runs the function interface_<interface_name>, and passes $ytfzf_video_json_file,
and $ytfzf_selected_urls This function takes no arguments.
download_thumbnails()
If $skip_thumb_download is 0, this function downloads thumbnails. This function
takes an unlimited number of arguments formatted in the following way:
<url_name>;<id>
This function should download <url_name> and save it as <id>.jpg in the $thumb_dir
folder.
prepare_for_set_args()
This function sets the variable $OLD_IFS to $IFS, then sets $IFS to the first
argument, lastly it runs set -f. This function takes one argument.
1 The new IFS.
end_of_set_args()
This function sets IFS to OLD_IFS. This function takes no arguments.
modify_ifs()
This function sets IFS to the first argument. This function takes one argument.
1 The value to set IFS to.
end_modify_ifs()
This function unsets $IFS. This function takes no arguments.
mul_str()
This function does string multiplication, then prints the result to stdout. This
function takes two arguments.
1 The string.
2 The amount to duplicate the string.
remove_ansi_escapes()
This function removes ansi escape sequences from a string passed to this function
through stdin. This function then prints the final string to stdout. This
function takes no arguments.
do_an_event_function()
This function runs an event if it exists, then runs event_<ext> for every loaded
extension $loaded_extensions, if they exist. This function takes an unlimited
number of arguments.
1 The name of the event.
... The arguments to pass to event
detach_cmd()
This function detaches a command from the terminal. This function takes an
unlimited number of arguments.
1 The command to run
... The arguments to pass to the command.
source_scrapers()
This function goes through each scraper listed in $scrape, and sources the
appropriate file. After sourcing the file, it runs the on_startup_<scrape>
function, if $__is_fzf_preview is 0. This function checks the following locations
for the file to source.
$YTFZF_CUSTOM_SCRAPERS_DIR
$YTFZF_SYSTEM_ADDON_DIR/scrapers
$YTFZF_CUSTOM_SCRAPERS_DIR
$YTFZF_SYSTEM_ADDON_DIR/scrapers
add_commas()
This function adds commas to a number (in the standard english way). This function
gets a number from stdin, and prints the result to stdout. This function takes no
arguments.
command_exists()
This function checks if a command exists. This function exits with status code 0
if it exists, and 1 if it does not. This function takes 1 argument.
1 The command to check
get_key_value()
This function gets the value by a key in a key_value string.
A key_value string is formatted in the following way:
<sep>key=value<sep>...
where <sep> is argument 3, by default a space.
If there is only one key_value pair, there must still be <sep> on each side.
After printing the value to stdout, this function sets the variable $KEY_VALUE to
the value of the key.
This function exits with status code 0 if the value is not empty, and 1 if it is
empty.
This function takes three arguments.
1 The key_value string.
2 The key to find the value for.
3 (optional)
The separator that separates each key_value pair. By default this is a
space.
title_str()
This function capitalizes the first letter of a string, and prints it to stdout.
This function takes one argument.
1 The string to title.
shuf() This function is only created if shuf is not installed. This function should act
the same as the base functionality of shuf
print_info()
This function prints information to stderr, if $log_level is greater than or equal
to 2. This function takes one argument.
1 The text to print
print_warning()
This function prints a warning to stderr, if $log_level is greater than or equal to
1. This function takes one argument.
1 The text to print
print_error()
This function prints a warning to stderr, if $log_level is greater than or equal to
0. This function takes one argument.
1 The text to print
clean_up()
This function kills all ytfzf(1) subprocesses, and removes $session_cache_dir if
$session_cache_dir exists, and if $keep_cache equals 0.
Lastly, it runs the on_clean_up event. This function takes no arguments.
is_relative_dir()
Checks if a string is a relative path. This function exits with status code 0 if
it is relative, and 1 if it is not. This function takes one argument.
1 The path to check
die() This function runs print_error with a string, then exits with a status code. This
function takes two arguments.
1 The exit status
2 The text to print with print_error.
trim_url()
This function reads lines from stdin, and prints the url from them to stdout. The
lines should be formatted in the following way:
text....|url
This function takes no arguments.
get_search_from_source()
This function sets _search to a search depending on the source. This function
takes an unlimited number of arguments.
1 The source to get the search from.
... The arguments to use as the search if $1 is fn-args, or if 1 is not matched,
... is given to get_search_from_<1>.
load_extension()
This function adds an extension to the $loaded_extensions variable, and sources the
extension. This function checks the following locations for the extension
$YTFZF_EXTENSIONS_DIR
$YTFZF_SYSTEM_ADDON_DIR/extensions
$PATH
This function exits with the same exit code as when the extension was loaded. This
function takes one argument.
1 The extension to load
extension_is_loaded()
This function checks if an extension is loaded. This function takes one argument.
1 The extension to check
load_sort_name()
This function loads a sort-name. This function checks the following locations for
the sort-name.
$YTFZF_SORT_NAMES_DIR
$YTFZF_SYSTEM_ADDON_DIR/sort-names
This function exits with status code 1 if the sort-name does not exist, otherwise
it exits with the same status code as when the sort-name was loaded. This function
takes one argument.
1 The sort-name to load
load_url_handler()
This function sets $url_handler to a url-handler. This function checks the
following locations for the url-handler.
$PATH, and functions in config file
$YTFZF_URL_HANDLERS_DIR
$YTFZF_SYSTEM_ADDON_DIR/url-handlers
If the url-handler does not exist, this function runs die.
This function takes one argument.
1 The url-handler to load
load_interface()
This function sets $interface to an interface.
If $1 is equal to ext, scripting, or "", $interface is set to 1.
This function checks the following locations for the interface.
$1
$YTFZF_CUSTOM_INTERFACES_DIR
$YTFZF_SYSTEM_ADDON_DIR/interfaces
This function takes one argument.
1 The interface to load
load_thumbnail_viewer()
This function sets $thumbnail_viewer to a thumbnail-viewer. If $i is equal to a
built-in thumbnail-viewer, $thumbnail_viewer is set to that. Otherwise, the
following locations are checked.
$1
$YTFZF_THUMBNAIL_VIEWERS_DIR
$YTFZF_SYSTEM_ADDON_DIR
This function takes one argument.
1 The thumbnail viewer to load
_get_request()
This function sends a request to a server and prints the response. This function
takes Unlimited arguments.
1 The url to send a request to
... Arguments to pass to curl(1)
_get_real_channel_link()
This function converts a youtube channel link in the form of
@user
https://www.youtube.com/user/<channel-name>
https://www.youtube.com/c/<channel-name>
This function takes one argument.
1 The link to convert