lastwave · terminal YouTube Music client

A cross-platform terminal YouTube Music client — browse the latest releases, search the full catalog, stream high-quality audio through mpv + yt-dlp, and sing along to synced lyrics (LRCLIB). Made by Nishal.M.

Runs on Windows, macOS, and Linux. Works guest-only, or with your own Google cookies for a personalized Home / Library.

┌ lastwave · terminal · yt music ──────────────────────▶ ON AIR · Daft Punk — Instant Crush ┐
│ View            │  Home · music · trending · mixes                                        │
│ ▶ Home        h │  ── Today's hits                                                       │
│   Explore    e  │    ▶ ♫ Pop Certified                …                                   │
│   Search     s  │      ♫ seniorita                      …                                   │
│   Queue      c  │                                      …                                   │
│   Library    a  │  ── New releases                     ...                                │
│   Liked      f  │                                      …                                   │
├─────────────────┼─────────────────────────────────────────────────────────────────────────┤
│ ▶ Instant Crush — Daft Punk · Julian Casablancas          ♪ LRC                            │
│   1:12 ━━━━━━━━━━━╸━━━━━━━━━━━ 5:38       ◔ vol 70                                        │
│ ↑/↓ move · Enter play · Space pause · j/y seek · ←/→ seek5 · n next · p prev …  q back/quit │
└────────────────────────────────────────────────────────────────────────────────────────────┘

Requirements

• Node.js 18+ (npm ships with it)
• mpv — the audio engine
• yt-dlp — extracts the YouTube Music streams for mpv

Install

The small command — works on Windows, Arch, and any OS with Node 18+:

npm i -g lastwave     # installs the app + all npm dependencies
lastwave --setup          # installs mpv + yt-dlp (the playback engine)
lastwave                  # start

lastwave --setup fetches the native playback tools with winget / pacman / apt / dnf / brew. Then just run lastwave. Verify anytime:

lastwave --doctor

Why two steps? npm 11+ blocks package install scripts by default (allow-scripts), so --setup is the reliable way to get mpv + yt-dlp on every npm version. No global install? Try npx lastwave.

From source (alternative)

git clone https://github.com/YOU/lastwave.git && cd lastwave
npm install
npm install -g .        # Windows: run PowerShell as needed; Arch: prefix with sudo
lastwave

Or use the bundled installers: scripts\install-windows.ps1 (Windows), ./scripts/install-arch.sh (Arch), ./scripts/install.sh (other Linux/macOS).

Manual install (any OS)

# ensure node/mpv/yt-dlp are installed, then:
npm install
npm install -g .
lastwave

Optional: connect your YouTube account

Browsing/searching/streaming works without an account. For login-gated data (your library, liked songs, personalized Home), export your browser cookies:

1. Install the "Get cookies.txt LOCALLY" browser extension (Chrome/Firefox).
2. Export cookies for music.youtube.com as cookies.txt.
3. Import into lastwave:

lastwave --import-cookies /path/to/cookies.txt

Usage

| Key(s) | Action | | --- | --- | | ↑ ↓ PgUp PgDn Home End | move selection | | Enter | play selected / open album·artist·playlist | | Space / k | play / pause | | j / y | seek −10s / +10s | | ← → , . | seek −5s / +5s | | [ ] / - = | volume down / up | | m | mute | | n / p | next / previous track | | l | now-playing + synced lyrics | | r | start radio from a song | | s or / | search | | 1..5 Tab | search category (songs/albums/artists/playlists/videos) | | z / x | shuffle queue / toggle autoplay | | d / D | download track / entire page to ~/Music/LastWave (with .lrc) | | f | like / unlike | | h e c a | Home / Explore(latest) / Queue / Library | | ? | help | | q or Esc | back / quit |

Commands

lastwave                # launch the TUI
lastwave --setup        # install mpv + yt-dlp (playback engine)
lastwave --doctor       # verify mpv + yt-dlp + node
lastwave --help         # CLI help & hotkeys
lastwave --version

Troubleshooting

• "mpv not found" — install mpv/yt-dlp and reopen your terminal, or point to custom binaries: SET LASTWAVE_MPV=C:\path\mpv.exe.
• No playback — run lastwave --doctor; if a tool is missing, rerun the installer.
• Login not applied — the import must be a Netscape-format cookies.txt (use the Get cookies.txt LOCALLY extension).

Credits

• Streaming metadata via youtubei.js
• Playback via mpv + yt-dlp
• Lyrics via LRCLIB (backed by Apple Music, Musixmatch, etc.)
• TUI via Ink
• Inspired by LastWave — the audiophile YT Music app.

GPL-3.0 · made by Nishal.M