ytunes

README

Ytunes v0.1.1

A TUI audio player built in Go and Bubble Tea.

May you never leave your terminal again!

About

yTunes plays audio from a YouTube URL (for now), in your terminal. Paste a link, hit enter, and it plays through mpv with a retro-styled Bubble Tea interface: transport controls, a live progress bar, and a handful of built-in themes.

Motivation

It all started when i was tired to have music playing tabs in chrome eating my RAM while doing works in terminal or some IDE. so i built this.

This started as (and still is) a hands-on Go learning project. I also submitted it as my Capstone Project in Boot.dev. I have used ai for discussing and brainstorming (and fixing the IPC socket because i am not so nerd yet) but most of the code has been generated by me.

Quick Start

Requirements: mpv and yt-dlp must be installed and on your PATH — ytunes shells out to both rather than bundling them (mpv and yt-dlp are their own, separately licensed projects).

Prebuilt binary (no Go required): grab the .tar.gz for your platform from the latest release (linux/darwin, amd64/arm64), then:

brew install mpv yt-dlp   # macOS — or your system's package manager
tar -xzf ytunes_<os>_<arch>.tar.gz
./ytunes

Move the extracted ytunes binary somewhere on your PATH (e.g. /usr/local/bin) if you want to run it as just ytunes from anywhere.

Already have Go?

brew install mpv yt-dlp   # macOS — or your system's package manager
go install github.com/sina96/ytunes@latest

This puts a ytunes binary in $(go env GOPATH)/bin — make sure that's on your PATH.

Don't have Go, or want it built from a local clone? Run the install script — it installs mpv/yt-dlp via your system's package manager (Homebrew on macOS; apt, dnf, or pacman on Linux) if they're missing, then builds and installs the ytunes binary:

./install.sh

Or do it by hand:

brew install mpv yt-dlp   # macOS
# or: sudo apt install mpv yt-dlp   (Debian/Ubuntu)

go build -o ytunes .
./ytunes

Updating

ytunes checks GitHub for a newer release on startup and shows a small notice on the idle screen if one exists — it never downloads or installs anything automatically. Run ytunes --version any time to see what you currently have.

To actually update, use whichever method matches how you installed it:

# Prebuilt binary: download the new release and replace the old binary
# https://github.com/sina96/ytunes/releases/latest

# go install
go install github.com/sina96/ytunes@latest

# local clone
git pull && go build -o ytunes .

# install.sh
git pull && ./install.sh

Usage

The --minimal flag runs a compact, sidebar-free layout. Run ytunes --help for more options.

Enjoy it with your theme choice! dracula, gruvbox, Catppuccin are included!

Known Issues

• First pause/play Latency: the first time you pause, there may be a noticeable delay before the pause is registered. Timer acts weird. Progress bar too. I need to work on this and see how we can make it smoother.
• Windows Support: Not supported yet. Sorry
• Some videos fail to play: YouTube's current anti-bot/PO-Token enforcement blocks some videos for yt-dlp/mpv entirely; this is upstream of ytunes and not something it can fix directly (see yt-dlp's PO Token Guide).

Contributing

• CONTRIBUTING.md — how to build/verify a change locally and what to expect from review.
• CHANGELOG.md — one-liner summary of what each development phase added.
• LICENSE — MIT.

Upcoming features

• Better compact version in IDEs
• Better visuals.
• Other vendors or local file play support.