u/Fragrant-Currency-86

Its been sometime since i made any change to the script, had some free time and decided to go all out

The script has been rewritten improving alot of the existing features and making it easy to maintain and read.

Plus now the script introduces a ton of cmdline options, to make it easier to script and connect to keybinds

Features (from github)

🔍 Search & Discovery

• Comprehensive Search Capabilities: Directly search for videos, playlists, channels, shorts or movies.
• Advanced 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: Deep dive into channels with dedicated menus for Videos, Featured content, Playlists, Shorts, Live Streams, Podcasts, and Channel-specific search.
• Channel Subcommand: Jump directly into a channel from the command line (e.g., yt-x channels -n "Linus Tech Tips" -v) – perfect for scripting and keyboard-driven workflows.

🖥️ User Interface & Experience

• Dual Launcher Support: Operates flawlessly in the terminal using FZF (Fuzzy Finder) or as a graphical desktop menu using Rofi.
• Rich Media Previews: Supports inline previews for search results containing:
  • High-resolution thumbnails rendered directly in the terminal via chafa, icat, kitten icat, or imgcat.
  • Detailed metadata including Channel Name, Follower Count, View Count, Duration, Upload Timestamp, Live Status, and formatted descriptions.
• Theming & Styling: True-color (24-bit) support with a default "Tokyo Night" inspired color scheme. Fully customizable UI formatting.
• Multi-language Support: Loadable language files (.lang) to easily localize the UI prompts and messages.
• Pagination: Smoothly browse through massive lists with Next/Previous pagination controls (fetches a configurable number of items per page, default is 30).
• Selection Skipping: New --playlist-skip (-ps) flag forces the launcher to automatically pick the first item in any list, bypassing interactive selection – ideal for non‑interactive scripts.
• Media Action Shortcuts: Directly perform actions (play, listen, download, save, etc.) without opening the media action menu – see “Media Action Shortcuts” below.

🎬 Playback & Media Handling

• Multiple Player Support: Out-of-the-box integration with mpv, vlc, and tplay.
• Video & Audio Modes: Choose to "Watch" (video) or "Listen" (audio-only, launching without a video window).
• Playlist Actions: Play individual videos, queue/play entire playlists, or queue "Listen to All" for audio-only marathon sessions.
• 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), allowing the UI to remain unblocked while media plays.
• Media Action Shortcuts (Skip the Media Menu):
  • --play / --play-all : Watch selected video or whole playlist.
  • --listen / --listen-all : Audio‑only playback.
  • --download / --download-all : Download video(s).
  • --download-audio / --download-audio-all : Download audio only.
  • --save : Save current video to saved list.
  • --save-playlist : Save current playlist to custom playlists.
  • --shell : Drop into a stateful subshell.
  • Many of these (e.g., --play-all, --save-playlist) implicitly enable --playlist-skip for seamless non‑interactive operation.

💾 Downloading & Archival

• Powered natively by yt-dlp.
• Granular Downloads: Download single videos, entire playlists, or extract audio-only (MP3 format).
• Smart Archiving: Utilizes a download archive directory 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.

📚 Library & Data Management

• Local Subscriptions Sync: Syncs your actual YouTube subscriptions locally by passing browser cookies to yt-dlp, creating a private, locally stored subscription feed.
• 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" natively within the CLI without needing a YouTube account.
• Cookie Integration: Seamlessly imports cookies from installed browsers (Brave, Chrome, Firefox, Safari, Edge, etc.) to access age-restricted or account-specific content.

⚙️ Extensibility & Power User Features

• Custom Commands: Create custom macros that execute specific URLs and yt-dlp options (e.g., setting up a command to browse a completely different streaming site).
• Extension System: Modular architecture allowing the autoloading of custom scripts, sites, themes, and commands placed in $HOME/.config/yt-x/extensions/.
• Stateful Sub-Shell Execution: Drop into a system shell (fish or sh) pre-loaded with the environment variables of your current session (current video title, URL, channel info, etc.) for advanced custom scripting on the fly.
• Desktop Integration: Built-in command (-E) to generate a .desktop entry file, allowing yt-x to be launched natively from application menus (Linux).
• Cache Management: Automatically cleans up stale preview images, auto-generated playlists, and logs older than a configurable retention period (default 7 days).
• Direct Shortcut Flags: Skip the interactive menu entirely with dedicated flags like --feed, --subscriptions-feed, --watch-later, --saved, --recent, --liked, --watch-history, --clips, and more – ideal for keybindings and scripting.
• Non‑Interactive Exit Helpers: --cmd-exit terminates the script after executing a shortcut, while --media-exit does the same after any media action – perfect for one‑off commands and aliases.
• Direct Access to Saved Items: Open a specific saved video (-sv, --saved-video), custom playlist (-cp, --custom-playlist), or custom command (-cc, --custom-cmd) without browsing menus, with tab completion in supported shells.

🛠️ Cross-Platform & Infrastructure

• 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).
• Configuration Management: Generates a robust config file automatically on first run. Allows editing configuration files directly from the UI menu.
• Auto-Updater: Built-in update checker that securely pulls the latest version from GitHub and prompts the user to apply updates inline.
• Shell Completions: Generates native shell autocomplete definitions (fish, with dynamic channel name completion from subscriptions.json, custom playlist and saved video name completion, and extension completion from ~/.config/yt-x/extensions/).

link

The readme is mostly generated by ai due to time constraints and effort required. But it was fully involved it did most of the writing and i did the thinking and even with it it took hours. I just did not want to spend several more weeks on a readme(1000+ lines) after manually rewriting the script which is now over 4k+ lines/