DOCSEARCHbyAlgolia
Submit Docs

yt-x

repository·master·Indexed 23 days ago

https://github.com/benexl/yt-x

A terminal-centric media browser that leverages yt-dlp to search, browse, and download content from YouTube and other supported sites. It integrates with launchers like fzf and rofi, supporting advanced search filters, search history recall via bang syntax, and multiple media players including mpv, vlc, and tplay. It features an extensible system for UI, themes, and languages via shell script extensions.

Tokens
9.7K
Snippets
11
Records
30
Agent score
32%

What's inside yt-x

  1. Overview of yt-x features

    master

    yt-x is a terminal-based or app-launcher-based tool for browsing YouTube and other yt-dlp supported sites.

    Key capabilities include:

    • Launcher Support: Works with fzf and rofi with preview support.
    • Advanced Search: Search for videos, playlists, channels, shorts, or movies using colon-prefixed filters (e.g., :4k, :newest, :video).
    • Search History: Recall previous searches using bang syntax (e.g., !1 for the most recent).
    • Media Management: Access YouTube feeds (Home, Trending, Watch Later, etc.), browse channels, and manage local subscriptions via browser cookies.
    • Playback & Downloads: Supports multiple players (mpv, vlc, tplay), granular downloads (video or audio-only), and organized file structures.
    • Extensibility: Extend functionality via .ui, .theme, .lang, and custom command extensions placed in $HOME/.config/yt-x/extensions/.
    • Cross-Platform: Supports Linux, macOS, Windows (via WSL/MSYS/Cygwin), and Android.

  2. Use inline search filters in yt-x

    master

    You can refine your searches by appending colon-prefixed filters directly to your query.

    Available Filters:

    • 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

  3. Recall previous searches using bang syntax

    master

    yt-x automatically saves your search history. You can quickly recall and re-run previous searches using the ! prefix followed by the search index number.

    • !1: The most recent search.
    • !2: The second most recent search, and so on.

  4. How extensions work in yt-x

    master

    yt-x uses an extension system to add or override functionality without modifying the core script. Extensions are POSIX-compliant shell scripts placed in ~/.config/yt-x/extensions/.

    Because extensions are sourced rather than executed, they run within the main script's context. This allows you to:

    • Override existing functions (e.g., menu_main, _menu_media_actions).
    • Add new menu items by appending to the actions variable.
    • Define new helper functions.
    • Access internal variables and functions (prefixed with _ or public functions like ui_prompt).

    Important Implementation Rules:

    • Do not use exit or exec: These will terminate the entire yt-x session. Use return instead to stop processing the extension script.
    • Command Extensions: If you are creating a command extension (to replace the main menu), your script must define a function named menu_main.

  5. Use Inline Search Syntax and Filters

    master

    When searching (via -s or the interactive prompt), you can append filters to refine results. Only one filter is supported at a time.

    Filters:

    • 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 news :today

    History Recall (Bang Syntax):

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

  6. Access age-restricted or members-only videos

    master

    To access restricted content, you must pass your browser cookies to yt-dlp. You can do this by setting the CONFIG_BROWSER variable in your ~/.config/yt-x/config to a supported browser (e.g., firefox, chrome, brave).

    If your browser is not natively supported (e.g., Zen), you can use a cookie export extension to save a cookies.txt file and pass it via CONFIG_YT_DLP_ARGS="--cookies /path/to/cookies.txt".

  7. Customize menus using extensions

    master

    You can reorder, add, or remove menu entries without modifying the main script by using extensions. Menus are built from lists of actions and can be overridden in extension files (e.g., ~/.config/yt-x/extensions/ui/custom.ui).

    Key menu functions you can override:

    • _menu_main – Main menu (Your Feed, Search, Channels, etc.)
    • _menu_miscellaneous – Misc menu (Explore Channels, Custom Commands, etc.)
    • _menu_channel_actions – Actions inside a channel (Videos, Playlists, Subscribe, etc.)
    • _menu_media_actions – Media action menu (Watch, Listen, Download, etc.)

    All these functions accept four optional arguments: _menu_NAME [sort] [filter_regex] [extra_actions] [handler_function]

    ArgumentPurpose
    sortComma-separated list of line numbers (1-based) to reorder items.
    filter_regexgrep pattern (extended regex) to remove matching lines.
    extra_actionsNewline-separated string of extra menu entries (must include icon and text).
    handler_functionFunction name to call when an extra action is selected.

    Note: Your custom handler receives the selected action text as $1. Return 0 if handled, 1 if not.

    # Example: Remove "Clips" and reorder Search (#2) to the top
menu_main() {
  _menu_main "2,1" "Clips"
}

# Example: Add a custom entry with a handler
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
}

  8. Create a custom yt-x extension

    master

    To build your own extension, follow these steps:

    1. Setup Directory: Create a subdirectory inside ~/.config/yt-x/extensions/ (e.g., ~/.config/yt-x/extensions/my-plugin/).
    2. Write Script: Create a POSIX-compliant shell script.
    3. Implement Logic:
      • To add menu items, append to the actions variable.
      • To replace the main menu, define a menu_main function.
      • To override UI elements, redefine the relevant internal functions.
    4. Test: Run yt-x -x my-plugin/your-script.sh to verify your changes.

  9. Install yt-x on Nix / NixOS

    master

    Imperative Installation

    Use the following command to install directly to your profile:

    nix profile install github:Benexl/yt-x

    Declarative Installation

    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";
  };
}

    System-wide installation (add to configuration.nix):

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

    User-level installation (via Home Manager in home.nix):

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

  11. Prerequisites for yt-x

    master

    Before installing yt-x, ensure your system meets the following requirements:

    Required Dependencies:

    • yt-dlp: For fetching data and downloading media.
    • fzf: The main launcher.
    • jq: For JSON parsing.
    • curl: For fetching script updates and preview images (version 7.6+ required for --parallel support).
    • sh: Any POSIX-compliant shell (e.g., Bash, Zsh, Dash).
    • Nerd Font: Recommended for icon rendering (e.g., JetBrains Mono Nerd Font).

    Optional Dependencies:

    • Media Players: mpv (default), vlc, or tplay.
    • Modern Terminals (True Color support): kitty (recommended), ghostty, or wezterm.
    • Terminal Image Viewers: chafa (cross-terminal), icat (Kitty/Ghostty), or imgcat (iTerm2/WezTerm).
    • Alternate Launcher: rofi.
    • Terminal QoL: gum (UI enhancements) or bat (improved diff viewing).

  12. Configure image previews

    master

    To enable and optimize image previews, ensure the following settings are configured in your ~/.config/yt-x/config:

    1. Enable previews:
      • CONFIG_ENABLE_PREVIEW=true
      • CONFIG_ENABLE_PREVIEW_IMAGES=true
    2. Select a renderer:
      • For Kitty / Ghostty: Use CONFIG_IMAGE_RENDERER="icat"
      • For iTerm2 / WezTerm: Use CONFIG_IMAGE_RENDERER="imgcat"
      • For Other Terminals: Use CONFIG_IMAGE_RENDERER="chafa" (falls back to ASCII/block characters).

    Troubleshooting: If images overlap text, your terminal may not support the clearing sequences used by chafa. If you change renderers, you may need to delete ~/.cache/yt-x/previews/text/fzf-preview.sh to clear old cached values.