Modern music streaming client for the terminal
Jellyfin-tui is a music streaming client for the Jellyfin media server. Inspired by CMUS and others, its goal is to offer a self-hosted terminal music player with all the modern features you need.
Ctrl+Up/DownAlso works with Navidrome's experimental Jellyfin API (setup).
If there is a feature you'd like to see, please open an issue :)
Pre-built binaries for Linux and macOS are available on
the releases page.
Download the binary for your platform, make it executable, and place it somewhere on your PATH.
jellyfin-tui is available as a package in the AUR. You can install it with your preferred AUR helper. Example:
paru -S jellyfin-tuijellyfin-tui is available as a package in Nixpkgs.
jellyfin-tui is available as a package in the Alpine Linux community repository.
Jellyfin-tui depends on libmpv2 (audio playback) and sqlite3 (offline caching), both of which should be
available in your distribution's package manager. On Debian/Ubuntu based systems, you may need to install libmpv-dev
and libssl-dev as well for building.
# If you're new to rust:
# install rust from https://rustup.rs and make sure ~/.cargo/bin is in your PATH (add this to ~/.bashrc or ~/.zshrc etc.)
export PATH=$PATH:~/.cargo/bin/
# Arch
sudo pacman -S mpv sqlite
# Ubuntu/Debian
sudo apt install mpv libmpv-dev sqlite3 libssl-dev# clone this repository
git clone https://github.com/dhonus/jellyfin-tui
cd jellyfin-tui
# optional: use latest tag
git fetch --tags
git checkout $(git tag | sort -V | tail -1)
cargo install --path .brew install mpv
git clone https://github.com/dhonus/jellyfin-tui
cd jellyfin-tui
# add exports to your shell profile (~/.zshrc etc.)
export LIBRARY_PATH="$LIBRARY_PATH:$(brew --prefix)/lib"
export PATH=$PATH:~/.cargo/bin/
cargo install --path .When you run jellyfin-tui for the first time, it will guide you through creating a configuration file. You can authenticate using either username/password, password file, or Jellyfin Quick Connect. Each of these options then uses locally stored auth tokens for future logins.
The program prints the config location when run. On Linux, the configuration file is located at
~/.config/jellyfin-tui/config.yaml. Feel free to edit it manually if needed.
…Since v0.64.0 Navidrome ships an experimental Jellyfin API. It's off by default; enable it
with Jellyfin.Enabled = true in navidrome.toml (or ND_JELLYFIN_ENABLED=true), as described in
Navidrome's docs. Then point
jellyfin-tui at https:///jellyfin, like the example server above.
Everything works except "Run a Jellyfin task" (an admin API, not a music one). Untested beyond that, so open an issue if something misbehaves.
Click to reveal theming documentation
Jellyfin-tui comes with several built-in themes in both light and dark variants. You can switch between themes in the global popup.
You can also define your own custom themes in the config by selecting a base theme and overriding any colors you want. Custom themes are hot-reloaded when you save the config file.
accent_color fileThe accent color gets written to a file each time it changes. It lives in the data directory (for example
~/.local/share/jellyfin-tui/accent_color on Linux) and contains the hex RGB color. Use it with pywal or similar tools.
"#rrggbb" (hex)"red","white","gray" (named)"auto" → uses the extracted accent from album art"tinted" → keeps the inherited base color but blends it slightly towards the album accent (strength controlled by
tint_strength)"tinted #rrggbb" / "tinted:#rrggbb" → same as above but with an explicit base color"none" → disables optional backgrounds (background,album_header_background only)Full list of keys
| Key | Description |
|---|---|
background |
Main background color. Optional — none uses terminal bg. |
foreground |
Primary text color. |
foreground_secondary |
Secondary text (artists in player, ...). |
foreground_dim |
Dimmed text for less important UI elements. |
foreground_disabled |
Disabled or unavailable UI elements, disliked tracks. |
section_title |
Titles of sections like Albums, Artists, etc. |
accent |
Fallback color for "auto", applied when album art isn't available or if auto_color is disabled. |
border |
Normal border color. |
border_focused |
Border color when a widget is focused. "auto" uses primary (album) color. |
selected_active_background |
Background of the currently selected row in the active section. |
selected_active_foreground |
Text color of the selected row in the active section. |
selected_inactive_background |
Background of selected rows in inactive sections. |
selected_inactive_foreground |
Foreground of selected rows in inactive sections. |
scrollbar_thumb |
Scrollbar handle color. |
scrollbar_track |
Scrollbar track color. |
progress_fill |
Played/filled portion of progress bars. |
progress_track |
Unfilled portion of progress bars. |
tab_active_foreground |
Text color of the active tab. |
tab_inactive_foreground |
Text color of inactive tabs. |
album_header_background |
Background for album/artist header rows (optional). |
album_header_foreground |
Foreground for album/artist header rows. |
tint_strength |
0.0–1.0 float. Controls how much "tinted" colors shift towards the album accent. Stock 0.0, default tinted themes use 0.06. |
…Built-in tinted themes — Tinted Dark and Tinted Light are available out of the box and apply the same treatment to the standard dark/light palettes. Switch to them from the theme picker.
The "auto" accent color is derived from album art by default. You can disable this by setting
auto_color: falsein the config file. This will use the accent color defined in the theme for all "auto" usages instead.
jellyfin-tui supports fully customizable key bindings via the config file.
You can:
Press ? inside jellyfin-tui to see all the available actions and your current bindings. Use the action names
exactly as shown there when defining your keymap.
The Help page is the authoritative reference for all actions and bindings.
How to customize
keymap:
ctrl-c: Quit
j: Down
k: Up
space: PlayPauseEach entry maps a key combination to an action.
Adding a new key does not remove existing bindings.
For example, if you want to add ctrl + s as an additional key for shuffling the queue, you can do:
keymap:
ctrl-s: ShuffleBoth ctrl + s and the default s will now trigger the Shuffle action.
If you bind a key that already exists, it replaces the previous action.
keymap:
ctrl-c: ResetNow ctrl + c will trigger the Reset action instead of quitting.
To unbind a particular keybinding, you can set its value to null.
keymap:
# the `Reset` action will now show (unbound) in the help page
ctrl-x: nullTo start with a completely empty keymap:
keymap_inherit: false
# only `Quit`, `Down` and `Up` will be bound
keymap:
ctrl-q: Quit
j: Down
k: UpSome actions accept parameters. It is important to use the correct syntax for these, which is
!ActionName "parameters":
keymap:
# seek 10 seconds forward or backward
ctrl-h: !Seek -10
ctrl-l: !Seek 10
# adjust volume by a delta (positive or negative)
ctrl-up: !Volume 5
ctrl-down: !Volume -5No open issues yet, or sync has not completed.