Full Demo:

Riced/Customized Previews:

Arch Linux users can install the bleeding-edge version directly from the Arch User Repository using their preferred AUR helper:

# Using yay
yay -S yt-x-git

# Using paru
paru -S yt-x-git

You can install yt-x either imperatively or declaratively using Nix flakes.

1. Imperative / Direct installation:

nix profile install github:Benexl/yt-x

2. Declarative / Config-based: First, add the repository to your flake.nix inputs:

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

• For system-wide installation (in configuration.nix):

  environment.systemPackages = [ inputs.yt-x.packages."${system}".default ];

• For user-level installation (via Home Manager in home.nix): nix home.packages = [ inputs.yt-x.packages."${system}".default ];

yt-x is fully compatible with Windows, provided you are running it inside a compatible terminal environment.

• Environment Detection: yt-x treats WSL natively as a Linux environment. However, if you are using Git Bash or MSYS/Cygwin, it correctly detects and treats them as Windows terminals.
• Launcher: You must use fzf as your launcher on Windows terminals. (rofi is specifically designed for Linux desktop environments).
• PATH Requirements: Ensure that Windows executables (like yt-dlp.exe, jq.exe, fzf.exe, and a media player like mpv.exe or vlc.exe) are accessible within your terminal's $PATH.
• URL Opening: The script automatically supports Windows URL launching. It utilizes wslview (for WSL setups) or cmd.exe /C start (for Git Bash/Cygwin) to open links smoothly in your native Windows browser.

No. yt-x is a highly advanced wrapper that orchestrates several powerful underlying tools. Before opening an issue on GitHub, please determine if the bug is actually related to yt-x or one of its backend utilities:

• Media Fetching/Downloading fails: This is handled by yt-dlp. If a specific site breaks or videos refuse to download, try updating yt-dlp first (yt-dlp -U).
• Video Playback stutters or crashes: This is handled by your media player (mpv, vlc, etc.).
• Menu rendering issues / freezes: This is handled by fzf or rofi.
• State management, navigation, or UI logic fails: This is handled by yt-x. Please open an issue!

You need to pass your browser cookies to yt-dlp. You can do this natively in yt-x by editing your config (~/.config/yt-x/config) and setting the CONFIG_BROWSER variable to your daily browser (e.g., firefox, chrome, brave).

Note: For the best playback experience, you should also configure your media player to use these cookies (see the MPV optimization tip below).

By default, mpv handles streaming via yt-dlp under the hood. To ensure mpv uses your browser cookies (for age-restricted content) and defaults to 1080p hardware-accelerated playback, add the following to your ~/.config/mpv/mpv.conf:

# Pass cookies to yt-dlp inside mpv
ytdl-raw-options=cookies-from-browser=firefox

# Force highest quality 1080p video + best audio
ytdl-format="bestvideo[vcodec^=avc1][height<=1080]+bestaudio/best"

# General QoL improvements
hwdec=auto
vo=gpu
slang=en,eng,enUS,en-US
sub-auto=fuzzy

yt-x ships with a default Tokyo Night color palette. You can easily "rice" it to match your system theme by either:

1. Editing CONFIG_FZF_OPTS directly in ~/.config/yt-x/config.
2. Creating a dedicated .theme file inside ~/.config/yt-x/extensions/themes/ and autoloading it.

Example: Custom Catppuccin-style Config

CONFIG_FZF_OPTS="
  --color=bg+:#283457,bg:#16161e,border:#27a1b9,fg:#c0caf5,header:#2ac3de,hl+:#2ac3de,hl:#2ac3de,info:#545c7e,marker:#ff007c,pointer:#ff007c,prompt:#2ac3de,query:#c0caf5,scrollbar:#27a1b9,separator:#ff9e64,spinner:#ff007c
  --border=rounded --prompt=' >' --marker=' >' --pointer='◆' --layout=reverse --cycle
"

You can save custom playlists via the yt-x UI, but you can also manually maintain them locally. They are stored in a simple JSON file located at ~/.config/yt-x/custom-playlists.json.

Ensure your file follows this structure:

[
  {
    "id": "PLYOURPLAYLISTID",
    "name": "My Custom Chill Mix",
    "url": "https://www.youtube.com/playlist?list=PLYOURPLAYLISTID"
  }
]

Image previews require a few components to work together:

