YOUTUBE-VIEWER(1)

📦
version 3.11.6 · 2 versions
, in alpine 3.24

💖 NAME 💖

okay so welcome to youtube-viewer(1) — it's literally YouTube, but make it command line 👑 no browser, no ads, no vibe-killing algorithm sidebar, just you and your terminal being iconic together.

youtube-viewer — YouTube from command line. that's it, that's the whole pitch 💅

and bestie, there's a whole help ecosystem, so peek at these whenever you're lost:

youtube-viewer --help
youtube-viewer --tricks
youtube-viewer --examples
youtube-viewer --stdin-help

🎀 CONFIGURATION OPTIONS 🎀

these are all the config keys, and yes there are a lot of them. don't panic. we go one by one, hand in hand 🫶

  • auto_captions — set this to 1 and auto-generated captions get retrieved. by default? auto-generated captions are ignored, no cap.
  • audio_quality — your preferred quality for the audio-track, and the valid values are:
best        # best audio quality available (<=192kbps)
medium      # medium audio quality (<=128kbps)
low         # low audio quality (<=50kbps)

you can also set it to a numeric value N, which selects an audio-track with <= Nkbps ✨

  • autoplay_mode — turns on autoplay mode, which will continuously play related videos. she just keeps going 💀
  • bypass_age_gate_native — bypasses age-restricted videos using the internal method 🔥
but lowkey these streaming URLs are heavily throttled by YouTube, so manage your expectations.

when this option is disabled, a fallback method gets used instead (yt-dlp/youtube-dl or invidious instances).

  • bypass_age_gate_with_proxy — bypasses age-restricted videos using a YouTube Account Proxy.
  • cache_dir — the cache directory, i.e. where to save temporary files.
  • colors — use colors for text 🌈 yes obviously.
  • comments_order — the sorting order for comments. valid values: time, relevance.
  • confirm — shows a confirmation message after each video played.
  • convert_cmd — the command used to convert videos. default value is:
"ffmpeg -i *IN* *OUT*"

*IN* gets replaced with the input file.

*OUT* gets replaced with the output file.

  • convert_to — the format each downloaded video gets converted into (e.g.: mp3).
  • cookie_file — load cookies from a file. super useful for overcoming that 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. save yourself the step 🎀

  • custom_layout_format — an array of hash values specifying a custom layout for video results, and the keys are:
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 a percentage of the terminal width (e.g.: "15%").

the special tokens for text are listed in:

youtube-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_segmented — include or exclude streams in Dynamic Adaptive Streaming over HTTP (DASH) format.
  • debug — enables debug/verbose mode, which prints some extra information.

valid values: 0, 1, 2, 3.

  • download_and_play — play downloaded videos.
  • 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. basically free speed, take it.

  • downloads_dir — the directory where downloaded files go, and where converted files get saved.
  • download_in_subdir — downloads videos in a new subdirectory inside the downloads_dir parent directory.

when enabled, videos get saved inside a subdirectory specified by download_in_subdir_format.

  • download_in_subdir_format — the format string used for creating that subdirectory where files get downloaded, whenever download_in_subdir is enabled.

the available special tokens are listed in:

pipe-viewer --tricks
and yes, it literally says pipe-viewer up there, not youtube-viewer — that's verbatim from the page, don't come for me 🙈
  • env_proxy — load proxy settings from *_proxy environment variables (if any).
  • fat32safe — when downloading a video, makes the filename compatible with the FAT32 filesystem.

additionally, if Text::Unidecode is available, then Unicode characters get converted to ASCII equivalents. cute and practical 💅

  • ffmpeg_cmd — path to the ffmpeg program.
  • force_fallback — forces the extraction of the streaming URLs to always use the fallback method (youtube-dl / invidious).
  • fullscreen — play videos in fullscreen mode. main character energy, obviously.
  • 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 disabling this option if the videos are lagging or dropping frames 😭
  • highlight_color — the 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 — the file where input history gets saved.
  • history_limit — the maximum number of entries in the history file.

when the limit is reached, the first half of the history file gets deleted.

set the value to -1 for no limit at all, go feral 🦋

  • hl — language code for categories. default: en_US.
  • http_proxy — sets the 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 gets 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 on how to merge the files.
  • merge_with_captions — include closed-captions inside the MKV container (if any).
  • order — the 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.

(that "Sory" up there is straight from the page, bestie — verbatim, I promise 💀)

  • page — page number of results.
  • prefer_av1 — prefer videos in AV1 format. (just for testing)
  • prefer_mp4 — prefer videos in MP4 (AVC) format.
