ytermusic: a terminal YouTube Music player with a local cache

A terminal player with a cache instead of a browser

YTerMusic is described as a TUI based YouTube Music player that aims to be as fast and simple as possible, and the project description adds the three words that explain the design: privacy, simplicity and performance.

What it does is narrow and clear. You can play your YouTube Music Playlist and Supermix. It caches all downloads and stores them, and it works even without a connection if the music was already downloaded. There is an automatic background download manager, so the cache fills while you listen rather than only when you ask.

The performance claim is specific. The feature list says memory efficient, around 20MB of RAM while fully loaded. For a terminal application that is a striking figure, and it is consistent with the architecture visible in the workspace layout, where there is a separate crate for the database, the download manager, the player and the API client. The changelog gives a hint about how it got there: a local database cache was added to improve IO accesses, and later the render performance and RAM usage were greatly improved.

The TUI itself is a list-driven interface with a playlist selector, and the screenshots show a playlist view with a colour scheme behind it. The feature list also records mouse support, search, shuffle, error message display in the TUI, and custom theming where you can use hex values, with an example of #05313d given alongside a colour swatch image.

The unchecked item in the checklist is the cache limit to not exceed some given disk space, which is worth noting because a download manager that caches everything without a cap is a slow way to fill a disk.

The project is written in Rust, licensed under Apache-2.0, and the last push was on 2026-05-13. The releases are betas: beta 0.1.5 from 2025-12-19, beta 0.1.3 from 2025-12-15 and beta 0.1.0 from 2024-02-12.

Installing the audio libraries and building the binary

Installation has two routes, and the libraries are the part people get wrong.

The system packages for Linux are:

	sudo apt install alsa-tools libasound2-dev libdbus-1-dev pkg-config

Those are the ALSA tools and headers, the D-Bus development package and pkg-config. A terminal music player has to reach the sound server, so the ALSA and D-Bus headers are a compile-time requirement rather than a runtime one.

With the libraries in place, cargo installs the latest version:

	cargo install ytermusic --git https://github.com/ccgauche/ytermusic

The `--git` flag means you are installing from the repository rather than from a crates.io release, which is a reasonable choice for a project whose releases are betas.

There is also a binary route. You can download the latest version from the releases page, and the README notes that third party AUR packages are available for Arch users.

Building from source has its own requirements, and they are stricter than the install. You clone the repository, install Rust nightly from rustup, and run:

Run `cargo build --release`.

The executable is then in target/release/ytermusic.exe or target/release/ytermusic. The nightly requirement is because the project depends on features that are not yet stable, which is a reasonable thing for a TUI to need and a mild annoyance for anyone whose toolchain is pinned to stable by a team policy.

The Cargo workspace is a cargo resolver version 3 workspace with six member crates: common-structs, database, download-manager, player, ytermusic and ytpapi2. The last of those is the YouTube Music API client, and the shared workspace dependencies section wires the internal crates to each other by path rather than by version, which is what keeps a monorepo of six crates consistent.

Authentication is a copied cookie, and the Raw switch matters

The setup section is the most unusual part of the project, and it is worth reading carefully before you start.

There is no OAuth flow and no login screen. You give ytermusic authentication to your account by copying out the headers, in a seven step manual process. Open the music.youtube.com website in your browser, open the developer tools, go to the Network tab, find the request to the music.youtube.com document slash page, copy the Cookie header from the associated response request, and create a headers.txt file in one of the checked paths. Then you create an entry like this:

	Cookie: <cookie>
	User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.0.0 Safari/537.36

The path is not arbitrary. The documentation links to the directories crate, the ProjectDirs struct and its config_dir method, and says the file must go in one of the checked paths. The changelog records that the location of the cache folder was changed to follow the XDG Base Directory Specification, so both the cache and the headers file end up in a standard place rather than wherever the binary happened to be run from.

The one instruction marked as important in the README is about Firefox. If you are using Firefox, enable the Raw switch so the cookie is not mangled. There is a screenshot of the setting next to it.