1. Ensure you have enabled them in your config: CONFIG_ENABLE_PREVIEW=true and CONFIG_ENABLE_PREVIEW_IMAGES=true.
2. Ensure you have a supported image renderer installed (e.g., chafa, icat, or imgcat).
3. Set the correct renderer in your config: CONFIG_IMAGE_RENDERER="chafa".
4. Ensure your terminal emulator actually supports image rendering (sixel, kitty graphics protocol, or iTerm2 protocol). If it doesn't, stick with chafa, which falls back to excellent ASCII/block character rendering.

yt-x passes the CONFIG_BROWSER variable directly to yt-dlp.

• Chromium v11+ / Brave / Edge: Modern Chromium browsers encrypt cookies via your OS keyring (GNOME Keyring, KWallet). yt-dlp needs access to this keyring to decrypt them.
• Flatpaks / Snaps: yt-dlp cannot easily read cookies from containerized browsers due to sandboxing. Use natively installed browsers (deb/rpm/AUR/Homebrew) for the best cookie compatibility.
• Alternative: If your browser (like Zen) isn't supported natively, use an extension like "Get cookies.txt LOCALLY", save the file, and pass it via your config: CONFIG_YT_DLP_ARGS="--cookies /path/to/cookies.txt".

If your images are overlapping with UI text, your terminal may not properly support the image clearing sequences used by chafa.

1. Kitty / Ghostty: Set CONFIG_IMAGE_RENDERER="icat". These terminals have native, high-performance image protocols.
2. iTerm2 / WezTerm: Try CONFIG_IMAGE_RENDERER="imgcat".
3. Other Terminals: Stick to CONFIG_IMAGE_RENDERER="chafa", but ensure your terminal supports Sixel or true-color ASCII. If overlaps persist, disable image previews (CONFIG_ENABLE_PREVIEW_IMAGES=false) and use text-only previews.

Since the UI is driven by fzf, you can easily customize keybindings by modifying the CONFIG_FZF_OPTS variable in your ~/.config/yt-x/config file. Add --bind flags to map your preferred keys. For example, to add Vim motions and page scrolling:

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

By default, yt-x blocks the terminal until the media player is closed. To browse while watching, enable background playback by setting CONFIG_DISOWN_PLAYER=true in your config, or launch the script with the --disown-player flag.

macOS ships with an outdated version of Bash (v3.x) and older standard utilities. yt-x requires modern tooling. Ensure you have installed the core dependencies via Homebrew (brew install yt-dlp fzf jq chafa mpv). If you encounter shell-specific errors, ensure your terminal is executing the script using a modern, Homebrew-installed shell environment rather than Apple's legacy /bin/sh.

While you can set CONFIG_VIDEO_QUALITY in yt-x, the actual stream negotiation is done by your media player (like mpv) via yt-dlp. If mpv decides to override the quality, you will get the maximum available resolution. To strictly enforce video quality, you must configure your media player. Add this to your ~/.config/mpv/mpv.conf: ytdl-format="bestvideo[height<=?1080]+bestaudio/best" (Change 1080 to your preferred maximum height).

On Android, yt-x does not play the media inside the terminal. Instead, it uses Android am start intents to pass the stream URL to an installed GUI application (like the VLC or MPV Android apps). If you have no audio or video, ensure you have the actual MPV or VLC Android application installed on your device, and check the app's internal settings.

Also since you can't directly use the mpv command in termux unless you have installed a window manager we use apps like mpv and vlc android through android intents api and there it only supports giving it one url

the script uses --get-url yt-dlp opt inorder to get the url but only picks the top one for video where the second maybe the audio file if the video has a separate audio file

so to 'fix' this you only need to specify --format yt-dlp opt in your config where you specify merged formats like best --format 'best'

in case someone figures out how to also pass an audio file(more than one url) using android intents this will always limit what you can stream to only merged files and incase you do please share :)

This typically happens for two reasons:

1. Corrupt Cache: A previous yt-x session crashed and didn't clean up its state files. You can manually fix this by deleting the cache directory: rm -rf ~/.cache/yt-x/state/.
2. FZF Aliases: If you have customized fzf in your .bashrc/.zshrc with aliases that alter its default output formatting, it will break yt-x's state parsing. Ensure fzf operates normally.

