yt-x

Browse YouTube from your terminal. Plus other sites yt-dlp supports.

Inspired by magic-tape

yt-x-github-demo.webm

Full Demo

yt-x-full-github-demo.webm

Features

• Interactive Menu: Text-based UI using fzf or rofi for seamless navigation.
• YouTube-Specific Menus: Access your feed, trending videos, playlists, watch later, subscriptions feed, liked videos, clips.
• Playback Support: Play videos and audio via mpv or vlc.
• Search Functionality: Search for videos, channels and playlists directly.
• Channel Exploration: Explore channels, including their videos, streams, podcasts, shorts, and playlists.
• Saved Channels: Bookmark your favorite channels for quick access, with support for importing existing subscriptions.
• Saved Videos: Save videos to watch later.
• Mixes: Generate and explore YouTube song mixes.
• Yt-x Shell: Run custom yt-dlp and mpv commands for downloading and viewing videos and playlists
• Custom Playlists: Save playlists for easier access.
• Download Management: Download videos, audio, and playlists using yt-dlp.
• History & Recents: Track your recent videos and search history.
• Configuration Management: Customize and manage configurations for yt-x, mpv and yt-dlp with ease.
• Extensions: Extend yt-x with your own custom ui and preview logic allowing more precise coverage of other sites that yt-dlp supports🥳
• Custom Commands: Basically a simple way to achieve the same thing with extensions. A custom command is just a yt-dlp command that loads a playlist or playlist like json.
• Miscellaneous Features:
  • Shell completions for bash, zsh, and fish.
  • Desktop entry generation for easy access.

📥 Installation

❄️ NixOS or Home Manager

On NixOS, you can install packages using two main methods:

1. Imperative/Direct installation:

nix profile install github:Benexl/yt-x

2. Declarative/Config-based:

   2.1 Add the following to your flake.nix:

   inputs = {
     yt-x.url = "github:Benexl/yt-x";
     ...
   }

   2.2 Then, add Yt-x to your packages:

   For system wide installation in configuration.nix

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

   For user level installation in home.nix

   home.packages = with pkgs; [
     inputs.yt-x.packages."${system}".default
   ];

Arch Linux

You can install yt-x from the Arch Linux AUR repository.

To install, use your preferred package manager paru or yay:

# for paru users
paru -S yt-x-git

# for yay users
yay -S yt-x-git

Cross-platform

# NOTE: ~/.local/bin should exist and be in path for this to work
curl -sL "https://raw.githubusercontent.com/Benexl/yt-x/refs/heads/master/yt-x" -o ~/.local/bin/yt-x && chmod +x ~/.local/bin/yt-x

Dependencies

Required

• jq - JSON parsing.
• curl - Download preview images.
• yt-dlp - Fetch YouTube data.
• fzf - Main UI navigation.
• mpv - Video and audio playback.
• ffmpeg - Proper HLS stream downloading.
• bash - Script interpreter.
• nerdfont - for the icons

Optional

• gum - Enhanced UI (highly recommended).
• rofi - Alternate UI.
• terminal image viewer:
  • chafa - Cross-terminal image rendering (recommended).
  • icat - recommended for kitty terminal and ghostty
  • imgcat
• terminal with image rendering support:
  • kitty - currently has the best image rendering capabilities (recommended)
  • wezterm
  • ghostty

---

Usage

# Launch the UI
yt-x

# Edit configuration
yt-x -e

# load an extension
# extensions are located at ~/.config/yt-x/extensions
# the extension name is the name of a file in the extensions folder
yt-x -x <extension-name>

# Specify player at runtime
yt-x --player <mpv/vlc>

# Set selector at runtime
yt-x -s <fzf/rofi>

# Specify Rofi theme path
yt-x --rofi-theme <path>

# Enable/disable preview
yt-x --preview / yt-x --no-preview

# Print desktop entry
yt-x -E

# Print shell completions
yt-x completions --bash
yt-x completions --zsh
yt-x completions --fish

# Update the script
yt-x --update

# Display help
yt-x --help

---

Tips

Enabling Imports of Subscriptions & Private Playlists

Set your preferred browser in the configuration file:

PREFERRED_BROWSER: firefox

To enable mpv to access private playlists and videos, add something like this to mpv.conf (you can also use the ui to edit mpv.conf):

ytdl-raw-options=cookies-from-browser=firefox

# --- bonus mpv tips ---

# define the quality for mpv to use
ytdl-format="bestvideo[vcodec^=avc1][height=1080]+bestaudio/best[vcodec^=avc1][height=1080]/bestvideo[vcodec^=avc1][height=720]+bestaudio/best[vcodec^=avc1][height=720]/best"

# defines where screenshots will be saved
screenshot-directory=~/Pictures/mpv_screenshots/

# enable hardware accelaration
hwdec=auto
vo=gpu

To customise download options with yt-dlp you can add something like this to yt-dlp.conf (you can also use the ui to edit yt-dlp.conf)

-f bestvideo[vcodec^=avc1][height=1080]+bestaudio/best[vcodec^=avc1][height=1080]/bestvideo[vcodec^=avc1][height=720]+bestaudio/best[vcodec^=avc1][height=720]/best
--embed-chapters
--sponsorblock-mark all
--embed-metadata
--embed-thumbnail
--add-metadata
--embed-subs
--sub-lang en
--merge-output-format mkv

For additional enhancements, consider:

• uosc for a modern mpv UI.
• thumbfast for thumbnail timeline previews.

Custom Playlists

Define custom playlists by editing ~/.config/yt-x/custom_playlists.json (or use the UI):

[
  {
    "name": "<playlist name>",
    "playlistUrl": "https://www.youtube.com/playlist?list=<playlist-id>",
    "playlistWatchUrl": "https://www.youtube.com/watch?list=<playlist-id>"
  }
]

Theming

To change the default colorscheme, set YT_X_FZF_OPTS env var and give it custom fzf opts.

eg. (.bashrc)

#yt-x
export YT_X_FZF_OPTS=$FZF_DEFAULT_OPTS'
--color=fg:#e0def4,fg+:#e0def4,bg:#232136,bg+:#44415a
--color=hl:#3e8fb0,hl+:#9ccfd8,info:#f6c177,marker:#3e8fb0
--color=prompt:#eb6f92,spinner:#c4a7e7,pointer:#c4a7e7,header:#3e8fb0
--color=border:#44415a,label:#ea9a97,query:#f6c177
--border="rounded" --border-label="" --preview-window="border-rounded" --prompt="> "
--marker=">" --pointer="◆" --separator="─" --scrollbar="│"'

Contribution

Pull requests are highly welcome!

Support

Need help? Join the community on Discord:

Supporting the Project

Give the project a star and consider contributing to the codebase.