#terminal #tui #music #gstreamer #youtube

app termusic

Terminal Music Player written in Rust. Can download music from youtube(netease/migu/kugou) and then embed lyrics and album photos into mp3/m4a/flac/wav/ogg vorbis files. Need GStreamer installed to play the music.

36 releases

Uses new Rust 2021

0.6.5 Jan 3, 2022
0.6.4 Dec 24, 2021
0.5.0 Oct 14, 2021
0.3.17 Oct 9, 2021
0.2.11 Jul 16, 2021

#17 in Audio

Download history 65/week @ 2021-09-25 79/week @ 2021-10-02 65/week @ 2021-10-09 44/week @ 2021-10-16 5/week @ 2021-10-23 15/week @ 2021-10-30 37/week @ 2021-11-06 6/week @ 2021-11-13 33/week @ 2021-11-20 41/week @ 2021-11-27 66/week @ 2021-12-04 17/week @ 2021-12-11 46/week @ 2021-12-18 19/week @ 2021-12-25 72/week @ 2022-01-01 21/week @ 2022-01-08

158 downloads per month

MIT and LGPL-3.0-or-later

10K SLoC

Terminal Music Player written in Rust

Listen to music freely as both in freedom and free of charge!

Freedom: As time goes by, online service providers controls pretty much everything we listen. Complicated copyright issues make things worse. If my favorite song cannot be found in a website, probably I'll just not listen to them for years.

Free of charge: you can download from youtube, netease,migu and kugou for free. No need to register monthly paid membership for several websites.

