YOUTUBE-VIEWER(1)

NAME
youtube-viewer - YouTube from command line.

See: youtube-viewer --help
     youtube-viewer --tricks
     youtube-viewer --examples
     youtube-viewer --stdin-help

CONFIGURATION OPTIONS

  auto_captions
When set to 1, auto-generated captions will be retrieved. By default, auto-generated captions are ignored.

  autoplay_mode
Enable autoplay mode, which will continuously play related videos.

  cache_dir
Cache directory where to save temporary files.

  colors
Use colors for text.

  comments_order
The sorting order for comments. Valid values: "time", "relevance".

  confirm
Display a confirmation message after each video played.

  convert_cmd
Command to convert videos.

Default value:

    "ffmpeg -i *IN* *OUT*"

*IN* gets replaced with the input file.

*OUT* gets replaced with the output file.

  convert_to
Format to convert each downloaded video into. (e.g.: "mp3").

  cookie_file
Load cookies from a file. Useful to overcome the "429: Too Many Requests" issue.

The file must be a "# Netscape HTTP Cookie File". Same format as "youtube-dl" requires.

See also:

    https://github.com/ytdl-org/youtube-dl#how-do-i-pass-cookies-to-youtube-dl

  copy_caption
When downloading a video, copy the closed-caption (if any) in the same folder with the video.

If "merge_into_mkv" and "merge_with_captions" are both enabled, there is no need to enable this option.

  custom_layout
Use a custom layout for video results, defined in "custom_layout_format".

Requires: Unicode::GCString or Text::CharWidth.

  custom_layout_format
An array of hash values specifying a custom layout for video results.

    align       # "left" or "right"
    color       # any color supported by Term::ANSIColor
    text        # the actual text
    width       # width allocated for the text

The value for "width" can be either a number of characters (e.g.: 20) or can be a percentage of the terminal width (e.g.: "15%").

The special tokens for "text" are listed in:

    youtube-viewer --tricks

  dash_mp4_audio
Include or exclude MP4/M4A (AAC) audio files.

  dash_segmented
Include or exclude streams in "Dynamic Adaptive Streaming over HTTP" (DASH) format.

  dash_support
Enable or disable support for split videos.

  debug
Enable debug/verbose mode, which will print some extra information.

Valid values: 0, 1, 2, 3.

  download_and_play
Play downloaded videos.

  download_with_wget
Download videos with "wget".

  downloads_dir
Directory where to download files and where to save converted files.

  env_proxy
Load proxy settings from *_proxy environment variables (if any).

  fat32safe
When downloading a video, make the filename compatible with the FAT32 filesystem.

  ffmpeg_cmd
Path to the "ffmpeg" program.

  fullscreen
Play videos in fullscreen mode.

  get_captions
Download closed-captions for videos (if any).

  get_term_width
Read the terminal width (`stty size`).

  hfr
Include or exclude High Frame Rate (HFR) videos.

  highlight_color
Highlight color used to highlight watched videos.

Any color supported by Term::ANSIColor can be used.

  highlight_watched
Highlight watched videos.

  history
Enable or disable support for input history.

Requires Term::ReadLine::Gnu.

  history_file
File where to save the input history.

  history_limit
Maximum number of entries in the history file.

When the limit is reached, the first half of the history file will be deleted.

Set the value to "-1" for no limit.

  hl
Language code for categories. Default: "en_US".

  http_proxy
Set HTTP(S)/SOCKS proxy, using the format:

    proto://domain.tld:port/

If authentication is required, use:

    proto://user:pass@domain.tld:port/

  ignore_av1
Ignore videos in AV1 format.

  interactive
Interactive mode, prompting for user-input.

  keep_original_video
Keep the original video after conversion. When set to 0, the original video will be deleted.

  maxResults
How many results to display per page.

  merge_into_mkv
During download, merge the audio+video files into an MKV container.

Requires "ffmpeg".

  merge_into_mkv_args
Arguments for "ffmpeg" how to merge the files.

  merge_with_captions
Include closed-captions inside the MKV container (if any).

  order
Search order for videos.

Valid values:

    date       – Sorted in reverse chronological order.
    rating     – Sorted from highest to lowest rating.
    relevance  – By relevance to the search query. (default)
    title      – Sorted alphabetically by title.
    videoCount – Sory by number of videos (for channels).
    viewCount  – Sorted from highest to lowest number of views.

  page
Page number of results.

  prefer_av1
Prefer videos in AV1 format. (just for testing)

  prefer_mp4
Prefer videos in MP4 (AVC) format.

  publishedAfter
The "publishedAfter" option indicates that the API response should only contain resources created at or after the specified time. The value is an RFC 3339 formatted date-time value (1970-01-01T00:00:00Z).

  publishedBefore
The "publishedBefore" option indicates that the API response should only contain resources created before or at the specified time. The value is an RFC 3339 formatted date-time value (1970-01-01T00:00:00Z).

  regionCode
