YTuff

YTuff is a terminal music player for local files and YouTube Music. it has a full TUI, a background playback daemon, playlists, downloads, lyrics, artwork, media controls, and local library scanning.

first of all, shoutout @Metrolist. they made the API part of the project pretty easy. i personally hate kotlin, but i love what they made out of it. all my best wishes and prayers to you guys.

fun fact: this originally started out as a SoundCloud terminal client, almost an year ago, or atleast i started planning it at that time. because the SoundCloud API said "if your application streams or uses SoundCloud data, it has to have the powered by SoundCloud logo" . well, i can't pay 15usd a month for artist pro. i'm broke. so then, i shifted to YT and well, here we are.

previously named rustplayer, because made in rust and music player, but since the name was taken, ytuff it is.

Features

• Terminal UI for local music and YouTube Music
• Local library scanning
• YouTube Music search
• YouTube playlist, album, artist, and home/library support
• Background daemon for playback
• Queue, history, repeat, shuffle, autoplay, seeking, volume control, and sleep timer
• Playlists stored locally
• Lyrics support
• Downloads as m4a or mp3
• Artwork rendering through wimg, Kitty graphics, Sixel, or block art
• Windows and Linux login window for YouTube Music auth
• OS media controls on Windows and Linux
• Tray support on Windows
• FFmpeg backed streaming and local playback fallback

Development and contributing

Build, packaging, release, repo layout, and development notes live in DEVELOPMENT.md.

Screenshots

result screen

search:

help section

YTuff TUI
Local library + YouTube Music + queue + artwork

Install

Windows

Winget: winget install ytuff

Download the latest Windows installer from Releases:

ytuff-windows-x64.msi

Or, if you want the portable build:

ytuff-windows-x64.zip

The portable Windows release should include:

ytuff.exe
wimg.exe
ffmpeg.exe
ffprobe.exe
WebView2Loader.dll
libgcc_s_seh-1.dll
libjpeg-8.dll
libpng16-16.dll
libsixel-1.dll
libwinpthread-1.dll
zlib1.dll
install-user.bat
install-user.ps1
README.txt
LICENSE

The MSI installs everything into Program Files\YTuff, adds that folder to PATH, and registers uninstall support.

For the portable zip, do not delete the DLL files. They are required by the bundled wimg.exe renderer.

To make the portable zip available from any terminal, run:

.\install-user.bat

Restart your terminal, then run:

ytuff tui

Linux

Arch User Repository(AUR)

yay -S ytuff-bin
yay -S ytuff

links to the packages: https://aur.archlinux.org/packages/ytuff-bin https://aur.archlinux.org/packages/ytuff

Download the Linux tarball, extract it, and run:

./ytuff tui

Install to your user PATH:

./install-user.sh

Then run:

ytuff tui

Linux builds expect system dependencies to be installed through your distro package manager.

Arch / Manjaro:

sudo pacman -S ffmpeg webkit2gtk-4.1 gtk3 alsa-lib

Ubuntu / Debian:

sudo apt install ffmpeg libwebkit2gtk-4.1-0 libgtk-3-0 libasound2

If your distro does not package libwebkit2gtk-4.1, install the closest WebKitGTK 4.1 package available for your release.

Quick start

Start the TUI:

ytuff tui

Search YouTube Music:

ytuff search "daft punk" --limit 10

Play something:

ytuff play "never gonna give you up"

Pause, resume, skip, or stop:

ytuff pause
ytuff resume
ytuff next
ytuff stop

Check status:

ytuff status

Stop the background daemon:

ytuff shutdown

Terminal artwork

YTuff supports multiple artwork renderers.

Set one manually:

Windows PowerShell:

$env:YTUFF_ART="wimg"
.\ytuff.exe tui

Linux shell:

YTUFF_ART=kitty ./ytuff tui

Supported renderer values:

wimg
kitty
sixel
blocks
off

Recommended values:

Windows: wimg
Kitty terminal: kitty
Sixel terminal: sixel
Fallback: blocks
No artwork: off

The Windows release bundles wimg.exe and its DLLs. Linux builds do not need wimg; use kitty, sixel, or blocks.

To force a specific wimg.exe path on Windows:

$env:YTUFF_WIMG="C:\path\to\wimg.exe"

The packaged Windows release should not need this because wimg.exe is bundled beside ytuff.exe.

TUI controls

Press ? or h inside YTuff to open the built in help.

Key	Action
s	Switch local / YouTube mode
/	Search current mode
Enter	Play track, or open selected YouTube playlist or album
Tab	Accept selected YouTube live suggestion
a	Add selected track to queue
c	Clear queue
P	Play selected playlist or album
Q	Queue selected playlist or album
Space	Pause
r	Resume
n	Next track
p	Previous track
R	Cycle repeat off / all / one
z	Toggle shuffle
Left / Right	Seek 5 seconds
b / f	Seek 30 seconds
o	Open selected YouTube link
i	Preview artwork with wimg
S	Save the current playing song to Liked playlist
y	Open lyrics
D	Download selected track, playlist, or album
g	Load YouTube home
m	Load account playlists
u	Go back
A	Toggle autoplay
l	Open YouTube login window
L	Sign out
+ / -	Volume up / down
0	Mute
d	Audio devices
F	Local folders
v	Visualizer
j / k	Move selection
J / K	Move inside queue
M	Minimize to tray
q	Quit or close overlay
Esc	Close overlay or cancel input

