Provided by: ytfzf_2.6.0-1_all bug

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