shellwave

A terminal-first YouTube audio player for developers.

Search from your terminal, pick a result with the keyboard, and play audio without opening a browser.

Install

npm install -g shellwave

If global npm installs fail with a permissions error, see Install Troubleshooting.

Requirements

Search works out of the box. Playback needs:

• mpv or ffplay, included with FFmpeg. mpv is preferred when available.
• yt-dlp, used to resolve YouTube audio URLs

Ubuntu/Debian:

sudo apt install mpv
sudo apt install pipx
pipx install yt-dlp

If you prefer FFmpeg tools, sudo apt install ffmpeg also works.

If your shell cannot find yt-dlp, add ~/.local/bin to your path.

fish:

fish_add_path ~/.local/bin

Bash/Zsh:

export PATH="$HOME/.local/bin:$PATH"

Alternative pip install:

sudo apt install python3-pip
python3 -m pip install --user -U yt-dlp

If Ubuntu blocks pip with an externally managed environment warning, use the pipx method above.

macOS:

brew install mpv yt-dlp

Windows:

winget install Gyan.FFmpeg
winget install yt-dlp.yt-dlp
winget install mpv.mpv

If mpv is available through your package manager, install it for the preferred playback backend.

Check your setup:

shellwave doctor

Usage

Search and play:

shellwave lofi coding music

or:

shellwave search "lofi coding music"

Check playback dependencies:

shellwave doctor

Controls:

Up/down      choose a search result
Enter        play selected result
a            add selected result to a playlist
Left/right   seek backward/forward
Space        pause/resume
s            stop and return to results
q            quit

When a track completes, shellwave automatically starts the next result from the current search list. If playback stops early, shellwave keeps the current result selected instead of skipping ahead.

Playlists

Add the selected search result to a playlist by pressing a:

a

If playlists exist, you'll be prompted to choose one. If no playlists exist, you'll be prompted to create a new one. The track is then saved to the selected or newly created playlist.

Manage playlists from the command line:

shellwave playlist list
shellwave playlist create favorites
shellwave playlist show favorites
shellwave playlist add favorites "https://www.youtube.com/watch?v=VIDEO_ID"
shellwave playlist play favorites
shellwave playlist remove favorites 1
shellwave playlist delete favorites

Shortcut:

shellwave pl play favorites

Playlists are stored locally at ~/.config/shellwave/playlists.json on Linux, or under your XDG_CONFIG_HOME if it is set.

Install Troubleshooting

EACCES during global install

If npm install -g shellwave fails with an error like:

EACCES: permission denied, mkdir '/usr/local/lib/node_modules/shellwave'

your npm global install directory is owned by root. Check it with:

npm config get prefix

If it prints /usr/local, prefer a user-owned npm prefix:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global

fish:

fish_add_path ~/.npm-global/bin

Bash/Zsh:

export PATH="$HOME/.npm-global/bin:$PATH"

Then install again:

npm install -g shellwave

For a longer-term Node setup, use a user-owned version manager such as nvm, fnm, or volta.

Search Providers

By default, shellwave uses a bundled no-key YouTube search provider. You do not need a YouTube API key for normal use.

Force the default no-key provider:

SHELLWAVE_SEARCH_PROVIDER=youtubei shellwave lofi coding music

Use the official YouTube Data API for search metadata:

export YOUTUBE_API_KEY=your_key
SHELLWAVE_SEARCH_PROVIDER=youtube-api shellwave lofi coding music

PowerShell:

$env:YOUTUBE_API_KEY="your_key"
$env:SHELLWAVE_SEARCH_PROVIDER="youtube-api"
shellwave lofi coding music

Use yt-dlp for search:

SHELLWAVE_SEARCH_PROVIDER=yt-dlp shellwave lofi coding music

Troubleshooting

If playback fails with a YouTube extraction error, update yt-dlp:

pipx upgrade yt-dlp

If playback starts but you hear no sound, verify your system audio works with mpv or ffplay and that your terminal session has access to your audio server.

Local Development

npm install
npm run build
npm link
shellwave ektaara

Run checks:

npm run typecheck
npm --cache .npm-cache pack --dry-run