Local library

Add a folder:

ytuff library add-path "/path/to/Music"

Windows example:

ytuff library add-path "D:\Music"

List folders:

ytuff library list-paths

Remove a folder by index:

ytuff library remove-path 0

You can also pass scan paths when starting the app:

ytuff --path "/path/to/Music" tui

Supported local file extensions include:

mp3, flac, wav, m4a, ogg, aac, opus, wma

YTuff uses FFmpeg as a fallback for formats that the native decoder does not handle cleanly.

YouTube Music auth

Guest playback works for many tracks, but YouTube can block or limit some requests. Signing in gives YTuff access to personalized home, account playlists, and more reliable playback.

Open the login window:

ytuff auth login

Show current auth state:

ytuff auth show

Import a cookie file:

ytuff auth cookie-file cookies.txt

Import a raw cookie header:

ytuff auth cookie-header "SID=...; SAPISID=..."

Import ytmusicapi headers:

ytuff auth headers-file headers.json

Sign out from the TUI with L.

Queue

Add something to the queue:

ytuff queue add "aphex twin xtal"

Show the queue:

ytuff queue show

Clear the queue:

ytuff queue clear

Playlists

Create a playlist:

ytuff playlist create mix

List playlists:

ytuff playlist list

Show a playlist:

ytuff playlist show mix

Add a track:

ytuff playlist add mix "https://music.youtube.com/watch?v=lYBUbBu4W08"

Import a YouTube playlist or album:

ytuff playlist import "https://music.youtube.com/playlist?list=..." --name my-playlist

Play a playlist:

ytuff playlist play mix

Queue a playlist:

ytuff playlist enqueue mix

Download a playlist:

ytuff playlist download mix --format m4a

Lyrics

Show lyrics for the current track:

ytuff lyrics

Use cached lyrics only:

ytuff lyrics --cached

Return JSON:

ytuff lyrics --json

In the TUI, press y to open lyrics for the current track.

Downloads

Download a track as M4A:

ytuff download "https://music.youtube.com/watch?v=lYBUbBu4W08" --format m4a

Download as MP3:

ytuff download "https://music.youtube.com/watch?v=lYBUbBu4W08" --format mp3

Choose an output folder:

ytuff download "https://music.youtube.com/watch?v=lYBUbBu4W08" --format mp3 --output "/path/to/output"

Windows example:

ytuff download "https://music.youtube.com/watch?v=lYBUbBu4W08" --format mp3 --output "D:\Music"

Autoplay and sleep timer

Enable autoplay:

ytuff autoplay on

Disable autoplay:

ytuff autoplay off

Set a sleep timer:

ytuff sleep 30

Clear the sleep timer:

ytuff sleep --off

JSON output

Some commands support JSON output through the global --json flag.

ytuff --json status

ytuff --json search "boards of canada" --limit 5

Configuration

Print the current config:

ytuff config

YTuff stores config, playlist data, downloads, and cached lyrics in your OS app directories under ytuff.

Important config values include:

quality
scan_paths
autoplay
lyrics_enabled
auto_fetch_lyrics
daemon_addr
downloads_dir
youtube_cookie_header
youtube_cookie_file
youtube_auth_user
start_background_on_boot

Development

Build, packaging, release, repo layout, and ongoing development notes live in DEVELOPMENT.md.

Troubleshooting

Artwork does not show on Windows

Use Windows Terminal and make sure Sixel support is available. Then force wimg:

$env:YTUFF_ART="wimg"
.\ytuff.exe tui

Make sure these files are beside ytuff.exe:

wimg.exe
libgcc_s_seh-1.dll
libjpeg-8.dll
libpng16-16.dll
libsixel-1.dll
libwinpthread-1.dll
zlib1.dll

YTuff is using the wrong wimg.exe

Check PATH:

where.exe wimg

Force the exact renderer:

$env:YTUFF_WIMG="C:\path\to\wimg.exe"

For packaged releases, keep wimg.exe beside ytuff.exe.

Local files show up but do not play

Make sure FFmpeg is available.

Windows packaged release:

ffmpeg.exe
ffprobe.exe

Linux:

ffmpeg -version
ffprobe -version

Test a local file directly:

ffmpeg -v error -i "/path/to/song.m4a" -f null -

On Windows:

.\ffmpeg.exe -v error -i "D:\Music\song.m4a" -f null -

If FFmpeg prints nothing and exits, it can decode the file.

Playback gets weird after rebuilding

Stop the old daemon:

ytuff shutdown

On Windows:

taskkill /IM ytuff.exe /F

Then start again:

ytuff tui

Search works but playback does not

Search and playback are separate paths. Search can work while the daemon or FFmpeg playback path is broken.

Check:

ytuff status
ffmpeg -version

Restart the daemon before testing again.

YouTube playback is blocked

Try logging in:

ytuff auth login

If needed, import headers:

ytuff auth headers-file headers.json

The Windows zip works on your machine but not on another PC

You probably forgot the wimg DLLs, WebView2Loader.dll, or the FFmpeg files. Ship the full Windows file set listed above.