PIPE-VIEWER(1)

NAME
pipe-viewer - YouTube from command line.

     pipe-viewer --help
     pipe-viewer --tricks
     pipe-viewer --examples
     pipe-viewer --stdin-help

CONFIGURATION OPTIONS

  api_host
Hostname of an invidious instance. When set to "auto", a random invidious instance is selected on-demand.

List of public invidious instances:

    https://api.invidious.io/

Tor instances are also supported if the "socks5://127.0.0.1:9050" Tor proxy is available and the Perl module LWP::Protocol::socks is installed.

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

  audio_quality
The preferred quality for the audio-track:

    best        # best audio quality available (<=192kbps)
    medium      # medium audio quality (<=128kbps)
    low         # low audio quality (<=50kbps)

The option can also be set to a numeric value N in order to select an audio-track with <= Nkbps.

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

  bypass_age_gate_native
Bypass age-restricted videos, using our internal method.

However, these streaming URLs are heavily throttled by YouTube.

When this option is disabled, a fallback method will be used instead ("yt-dlp"/"youtube-dl" or invidious instances).

  bypass_age_gate_with_proxy
Bypass age-restricted videos using an YouTube Account Proxy.

  cache_dir
Cache directory where to save temporary files.

  colors
Use colors for text.

  comments_order
The sorting order for comments. Valid values: "top", "new".

  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) into 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_format
An array of hash values specifying a custom layout for video results.

    align       # "left" or "right"
    color       # any color name 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:

    pipe-viewer --tricks

For better formatting, it's highly recommended to install Unicode::GCString or Text::CharWidth.

  custom_channel_layout_format
An array of hash values specifying a custom layout for channel results.

  custom_playlist_layout_format
An array of hash values specifying a custom layout for playlist results.

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

  date
Search for videos uploaded within a specific amount of time.

Valid values: "anytime", "hour", "today", "week", "month", "year".

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

Valid values: 0, 1, 2, 3.

  dislikes_api
Enable the Return YouTube Dislike API to fetch dislike counts and 5-star ratings. These will be fetched from https://returnyoutubedislike.com.

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

  download_and_play
Play downloaded videos.

  download_in_subdir
Download videos in a new subdirectory inside the "downloads_dir" parent directory.

When enabled, videos will be saved inside a subdirectory specified by "download_in_subdir_format".

  download_in_subdir_format
Format string used for creating the subdirectory where to download the files, when "download_in_subdir" is enabled.

The available special tokens are listed in:

    pipe-viewer --tricks

  download_with_wget
Download videos with "wget".

  download_with_ytdl
Download videos with `yt-dlp` or `youtube-dl`.

By enabling this option and setting the value of "ytdl_cmd" to "yt-dlp", download speed will be greatly improved.

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

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

Additionally, if Text::Unidecode is available, then Unicode characters are converted to ASCII equivalents.

  features
A list of video features, return only videos with the specified features:

    live               # Live stream
    4k                 # 4K resolution
    hd                 # HD resolution (>=720p)
    subtitles          # Video has subtitles/closed-captions
    creative_commons   # Creative Commons license
    360                # 360° field of view
    vr180              # Stereoscopic widh a 180° field of view
    3d                 # 3D
    hdr                # High dynamic range

  ffmpeg_cmd
Path to the "ffmpeg" program.

  force_fallback
Force the extraction of the streaming URLs to always use the fallback method (youtube-dl / invidious).

  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
Prefer or ignore High Frame Rate (HFR) video streams.

Try to disable this option if the videos are lagging or dropping frames.

  highlight_color
Highlight color used to highlight watched videos.

Any color name 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 oldest half of the history file will be deleted.

For no limit, set the value to -1.

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

For example, to use Tor, install LWP::Protocol::socks and set this value to:

    "socks://127.0.0.1:9050"

  ignore_av1
Ignore videos in AV1 format.

  ignored_projections
An array of video projections to ignore.

For example, to prefer rectangular projections of 360° videos, use:

    ignored_projections => ["mesh", "equirectangular"],

  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.

  local_playlist_limit
When set to a positive value, will restrict the size of the local playlists to this many entries. When this limit has been reached, older entries will be discarded from the playlist.

A reasonable value would be between 500 and 1000.

For no limit, set the value to -1.

  maxResults
How many results to display per page.

Currently, this is not implemented.

  merge_into_mkv
When downloading split videos, 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: "relevance", "rating", "upload_date", "view_count".

  page
Page number of results.

  prefer_av1
Prefer videos in AV1 format. (experimental)

  prefer_mp4
Prefer videos in MP4 (AVC) format.

Try to enable this option if the videos are lagging or dropping frames.

  prefer_m4a
Prefer audio streams in M4A (AAC) format.

By default, the OPUS format for audio is preferred.

  prefer_invidious
Prefer invidious instances over parsing the YouTube website directly.

  region
ISO 3166 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.

  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.

  skip_youtube_extraction
If enabled, the application will not extract direct video/audio URLs from YouTube. Instead, it will pass the original YouTube page URL to the media player (e.g., mpv, VLC), letting the player handle extraction. This can be usefull for avoiding slow double extraction.

  split_videos
Enable or disable support for split-videos. Split-videos are videos that do not include audio and video in the same file.

Disable this option if the videos are loading too slowly, as non-split videos are not throttled by YouTube. Although, the highest resolution of non-split videos is 360p.

  srt_languages
List of SRT languages in the order of preference.

  saved_channels_file
Absolute path to the file where to store saved channels (":save=i").

  set_mtime
When enabled, it will set the original modification date of a downloaded video, using the published date of the video.

  subscribed_channels_file
Absolute path to the file where to store subscribed channels (":sub=i").

  subscription_results
Comma-separated list of methods used to retrieve videos from subscribed channels.

    subscription_results => "uploads,streams",   # include streams in feed

Valid values: uploads, streams, shorts.

  subscriptions_lifetime
Amount of time, in seconds, before rescanning the subscribed channels for new videos (during "-ls").

  subscriptions_limit
Maximum number of subscription videos to store in the local database. Set to 0 for no limit.

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

  max_retries
Maximum number of retry attempts for failed network requests (default: 3). Applies to both GET and POST requests, including thumbnails, API calls, and video data fetching.

  retry_delay
Initial delay in seconds between retry attempts (default: 1). Uses exponential backoff: 1s → 2s → 4s → 8s (capped at 30s) with jitter.

  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
Format string used for creating the filename of downloaded videos.

The available special tokens are listed in:

    pipe-viewer --tricks

  video_player_selected
The selected video player defined in 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

  videoDuration
Retrieve only short or long videos in search results.

Valid values: "any", "short" (under 4 minutes), "average" (4-20 minutes), and "long" (over 20 minutes).

  watch_history
Set to 1 to remember and highlight watched videos across multiple sessions.

Watched videos can be listed with:

    pipe-viewer -wv

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

  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_video_url
Format for sprintf() for constructing an YouTube video URL given the video ID.

  youtube_channel_url
Format for sprintf() for constructing an YouTube channel URL given the channel ID.

  youtube_playlist_url
Format for sprintf() for constructing an YouTube playlist URL given the playlist ID.

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

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

  ytdl_cmd
Command for "yt-dlp" or "youtube-dl" when "ytdl" is set to 1.

Also command for "yt-dlp" for extracting YouTube comments when "ytdlp_comments" is set to 1.

  ytdlp_comments
When set to 1, use "yt-dlp" for extracting YouTube comments. (experimental)

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

  ytdlp_max_comments
Maximum number of comments to extract with "yt-dlp".

Replies count as comments.

  ytdlp_max_replies
Maximum number of replies per thread.

Use 0 to disable replies.

Use "all" to extract all replies.

CONFIGURATION FILES
The configuration files are:

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

INVIDIOUS API REFERENCE
https://github.com/iv-org/invidious/wiki/API

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

LICENSE AND COPYRIGHT
Copyright 2010-2026 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.