As a contributor of GOMU(https://github.com/issadarkthing/gomu), I met serious problems during development. The main problem is data race condition. So I basically rewrite the player in rust, and hope to solve the problem.

As for now, mp3, m4a, flac,aiff, wav,opus and ogg/vorbis are supported.

By the way, for mobile devices, I recommend sync your music library with mobile by verysync and listen to them with vinyl(which I contributed also).

main tageditor


Need gstreamer and related plugins installed to play music. Please check below:

(Additonally for gentoo:)
(Additionally for macos:)

Optionally you need youtubedl and ffmpeg installed to download mp3 from youtube. yt-dlp is supported under feature gate yt-dlp.

On windows, please download and install gstreamer development package from https://gstreamer.freedesktop.org/download/.


cargo install termusic

Or manually:

git clone https://github.com/tramhao/termusic.git
cd termusic

Then install with:

make install

Or if you need dbus mpris support(need to have dbus installed):

make mpris

By default, termusic can display album cover in kitty or iterm2(mac, not tested). If you need album cover displayed on other terminals, please install ueberzug(https://github.com/seebye/ueberzug) by pip3 install ueberzug or paru -S ueberzug, then:

make cover

If you need both mpris and cover(and also yt-dlp), you can:

make full

Finally, you can run it with:


You can copy it anywhere in your $PATH. The configuration file is located in ~/.config/termusic/config.toml. However, as this is a minimalistic program, you don't need to edit the configuration file and everything can be set from the app. For example, you can change music dir with enter and backspace, and it'll be saved to config. You can change loop mode with m key and it'll be saved too. You can change volume with +/-, and it'll be saved also.

You need stable branch rust toolchain installed to build it. I'm building with 1.56(rust edition 2021). According to user feedback, version less than 1.52 is not working.

Distro Packages

Arch Linux

Arch Linux users can install termusic from the AUR using an AUR helper. For example:

paru termusic


NetBSD users can install termusic from the official repositories.

pkgin install termusic



  • Released on: Jan 3rd, 2022 .
  • New: key configuration. To configure a value, please note the modifier bits value: Shift=1,Ctrl=2,Alt=4. You can combine them for example 6 is Ctrl+Alt. and 7 is Ctrl+Alt+Shift. Please note, whenever shift is configured, the args for char letter should be capital at the same time, for example Q.
  • New: option to disable confirmation message box for quitting.
  • New: aiff metadata supported by lofty-rs.
  • New: shift_tab works in tag editor and color editor to switch focus.
  • Fix: configuration for album photo position and size. Please note, default align for photo is BottomRight, means the x and y specifies bottom right corner of the photo. Supported align: BottomRight,BottomLeft,TopRight,TopLeft. Also, width should be between 1-100 because it's a relative number compared to terminal size. We don't specify height and it's calculated from width and the photo ratio is kept. Meanwhile, when x,y lead to display outside of terminal, app will correct it and try to draw on the terminal.
  • Fix: wrong mime-type for embeded album photo.


  • Released on: Dec 24, 2021.
  • New feature: using yt-dlp for downloading because youtube-dl is slower caused by throttle problem. For details please check this reddit thread. To use it, it's under feature gate yt-dlp. make full will enable all features including this one.
  • New: opus format support. Metadata is supported by lofty-rs.
  • New: configuration for album photo size and position.
  • Fix: youtube search next page doesn't work.
  • Fix: color editor playlist highlight symbol doesn't work.
  • Fix: focus issue after exit tag editor.
  • Fix: focus issue after download.
  • Fix: command line open music dir not working.


  • Released on: Dec 19, 2021.
  • New: color theme support. Shift+C to open color editor. You can change the whole theme, or edit the specific color. The themes are from alacritty-themes, and are localed in ~/.config/termusic/themes/ folder. If you open color editor, and found no themes, please copy them manually.


  • Released on: Dec 12, 2021.
  • change icons on playlist title.
  • New: search works in playlist also.


  • Release on: Dec 3, 2021.
  • fix: bug when using kitty, and there is a 1/5 chances that will lead to freeze when start the app.
  • fix: when start the app, the first song in playlist will be skipped.


  • Released on: Dec 1,2021.
  • Update to tui-realm 1.0. Please note, as it's basically a rewrite, small bugs are inevitable. Please report it in issues and I'll respond very fast.
  • Hotkey to quit changed from Q to q, as now there will show a popup confirmation so it's unlikely to quit accidentally.
  • Can add a song to the beginning of playlist or the end. Switch by a. Note: I add this to configuration file, and it'll reset your configuration file to default values. Please backup if you need. Basically it's not necessary as all options can be set from inside termusic.


  • Released on: Oct 15, 2021.
  • New: album photo for all kinds of terminals. Alacritty,kitty and st tested. Require install ueberzug.


  • Released on: Oct 10, 2021.
  • Added rust-toolchain.toml to avoid using nightly toolchain.
  • iterm2 album photo support.
  • Minor fix: playingbar title length limit.
  • Refactor mpris to operate faster(100ms).


  • Released on: Oct 1, 2021.
  • Rename playlist to library, and queue to playlist.
  • New: loop mode configuration. Default is queue mode(aka consume mode), can switch to loop mode and single loop mode by pressing "m" key when focusing Playlist. In queue mode, previous song cannot be played as it's already consumed from the playlist. In single loop mode, previous song will be ignored.
  • Show volume in progress bar title.


  • Released on: Sep 27, 2021.
  • Revert mpris to optional as some users don't have dbus installed( NetBSD and MacOs).


  • Released on: Sep 27 , 2021.
  • Minor fix: popup message will display for 5 seconds. no message overlapping each other.
  • New: search in playlist. Key binding: "/".
  • New: wav file support.
  • Fix: All lrc files was merged into mp3 after downloading. Should be distinguished by file name.
  • Fix: play any folder with command line args.
  • Fix: spamming mpris propertieschanged messages. Thus mpris is default now.


  • Released on: Sep 23, 2021.
  • New: mpris support(optional). use "make mpris" to compile and install it.
  • Show a message when start playing a song.
  • Remove the usage of msgbox component and use paragraph instead.
  • press "N" for previous song.


  • Released on: Sep 15, 2021.
  • Minor fix: wrong hints for empty queue.
  • Load queue faster.
  • Remove dependency of openssl.
  • Remove dependency of urlqstring.


  • Released on: Sep 13, 2021.
  • Load faster by loading queue after app start.
  • Remove dependency of ogg-metadata.
  • Display version info in both tui and cli.
  • Could override music directory with command line arguments.


  • Released on: Sep 11, 2021.
  • New: ogg vorbis format support.


  • Released on: Sep 7, 2021.
  • New: flac format support.
  • Refactor invidious.rs.


  • Released on: Sep 4, 2021.
  • Remove the usage of configr, also make the app minimal.
  • Change hotkey for help to Ctrl+h.
  • Rearrange components in tag editor.
  • Embed duration into tag. Load faster.
  • Remove dependency of mp3-duration.
  • Minor fix: lyric lang_ext was set to wrong names.


  • Released on: Sep 2, 2021.
  • Fix table focus issue.
  • Fix invidious search slow down the whole program.
  • Change http client from reqwest to ureq, to make the app minimal, thus speed up compilation.


  • Released on: Aug 31, 2021.
  • Remove the dependency of unicode truncate, as tui-realm-stdlib implemented width for table.
  • Fix playlist sorting with characters of mixed languages.
  • Speed up load_queue and sort playlist.
  • Minor fix: duration display in queue.


  • Released on: Aug 26, 2021.
  • Refactoring status line, to show download success or fail message.
  • Parsing output of youtube-dl to select downloaded song in playlist.
  • Embed all lyrics after youtube download. Switch lyric with "T" key while playing.
  • Show popup messages on top right corner.
  • Sort file name(including chinese) in tree.
  • Can delete single lyric from tag editor.
  • Currently only mp3 support several lyrics.


  • Released on: Aug 24 2021.
  • Refactoring lyric mod to songtag mod.
  • Run songtag search in threads so it'll not block tageditor.
  • Refactoring youtube_options and no more search error with youtube.


  • Released on: August 21, 2021.
  • Run songtag search in parallel to save some time in tageditor.

Implemented features(changelog before v0.3.3):

  • Music library below ~/Music, can be changed via editing $HOME/.config/termusic/config.toml
  • Pause/Skip
  • Seek forward/backward
  • USLT lyric
  • Album Photo display(only for kitty terminal)
  • Youtube-dl integration
  • lyric and tag download
  • yank and paste in playlist
  • Lyric offset adjustment
  • Local service to fetch lyrics
  • Download song in tag editor
  • Configuration v0.2.6
  • Local service for kugou v0.2.10
  • Youtube-dl progress indication(indicated by status line)
  • Youtube search by invidious V0.2.7(from the same dialogue of download)
  • Local service for migu v0.2.8
  • m4a format support v0.2.12
  • switch to Gstreamer playing backend in order to support m4a v0.2.12
  • m4a meta support v0.3.0
  • Invidious servers are random selected and verified, thus no configuration is needed.v0.3.2

Thanks for


GPLv3 for netease api code under src/lyric/netease. MIT License for other code.


~445K SLoC