try enabling 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.

  • 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 — the preferred resolution for videos.

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

  • safeSearch — the safeSearch option indicates whether the search results should include restricted content as well as standard content.

valid values: strict, moderate, none.

  • set_mtime — when enabled, it sets the original modification date of a downloaded video, using the published date of the video ✨
  • show_video_info — show extra info for videos when they're selected.
  • skip_if_exists — when downloading, skip if the file already exists locally.
  • skip_watched — skip already watched/downloaded videos.
  • 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, because non-split videos are not throttled by YouTube. although… the highest resolution of non-split videos is 360p. pick your fighter 💀
  • srt_languages — list of SRT languages in the order of preference.
  • subscriptions_order — the sorting order for subscriptions.

valid values:

alphabetical – Sort alphabetically.
relevance    – Sort by relevance.
unread       – Sort by order of activity.
  • subscription_videos_per_channel — how many recent videos to fetch from each channel in local subscription videos (-ls).

valid values are between 1 and 50.

  • thousand_separator — the thousands separator character for numbers >= 1000.
  • timeout — the HTTPS timeout value in seconds. the default value is 10 seconds.
  • user_agent — the token that's used to identify the user agent on the network. the agent value gets sent as the User-Agent header in the requests.
  • video_filename_format — the format string used for creating the filename of downloaded videos.

the available special tokens are listed in:

youtube-viewer --tricks
  • video_min_seconds — filters out from results videos with less than video_min_seconds seconds.
  • video_player_selected — the selected video player, as 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
  • 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:

hang tight, bestie — part 2 is literally loading… 🦋

  • any — returns literally every video, no matter the resolution 💅
  • high — only pulls the HD ones ✨
  • standard — only the standard-definition girlies 🎀

videoDimension

Okay so videoDimension is your 3D-or-not filter for searches. It's giving "I only want flat videos" or "give me the depth, bestie."

The valid values are:

  • 2d — restricts results so 3D videos are excluded entirely.
  • 3d — restricts results so only 3D videos show up. main character 3D energy 👑
  • any — includes both the 3D and the non-3D videos in the results.

videoDuration

The videoDuration parameter filters your video search results by how long the videos are. Very "I have 4 minutes before class" of it, honestly.

Valid values: any, short, long. (And then the page lists the full menu again, iconic of it 💀 — here's the whole thing:)

  • any — does not filter your search results by duration at all.
  • long — only includes videos longer than 20 minutes.
  • medium — only includes videos that are between 4-20 minutes.
  • short — only includes videos that are less than 4 minutes long.

videoLicense

videoLicense filters your search results so you only get videos rockin' a particular license.

The valid values:

  • any — all the videos, no matter which license they're carrying.
  • creativeCommon — only returns videos with a "Creative Commons" license 🫶
  • youtube — only returns videos with the standard YouTube license.

videoSyndicated

videoSyndicated lets you restrict a search to only the videos that can actually be played outside of youtube.com. So like, the ones allowed to travel 🦋

Valid values:

  • any — returns all videos, syndicated or not.
  • true — only retrieves the syndicated ones.

watch_history

Remember the videos you've watched across multiple sessions. Memory queen behavior 🧠✨

The video IDs get saved in the filename you specify with watch_history_file.

Heads up bestie: this option is also required for --watched-videos. No history, no watched-videos list, that's the deal 💅

watch_history_file

The file where the video IDs of your watched/downloaded videos get saved, but only when watch_history is set to a true value. It's the lil storage spot for your receipts 📁

wget_cmd

The command that gets used for wget, but only when download_with_wget is set to a true value.

youtube_users_file

Path to a list of YouTube channels, using this format:

ChannelID NAME

And you can list those channels with the command-line option -fc 😌

youtube_video_url

The format for sprintf() used for constructing a YouTube video URL given the video ID. It's the lil URL blueprint, iykyk 🔗

ytdl

Use youtube-dl for videos with encrypted signatures.

When it's set to 0, invidious instances get used instead. Two totally different vibes, pick your fighter ✨

ytdl_cmd

The command for yt-dlp or 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

Copyright 2010-2025 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.

And that's the whole page, bestie, we ate that 🍓💜 Quick sign-off for the record: this beauty's running on perl v5.42.2, dated 2026-02-15, and it's page YOUTUBE-VIEWER(1) — periodt 💅✨

📦 where this page comes from