Full Demo:

Riced/Customized Previews:

1. Imperative:

nix profile install github:Benexl/yt-x

2. Declarative: 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 ];

No. yt-x is just a wrapper over amazing cmdline tools. (yt-dlp,fzf,rofi,mpv etc) Before opening an issue on GitHub, please determine if the bug is actually related to yt-x or one this tools

For example:

• 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).
• State management, navigation, or UI/preview 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 a supported browser by yt-dlp (e.g., firefox, chrome, brave).

Note: you can 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 and defaults to 1080p hardware-accelerated playback, add something like this to your ~/.config/mpv/mpv.conf: You can also do it from the miscellaneous menu

# 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

Something like this

# 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\]"

Add something like this to yt-dlp config

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

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".
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.

also make sure to delete the ~/.cache/yt-x/previews/text/fzf-preview.sh file to clear out old cached values that may have been generated with the wrong renderer settings

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) This is due to licensing issues and mac being mac you cant even remove it apparently 😂 Ensure you have installed the core dependencies via Homebrew (brew install bash). Homebrew's installation location should be at the top of path so its preferred over the older bash which you cant remove

Currently working on figuring out whats the syntax issue preventing the script from working with 3.x but for security reasons, even when the script supports it, prefer the latest version for daily use ohh and any help on the 3.x issue would be appreciated

Configure your media player. Add something like this to your ~/.config/mpv/mpv.conf: ytdl-format="bestvideo[height<=?1080]+bestaudio/best"

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).

Since you can't directly use the mpv command in termux unless you have installed a window manager so apps like mpv and vlc android are used 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 :)

Its either a bug or you pressed ctrl+c too fast and it triggered the state dir to be wiped by trap cmd

This is an fzf error especially in debian systems where the fzf version maybe older. So just update it using more upto date ppa's or use Homebrew its what i used to use when i first started using linux (ubuntu) works supprisingly well

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.

This is actually a feature of your media player rather than yt-x. Integrating this directly into yt-x would require intercepting mpv's output using Lua scripts or enforcing playerctl + MPRIS , which i don't want to do nor think its a good idea

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, this is how it looks in myNoctalia setup on Niri:

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 --media-exit --play -s "Dota"

# 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

read usage for more examples and cmdline docs

--shell(media action) drops you into a subshell that is pre‑loaded with all the current session’s state variables. Its useful for running custom cmds on the current results

Available variables in the subshell include:

• 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. Note some are json so use jq to parse and inspect them or interactive ones like ijq and jnv

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.).

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. You also get to implement your own state logic from scratch, data transformation pipelines, and such since there are no shell libraries which you can use to do the same managing a really long monolithic program and dealing with lack of certain data structures, being conscious on the commands you run since creating a process incurs an overhead

so its one hell of a learning xp

Incase you are wondering how to traverse it and explore it efficiently use a symbols search lsp(make sure you have installed bash-lsp) The code is structured and ordered into sections and each section is demarcated by a header so you could easily use code folding and it becomes drastically shorter while still knowing where you are all functions also have a namespace using the function name ui preview app etc there are also sub namespaces like fzf or rofi

The cognitive overload you get is high but still its pretty fun once you get used to it and an asset for getting use to mapping large systems entirely in your head and working with several constraints

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

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

Though whether you chose yt-x or magic-tape its upto you

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.