That detail is the difference between working and not working, and the reason it is called out is that Firefox rewrites cookie values by default for privacy reasons. A mangled cookie is not an invalid cookie, it is a valid but different value, so the server rejects it in a way that does not obviously point at the browser. The changelog shows the project has been through this: error messages for invalid headers or cookies and for expired cookies were both added in alpha 0.0.11, so at least the failure mode is now explained by the app rather than silent.

There is an optional extra for people with a brand account. You switch to your brand account in the Google account page, copy the number written in the URL, and paste it into a new account_id.txt file in the same folder as the headers file.

The key bindings and the maintenance commands

The usage section is a complete keymap, and it reads like a music player rather than a terminal tool.

Space plays and pauses, Enter selects a playlist or a track, f searches, s shuffles, and r removes a track from the main playlist. The arrow keys and the angle bracket keys move through the timeline: right or greater-than skips five seconds, left or less-than goes back five seconds, and with Control held, right goes to the next song and left to the previous one. Plus and minus change the volume, the up and down arrows scroll, Escape exits the current menu, and Control+C or Control+D quits. The mouse works too, if the terminal supports it, for clicking in lists.

The horizontal versus vertical split is worth noting. The horizontal pair seeks within a track, the Control-modified pair changes track, and the vertical pair scrolls. That is a sensible layout for a terminal player, where horizontal space is used for the progress bar and vertical space for the list.

Then there are the three maintenance commands, which exist because the app maintains a local cache database:

ytermusic --fix-db

ytermusic --clear-cache

ytermusic --files

The first tries to fix any issues with the cache database, the second clears the cache, and the third reports issues or finds the files related to ytermusic, which is the command to run before filing a bug since it produces the paths the maintainer will ask for.

Having a repair command for the database is a sign of how much state the app keeps locally, and the changelog shows that state being added incrementally. Alpha 0.0.5 added the local database cache to improve IO accesses, alpha 0.0.3 added the download limiter and connectionless music playing, and alpha 0.0.7 fixed a log file bloat issue and made major changes to the API.

The changelog is unusually detailed for a small project, and it documents the sort of changes you would not find in a release note, such as fixing music artists getting smashed together, changing how tasks are distributed to the thread pool, and switching to Rustls instead of openSSL.

Against a browser player and against a local music library

The comparison worth making is with the two alternatives you already have: the YouTube Music web player and a local music directory with any terminal player.

Against the web player, the difference is that YTerMusic is a native binary that starts instantly, uses a fraction of the memory, and keeps a cache on your disk. The privacy angle is the more interesting one, though it needs to be stated precisely. The project describes itself as focused on privacy, but the authentication mechanism is a cookie copied out of a browser session, and the audio itself is downloaded from YouTube. So the privacy claim is about the application being a local binary with no account of its own and no tracking of its own, rather than about the traffic being different from what the browser does. The cache is also on your disk in a standard location, and the app is told to work offline from it, so downloaded music persists after the fact.

Against a local library, the trade runs the other way. A local player over your own files is offline, has no authentication step, and no dependency on a service that can change its API underneath you. YTerMusic gives you a catalogue you did not have to assemble, a search across the YouTube Music library, and a Supermix. What it costs is the cookie setup, the fact that a service change can break downloads, and the fact that the project is in beta with a 2025 release line.

That last point is the real risk. The changelog shows the project reacting to service changes, with a beta 0.1.0 entry that includes fixed youtube downloads and improved performance and updated dependencies, and a beta 0.1.1 entry that fixed the default style to support transparency and added more colour configuration options. A client of an undocumented web API will keep needing that kind of maintenance, and the beta tag on every release is an honest signal of it.

For the specific use case the project targets, someone who works in the terminal all day, wants the music playing while they do, and does not want a browser tab, the trade is clearly worth it. For anyone who just wants their own files playing, a local player is simpler and more reliable.

Editorial conclusion

Adopt ytermusic if you want a terminal-native YouTube Music player that keeps a local cache and works offline, and you are willing to do the one-off cookie setup. Do not adopt it if you need a signed release rather than a beta, since the tags are beta versions and the newest listed one is beta 0.1.5, and check first that the cookie you copy is a Raw value rather than a mangled one, because the documentation calls that out specifically and the wrong cookie produces authentication errors rather than a clear message.

Frequently asked questions

Official sources

1. ccgauche/ytermusic on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases