.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PIPE-VIEWER 1"
.TH PIPE-VIEWER 1 "2025-05-08" "perl v5.34.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
pipe\-viewer \- YouTube from command line.
.PP
.Vb 4
\&     pipe\-viewer \-\-help
\&     pipe\-viewer \-\-tricks
\&     pipe\-viewer \-\-examples
\&     pipe\-viewer \-\-stdin\-help
.Ve
.SH "CONFIGURATION OPTIONS"
.IX Header "CONFIGURATION OPTIONS"
.SS "api_host"
.IX Subsection "api_host"
Hostname of an invidious instance. When set to \f(CW"auto"\fR, a random invidious instance is selected on-demand.
.PP
List of public invidious instances:
.PP
.Vb 1
\&    https://api.invidious.io/
.Ve
.PP
Tor instances are also supported if the \f(CW\*(C`socks5://127.0.0.1:9050\*(C'\fR Tor proxy is available and the Perl module LWP::Protocol::socks is installed.
.SS "auto_captions"
.IX Subsection "auto_captions"
When set to \f(CW1\fR, auto-generated captions will be retrieved. By default, auto-generated captions are ignored.
.SS "audio_quality"
.IX Subsection "audio_quality"
The preferred quality for the audio-track:
.PP
.Vb 3
\&    best        # best audio quality available (<=192kbps)
\&    medium      # medium audio quality (<=128kbps)
\&    low         # low audio quality (<=50kbps)
.Ve
.PP
The option can also be set to a numeric value N in order to select an audio-track with <= Nkbps.
.SS "autoplay_mode"
.IX Subsection "autoplay_mode"
Enable autoplay mode, which will continuously play related videos.
.SS "bypass_age_gate_native"
.IX Subsection "bypass_age_gate_native"
Bypass age-restricted videos, using our internal method.
.PP
However, these streaming URLs are heavily throttled by YouTube.
.PP
When this option is disabled, a fallback method will be used instead (\f(CW\*(C`yt\-dlp\*(C'\fR/\f(CW\*(C`youtube\-dl\*(C'\fR or invidious instances).
.SS "bypass_age_gate_with_proxy"
.IX Subsection "bypass_age_gate_with_proxy"
Bypass age-restricted videos using an YouTube Account Proxy.
.SS "cache_dir"
.IX Subsection "cache_dir"
Cache directory where to save temporary files.
.SS "colors"
.IX Subsection "colors"
Use colors for text.
.SS "comments_order"
.IX Subsection "comments_order"
The sorting order for comments. Valid values: \*(L"top\*(R", \*(L"new\*(R".
.SS "confirm"
.IX Subsection "confirm"
Display a confirmation message after each video played.
.SS "convert_cmd"
.IX Subsection "convert_cmd"
Command to convert videos.
.PP
Default value:
.PP
.Vb 1
\&    "ffmpeg \-i *IN* *OUT*"
.Ve
.PP
\&\fB*IN*\fR gets replaced with the input file.
.PP
\&\fB*OUT*\fR gets replaced with the output file.
.SS "convert_to"
.IX Subsection "convert_to"
Format to convert each downloaded video into. (e.g.: \f(CW"mp3"\fR).
.SS "cookie_file"
.IX Subsection "cookie_file"
Load cookies from a file. Useful to overcome the \*(L"429: Too Many Requests\*(R" issue.
.PP
The file must be a \f(CW\*(C`# Netscape HTTP Cookie File\*(C'\fR. Same format as \f(CW\*(C`youtube\-dl\*(C'\fR requires.
.PP
See also:
.PP
.Vb 1
\&    https://github.com/ytdl\-org/youtube\-dl#how\-do\-i\-pass\-cookies\-to\-youtube\-dl
.Ve
.SS "copy_caption"
.IX Subsection "copy_caption"
When downloading a video, copy the closed-caption (if any) into the same folder with the video.
.PP
If \f(CW\*(C`merge_into_mkv\*(C'\fR and \f(CW\*(C`merge_with_captions\*(C'\fR are both enabled, there is no need to enable this option.
.SS "custom_layout_format"
.IX Subsection "custom_layout_format"
An array of hash values specifying a custom layout for video results.
.PP
.Vb 4
\&    align       # "left" or "right"
\&    color       # any color name supported by Term::ANSIColor
\&    text        # the actual text
\&    width       # width allocated for the text
.Ve
.PP
The value for \f(CW\*(C`width\*(C'\fR can be either a number of characters (e.g.: 20) or can be a percentage of the terminal width (e.g.: \*(L"15%\*(R").
.PP
The special tokens for \f(CW\*(C`text\*(C'\fR are listed in:
.PP
.Vb 1
\&    pipe\-viewer \-\-tricks
.Ve
.PP
For better formatting, it's highly recommended to install Unicode::GCString or Text::CharWidth.
.SS "custom_channel_layout_format"
.IX Subsection "custom_channel_layout_format"
An array of hash values specifying a custom layout for channel results.
.SS "custom_playlist_layout_format"
.IX Subsection "custom_playlist_layout_format"
An array of hash values specifying a custom layout for playlist results.
.SS "dash"
.IX Subsection "dash"
Include or exclude streams in \*(L"Dynamic Adaptive Streaming over \s-1HTTP\*(R"\s0 (\s-1DASH\s0) format.
.SS "date"
.IX Subsection "date"
Search for videos uploaded within a specific amount of time.
.PP
Valid values: \*(L"anytime\*(R", \*(L"hour\*(R", \*(L"today\*(R", \*(L"week\*(R", \*(L"month\*(R", \*(L"year\*(R".
.SS "debug"
.IX Subsection "debug"
Enable debug/verbose mode, which will print some extra information.
.PP
Valid values: 0, 1, 2, 3.
.SS "downloads_dir"
.IX Subsection "downloads_dir"
Directory where to download files and where to save converted files.
.SS "download_and_play"
.IX Subsection "download_and_play"
Play downloaded videos.
.SS "download_in_subdir"
.IX Subsection "download_in_subdir"
Download videos in a new subdirectory inside the \f(CW\*(C`downloads_dir\*(C'\fR parent directory.
.PP
When enabled, videos will be saved inside a subdirectory specified by \f(CW\*(C`download_in_subdir_format\*(C'\fR.
.SS "download_in_subdir_format"
.IX Subsection "download_in_subdir_format"
Format string used for creating the subdirectory where to download the files, when \f(CW\*(C`download_in_subdir\*(C'\fR is enabled.
.PP
The available special tokens are listed in:
.PP
.Vb 1
\&    pipe\-viewer \-\-tricks
.Ve
.SS "download_with_wget"
.IX Subsection "download_with_wget"
Download videos with \f(CW\*(C`wget\*(C'\fR.
.SS "download_with_ytdl"
.IX Subsection "download_with_ytdl"
Download videos with `yt\-dlp` or `youtube\-dl`.
.PP
By enabling this option and setting the value of \f(CW\*(C`ytdl_cmd\*(C'\fR to \f(CW"yt\-dlp"\fR, download speed will be greatly improved.
.SS "env_proxy"
.IX Subsection "env_proxy"
Load proxy settings from \f(CW*_proxy\fR environment variables (if any).
.SS "fat32safe"
.IX Subsection "fat32safe"
When downloading a video, make the filename compatible with the \s-1FAT32\s0 filesystem.
.PP
Additionally, if Text::Unidecode is available, then Unicode characters are converted to \s-1ASCII\s0 equivalents.
.SS "features"
.IX Subsection "features"
A list of video features, return only videos with the specified features:
.PP
.Vb 9
\&    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
.Ve
.SS "ffmpeg_cmd"
.IX Subsection "ffmpeg_cmd"
Path to the \f(CW\*(C`ffmpeg\*(C'\fR program.
.SS "force_fallback"
.IX Subsection "force_fallback"
Force the extraction of the streaming URLs to always use the fallback method (youtube-dl / invidious).
.SS "fullscreen"
.IX Subsection "fullscreen"
Play videos in fullscreen mode.
.SS "get_captions"
.IX Subsection "get_captions"
Download closed-captions for videos (if any).
.SS "get_term_width"
.IX Subsection "get_term_width"
Read the terminal width (`stty size`).
.SS "hfr"
.IX Subsection "hfr"
Prefer or ignore High Frame Rate (\s-1HFR\s0) video streams.
.PP
Try to disable this option if the videos are lagging or dropping frames.
.SS "highlight_color"
.IX Subsection "highlight_color"
Highlight color used to highlight watched videos.
.PP
Any color name supported by Term::ANSIColor can be used.
.SS "highlight_watched"
.IX Subsection "highlight_watched"
Highlight watched videos.
.SS "history"
.IX Subsection "history"
Enable or disable support for input history.
.PP
Requires Term::ReadLine::Gnu.
.SS "history_file"
.IX Subsection "history_file"
File where to save the input history.
.SS "history_limit"
.IX Subsection "history_limit"
Maximum number of entries in the history file.
.PP
When the limit is reached, the oldest half of the history file will be deleted.
.PP
For no limit, set the value to \f(CW\*(C`\-1\*(C'\fR.
.SS "http_proxy"
.IX Subsection "http_proxy"
Set \s-1HTTP\s0(S)/SOCKS proxy, using the format:
.PP
.Vb 1
\&    \*(Aqproto://domain.tld:port/\*(Aq
.Ve
.PP
If authentication is required, use:
.PP
.Vb 1
\&    \*(Aqproto://user:pass@domain.tld:port/\*(Aq
.Ve
.PP
For example, to use Tor, install LWP::Protocol::socks and set this value to:
.PP
.Vb 1
\&    "socks://127.0.0.1:9050"
.Ve
.SS "ignore_av1"
.IX Subsection "ignore_av1"
Ignore videos in \s-1AV1\s0 format.
.SS "ignored_projections"
.IX Subsection "ignored_projections"
An array of video projections to ignore.
.PP
For example, to prefer rectangular projections of 360° videos, use:
.PP
.Vb 1
\&    ignored_projections => ["mesh", "equirectangular"],
.Ve
.SS "interactive"
.IX Subsection "interactive"
Interactive mode, prompting for user-input.
.SS "keep_original_video"
.IX Subsection "keep_original_video"
Keep the original video after conversion. When set to \f(CW0\fR, the original video will be deleted.
.SS "local_playlist_limit"
.IX Subsection "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.
.PP
A reasonable value would be between 500 and 1000.
.PP
For no limit, set the value to \f(CW\*(C`\-1\*(C'\fR.
.SS "maxResults"
.IX Subsection "maxResults"
How many results to display per page.
.PP
Currently, this is not implemented.
.SS "merge_into_mkv"
.IX Subsection "merge_into_mkv"
When downloading split videos, merge the audio+video files into an \s-1MKV\s0 container.
.PP
Requires \f(CW\*(C`ffmpeg\*(C'\fR.
.SS "merge_into_mkv_args"
.IX Subsection "merge_into_mkv_args"
Arguments for \f(CW\*(C`ffmpeg\*(C'\fR how to merge the files.
.SS "merge_with_captions"
.IX Subsection "merge_with_captions"
Include closed-captions inside the \s-1MKV\s0 container (if any).
.SS "order"
.IX Subsection "order"
Search order for videos.
.PP
Valid values: \*(L"relevance\*(R", \*(L"rating\*(R", \*(L"upload_date\*(R", \*(L"view_count\*(R".
.SS "page"
.IX Subsection "page"
Page number of results.
.SS "prefer_av1"
.IX Subsection "prefer_av1"
Prefer videos in \s-1AV1\s0 format. (experimental)
.SS "prefer_mp4"
.IX Subsection "prefer_mp4"
Prefer videos in \s-1MP4\s0 (\s-1AVC\s0) format.
.PP
Try to enable this option if the videos are lagging or dropping frames.
.SS "prefer_m4a"
.IX Subsection "prefer_m4a"
Prefer audio streams in M4A (\s-1AAC\s0) format.
.PP
By default, the \s-1OPUS\s0 format for audio is preferred.
.SS "prefer_invidious"
.IX Subsection "prefer_invidious"
Prefer invidious instances over parsing the YouTube website directly.
.SS "region"
.IX Subsection "region"
\&\s-1ISO 3166\s0 country code (default: \*(L"\s-1US\*(R"\s0).
.SS "remove_played_file"
.IX Subsection "remove_played_file"
When \f(CW\*(C`download_and_play\*(C'\fR is enabled, remove the file after playing it.
.SS "resolution"
.IX Subsection "resolution"
Preferred resolution for videos.
.PP
Valid values: best, 2160p, 1440p, 1080p, 720p, 480p, 360p, 240p, 144p, audio.
.SS "show_video_info"
.IX Subsection "show_video_info"
Show extra info for videos when selected.
.SS "skip_if_exists"
.IX Subsection "skip_if_exists"
When downloading, skip if the file already exists locally.
.SS "skip_watched"
.IX Subsection "skip_watched"
Skip already watched/downloaded videos.
.SS "split_videos"
.IX Subsection "split_videos"
Enable or disable support for split-videos. Split-videos are videos that do not include audio and video in the same file.
.PP
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.
.SS "srt_languages"
.IX Subsection "srt_languages"
List of \s-1SRT\s0 languages in the order of preference.
.SS "saved_channels_file"
.IX Subsection "saved_channels_file"
Absolute path to the file where to store saved channels (\f(CW\*(C`:save=i\*(C'\fR).
.SS "set_mtime"
.IX Subsection "set_mtime"
When enabled, it will set the original modification date of a downloaded video, using the published date of the video.
.SS "subscribed_channels_file"
.IX Subsection "subscribed_channels_file"
Absolute path to the file where to store subscribed channels (\f(CW\*(C`:sub=i\*(C'\fR).
.SS "subscription_results"
.IX Subsection "subscription_results"
Comma-separated list of methods used to retrieve videos from subscribed channels.
.PP
.Vb 1
\&    subscription_results => "uploads,streams",   # include streams in feed
.Ve
.PP
Valid values: uploads, streams, shorts.
.SS "subscriptions_lifetime"
.IX Subsection "subscriptions_lifetime"
Amount of time, in seconds, before rescanning the subscribed channels for new videos (during \f(CW\*(C`\-ls\*(C'\fR).
.SS "subscriptions_limit"
.IX Subsection "subscriptions_limit"
Maximum number of subscription videos to store in the local database. Set to \f(CW0\fR for no limit.
.SS "thousand_separator"
.IX Subsection "thousand_separator"
Thousands separator character for numbers >= 1000.
.SS "timeout"
.IX Subsection "timeout"
\&\s-1HTTPS\s0 timeout value in seconds. The default value is 10 seconds.
.SS "user_agent"
.IX Subsection "user_agent"
Token that is used to identify the user agent on the network. The agent value is sent as the \f(CW\*(C`User\-Agent\*(C'\fR header in the requests.
.SS "video_filename_format"
.IX Subsection "video_filename_format"
Format string used for creating the filename of downloaded videos.
.PP
The available special tokens are listed in:
.PP
.Vb 1
\&    pipe\-viewer \-\-tricks
.Ve
.SS "video_player_selected"
.IX Subsection "video_player_selected"
The selected video player defined in the \f(CW\*(C`video_players\*(C'\fR table.
.SS "video_players"
.IX Subsection "video_players"
A table of video players.
.PP
The keys for each player are:
.PP
.Vb 6
\&    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
.Ve
.SS "videoDuration"
.IX Subsection "videoDuration"
Retrieve only short or long videos in search results.
.PP
Valid values: \*(L"any\*(R", \*(L"short\*(R" (under 4 minutes), \*(L"average\*(R" (4\-20 minutes), and \*(L"long\*(R" (over 20 minutes).
.SS "watch_history"
.IX Subsection "watch_history"
Set to \f(CW1\fR to remember and highlight watched videos across multiple sessions.
.PP
Watched videos can be listed with:
.PP
.Vb 1
\&    pipe\-viewer \-wv
.Ve
.PP
The video IDs are saved in the filename specified by \f(CW\*(C`watch_history_file\*(C'\fR.
.SS "watch_history_file"
.IX Subsection "watch_history_file"
File where to save the video IDs of watched/downloaded videos when \f(CW\*(C`watch_history\*(C'\fR is set to a true value.
.SS "wget_cmd"
.IX Subsection "wget_cmd"
Command for \f(CW\*(C`wget\*(C'\fR when \f(CW\*(C`download_with_wget\*(C'\fR is set to a true value.
.SS "youtube_video_url"
.IX Subsection "youtube_video_url"
Format for \f(CW\*(C`sprintf()\*(C'\fR for constructing an YouTube video \s-1URL\s0 given the video \s-1ID.\s0
.SS "youtube_channel_url"
.IX Subsection "youtube_channel_url"
Format for \f(CW\*(C`sprintf()\*(C'\fR for constructing an YouTube channel \s-1URL\s0 given the channel \s-1ID.\s0
.SS "youtube_playlist_url"
.IX Subsection "youtube_playlist_url"
Format for \f(CW\*(C`sprintf()\*(C'\fR for constructing an YouTube playlist \s-1URL\s0 given the playlist \s-1ID.\s0
.SS "ytdl"
.IX Subsection "ytdl"
Use \f(CW\*(C`youtube\-dl\*(C'\fR for videos with encrypted signatures.
.PP
When set to \f(CW0\fR, invidious instances will be used instead.
.SS "ytdl_cmd"
.IX Subsection "ytdl_cmd"
Command for \f(CW\*(C`yt\-dlp\*(C'\fR or \f(CW\*(C`youtube\-dl\*(C'\fR when \f(CW\*(C`ytdl\*(C'\fR is set to \f(CW1\fR.
.PP
Also command for \f(CW\*(C`yt\-dlp\*(C'\fR for extracting YouTube comments when \f(CW\*(C`ytdlp_comments\*(C'\fR is set to \f(CW1\fR.
.SS "ytdlp_comments"
.IX Subsection "ytdlp_comments"
When set to \f(CW1\fR, use \f(CW\*(C`yt\-dlp\*(C'\fR for extracting YouTube comments. (experimental)
.PP
When set to \f(CW0\fR, invidious instances will be used instead.
.SS "ytdlp_max_comments"
.IX Subsection "ytdlp_max_comments"
Maximum number of comments to extract with \f(CW\*(C`yt\-dlp\*(C'\fR.
.PP
Replies count as comments.
.SS "ytdlp_max_replies"
.IX Subsection "ytdlp_max_replies"
Maximum number of replies per thread.
.PP
Use \f(CW0\fR to disable replies.
.PP
Use \f(CW"all"\fR to extract all replies.
.SH "CONFIGURATION FILES"
.IX Header "CONFIGURATION FILES"
The configuration files are:
.PP
.Vb 2
\&    ~/.config/pipe\-viewer/pipe\-viewer.conf
\&    ~/.config/pipe\-viewer/gtk\-pipe\-viewer.conf
.Ve
.SH "INVIDIOUS API REFERENCE"
.IX Header "INVIDIOUS API REFERENCE"
https://github.com/iv\-org/invidious/wiki/API
.SH "REPOSITORY"
.IX Header "REPOSITORY"
https://github.com/trizen/pipe\-viewer
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright 2010\-2025 Trizen.
.PP
This program is free software; you can redistribute it and/or modify it
under the terms of either: the \s-1GNU\s0 General Public License as published
by the Free Software Foundation; or the Artistic License.
.PP
This program is distributed in the hope that it will be useful,
but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0
.PP
See <https://dev.perl.org/licenses/> for more information.