This is an fzf error. If you modified CONFIG_FZF_OPTS to add custom hex colors (e.g., #2ac3de), you must ensure your terminal emulator actually supports True Color (24-bit). If it doesn't, fzf will crash. Revert to standard ANSI colors (like blue, red, cyan) in your config if your terminal lacks True Color support.

This happens if yt-x lacks the correct permissions to write to its own file. If you installed yt-x system-wide using sudo (e.g., to /usr/local/bin), the auto-updater running as your normal user cannot overwrite the binary. Fix: Reinstall yt-x to your local user directory (~/.local/bin/yt-x) as shown in the Installation guide, or disable the updater by setting CONFIG_CHECK_FOR_UPDATES=false in your config.

You need to sync your subscriptions first.

1. Ensure CONFIG_BROWSER is set to the browser where you are logged into YouTube.
2. Go to the Main Menu -> Miscellaneous -> Sync YouTube Subscriptions. yt-dlp will use your browser cookies to fetch your subscriptions and populate the ~/.config/yt-x/subscriptions.json file.

Yes! yt-x uses rofi's native \0icon\x1f protocol to display images. Ensure you have CONFIG_ENABLE_PREVIEW_IMAGES=true enabled in your yt-x config. Furthermore, your custom Rofi .rasi theme (CONFIG_ROFI_THEME_PREVIEW) must be configured to actually display the element-icon property.

This is actually a feature of your media player rather than yt-x. Integrating this directly into yt-x would require complex workarounds (such as intercepting mpv's output using Lua scripts or enforcing playerctl + MPRIS dependencies), which goes against yt-x's lightweight design philosophy.

The Solution: The cleanest way to achieve this is by enabling MPRIS support directly in your media player.

• For mpv: Install the mpv-mpris plugin. This allows mpv to broadcast the current track's metadata to your OS, exactly like a web browser does for YouTube.
• For other players: Search for similar MPRIS or D-Bus integration plugins/settings.

Once configured, any compatible desktop widget or notification daemon will automatically pick it up and display what's playing. For example, using the Noctalia daemon on the Niri compositor handles this beautifully:

yt-x now supports several flags that let you bypass all menus and run actions non‑interactively – perfect for scripting, keybindings, or quick one‑off commands.

• --playlist-skip (-ps) : Automatically picks the first item in any list (search results, playlist, etc.) without showing the selection menu.
• --play-all, --listen-all, --download-all, --download-audio-all, --save-playlist : These implicitly enable --playlist-skip and act on the whole playlist immediately.
• --media-exit (-me) : After performing a media action (play, download, save, etc.), exit the script.
• --cmd-exit (-ce) : After processing any shortcut menu command (e.g., --feed, --subscriptions-feed), exit.

Examples:

# Play the first video from a search and exit
yt-x --playlist-skip --play -s "cute kittens" --media-exit

# Download the whole Watch Later playlist without any prompts
yt-x --download-all --watch-later

# Save the current playlist as a custom playlist and exit
yt-x --save-playlist --media-exit

Use the -sv / --saved-video, -cp / --custom-playlist, and -cc / --custom-cmd flags to jump straight to an item.
In supported shells (Fish), you get tab completion for the names.

# Open a specific saved video by its title
yt-x -sv "My favourite coding tutorial"

# Open a specific custom playlist
yt-x -cp "Jazz for studying"

# Execute a specific custom command by name
yt-x -cc "My Custom Search"

If you omit the argument, yt-x will prompt you to select from the list interactively.

--shell drops you into a subshell (either fish or POSIX sh) that is pre‑loaded with all the current session’s state variables. This is a power‑user feature for advanced scripting or ad‑hoc manipulation.

Available variables in the subshell:

• STATE_CURRENT_VIDEO, STATE_CURRENT_VIDEO_URL, STATE_CURRENT_VIDEO_TITLE
• STATE_CURRENT_PLAYLIST_RESULTS, STATE_CURRENT_PLAYLIST_URL, STATE_CURRENT_PLAYLIST_TITLE
• Channel info, pagination indices, etc.

You can use this to, for example, manually run yt-dlp commands on the current video, extract metadata, or automate custom post‑processing.

yt-x --shell   # After navigating to a video, you'll get a shell with that video's info loaded

Type exit to return to yt-x.

--play-all, --listen-all, --download-all, --download-audio-all, and --save-playlist are designed for whole‑playlist actions. They assume you want to act on the entire list, not a single item, so they automatically set --playlist-skip internally. This saves you from having to type both flags and makes command‑line usage more intuitive.

If you do want to select a specific item from a playlist before playing the whole list, just use --play (without -all) and choose interactively.

Fish shell completions are fully supported and include dynamic completion for:

• -cp / --custom-playlist : reads playlist names from ~/.config/yt-x/custom-playlists.json
• -sv / --saved-video : reads video titles from ~/.config/yt-x/saved-videos.json
• -cc / --custom-cmd : reads command names from ~/.config/yt-x/custom-cmds.json
• channels -n : reads channel names from ~/.config/yt-x/subscriptions.json
• -x / --extension : lists files in ~/.config/yt-x/extensions/

To install Fish completions:

yt-x completions --fish > ~/.config/fish/completions/yt-x.fish

Bash and Zsh completions are not yet implemented – contributions are welcome!

--cmd-exit works by setting a flag that tells yt-x to exit once the current “command” (menu or action) returns to the main loop. If you use --cmd-exit with a shortcut that opens another menu (e.g., --saved followed by selecting a video), the exit will only happen after you fully exit that sub‑menu (by pressing Back/Exit). For a hard exit right after a media action, use --media-exit instead.

Use the dedicated search flags to jump straight to results:

• -s, --search <term> : Video search
• -sp, --search-playlist <term> : Playlist search
• -sc, --search-channel <term> : Channel search
• -ss, --search-short <term> : Shorts search
• -sm, --search-movie <term> : Movie search

If you omit the search term, yt-x will prompt you to enter one interactively.

Example:

yt-x -s "linux kernel tutorial"
yt-x -sp "jazz playlist"
yt-x -sc "tech news"

Yes, use the -l / --launcher and -p / --player flags. These override the config file settings for a single run.

# Use rofi as the menu launcher for this session
yt-x -l rofi

# Use vlc as the media player
yt-x -p vlc

# Combine with other options
yt-x -l rofi -p vlc --preview

Use -i to enable previews or -I to disable them. This overrides your CONFIG_ENABLE_PREVIEW setting for that run.

# Run with previews enabled
yt-x -i

# Run with previews disabled (useful for slow connections)
yt-x -I

Previews can also be toggled inside fzf using ctrl-/ (if not disabled in your config).

Use the -E / --generate-desktop-entry flag. It prints a .desktop file to stdout, which you can redirect to the appropriate directory.

# For a terminal‑based launcher (fzf)
yt-x -E > ~/.local/share/applications/yt-x.desktop

# For a GUI‑style launcher with rofi (no terminal window)
# (Modify the generated file to set Terminal=false and add --launcher rofi)

After saving, run update-desktop-database ~/.local/share/applications/ to refresh the menu.

Run yt-x -U or yt-x --update. The script will check the GitHub repository for changes, show you a diff if available, and prompt you to apply the update. If you installed yt-x to a system‑wide location (e.g., /usr/local/bin) without proper write permissions, you may need to reinstall it in your ~/.local/bin directory for the auto‑updater to work.

To disable automatic update checks, set CONFIG_CHECK_FOR_UPDATES=false in your config file.

Use the -x / --extension flag followed by the extension file name (relative to ~/.config/yt-x/extensions/) or an absolute path. Extensions can be anything from theme files (.theme), language files (.lang), site definitions (.site), or custom command scripts (.cmd).

# Load a theme
yt-x -x themes/catppuccin.theme

# Load a site extension for a different video platform
yt-x -x sites/dailymotion.site

# Load a custom command script
yt-x -x cmd/my-search

Multiple -x flags can be used. To autoload extensions on every startup, list them in CONFIG_AUTOLOADED_EXTENSIONS (comma‑separated) in your config file.

Every config variable can be overridden by an environment variable prefixed with YT_X_. This is useful for scripting or one‑off changes without touching the config file.

Examples:

# Use rofi as launcher for this session
YT_X_LAUNCHER=rofi yt-x

# Enable previews and use chafa for images
YT_X_ENABLE_PREVIEW=true YT_X_IMAGE_RENDERER=chafa yt-x

# Change download directory temporarily
YT_X_DOWNLOAD_DIR="$HOME/Downloads/temp" yt-x --download-all

See the config file for all available variables (e.g., YT_X_PLAYER, YT_X_BROWSER, YT_X_PER_PAGE, etc.).

yt-x automatically cleans up old cache files (preview images, auto‑generated playlists, logs) based on CONFIG_CACHE_RETENTION_DAYS (default 7 days). The cache directories are located under ~/.cache/yt-x/.

To manually clean everything:

rm -rf ~/.cache/yt-x/

To keep the cache but remove only stale items older than a certain number of days (e.g., 3):

find ~/.cache/yt-x/ -type f -mtime +3 -delete

Clearing the cache will not affect your saved videos, custom playlists, or subscriptions – those are stored in ~/.config/yt-x/.

The channels subcommand accepts -n (channel name) plus an action flag. You can combine it with --cmd-exit to exit after browsing the channel.

Examples:

# Open a channel's videos and exit when you go back
yt-x channels -n "Linus Tech Tips" -v --cmd-exit

# Search within a channel without any interactive channel selection
yt-x channels -n "freeCodeCamp.org" -s "python tutorial"

# List a channel's playlists and then exit
yt-x channels -n "StarTalk" -p --cmd-exit

If -n is omitted, you'll be prompted to pick from your subscriptions. If no action flag is given, you'll enter the channel's interactive menu.

These flags take you straight to specific sections:

Combine these with --cmd-exit for non‑interactive workflows.

i am using niri as my compositer and noctalia does all the theming for me. Though am planning to create my own riced setup when i gate free time, and maybe even a my own widget system which should also function as an sddm alternative since i personally dont like quickshell since its a resource hog and one of the reasons i like linux is low resource usage; especially since my first laptop was not powerful (celeron, 4gb ram, 1tb harddisk), so i still have the over optimizing mindset. I even have a name for it lol, i cant remember it now but i know it has an 'x' in it lol its probably going to be based on iced-rs and the config language rhai since i like its concept and prefer not to have to deal with ffi bindings of another lang so no lua. And i want it to be as stable as possible and no points of failure due to memory stuff

does that mean am a rust fanatic, nope just dont want to deal with a class of bugs and want to focus on logic though i still plan to master zig after rust since i like its concept of explicit memory management it helps in reducing cognitive overload in large systems and there are times where manual memory management is useful like when you need to squeeze every single bit of performance plus its syntax looks interesting

its kitty's quake terminal mode, you can set one using quake-terminal kitten for kitty users. Other terminals also implement may also implement a similar feature.

I personaly use uosc which in my opinion its by far the best ui for mpv. They have even implemented rendering yt's heatmap in the timeline. You can even also install thumbfast which will add timeline previews.

Honestly, it was initially cause at the time the project where i first saw the concept was in bash magictape. Other than that i had know meaningful reason then. But now i can say its portability(runs in zsh, dash, bash, ksh; posix compliant systems) and its really easy to modify, audit and build upon a shell script since the excutable is just one file and you can open it up in your editor anytime or easily modify it to do what you want without having to open a pr have a fork etc. I have also grown to like writing shell scripts and the challenge involved its kinda cool and ais suck at writing it esp long ones lol, so yeah. Though for the same reason it makes it had to find reliable material or information on some concepts, so its one hell of a learning xp

Initially previews on kitty did not work and it took sometime before my issue was answered and solved, and a month later i decided to write my own on github(what am use to) in contrast with magic tape on gitlab.

And thus in my first year, during orientation week, yt-x was born and became my second popular oss project.

well non really just there to show the progression to a stable version v1.0.0. where i wont wake up one night with a ton of ideas and implement them before i go back to sleep the next day lol.

Other than that i dont think going forward there will be that many changes esp since the heavy lifting is done by its dependencies like yt-dlp. The script will proabably work for many years to come as long as yt-dlp exists, which i think it will. And ways the last major change i have made before v1.0.0 was the rewrite v0.5.0 which was done in a separate branch and took a week ~8hrs a day to write and i aint doing that again lol

Plus the update process is pretty transparent since you always get to see what changed. Which i think its unique to yt-x.

My goal with this was to make it easier to build ontop of a feature or menu without losing the original functionality eg in extensions. In other languages this would be trivial without need for the redundancy but in shell this is the best idea i have so far

Well i only have so much time and i really do have to sleep lol such is the fate of organic lifeforms lol. Though prs are mighty welcomed

Like i have so many ideas, though i decided not to implement some due to the illusion of how long it will take like v0.5.0, thought i could do the rewrite in a day lol, ended up being a week working nearly most of the day. There are even somethings i mentioned i will do at the start of the pr that i got so tired i decided not to implement.

And for the same reason if you want to request a feature its fine, though whether i personally will implement it is entirely whether i find it interesting enough or i will use it.

Otherwise you will probably have to open a pr or wait for someone else to implement it

well most of the issues that have been opened in github since before the faq are not related to yt-x itself and i thought why not just share all the knowledge i have on the tools the script is using or ones i have shown in my demos. Plus i remember how hard and long it took to solve some issues and want the script to be something you install and it just works.