drift/README.md

Drift

A YouTube Music player for your terminal, with Vim keybinds.

Search, queue and play music with no account, no login and no browser.

---

---

Features

• Vim-style keybinds - j/k, gg/ge, counts like 5j, and : for the command line
• Synced lyrics - a side panel or fullscreen view that highlights the current line and fills it in as it's sung
• Queue & playlists - build a queue, save and reorder playlists, or import any YouTube / YouTube Music playlist by URL
• Discovery - press ga for an artist's songs, gs for similar songs, or use :album and :playlist to search albums and playlists
• Song menu - press G on a song to play it, qeue it, add it to a playlist, jump to the artist or see its info
• Command palette - :search, :seek, :vol, :import and more, with completion and history
• Picks up where you left off - your queue and position are restored the next time you start Drift
• Desktop integration - media keys and playerctl on Linux (MPRIS), plus optional Discord rich precense
• Configurable - volume, seek step, shuffle/repeat defaults, accent color, custom keybinds and more in a single TOML file

Installation

Drift needs mpv for playback and yt-dlp for stream extraction. Run drift --check at any time to verify both are installed.

Arch Linux (AUR)

yay -S driftmusic-git

Any AUR helper works, or build it by hand:

git clone https://aur.archlinux.org/driftmusic-git.git
cd driftmusic-git
makepkg -si

mpv and yt-dlp are installed automatically.

Install script

On Arch, Debian/Ubuntu, Fedora, openSUSE, Gentoo & Void the install script installs the dependencies and builds Drift with cargo:

git clone https://github.com/socatlolmeow/drift.git
cd drift
./install.sh

From source

Install the dependencies and Rust, then:

git clone https://github.com/socatlolmeow/drift.git
cd drift
cargo install --path .

This puts drift in ~/.cargo/bin/, which is on your $PATH if you installed Rust with rustup.

Installing mpv and yt-dlp manually

Platform	Command
Debian / Ubuntu	sudo apt install mpv and pipx install yt-dlp
macOS	brew install mpv yt-dlp
Arch	sudo pacman -S mpv yt-dlp
Windows	winget install mpv.net yt-dlp.yt-dlp or scoop install mpv yt-dlp

Usage

drift                    # start the player
drift "daft punk"        # start with a search
drift --check            # verify mpv and yt-dlp are installed

Press / to search, Enter to play, a to queue and ? for the full list of keybinds.

Keybinds

Key	Action
j k / ↓ ↑	move (counts work: 5j)
gg ge	jump to top / bottom (5gg goes to row 5)
Tab Shift-Tab	cycle Results / Queue / Playlists
gr gq gp	jump to Results / Queue / Playlists
Enter	play the selected song
Space	pause / resume
n N	next / previous track
h l / ← →	seek back / forward (counts: 6l)
+ -	volume up / down
s r	toggle shuffle / cycle repeat
a A P	queue the song / queue all results / play all results
dd x	remove from queue or playlist
J K	move a queue or playlist item down / up
G	song menu
ga	go to the artist
gs	see similar songs
gb	go to the album
gB	save the album as a playlist
L	toggle the lyrics panel
F	fullscreen lyrics
/ :	search / command line
?	help
q	quit

These are the defaults. See Custom keys to change them.

Commands

Command	Action
:search "query"	search YouTube Music
:play [N]	play or resume, or play row N
:seek 90 1:30 +10	absolute or relative seek
:vol 50 +5	set or change the volume
:shuffle :repeat [off|all|one]	playback modes
:add [N] :addall :playall	queue results
:save name :load name :append name	work with playlists
:savealbum [name] :saveresults [name]	save album or results directly as a playlist
:addto name :delpl name	add a song to / delete a playlist
:import URL	import a YouTube / YouTube Music playlist
:album [query]	open the selected song's album, or search albums
:playlist query	search YouTube Music playlists
:similar	radio: songs similar to the selected one (also :radio)
:artist	songs by the selected song's artist
:lyrics	toggle the lyrics panel

Lyrics

Press L for a side panel (needs a terminal at least 70 columns wide) or F for fullscreen. The current line is highlighted and fills in as it's sung. Songs without synced lyrics show plain text you can scroll with j/k.

Lyrics come from LRCLIB and are only fetched while the panel or fullscreen view is open.

Configuration

Settings live in config.toml inside Drift's config directory (~/.config/drift/ on Linux). Drift only reads the file and never rewrites it, so your comments are safe. Restart Drift after editing.

[playback]
volume = 80
shuffle = false
repeat = "off"        # off, all or one
autoplay = false
restore_session = true
seek_step = 5.0
volume_step = 5.0

[artist]
popular_first = false

[ui]
accent = "cyan"       # a color name or a hex value like "#FF8800"

[discord]
client_id = ""        # change this for Discord RPC to work in Drift

[audio]
download = false              # false: stream songs; true: download to the cache first
download_max_minutes = 15     # with download = true, longer songs are still streamed (0 = no limit)
cookies_from_browser = ""     # e.g. "firefox" or "chrome"; passed to yt-dlp when YouTube blocks playback

By default Drift streams songs, so playback starts right away even for hour long tracks. Set download = true to cache songs on disk first (this also prefetches the next song). If YouTube asks you to sign in or playback fails, set cookies_from_browser to the browser where youre logged into YouTube. If you alr have a config.toml, add the [audio] section by hand, since Drift never rewrites it.

Custom keys

The keys in the table above are the defaults. To change them add a [keys] section to config.toml. Each line sets an action to one key or a list of keys and replaces that action's default keys; everything you leave out keeps its default.

[keys]
quit = "Q"
move_down = ["j", "down", "ctrl+n"]
move_up = ["k", "up", "ctrl+p"]
go_top = ["gg", "home"]
shuffle = []                  # an empty list unbinds the action

A key is a character ("x", "G", "/"), a name (space, enter, esc, tab, backtab, backspace, delete, insert, home, end, pageup, pagedown, up, down, left, right, menu, f1 to f12), ctrl+ plus a key, or a sequence like "gg" or "ctrl+x g". Counts (5j) keep working on any binding. If you bind a key that is a default of another action, the other action loses it. A mistake in [keys] shows a message at startup and falls back to the default keys.

Action	Default keys
move_down move_up	j down / k up
half_page_down half_page_up	ctrl+d / ctrl+u
page_down page_up	ctrl+f pagedown / ctrl+b pageup
go_top go_bottom	gg home / ge end
next_view prev_view	tab / backtab
view_results view_queue view_playlists	gr / gq / gp
activate	enter
pause	space
next prev	n > / N <
seek_back seek_forward	h left / l right
volume_up volume_down	+ = / - _
add add_all play_all	a / A / P
delete	x delete dd
move_item_down move_item_up	J / K
shuffle repeat	s / r
menu	G menu
go_artist go_similar go_album save_album	ga / gs / gb / gB
lyrics_panel lyrics	L / F
search command	/ / :
help	?
quit	q
back	backspace esc

In the Playlists tab seek_forward opens the selected playlist, and seek_back or back leaves it. Only the main view is remappable; popups, the command line and fullscreen lyrics keep their own keys, and the in-app help (?) still lists the defaults.

Set DRIFT_CONFIG_DIR or DRIFT_STATE_DIR to change where Drift keeps its config, playlists and session.

Contributing

Bug reports, ideas and pull requests are welcome. See CONTRIBUTING.md before you start.

Star History

License

Drift is free software, released under the GNU General Public License version 3 or later.