📺 yt-x

Browse YouTube and other yt-dlp supported sites directly from your terminal or app launcher.

View Demos & Previews

Full Demo:

yt-x-full-github-demo.webm

Riced/Customized Previews:

Table of Contents

• Features
• Installation
  • Prerequisites
  • Universal Installation
  • Platform-Specific Instructions
• Usage
  • Quick Start
  • Command-Line Options
  • Inline Search Syntax & Filters
  • Environment Variables
  • Examples & Workflows
• Configuration
  • Configuration File Location
  • Configuration Variables
• Extensions
  • Official Extensions
• Frequently Asked Questions (FAQ)
• Contribution
• Support

Features

• Multiple Launcher Support: with fzf, rofi all supporting previews
• Search For Media: videos, playlists, channels, shorts or movies.
• Search Filters: Apply colon-prefixed quick filters directly to search queries:
  • Time: :hour, :today, :week, :month, :year
  • Type: :video, :movie, :live, :short, :long
  • Features: :4k, :hd, :hdr, :subtitles, :360, :vr, :3d, :local
  • Sort by: :newest, :views, :rating
• Search History & Recall: Automatically saves search history. Allows quick recall of previous searches using bang syntax (e.g., !1 for the most recent search, !2 for the second, etc.).
• YouTube Feeds: Access personal feeds including the Home Feed, Trending, Watch Later, Liked Videos, Watch History, and Clips.
• Channel Browsing: access a channel's Videos, Featured content, Playlists, Shorts, Live Streams, Podcasts, and search pages.
• Customizable Menus: Reorder, add, or filter out menu entries using .ui extensions
• Theming & Styling: theming support through .theme extensions with tokyo night as the default theme.
• Multi-language Support: Loadable language files (.lang) to easily localize the UI prompts and messages(currently es and br. Contributions for additional languages are welcome.
• Pagination: browse through massive lists with Next/Previous pagination controls (default is 30).
• scriptable Shortcuts: Bypass menus and jump straight to specific feeds, searches, or actions using direct command-line flags . See usage
• Multiple Player Support: with mpv, vlc, and tplay.
• Playlist Actions: Play individual videos, queue/play entire playlists, or queue "Listen to All" for audio-only
• Auto-Mix Generation: Dynamically generates .m3u8 playlist mixes based on a single video (YouTube "Mix" feature replication).
• Background Playback: Option to disown the media player process (CONFIG_DISOWN_PLAYER)
• Granular Downloads: Download single videos, entire playlists, or extract audio-only (MP3 format).
• Smart Archiving: Utilizes a download archive directory(yt-dlp's --download-archive opt) to track previously downloaded media and prevent duplicate downloads.
• Organized File Structure: Automatically routes downloads into structured directories (e.g., video/individual/ChannelName/ or audio/PlaylistName/ChannelName/).
• Enumeration Toggle: Easily toggle file prefix enumeration (01 -, 02 -) to keep downloaded playlist items in order.
• Local Subscriptions Sync: Syncs your actual YouTube subscriptions locally by passing browser cookies to yt-dlp
• Local Watch History (Recent): Automatically tracks recently watched media in a local JSON file to resume or re-watch easily.
• Saved Videos & Playlists: Create local "Saved Videos" and "Custom Playlists for watching later without having to download them
• Browser Cookies: optionally configure a browser (CONFIG_BROWSER passes to yt-dlp's --cookies-from-browser) to access age-restricted or account-specific content.
• Custom Commands: Create custom cmds that execute specific URLs and yt-dlp options (e.g., setting up a command to browse a completely different streaming site that yt-dlp supports).
• Extensions: extend yt-x with custom scripts, sites, themes, and commands placed in $HOME/.config/yt-x/extensions/.
• Stateful Sub-Shell Execution: Drop into a shell pre-loaded with the environment variables of your current session (current video title, URL, channel info, etc.) for custom scripting
• Desktop Integration: generate a .desktop file, to be launched natively from application menus (Linux).
• Cache Management: Automatically cleans up stale preview images, auto-generated playlists, and logs older than a set period (Default: 3 days)
• OS Support: Works across Linux, macOS, Windows (via WSL/MSYS/Cygwin), and Android (uses am start intents to open media natively in Android apps like VLC or MPV).
• Auto-Updater: update checker that securely pulls the latest version from GitHub and shows you the changes diff so you can decide whether to apply the update or not.
• Shell Completions: currently supports for fish shell with tab complete for some options (e.g., channel names, custom cmd names, etc.), Contributions for bash and zsh completions are welcome.

Installation

Prerequisites

Required:

• yt-dlp - For fetching the data and downloading media.
• fzf - Main launcher
• jq - For parsing json
• curl - For fetching script updates and preview images. (version 7.6+; that supports --parallel downloads)
• sh - Any POSIX-compliant shell (Bash, Zsh, Dash, etc.).
• Nerd Font - For the icons (Recommended JetBrains Mono Nerd Font).

Optional:

• Media Players: mpv (default), vlc, or tplay
• Modern Terminal That Supports True Color:
  • kitty personal favourite; started the great terminal era lol
  • ghostty
  • wezterm
• Terminal Image Viewers:
  • chafa (Cross-terminal)
  • icat (Recommended for Kitty and Ghostty)
  • imgcat (For iTerm2/WezTerm)
• Alternate Launcher: rofi (Great if you want a desktop app launcher, you could even keybind the command, its really cool).
• Terminal QoL:
  • gum (Better terminal ui; loaders, prompts etc).
  • bat to show update diffs in a nicer way

Universal Installation

Ensure ~/.local/bin exists and is added to your system's $PATH.

curl -sL "https://github.com/Benexl/yt-x/releases/download/v0.8.6/yt-x" -o ~/.local/bin/yt-x
chmod +x ~/.local/bin/yt-x

To uninstall ,just run: rm ~/.local/bin/yt-x, then to remove its related data folders rm -r ~/.config/yt-x and rm -r ~/.cache/yt-x.

Platform-Specific Instructions

Note am not the one who maintains any of this packages and you should probably turn off auto updates if using them

yay -S yt-x-git

# or if you prefer paru

paru -S yt-x-git

nix profile install github:Benexl/yt-x

inputs = {
  nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
  yt-x = {
    url = "github:Benexl/yt-x";
    inputs.nixpkgs.follows = "nixpkgs";
  };
}

Usage

You can opt to either us it via menus or cmdline shortcuts for purposes of scripting or keybinding

yt-x [OPTIONS]
yt-x [OPTIONS] channels [CHANNEL OPTIONS]
yt-x completions [--fish | --bash | --zsh | --help]

Quick Start

To launch the interactive terminal interface with your default settings, run:

yt-x

Command‑Line Options

Search

If you don't pass an argument to any of this options you will be prompted for the term

• -s, --search <term> : Immediately execute a video search and bypass the main menu. (supports search history completion)
• -sp, --search-playlist <term> : Immediately execute a playlist search.
• -sc, --search-channel <term> : Immediately execute a channel search.
• -ss, --search-short <term> : Immediately execute a short search.
• -sm, --search-movie <term> : Immediately execute a movie search.

Access saved items

The values must be exact to the ones in the respective json files, completions make this easy All of them support tab completion for the saved items

• -cp, --custom-playlist <name> : Open a specific custom playlist by its saved name
• -cc, --custom-cmd <name> : Execute a specific custom command by its saved name
• -sv, --saved-video <title> : Open a specific saved video by its title

Ui

• -l, --launcher <fzf|rofi> : Override the default menu launcher.
• --preview : Enable the preview window (images/text)
• --no-preview Disable the preview window
• --preview-images Enable the image preview
• --no-preview-images Disable the image preview
• -ce, --cmd-exit : Exit after shortcut menu command‑line options (useful for scripting).
• -ps, --playlist-skip : Skip the playlist selection menu and automatically pick the first entry in a playlist.
• -me, --media-exit : Exit after performing a media action (watch, listen, download, etc.).

Media Action Shortcuts (skip the media action menu)

All this options can be paired with --media-exit and after the media cmd is executed the cli terminates

• --play : Immediately watch the selected video (you still choose from the list).
• --play-all : Immediately play the whole playlist (implies --playlist-skip).
• --listen : Immediately listen to the audio of the selected video.
• --listen-all : Immediately listen to the whole playlist ( implies --playlist-skip).
• --download : Download the selected video.
• --download-all : Download the whole playlist (implies --playlist-skip).
• --download-audio : Download only the audio of the selected video.
• --download-audio-all : Download the whole playlist as audio (implies --playlist-skip).
• --save : Save the selected video to your local saved videos list so you can watch it later without needing to download it.
• --save-playlist : Save the current playlist to your custom playlists for the same reasons as above without needing an acc (implies --playlist-skip).
• --shell : Open a subshell with the current state variables. (you can use it run custom cmds on the results yt-x has gotten)

Player & Playback

• -p, --player <mpv|vlc|tplay> : Specify the media player
• --mpv-args : Pass custom mpv args at runtime
• --vlc-args : Pass custom vlc args at runtime
• --tplay-args : Pass custom tplay args at runtime
• --disown-player : Detach the player process from the terminal (allows you to keep browsing while watching).
• --no-disown-player : Keep the player attached to the terminal session (default).

Android specific

• --mpv-activity-name : Custom application activity name to launch when using mpv player
• --vlc-activity-name : Custom application activity name to launch when using vlc player

Direct Shortcuts (skip the main or miscellaneous menus)

All this options can be paired with --cmd-exit so that the start of the menus changes to the shortcuts so going back will exit the cli

• --feed : Open your personalised feed immediately.
• --subscriptions-feed : Open the subscriptions feed.
• --watch-later : Open your Watch Later playlist.
• --playlists : Browse saved YouTube playlists.
• --custom-playlists : Browse custom playlists you've saved.
• --saved : Open saved videos.
• --recent : Show recently watched videos.
• --liked : Open your Liked Videos playlist.
• --watch-history : Show your watch history.
• --clips : Browse your clips.
• --new-custom-cmd : Jump straight to creating a custom command.
• --custom-cmds : Execute an existing custom command.
• --search-history : Browse your search history.
• --edit-search-history : Edit the search history file.
• --edit-custom-playlists : Edit the custom playlists JSON file.
• --edit-mpv-config : Edit mpv’s configuration.
• --edit-yt-dlp-config : Edit yt‑dlp’s configuration.
• --edit-custom-cmds : Edit the custom commands JSON file.

Rofi

Note there are rofi themes in repo which you can use i customized them to make the experience just cool At least thats what i think you be the judge lol

• --rofi-theme-main <path>
• --rofi-theme-preview <path>
• --rofi-theme-prompt <path>
• --rofi-theme-confirm <path>
• --rofi-theme-pager <path>

Others

• -x, --extension <ext> : Load a specific extension file (absolute path or relative to ~/.config/yt-x/extensions/; supports fish tab complete).
• -e, --edit-config : Open the yt-x configuration file in your $EDITOR.
• -U, --update : Check for and apply the latest script update from GitHub.
• -E, --generate-desktop-entry : Print a .desktop application entry to stdout; its pretty cool esp with the rofi theme in github repo for example.
• -v, --version : Print version information and exit.
• -h, --help : Show the help message and exit.
• --config-write : Write the current runtime config to the config file

Channels Subcommand

Works only for subscribed to channels Its pretty useful for creating shortcuts and aliases to your favourite channels

yt-x [OPTIONS] channels [OPTIONS]

Options:

• -n, --name <channel> : Specify the channel name (exact match, case‑sensitive; tab complete supported).
• -s, --search <query> : Search within the channel’s uploads.
• -v, --videos : List the channel’s uploaded videos.
• -f, --featured : Show the channel’s featured playlists.
• -p, --playlists : List the channel’s playlists.
• -sh, --shorts : Show the channel’s shorts.
• -st, --streams : Show live streams & past broadcasts.
• -po, --podcasts : Show the channel’s podcasts.

Examples:

yt-x channels                                  # Pick from subscriptions interactively
yt-x channels -n "Linus Tech Tips" -v          # Browse latest videos
yt-x channels -n "iambenexl" -s "Top linux tools"   # Search inside a channel
yt-x channels -n "StarTalk" -p             # Show channel playlists
yt-x channels -n "The PrimeTime" -st            # Show channel streams
yt-x --cmd-exit channels -n 'freeCodeCamp.org' -p # Browse freecodecamp playlists and immediately exit on back
yt-x --cmd-exit channels -n 'freeCodeCamp.org' # useful for setting aliases eg a shortcut to always go to freecodecamp channel `freecodecamp`
yt-x --launcher rofi --cmd-exit channels -n 'freeCodeCamp.org' # or as an app eg  `freecodecamp-app`

Inline Search Syntax & Filters

When entering a search query (either via the -s flag or within the interactive prompt) Currently only one at a time is supported

• Time: :hour, :today, :week, :month, :year
• Format: :video, :movie, :live, :short, :long
• Quality/Features: :4k, :hd, :hdr, :360, :vr, :3d, :local, :subtitles
• Sorting: :newest, :views, :rating

Example: :4k pbs eons or at the end news :today

History Recall is also supported for both (Bang Syntax)

• !1 : Re‑run your most recent search.
• !2 : Re‑run your second most recent search, etc.

Environment Variables

Almost all CLI options can be permanently set in ~/.config/yt-x/config or overridden using environment variables.

• YT_X_LAUNCHER (e.g., fzf or rofi)
• YT_X_PLAYER (e.g., mpv)
• YT_X_ENABLE_PREVIEW (true or false)
• YT_X_ENABLE_PREVIEW_IMAGES (true or false)
• YT_X_IMAGE_RENDERER (chafa, icat, imgcat)
• YT_X_BROWSER (e.g., firefox, brave )

Examples & Workflows

Hello world

# always put --config-write at the end
# it will first save the runtime config and proceed with normal execution of the command
YT_X_IMAGE_RENDERER=icat YT_X_BROWSER=firefox yt-x --preview --preview-images --config-write

Desktop app launcher

Launch yt-x as a graphical application using Rofi Its really cool esp with the custom themes in the repo, so be sure to try

# allowing the player to run in the background when using rofi
# is a bad idea since the player will launch and rofi will launch again and block it
yt-x --launcher rofi --preview --preview-images --no-disown-player

Audio only background music

yt-x -l fzf -p mpv --disown-player --listen-all -sp "lofi hip hop radio" # skip playlist results menu
# or
yt-x -l fzf -p mpv --disown-player --listen -sp "lofi hip hop radio" # choose specific video to listen to

Binge your watch later

yt-x --play-all --watch-later

Save the playlist and exit

yt-x --save-playlist --media-exit --search-playlist "anatomy"

Download playlist and exit

yt-x --download-all --media-exit --search-playlist "general relativity"

Search a channel and play a video

# though i already think its obvious lol
yt-x channels -n "Linus Tech Tips" -s "linux or mac" --play

create a desktop entry

yt-x -E > ~/.local/share/applications/yt-x.desktop

Shell completions

# NOTE: incase of updates the completions may change or more maybe added
yt-x completions --fish > ~/.config/fish/completions/yt-x.fish

listen to a saved video

yt-x --listen --media-exit -sv "podcast"

listen to a custom playlist

# you could easily keybind this
yt-x --launcher rofi --no-disown-player --listen-all --media-exit -cp "study music"

Explore a custom sites playlist and play the video

# you could easily keybind this
yt-x --launcher rofi --no-disown-player --play --media-exit -cc "my custom cmd for exploring a different streaming site that yt-dlp supports"

search for shorts and download

yt-x --download --media-exit -ss "linux meme"

Explore the latest news and play on selection

# you could easily keybind this
yt-x --launcher rofi --no-disown-player --play --media-exit -s ":today world news"

create convinience aliases

function play
    yt-x --play --media-exit $argv
end

funcsave play

play -s "Top Movies"

# you could do sth similar for zsh or bash
# if you want auto complete for play just dump the completions to play.fish and find and replace yt-x with play

# also do channel aliases
function freecodecamp
    yt-x --launcher fzf channel -n "freeCodeCamp.org" $argv
end

function freecodecamp-app
    yt-x --launcher rofi --no-disown-player channel -n "freeCodeCamp.org" $argv
end

funcsave freecodecamp

freecodecamp --search "how llms work"

Configuration

By default, the main configuration file is located at:

~/.config/yt-x/config

(Note: It respects the $XDG_CONFIG_HOME environment variable if set).

You can open it using the cli

yt-x --edit-config

Configuration Variables

Display & Interface

Media Previews

Playback & Media Handling

For configuring a player prefer its config file which you can also edit from why yt-x in the misc menu They exist purely for convinience and is more useful when passing from cmdline or env vars

yt-dlp

Downloading

History & Caching

Fzf, gum and Rofi

Check the repo for pre-configured rofi themes

Others

Extensions

yt-x supports extensions to add or override functionality without modifying the core script.
Extensions are shell scripts placed in ~/.config/yt-x/extensions/ and can be loaded on demand or automatically.

Official Extensions

The following extensions are maintained and included in the repository.

Command Extensions (cmds/)

downloads by Benexl

Replaces the main menu with a local media browser.
Lets you explore and play videos/audio files already downloaded to CONFIG_DOWNLOAD_DIR.

Features:

• Browse by individual files, playlists (subfolders), or channels (nested folders).
• Previews with ffmpegthumbnailer (if installed).
• Play, play all, listen, listen all – supports the same media actions as online content.

Load with:
yt-x -x cmds/downloads

UI Extensions (ui/)

Language Extensions (langs/)

Site Extensions (sites/)

Theme Extensions (themes/)

catppuccin-mocha.theme by Benexl

Applies the Catppuccin Mocha color scheme to fzf and the terminal output.
Includes custom fzf options (border, colors, preview window) and ANSI escape codes for primary/secondary/accent/error colors.

Requirements: True‑color terminal support (COLORTERM=truecolor).
Load with:
yt-x -x themes/catppuchin-mocha.theme

Loading Extensions

Temporary (single session)

yt-x -x sites/dailymotion.site
yt-x -x langs/es.lang
yt-x -x themes/catppuchin-mocha.theme
yt-x -x cmds/downloads             # replaces main menu with a local media browser
yt-x -x ui/custom-menus.ui         # injects custom menu entries seamlessly

Permanent
Add to ~/.config/yt-x/config:

CONFIG_AUTOLOADED_EXTENSIONS="themes/catppuchin-mocha.theme,langs/es.lang,ui/custom-menus.ui"

Creating Your Own Extension

1. Create the appropriate subdirectory (if missing) inside ~/.config/yt-x/extensions/.
2. Write a POSIX‑compliant shell script.
3. The script is sourced by yt-x, so you can:
   • Override any function (e.g., menu_main, _menu_media_actions).
   • Add new menu items by appending to the actions variable.
   • Define new helper functions.
   • Use all internal variables and functions (prefixed with _ or public like ui_prompt).

Important Notes

• Extensions are sourced, not executed – they run inside the main script’s context.
• Avoid exit or exec unless you really want to terminate yt-x.
• Use return instead of exit to stop processing the extension.
• You can combine multiple extensions; load order is the order they appear in CONFIG_AUTOLOADED_EXTENSIONS (or the order of -x flags).
• For commands (cmds/), your script must define a function menu_main that replaces the default main menu (see cmds/downloads).

Check the extensions/ folder in the repository for examples.

Frequently Asked Questions (FAQ)

# Pass cookies to yt-dlp inside mpv
# Force highest quality 1080p video + best audio
# plus handle subs
# you could also add sponsor block and chapters
# by adding --embed-chapters --sponsorblock-mark all to the list
ytdl-raw-options=format-sort="res:1080,vcodec:vp9,acodec:opus,fps",sub-lang="en,eng,enUS,en-US",write-sub=,write-auto-sub=,cookies-from-browser=firefox
ytdl-format=bestvideo+bestaudio/best

# if you know the exact decoder specify it vaapi for intel gpus or i think *nvdec for nvidia gpus
hwdec=auto
vo=gpu

# subs
slang=en,eng,enUS,en-US
sub-auto=fuzzy

# though format sort would be better just recently discovered it lol check the mpv faq above to see how or the official readme
-f bestvideo[height=1080][fps=60][vcodec^=vp9]+bestaudio/best[height=1080][fps=60][vcodec^=hevc]+bestaudio/best[height=1080][fps=60][vcodec^=avc1]/bestvideo[height=1080][fps<=30][vcodec^=vp9]+bestaudio/best[height=1080][fps<=30][vcodec^=hevc]+bestaudio/best[height=1080][fps<=30][vcodec^=avc1]/bestvideo[height>=720][height<1080][fps=60][vcodec^=vp9]+bestaudio/best[height>=720][height<1080][fps=60][vcodec^=hevc]+bestaudio/best[height>=720][height<1080][fps=60][vcodec^=avc1]/bestvideo[height>=720][height<1080][fps<=30][vcodec^=vp9]+bestaudio/best[height>=720][height<1080][fps<=30][vcodec^=hevc]+bestaudio/best[height>=720][height<1080][fps<=30][vcodec^=avc1]/bestvideo[height>=720]+bestaudio/best
--embed-chapters
--sponsorblock-mark all
--embed-metadata
--embed-thumbnail
--add-metadata
--embed-subs
--sub-lang en
--merge-output-format mkv
--no-warnings
--quiet
--reject-title "\[Deleted video\]|\[Private video\]"
--progress

--reject-title "\[Deleted video\]|\[Private video\]"

_menu_main [sort] [filter_regex] [extra_actions] [handler_function]

# override menu_main with a filter
menu_main() {
  _menu_main "" "Clips"
}

menu_main() {
  _menu_main "2,1"   # Search first, then Feed
}

my_custom_handler() {
  case "$1" in
    "My Favourites") yt-x -cp "My Favourites" ;;
    *) return 1 ;;
  esac
}

menu_main() {
  extra="   My Favourites"
  _menu_main "" "" "$extra" my_custom_handler
}

menu_main() {
  _state_init
  # Remove "Clips", reorder (Search #2 first), add a "Daily Mix" entry
  _menu_main "2,1" "Clips" " 󰀄  Daily Mix" my_custom_handler
}

convert_to_mp3() {
  # your conversion logic using STATE_CURRENT_VIDEO_URL
  notify-send "Converting..."
}

menu_media_actions() {
  _menu_media_actions "" "Mix\\|Save Playlist" " 󰒄  Convert to MP3" convert_to_mp3
}

TXT_ICON_MENU_MAIN_FEED=""
TXT_ICON_MENU_MAIN_SEARCH=""
TXT_ICON_MENU_MEDIA_ACTIONS_WATCH=""

# Or replace them with simple ASCII prefixes
TXT_ICON_MENU_MAIN_FEED="[F]"
TXT_ICON_MENU_MAIN_SEARCH="[S]"
TXT_ICON_MENU_MEDIA_ACTIONS_WATCH="[W]"
# ... add more as needed

CONFIG_BROWSER="chromium:~/.local/share/qutebrowser"

CONFIG_FZF_OPTS="...your existing options... --bind 'j:down,k:up,ctrl-u:half-page-up,ctrl-d:half-page-down'"