youtube-viewer

Search for a video

$ youtube-viewer [search_term]

$ youtube-viewer --login

$ youtube-viewer --player=[vlc] [https://youtube.com/watch?v=dQw4w9WgXcQ]

$ youtube-viewer -[7]

youtube-viewer [OPTIONS] [QUERY | URL]

-s, --search QUERY
    Searches for videos matching the specified query.

-p, --play NUMBER
    Plays the Nth video from the current search results or playlist.

-u, --url URL
    Plays the video from the given YouTube URL.

-q, --dl-quality QUALITY
    Specifies the download quality (e.g., 'medium', 'high', 'best').

-o, --order-by ORDER
    Orders search results by 'relevance', 'upload_date', 'view_count', 'rating'.

-m, --max-results N
    Limits the maximum number of search results to display.

--playlist-start N
    Starts playback from the Nth item in a playlist.

--no-colors
    Disables colored output in the terminal.

--safe-search
    Enables safe search for filtered content.

-h, --help
    Displays the help message and exits.

-v, --version
    Displays program version information and exits.

youtube-viewer is a Linux command-line utility designed to browse, search, and play YouTube videos directly from your terminal. It offers an ncurses-based interactive interface, allowing users to navigate YouTube content without needing a web browser or graphical environment. This makes it particularly useful for remote servers, low-resource systems, or simply for users who prefer to stay within a terminal-centric workflow.

The command acts as a frontend, leveraging external tools like youtube-dl (or its successor, yt-dlp) to extract video information and stream URLs, and then piping these streams to a media player such as mpv for actual playback. Users can perform video searches, view search results, access video details, and initiate playback, all through text-based interactions. While it provides a convenient way to access YouTube, its functionality heavily relies on the stability of YouTube's API and the continuous updates of its backend dependencies.

youtube-viewer is largely considered a discontinued or unmaintained project. Due to frequent changes in YouTube's API and website structure, the command's functionality can often break without updates. Users are advised to ensure their youtube-dl or yt-dlp dependencies are up-to-date for the best chance of successful operation. It also relies heavily on external media players like mpv for playback, which must be installed and configured separately.

youtube-viewer functions primarily as an interactive frontend. When a user searches or selects a video, it internally calls youtube-dl (or a configured alternative like yt-dlp) to parse the YouTube page, extract direct video stream URLs, and retrieve metadata. Once a stream URL is obtained, it then pipes this URL to an external media player, most commonly mpv, for actual video and audio playback. This modular approach allows youtube-viewer to abstract the complexities of video fetching and playback, relying on specialized tools for those tasks.

Developed as an elegant solution for terminal-based YouTube consumption, youtube-viewer gained popularity among power users and those working in SSH environments. Its design aimed to provide a lightweight, interactive experience for searching and playing videos without a full browser. However, the continuous evolution of YouTube's underlying technology, particularly its API and video serving mechanisms, posed a significant maintenance challenge. Keeping the project functional required constant updates to adapt to these changes. Over time, active development waned, leading to its current status as an unmaintained tool, with many users opting for direct `mpv` integration with `yt-dlp` as a more robust alternative.

youtube-dl(1), yt-dlp(1), mpv(1), curl(1)