ytsurf

YouTube in your terminal. Clean and distraction-free.

demo

Features

Syncplay support – watch videos together in sync
Audio-only playback & downloads
Download videos or audio
Interactive format/quality selection when playing or downloading
External config file
Playback history and quick re-play
Adjustable search result limit
Custom download directory
Self-update (--update) for manual installations only
Copy short YouTube URLs to clipboard or print them
Channel subscriptions with a personalized feed
Import subscriptions from youtube

Selector	Features	Best For
fzf (default)	Terminal-based, thumbnail previews, lightweight	Most users (fast + previews)
rofi	GUI menu, keyboard-driven, clean look	Users who prefer a graphical menu
sentaku	Very minimal, no previews	Systems without Go/`fzf` support

Installation

Arch Linux (AUR)

yay -S ytsurf
# or
paru -S ytsurf

Homebrew

brew tap stan-breaks/ytsurf https://github.com/stan-breaks/ytsurf
brew install stan-breaks/ytsurf/ytsurf

NixOS (system-wide, flakes)

In your flake.nix (system config)


{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    ytsurf.url = "github:Stan-breaks/ytsurf";
  };
outputs = { self, nixpkgs, ytsurf, ... }:
let
system = "x86_64-linux";
in {
nixosConfigurations.thanaros = nixpkgs.lib.nixosSystem {
inherit system;
modules = [
({ pkgs, ... }: {
nixpkgs.overlays = [
ytsurf.overlays.default
];
      environment.systemPackages = with pkgs; [
        ytsurf
      ];
    })
  ];
};

};
}

Manual Installation

mkdir -p ~/.local/bin
curl -o ~/.local/bin/ytsurf https://raw.githubusercontent.com/Stan-breaks/ytsurf/main/ytsurf.sh
chmod +x ~/.local/bin/ytsurf

Make sure ~/.local/bin is in your PATH.

Dependencies

Required: bash, yt-dlp, jq, curl, mpv, fzf, chafa, ffmpeg
Optional: rofi, sentaku, syncplay

Arch Linux install:

sudo pacman -S yt-dlp jq curl mpv fzf chafa rofi ffmpeg

Usage

USAGE: ytsurf [OPTIONS] [QUERY] OPTIONS: --audio Play/download audio-only version --download Download instead of playing --format Interactively choose format/resolution --rofi Use rofi instead of fzf for menus --syncplay Watch youtube with friend from the terminal --subscribe, -s Add a channel to subscriptions locally --unsubscribe Remove a channel to subscriptions locally --import-subs Import subscriptions from youtube --feed,-F View videos from your feed --sentaku Use sentaku instead of fzf or rofi(for system that can't compile go) --history Show and replay from viewing history --limit <N> Limit number of search results (default: $DEFAULT_LIMIT) --edit, -e edit the configuration file --help, -h Show this help message --version Show version info --copy-url Copy or display the video link

EXAMPLES: ytsurf lo-fi study mix ytsurf --audio orchestral soundtrack ytsurf --download --format jazz piano ytsurf --history

Run ytsurf without arguments to enter interactive mode.

Configuration

Defaults check for default config in ~/.config/ytsurf/config. CLI flags always override config values.

Example config:

# ~/.config/ytsurf/config Set a higher default search limit limit=25 Always use audio-only mode audio_only=true Set a custom download directory

download_dir="$HOME/Videos/YouTube"

Troubleshooting

MPV doesn't play the selected video

Some systems have mpv configured to prefer youtube-dl instead of yt-dlp, which causes ytsurf to show “playing…” without actually starting playback.

Fix: Rename your yt-dlp binary so that MPV uses it automatically:

sudo mv /usr/bin/yt-dlp /usr/bin/youtube-dl

Or create a symlink instead (safer):

sudo ln -s /usr/bin/yt-dlp /usr/local/bin/youtube-dl

MPV will now correctly pick up yt-dlp for streaming.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md. Check out FUTURE_FEATURES.md for upcoming ideas.

License

Released under the GNU General Public License v3.0.

NAME

SYNOPSIS

INFO

DESCRIPTION

README