.TH YTFZF 5 "2021 September" "ytfzf 2.0" .SH NAME ytfzf \- the configuration file for \fBytfzf\fR. .SH SYNOPSIS .I ~/.config/ytfzf/conf.sh .SH DESCRIPTION .PP The configuration file is a \fI.sh\fR file and can be used as such. The file can be completely empty and \fBytfzf\fR will still work with the default settings. The options should be set as environment variables and functions. .SH CONFIGURATION FILES .PP Configuration files are stored in .IR "$XDG_CONFIG_HOME/ytfzf (or $HOME/.config/ytfzf)" . .SS conf.sh .PP A shell script that gets sourced into ytfzf when ytfzf is run. .SS subscriptions .PP A file that is a list of links to youtube channel's video page, such as: .RS .EX .I https://www.youtube.com/channel/UCtMVHI3AJD4Qk4hcbZnI9ZQ .EE .RE .PP If a channel appears similar to "https://www.youtube.com/c/SomeOrdinaryGamers", run .br ytfzf --channel-link="https://www.youtube.com/c/SomeOrdinaryGamers" .br Before adding it to your subscriptions file .PP A comment can be created by having '#comment' on its own line or after a link. For example: .RS .EX .I link-to-channel #comment .IR link-to-channel " #best channel" .EE .RE .SS scrape lists .PP A file that is a list of scrape types an searches, such as: .RS .EX .I youtube this is a search .EX .I odysee this is an odysee search .EE .RE .PP Just like subscriptions, scrape lists can have comments .RE .SS scrapers .PP A folder that contains executable files that scrape websites See CUSTOM SCRAPERS for more information .RE .SH CONFIGURATION OPTIONS .SS VARIABLES .PP conf.sh is used mainly for setting variables for \fBytfzf\fR. If a variable has no default, that means it is set to an empty string. .br To set a variable in conf.sh be sure to use .br variable_name="value" .br leave out the $ at the start of the variable name. .PP Files and directories .RS .TP .RB $ cache_dir The directory to store cache files in. .br It is highly recommended to only change this if $__is_submenu is 0, or funky things could happen .br .IR default: " $XDG_CACHE_HOME/ytfzf (or $HOME/.cache/ytfzf)" .TP .RB $ hist_file The file to write watch history to if $enable_hist is 1 .br It is highly recommended to only change this if $__is_submenu is 0, or funky things could happen .br .IR default: " $cache_dir/watch_hist" .TP .RB $ search_hist_file The file to write search history to if $enable_search_hist is 1 .br .IR default: " $cache_dir/search_hist" .TP .RB $ ytfzf_selected_urls The file to store the ids of selected video(s) in. .br .IR default: " $cache_dir/urls" .TP .RB $ ytfzf_video_json_file The file to store the json data of scraped videos. .br .IR default: " $cache_dir/videos_json" .RE .PP How to play the selected videos. .RS .TP .RB $ is_detach Whether or not to detach the video player from the terminal. .br .IR default: " 0" .TP .RB $ is_audio_only Whether or not to only play audio. .br .IR default: " 0" .TP .RB $ url_handler The function/programs to handle the selected videos .br See URL handlers for a list of built-in url handlers .IR default: " multimedia_player" .TP .RB $ yt_video_link_domain The domain to play youtube videos from (does not apply to odysee and peertube or youtube playlists) .br .IR default: " https://www.youtube.com" .TP .RB $ info_to_print The information to print instead of playing a video. The available options for this variable are: .RS .TP .IR L " | " l " | " link Print the URL of the selected videos. .TP .IR VJ " | " vj " | " video\-json Prints the json of the selected videos. .TP .IR J " | " j " | " json Prints the json of all the videos in the search results. .TP .IR F " | " f " | " format Prints the video format being used. .TP .IR R " | " r " | " raw Prints the data of the selected videos, as appears in the menu. .RE .TP .RB $ info_wait_action The action to do when $info_wait is 1. .br Valid actions: .RS .TP .IR q quit (will go back to menu, if $is_loop is 1). .TP .IR Q quit regardless if loop is enabled or not. .TP .IR m return to menu. .br .IR default: " q" .TP .BR $ info_wait Whether or not to wait for input after printing info. .br .IR default: " 0" .TP .RB $ video_pref The video preference to use for youtube-dl in mpv. .br .IR default: " bestvideo" .TP .RB $ audio_pref The audio preference to use for youtube-dl in mpv. .br .IR default: " bestaudio" .TP .RB $ ytdl_pref The preference to use for youtube-dl in mpv. .br .IR default: " $video_pref+$audio_pref/best/$video_pref/$audio_pref" .TP .RB $ 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 .BR url_handler_opts .RE .RE .PP Menu options .RS .TP .RB $ interface The interface/menu to use. .br Valid options. .RS .TP .IR ext same as \-D .TP .IR scripting is applied when \-a, \-r, or \-A is used .TP .IR "''" default .RE .TP .RB $ external_menu_len The amount of cols in interface_ext, (\-D) .br .IR default: " 210" .TP .RB $ fzf_preview_side The side to show the preview in fzf. .br Valid options: .RS .TP .IR left .TP .IR right .TP .IR up .TP .IR down .TP .IR default: " left" .RE .TP .RB $ thumbnail_viewer The program to display images for thumbnail previews .br Valid options: .RS .TP .IR chafa .TP .IR chafa-16 Uses chafa with 16 colors .TP .IR chafa-tty Uses chafa with 4 colors .TP .IR catimg .TP .IR catimg-256 Uses catimg with 256 colors .TP .IR w3m Uses a workaround to get w3m to work in fzf, may take up a lot of cpu, make sure $w3mimgdisplay_path is set to the path to w3mimgdisplay .TP .IR imv Good with tiling window managers .TP .IR kitty For the kitty terminal. .TP .IR swayimg Only works on the sway wayland compositor .TP .IR default: " ueberzug" .RE .TP .RB $ w3mimgdisplay_path Path to w3mimgdisplay .br .IR default: " /usr/lib/w3m/w3mimgdisplay" .TP .RB $ show_formats Whether or not to bring up the format selection menu. .br .IR default: " 0" .TP .RB $ format_selection_screen The format that selection screen will use. Types: .RS .IR simple .IR normal .br .IR default: " simple" .RE .TP .RB $ format_selection_sort The \-\-format\-sort to use in ytdl. .br .IR default: " height" .TP .RB $ enable_submenus Whether or not to enable submenus, .br A submenu is a menu that appears after a playlist or channel is selected. (Currently only supported with youtube/invidious scraper) .IR default: " 1" .TP .RB $ enable_back_button Whether or not to enable back button in submenus. .IR default: " 1" .TP .RB $ submenu_opts Options to use in submenus. .IR default: "" .TP .RB $ submenu_scraping_opts Options to use for scraping for submenus. .IR default: "" .TP .RB $ is_sort Whether or not to sort scraped videos by date in the menu .IR default: " 0" .TP .RB $ fancy_subs Whether or not to have a separator between each subscription .IR default: " 0" .TP .RB $ fancy_subs_left The text to display on the left of the channel name when fancy_subs is 1. .IR default: " -------------" .TP .RB $ fancy_subs_right The text to display on the right of the channel name when fancy_subs is 1. .IR default: " $fancy_subs_left" .TP .RB $ show_thumbnails Whether or not to show thumbnails in fzf. .br .IR default: " 0" .TP .RB $ skip_thumb_download Whether or not to skip thumbnail download. .br .IR default: " 0" .TP .RB $ thumbnail_quality Select the quality of the thumbnails. Currently only supports youtube (uses invidious api). .br This does not work for the \(aq\fB-cS\fR\(aq scraper as it scrapes youtube not invidious (use \(aq\fBSI\fR\(aq instead). .br For lower internet speeds it is recommended to use default. .br Available options: .RS .TP .IR maxres .TP .IR maxresdefault .TP .IR sddefault .TP .IR high " (default)" .TP .IR medium .TP .IR default .TP .IR start The first frame of the video (low quality) .TP .IR middle The middle frame of the video (low quality) .TP .IR end The end frame of the video (low quality) .RE .br .TP .RB $notify_playing Whether or not to send a notification when a video is about to be played. .br .IR default: " 0" .TP .RB $ is_loop Whether or not to show the menu after the selected videos have stopped playing. .br .IR default: " 0" .TP .RB $ search_again Whether or not to make another search after fzf is closed. .br .IR default: " 0" .TP .RB $ download_shortcut The shortcut to download the selected videos. .br .IR default: " alt-d" .TP .RB $ video_shortcut The shortcut to watch the selected videos. .br .IR default: " alt-v" .TP .RB $ audio_shortcut The shortcut to listen to the selected videos. .br .IR default: " alt-m" .TP .RB $ detach_shortcut The shortcut to use the detach player. .br .IR default: " alt-e" .TP .RB $ print_link_shortcut The shortcut to use to print the link. .br .IR default: " alt-l" .TP .RB $ show_formats_shortcut The shortcut to show formats before playing the video. .br .IR default: " alt-f" .TP .RB $ info_shortcut The shortcut to get all info about the selected video. .br .IR default: " alt-i" .TP .RB $ search_again_shortcut The shortcut to make another search. .br .IR default: " alt-s" .TP .RB $ next_page_shortcut The shortcut to scrape the next page. .br Currently only applies to the comments scrape. .IR default: " alt-p" .TP .RB $ shortcut_binds The keys to listen for in fzf. .br .IR default: " Enter,double-click,$next_page_shortcut,$download_shortcut, $video_shortcut,$detach_shortcut,$print_link_shortcut,$show_formats_shortcut, $info_shortcut,$search_again_shortcut,$custom_shortcut_binds" .TP .RB $ custom_shortcut_binds The custom shortcut keys. Automatically appended to $shortcut_binds .br If $shortcut_binds is set manually, this must also manually be appended. .RE .PP Auto selecting .RS .TP .RB $ is_auto_select Whether or not to auto select the first \-n videos. (only works if $interface=scripting) .br .IR default: " 0" .TP .RB $ is_random_select Whether or not to randomly select \-n videos. (only works if $interface=scripting) .br .IR default: " 0" .TP .RB $ is_specific_select Whether or not to select a specific video (use $ scripting_video_count to specify which) (only works if $interface=scripting) .br .IR default: " 0" .TP .RB $ scripting_video_count The amount of videos to get with \-a or \-r. .br .IR default: " 1" .RE .PP Scrapers .RS .TP .RB $ scrape The website to scrape by default. The currently supported options are: .RS .TP .IR youtube , .TP .IR youtube\-trending , .TP .IR youtube\-subscriptions , .TP .IR peertube , .TP .IR odysee / lbry . .TP .IR youtube-playlist , .TP .IR youtube-channel , .TP .IR invidious-channel , .TP .IR video-recommended , .TP .IR playlist/json-file , .PP The search will be a path to a json file layed out as described in VIDEO JSON FORMAT .TP .IR history , .TP .IR url , .TP .IR comments .br .IR default: " youtube" .RE .TP .RB $ multi_search Whether or not to enable multi search. .IR default: " 0" .TP .RB $ search_sort_by The attribute to sort by when searching. .RS .TP .IR relevance " (default)" .TP .IR rating " (youtube only)" .TP .IR upload_date .TP .IR oldest_first " (odysee only)" .TP .IR view_count " (youtbe only)" .RE .TP .RB $ search_upload_date Search for videos within the last: .RS .TP .IR hour .TP .IR today .TP .IR week .TP .IR month .TP .IR year .RE .TP .RB $ search_video_duration Whether or not to search for long or short videos. Possible options: .RS .TP .IR short .TP .IR long .RE .TP .RB $ search_result_type The type of results to get. .RS .TP .IR video " (default)" .TP .IR playlist .TP .IR channel .TP .IR all " (may not work on some instances)" .RE .TP .RB $ nsfw Whether or not to search for nsfw videos in odysee/O. .br .IR default: " false" .TP .RB $ search_result_features The features to have on a video (comma separated). .RS .TP .IR hd .TP .IR subtitles .TP .IR creative_commons .TP .IR 3d .TP .IR live .TP .IR 4k .TP .IR 360 .TP .IR location .TP .IR hdr .RE .TP .RB $ search_region The region (country code) to search. .IR default: " US" .TP .RB $ invidious_instance The instance of invidious to use. .br .IR default: " https://vid.puffyan.us" .TP .RB $ pages_to_scrape The amount of pages to scrape on youtube/invidious. .br .IR default: " 1" .TP .RB $ 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) .br .IR default: " 20" .TP .RB $ odysee_video_search_count The amount of videos to scrape on odysee. .br .IR default: " 30" .TP .RB $ sub_link_count The amount of videos to scrape per channel when getting subscriptions. .br .IR default: " 2" .RE .PP Misc .RS .TP .RB $ scrape_search_exclude The scrapers to not ask for a search query. .br Be sure to have a space at the end and beginning of the string. .br .IR default: " youtube-subscriptions S SI T youtube-trending H history " .TP .RB $ custom_scrape_search_exclude Extra scrapers to not ask for a search query. .br This will automatically be appended to $ scrape_search_exclude. .br In addition, you do not need spaces at the start, and end, only between scrapers. .IR default: "" .TP .RB $ gap_space A number of spaces equal to half the width of your terminal .br .IR default: " 115 spaces" .TP .RB $ enable_hist Whether or not to keep track of history .br .IR default: " 1" .TP .RB $ enable_search_hist Whether or not to keep track of search history .br .IR default: " 1" .TP .RB $ use_search_hist Whether or not to use search history instead of a search. .br .IR default: " 0" .TP .RB $ log_level How much debug information to log. .RS .TP .IR 2 Log everything .TP .IR 1 Log only warnings and errors .TP .IR 0 Log only errors .TP .IR default: " 2" .RE .TP .RB $ useragent The useragent to use when scraping websites. .br .IR default: " \(dqMozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.152 Safari/537.36\(dq" .TP .RB $ ytdl_opts The command\-line options to pass to youtube\-dl when downloading. .TP .RB $ ytdl_path Path to youtube\-dl or a fork of youtube\-dl for downloading. .br If .I yt-dlp is installed that will be preferred over .I youtube-dl .br .IR default: " youtube\-dl" .RE .PP Option Parsing .RS .TP .RB $ long_opt_char The char to use for long opts. .br .IR default: " \-" .RE .PP State .br State values are \fBNOT\fR meant to be modified by the user. .RS .TP .RB $ __is_submenu Whether or not the script is in a submenu. .TP .RB $ __is_scrape_for_submenu Whether or not the script is scraping for a submenu. .TP .RB $ __is_fzf_preview Whether or not the script is running to display an fzf preview .TP .RB __scrape_count The current scrape count starting at 1. .SS FUNCTIONS .PP 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 .IR "function_exists \(dq\(dq" . .PP Menu related functions .RS .TP .BR external_menu () When $\fBinterface\fR is \fIext_menu\fR, call this function instead of fzf. .br This function takes 1 argument, a prompt string. .TP .BR get_sort_by () This function is called to get the value to sort by when $\fBis_sort\fR is \fI1\fR. .br This function takes in a line in the form of .IR "\(dqtitle |channel |duration |views |date |id\(dq" . .TP .BR data_sort_fn () This function sorts the data that is being piped into it. .br This function takes no arguments, all data is piped into it. .TP .BR custom_info_wait_action_ () This function is called if an unknown $info_wait_action is given or read. .br should be replaced with the text wanted from $info_wait_action, eg: \fIcustom_info_wait_e\fR. .br This function takes no arguments. .TP .BR video_info_text () This function prints the text for the selection menu. .br Must end with a new line, .br The url must be the last thing printed. .br This function takes no arguments, the relevant variables are listed here: .RS .EX .I title .I channel .I duration .I views .I date .I url .EE It is recommended to check the script to see how each thing is printed. .RE .TP .BR thumbnail_video_info_text () This function prints text in the preview area of fzf when thumbnails are enabled. .br Everything can be printed however you like. .br This function takes no arguments, the relevant variables are listed here: .RS .EX .I title .I channel .I duration .I views .I date .I url .EE .RE .TP .BR thumbnail_video_info_text_ () This function is the same as thumbnail_video_info_text() for the scraper specified. .TP .BR get_ueberzug_positioning_left () This function sets the variables, $width, $height, $x, and $y. $x, and $y, should represent cols and lines not pixels. .br These variables will be used to position and size the image in the fzf preview when $fzf_preview_side is left. .br This function takes 2 arguments: .RS .EX .I max_width .I max_height .RE .TP .BR get_ueberzug_positioning_right () This function sets the variables, $width, $height, $x, and $y. $x, and $y, should represent cols and lines not pixels. .br These variables will be used to position and size the image in the fzf preview when $fzf_preview_side is right. .br This function takes 2 arguments: .RS .EX .I max_width .I max_height .RE .TP .BR get_ueberzug_positioning_up () This function sets the variables, $width, $height, $x, and $y. $x, and $y, should represent cols and lines not pixels. .br These variables will be used to position and size the image in the fzf preview when $fzf_preview_side is up. .br This function takes 2 arguments: .RS .EX .I max_width .I max_height .RE .TP .BR get_ueberzug_positioning_down () This function sets the variables, $width, $height, $x, and $y. $x, and $y, should represent cols and lines not pixels. .br These variables will be used to position and size the image in the fzf preview when $fzf_preview_side is down. .br This function takes 2 arguments: .RS .EX .I max_width .I max_height .RE .TP .BR get_swayimg_positioning_left () This function sets the variables, $x, $y, $img_w, and $img_h. $x, and $y, should represent pixels. .br These variables will be used to position and size the image in the fzf preview when $fzf_preview_side is left. .br This function takes 8 arguments: .RS .EX .I img_w .I img_h .I max_width .I max_height .I max_height .I term_x .I term_y .I col_px_width .I line_px_height .RE .TP .BR get_swayimg_positioning_right () This function sets the variables, $x, $y, $img_w, and $img_h. $x, and $y, should represent pixels. .br These variables will be used to position and size the image in the fzf preview when $fzf_preview_side is right. .br This function takes 8 arguments: .RS .EX .I img_w .I img_h .I max_width .I max_height .I max_height .I term_x .I term_y .I col_px_width .I line_px_height .RE .TP .BR get_swayimg_positioning_up () This function sets the variables, $x, $y, $img_w, and $img_h. $x, and $y, should represent pixels. .br These variables will be used to position and size the image in the fzf preview when $fzf_preview_side is up. .br This function takes 8 arguments: .RS .EX .I img_w .I img_h .I max_width .I max_height .I max_height .I term_x .I term_y .I col_px_width .I line_px_height .RE .TP .BR get_swayimg_positioning_down () This function sets the variables, $x, $y, $img_w, and $img_h. $x, and $y, should represent pixels. .br These variables will be used to position and size the image in the fzf preview when $fzf_preview_side is down. .br This function takes 8 arguments: .RS .EX .I img_w .I img_h .I max_width .I max_height .I max_height .I term_x .I term_y .I col_px_width .I line_px_height .RE .TP .BR search_prompt_menu () This function asks the user to make a search query, and sets the variable $_search to the query. .br This function is called if ytfzf is started without a search. (and is using the default interface) .br This function takes no arguments. .TP .BR search_prompt_ext () This function asks the user to make a search query, and sets the variable $_search to the query. .br This function is called if ytfzf is started without a search. (and is using the \-D flag) .br This function takes no arguments. .TP .BR search_prompt_scripting () This function asks the user to make a search query, and sets the variable $_search to the query. .br This function is called if ytfzf is started without a search. (and is using the \-r, \-a, or \-A flag) .br This function takes no arguments. .TP .BR quick_menu () This function should take user input and echo it back .br This function is called with -f, and -q. Or any other time a generic menu is needed. (and the default interface is being used) .br This function takes 1 argument, and takes input from stdin .br 1: The prompt to use. .br stdin: the items to choose from (separated by new lines) .TP .BR quick_menu_ext () This function should do the same thing as quick_menu() .br This function is called when quick_menu() would be called, but when \-D is enabled. .br This function takes 1 argument, and takes input from stdin .br 1: The prompt to use. .br stdin: the items to choose from (separated by new lines) .TP .BR quick_menu_scripting () This function should do the same thing as quick_menu() .br This function is called when quick_menu() would be called, but when \-a, \-r, or \-A is enabled. .br This function takes 1 argument, and takes input from stdin .br 1: The prompt to use. .br stdin: the items to choose from (separated by new lines) .RE .PP URL handlers .RS .PP A URL handler is a function that handles the urls given, .br URL handlers should take into account these modifier values, .B $video_pref ", " .B $is_audio_only ", " and .B $is_detach .PP Modifier variables will be piped into a URL handler to allow for URL handlers to be written in any language. .br They will be piped in the order shown above separated by spaces. .TP .BR multimedia_player () The handler that is called by default. .br This function opens either video_player() or audio_player() depending on whether or not .br $is_audio_only (\-m) is enabled. .br This function takes in an unlimited amount of arguments, each of which is a link to a video. .TP .BR video_player () Plays the urls with a video player .br This function takes in an unlimited amount of arguments, each of which is a link to a video. .TP .BR audio_player () Plays the urls with an audio player .br This function takes in an unlimited amount of arguments, each of which is a link to a video. .TP .BR downloader () Downloads the urls .br This function takes in an unlimited amount of arguments, each of which is a link to a video. .TP .BR get_video_format_() A custom format selection screen .br should be the the wanted value of $format_selection_screen .br This function should print the final ytdl format to use. .br This function takes all urls as separate arguments. .RE .PP Search History .RS .TP .BR handle_search_history() This function handles appending the search to the given search file. .br This function takes 2 arguments: .RS .TP .IR 1 The search to write .TP .IR 2 The file to append to. .RE .TP .BR parse_search_hist_file() This function should parse the search history file, and print out each search separated by new lines. .br The search history file will be fed through stdin. .RE .PP Misc .RS .TP .BR handle_playing_notifications() This function sends a notification for the videos that are about to be played. .br This function takes an unknown amount of urls as arguments. .TP .BR 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. .br This function takes 4 arguments: .EX .I 1 .ti +4 The current option being parsed .I 2 .ti +4 The current option argument being parsed .I 3 .ti +4 The unmodified option being parsed. .ti +4 For an option such as \-a, this value will be the same as $1. .ti +4 However, for every \-\-long\-option this value will be "\-". .I 4 .ti +4 The unmodified option argument being parsed. .ti +4 For an option such as \-c S, this value will be the same as $2. .ti +4 However, for every \-\-long\-option=value, this value will be \-long\-option=value. .EE .TP .BR on_opt_parse () This function gets called before an option is parsed. A non 0 exit code will override the default behavior of a specific option. .br This function takes 3 arguments: .RS .TP .I 1 The the optarg .TP .I 2 The raw opt .TP .I 3 The raw optarg .RE .TP .BR on_post_set_vars () This fnction gets called after all vars are set, and all opts are parsed. .br This function takes no arguments. .TP .BR on_post_set_vars_ () Replace ext_name with the name of an extension (with - replaced with _). This function is the same as \fBon_post_set_vars\fR .TP .BR on_search () This function gets called each time a website is scraped. .br This function takes 2 arguments: .EX .I 1 .ti +4 The search query .I 2 .ti +4 The current scrape .EE .TP .BR on_search_ () This function gets called each time a website is scraped if the current search matches . .br This function takes 1 argument. .RS .TP .I 1 The current scrape .RE .TP .BR on_clean_up () This function is called when the script is cleaning up files from the search, or when the script exits. .br This function takes no arguments. .TP .BR 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. .br This function takes 1 argument: .EX .I 1 .ti +4 The key pressed. .EE .TP .BR 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. .br The job of this function is to undo the changes of the last keypress. .br This function takes no arguments, it must get the keypress from $keypress_file .TP .BR handle_keypress_* () The name of this function should replace the "*" with the name of the shortcut, eg: \fIalt_d\fR .br in addition replace any "\-" with "_". .br This function is called after handle_custom_keypresses() if it returned 0, and the shortcut is not a built-in shortcut. .br This function takes 0 arguments. .TP .BR handle_post_keypress_* () The name of this function should replace the "*" with the name of the shortcut, eg: \fIalt_d\fR .br in addition replace any "\-" with "_". .br This function is called after handle_custom_post_keypresses() if it returned 0, and the shortcut is not a built-in shortcut. .br this function takes 0 arguments. .TP .BR handle_custom_action () This function is called when an unknown action (as described in VIDEO JSON FORMAT) is given. .br This function takes 1 argument: .EX .I .ti +4 The action. .EE .br Exit Codes: .RS .TP .IR 1 go back to menu .TP .IR 2 exit .RE .RE .SH CUSTOM THUMBNAILS .PP Custom thumbnails are located in $YTFZF_CUSTOM_THUMBNAILS_DIR. The name of the image must be .I .jpg .PP To see an example, make a search with \fIytfzf\fR and locate the \fIthumbnails\fR folder in $cache_dir/search .PP Custom thumbnails are going to try to be loaded before the official thumbnail. .br If a custom thumbnail, and the official thumbnail doesn't exist, ytfzf will try to use .I $YTFZF_CUSTOM_THUMBNAILS_DIR/YTFZF:DEFUALT.jpg . .SH VIDEO JSON FORMAT .PP This is the format used for playlists, and custom scrapers. .br Videos should be objects in a list. .PP Required object keys: .EX .RE 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) .EE .RE .PP .RS .EX 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...]" .EE .RE .PP Example JSON: .EX [ { "ID": "dQw4w9WgXcQ", "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "title": "definitely not never gonna give you up" } ] .EE .SH PLAYLISTS .PP A playlist is a json file in the format of VIDEO JSON FORMAT, To easily get the formatted json for a video, run .I "ytfzf -I VJ .RS This function will be called when the scraper is sourced (which is when the user asks for it). .PP This function takes no arguments. .RE .PP .I thumbnail_video_info_text_ .RS This function shall print information for the thumbnails interface. .PP This function is effectively the same as thumbnail_video_info_text(). .RE .PP .IR scrape_next_page_ .RS .PP This function shall scrape more videos from . .PP should be the name put in the "scraper" attribute in VIDEO JSON FORMAT .PP This function will happen if the user presses alt-p in fzf. .PP This function takes no arguments. .RE .PP .IR handle_custom_action_ .RS .PP This function shall handle a custom action. .PP should be the name of the action replacing any "\-" with "_". .PP This function takes 1 argument. .RS .TP .IR 1 The action arguments .RE Exit Codes: .RS .TP .IR 1 go back to menu .TP .IR 2 exit .RS .RE .RE .SH CUSTOM INTERFACES .PP Custom interfaces are shell scripts located in $YTFZF_CUSTOM_INTERFACES_DIR. .br 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" .br The shell script must be the same shell as your /bin/sh. .br In addition, the script must also define the function .I interface_ .br With _ replacing \-. .br This function could handle everything itself, or call another program written in any language to handle it. .RE .PP interface_ will take a path to the json file holding all data about all the videos as the first argument. .br The second argument will be a path to a file to store the selected url in, separated by new lines. .PP Other functions the scraper may define: .TP .IR search_prompt_menu_ This function should do the same thing as search_prompt_menu(). This function takes no arguments. .br If this function is not defined, search_prompt_menu_ext() will be called instead. .TP .IR quick_menu_ This function should do the same thing as quick_menu(). This function takes no arguments. .br If this function is not defined, quick_menu_ext() will be called instead. .SH THUMBNAIL VIEWERS Custom thumbnail viewers are programs in $YTFZF_THUMBNAIL_VIEWERS_DIR. Arguments: .RS .TP .IR 1 An action, there are 3 actions, start, stop, view, no-img .TP .IR 2 The path to the thumbnail. .TP .IR 3 x position (in columns) of the image .TP .IR 4 y position (in lines) of the image .TP .IR 5 width of image (in columns) .TP .IR 6 height of image (in lines) .TP .IR 7 max width of image (in columns) (width already accounts for this) .TP .IR 8 max height of image (in lines) (height already accounts for this) .TP .IR 9 side of the terminal to display the image (x, y, width, height already account for this) .br this will be either \fIup\fR \fIdown\fR \fIleft\fR \fIright\fR .RE .SH EXTENSIONS .PP Extensions are essentially extra config files that you can load in your own config file. .PP Extensions should either be in $YTFZF_EXTENSIONS_DIR or $YTFZF_SYSTEM_ADDON_DIR/extensions .PP An extension can do anything a config file can, this includes modifying the default utility functions in ytfzf (which could break the script) .PP To load an extension add .I "load_extension name-of-extension" to $YTFZF_CONFIG_FILE