The "regionCode" option instructs the API to return search results for videos that can be viewed in the specified country. The parameter value is an ISO 3166-1 alpha-2 country code. (default: "US")

  remove_played_file
When "download_and_play" is enabled, remove the file after playing it.

  resolution
Preferred resolution for videos.

Valid values: best, 2160p, 1440p, 1080p, 720p, 480p, 360p, 240p, 144p, audio.

  results_fixed_width
Results in fixed-width format.

Requires: Unicode::GCString or Text::CharWidth.

  results_with_colors
Results with colors.

  results_with_details
Results with extra details.

  safeSearch
The "safeSearch" option indicates whether the search results should include restricted content as well as standard content.

Valid values: "strict", "moderate", "none".

  show_video_info
Show extra info for videos when selected.

  skip_if_exists
When downloading, skip if the file already exists locally.

  skip_watched
Skip already watched/downloaded videos.

  srt_languages
List of SRT languages in the order of preference.

  subscriptions_order
Sorting order for subscriptions.

Valid values:

    alphabetical – Sort alphabetically.
    relevance    – Sort by relevance.
    unread       – Sort by order of activity.

  thousand_separator
Thousands separator character for numbers >= 1000.

  timeout
HTTPS timeout value in seconds. The default value is 10 seconds.

  user_agent
Token that is used to identify the user agent on the network. The agent value is sent as the "User-Agent" header in the requests.

  video_filename_format
The format of filename for downloaded files.

The available special tokens are listed in:

    youtube-viewer --tricks

  video_player_selected
The selected video player defined the "video_players" table.

  video_players
A table of video players.

The keys for each player are:

    arg        # any arguments for the video player
    audio      # option specifying the *AUDIO* file
    cmd        # the main player command
    fs         # the fullscreen option
    novideo    # the no-video mode option
    srt        # option specifying the *SUB* file

  videoCaption
The "videoCaption" option indicates whether the API should filter video search results based on whether they have captions.

Valid values:

    any           – Do not filter results based on caption availability.
    closedCaption – Only include videos that have captions.
    none          – Only include videos that do not have captions.

  videoDefinition
The "videoDefinition" option lets you restrict a search to only include either high definition (HD) or standard definition (SD) videos.

Valid values:

    any      – Return all videos, regardless of their resolution.
    high     – Only retrieve HD videos.
    standard – Only retrieve videos in standard definition.

  videoDimension
The "videoDimension" option lets you restrict a search to only retrieve 2D or 3D videos.

Valid values:

    2d  – Restrict search results to exclude 3D videos.
    3d  – Restrict search results to only include 3D videos.
    any – Include both 3D and non-3D videos in returned results.

  videoDuration
The "videoDuration" parameter filters video search results based on their duration.

Valid values: "any", "short", "long".

Valid values:

    any     – Do not filter video search results based on their duration.
    long    – Only include videos longer than 20 minutes.
    medium  – Only include videos that are between 4-20 minutes.
    short   – Only include videos that are less than 4 minutes long.

  videoLicense
The "videoLicense" option filters search results to only include videos with a particular license.

Valid values:

    any            – All videos, regardless of which license they have.
    creativeCommon – Only return videos that have a "Creative Commons" license.
    youtube        – Only return videos that have the standard YouTube license.

  videoSyndicated
The "videoSyndicated" option lets you to restrict a search to only videos that can be played outside youtube.com.

Valid values:

    any  – Return all videos, syndicated or not.
    true – Only retrieve syndicated videos.

  watch_history
Remember watched videos across multiple sessions.

The video IDs are saved in the filename specified by "watch_history_file".

This option is also required for "--watched-videos".

  watch_history_file
File where to save the video IDs of watched/downloaded videos when "watch_history" is set to a true value.

  wget_cmd
Command for "wget" when "download_with_wget" is set to a true value.

  youtube_users_file
Path to a list of YouTube channels, using the following format:

    ChannelID NAME

The channels can be listed with the command-line option: "-fc".

  youtube_video_url
Format for "sprintf()" for constructing an YouTube video URL given the video ID.

  ytdl
Use "youtube-dl" for videos with encrypted signatures.

When set to 0, invidious instances will be used instead.

  ytdl_cmd
Command for "youtube-dl" when "ytdl" is set to a true value.

CONFIGURATION FILES
The configuration files are:

    ~/.config/youtube-viewer/youtube-viewer.conf
    ~/.config/youtube-viewer/gtk-youtube-viewer.conf

YOUTUBE API REFERENCE
https://developers.google.com/youtube/v3/docs/

REPOSITORY
https://github.com/trizen/youtube-viewer

LICENSE AND COPYRIGHT
Copyright 2010-2020 Trizen.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

This program 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 <https://dev.perl.org/licenses/> for more information.