Name: mpv-music
Author: furqanhun

███╗   ███╗██████╗ ██╗   ██╗
████╗ ████║██╔══██╗██║   ██║
██╔████╔██║██████╔╝██║   ██║
██║╚██╔╝██║██╔═══╝ ╚██╗ ██╔╝
██║ ╚═╝ ██║██║      ╚████╔╝
╚═╝     ╚═╝╚═╝       ╚═══╝

███╗   ███╗██╗   ██╗███████╗██╗ ██████╗
████╗ ████║██║   ██║██╔════╝██║██╔════╝
██╔████╔██║██║   ██║███████╗██║██║
██║╚██╔╝██║██║   ██║╚════██║██║██║
██║ ╚═╝ ██║╚██████╔╝███████║██║╚██████╗
╚═╝     ╚═╝ ╚═════╝ ╚══════╝╚═╝ ╚═════╝

Music for your terminal.
Blazing fast, Rust native 🦀.
Stable v0.29.0+ available.

Rust (1.93.0+)

cargo install mpv-music

Linux / macOS

curl -sL https://raw.githubusercontent.com/FurqanHun/mpv-music/master/install.sh | bash

Windows (PowerShell)

iwr https://raw.githubusercontent.com/FurqanHun/mpv-music/master/install.ps1 -UseBasicParsing | iex

Or download binary manually (Direct Downloads)

Latest Stable: Checking...

Dev Channel: ...

Showcase

Direct CLI Experience

Terminal recording showing playback of an artist's tracks using -a ado -p, skipping to the next song with Enter, and title searching with -t viva

Interactive TUI Experience

Terminal recording showing interactive mode selection, fuzzy searching with live metadata preview, queuing multiple tracks with Tab, and playback skipping with Enter

Supported Systems

Linux (x86_64, ARM64), BSD/macOS, WSL, Windows

Why?

While I do appreciate a good GUI, I prefer my tools to be lightweight, incredibly fast, and follow the UNIX philosophy. There's an abundance of terminal music players and scripts out there, but they almost always try to do too much—whether it's rendering heavy visualizers, managing podcasts, or running background daemons (which I'm firmly against for a simple music app).

I just wanted something that plays music and gets out of the way, without reinventing the wheel. I love mpv and yt-dlp, and since they are already installed on my system, why write a custom audio engine from scratch? It's not that I hate having multiple tools doing similar things, but I have a strong personal bias toward mpv. Because no existing player fit my workflow, I built a blazing-fast Rust frontend around the tools I already use and love.

Manifesto & Features

Do One Thing Well: Stay lightweight and never chew more than what should be chewed. No daemons, no background services, no feature bloat.
Forgiving & Smart CLI: Powerful command-line filters. If your query has exactly one match, it auto-plays instantly. If it's ambiguous, it safely drops you into the interactive picker.
Minimal TUI Menu: Initially added because an early tester hated CLI arguments, but having a minimal interactive menu actually ended up being much smoother for browsing the library.
Keyboard Native: Designed for an entirely keyboard-driven workflow. (Though the UI technically supports mouse clicks, the keyboard is just faster).
Radio & Web Streams: Seamless integration with ad-free internet radio streams (SomaFM, LISTEN.moe, Lofi) and native YouTube streaming.
Terminal-Native Aesthetics: Standard emojis by default for 100% out-of-the-box reliability, plus optional Symbols Nerd Font support (Mono & Normal) for crisp monochrome icons that automatically blend into your terminal's color theme.

Usage

Simply run mpv-music to launch the interactive TUI, or use arguments for instant playback:

mpv-music -a "Daft Punk" (Filter by artist, instant-play if 1 match)
mpv-music --radio lofi (Jump straight into ad-free Lofi Hip Hop)
mpv-music --yt "never gonna give you up" (Search & stream directly from YouTube)
mpv-music "https://youtu.be/..." (Instantly play a URL)
mpv-music --help (See all available commands and shortcuts)

For full documentation, configuration options, and keybindings, please refer to the README.