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.

• stream your music from Jellyfin
• sixel cover image, courtesy of ratatui-image
• lyrics with autoscroll (Jellyfin > 10.9)
• custom themes, color extraction from album art + smooth interpolated transitions
• spotify-like double queue with order control, etc.
• full offline mode with metadata caching, track downloads, background updates and slow network fallback
• last.fm scrobbling, you need jellyfin-plugin-lastfm
• multi-library support
• vim-style keybindings
• MPRIS integration
• playlists (play/create/edit)
• transcoding, shuffle, repeat modes, the works
• works over ssh (and tmux)
• fast and just kind of nifty really

• other media types (movies, tv shows)
• jellyfin-wide remote control and much more
• if there is a feature you'd like to see, please open an issue :)

jellyfin-tui is available as a package in the AUR. You can install it with your preferred AUR helper. Example:

paru -S jellyfin-tui

jellyfin-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.

servers:
  - name: Password Server
    url: 'https://jellyfin.example.com'
    username: 'username'
    password: 'imcool123'
    default: true # Add to skip server picker on startup. Use --select-server to override
  - name: Quick Connect Server
    url: 'http://localhost:8096'
    quick_connect: true # use jellyfin quick connect
  - name: Password File Server
    url: 'http:/jellyfin.example2.com'
    username: 'username'
    password_file: /home/myusername/.jellyfin-tui-password # use a file containing the password

# All following settings are OPTIONAL. What you see here are the defaults.

# Show album cover image
art: true
# Save and restore the state of the player (queue, volume, etc.)
persist: true
# Grab the primary color from the cover image (false => uses the current theme's `accent` instead)
auto_color: true
# Time in milliseconds to fade between colors when the track changes
auto_color_fade_ms: 400
# Always show the lyrics pane, even if no lyrics are available
lyrics: 'always' # options: 'always', 'never', 'auto'
# Swap the play and pause icons
swap_play_pause: false

rounded_corners: true

transcoding:
  bitrate: 320
  # container: mp3

# Discord Rich Presence. Shows your listening status on your Discord profile if Discord is running.
discord: APPLICATION_ID
# Displays album art on your Discord profile if enabled
# !!CAUTION!! - Enabling this will expose the URL of your Jellyfin instance to all Discord users!
discord_art: false
# Sets the text shown in your Discord status. (Listening to {})
# name: jellyfin-tui
# state: artist
# details: track title
discord_status: "state"

# Customize the title of the terminal window
window_title: true # default -> {title} – {artist} ({year})
# window_title: false # disable
# Custom title: choose from current track's {title} {artist} {album} {year}
# window_title: "\"{title}\" by {artist} ({year}) – jellyfin-tui"

# Options specified here will be passed to mpv - https://mpv.io/manual/master/#options
mpv:
  replaygain: album
  af: lavfi=[loudnorm=I=-23:TP=-1]
  no-config: true
  log-file: /tmp/mpv.log

themes:
  - name: "Transparent Light"
    base: "Light"

    # remove background
    background: "none"

    # make active tab text use album accent color
    tab_active_foreground: "auto"

  - name: "Monochrome Dark (Tweaked)"
    base: "Monochrome Dark"

    # remove background and album header backgrounds
    background: "none"
    album_header_background: "none"

    # make progress bar follow album accent
    progress_fill: "auto"

    # high contrast row selection
    selected_active_background: "#eeeeee"
    selected_active_foreground: "black"

auto_color: false

jellyfin-tui supports fully customizable key bindings via the config file.

You can:

• add new bindings
• override existing bindings
• or disable defaults entirely

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.

keymap:
  ctrl-c: Quit
  j: Down
  k: Up
  space: PlayPause

keymap:
  ctrl-s: Shuffle

keymap:
  ctrl-c: Reset

keymap:
  # the `Reset` action will now show (unbound) in the help page
  ctrl-x: null

keymap_inherit: false
# only `Quit`, `Down` and `Up` will be bound
keymap:
  ctrl-q: Quit
  j: Down
  k: Up

keymap:
  # seek 10 seconds forward or backward
  ctrl-h: !Seek -10
  ctrl-l: !Seek 10
  # run a shell command, in this case detaching from tmux
  q: !Shell "tmux detach"

ctrl-c: Quit
shift-enter: QueueTempBack
alt-j: Down
ctrl-left: ShrinkPane
ctrl-shift-s: GlobalShuffle
':': !Shell "notify-send hello"

enter
esc
tab
backtab
left right up down
home end
pageup pagedown
delete backspace
space

There are only so many keys to bind, so some actions are hidden behind a popup. Press p to open it and ESC to close it. To open the Global Popup, press Shift+p. The popup is context-sensitive and will show different options depending on where you are in the program.

The Global Popup includes several toggleable preferences:

Regular popups include options relevant to the current context. For example, in the discography view, you can choose the order in which albums are displayed:

Jellyfin-tui has a double queue similar to Spotify. You can add songs to the queue by pressing e or shift + enter. Learn more about what you can do with the queue by pressing ? and reading through the key bindings.

You can shuffle from your entire library with the Global Shuffle feature. Open it with Ctrl+S, select from the options it offers, and hit Play to start playing.

Jellyfin-tui registers itself as an MPRIS client, so you can control it with any MPRIS controller. For example, playerctl.

In the Artists and Tracks lists you can search by pressing / and typing your query. The search is case-insensitive and will filter the results as you type. Pressing ESC will clear the search and keep the current item selected.

You can search globally by switching to the Search tab. The search is case-insensitive and will search for artists, albums and tracks. It will pull everything without pagination, so it may take a while to load if you have a large library. This was done because jellyfin won't allow me to search for tracks without an artist or album assigned, which this client doesn't support.

Downloading music is very simple, just press d on a track, or album. More download options can be found in popups.

You can launch jellyfin-tui in offline mode by passing the --offline flag. This will disable all network access and only play downloaded tracks.

A local copy of commonly used data is stored in a local database. This speeds up load times and allows you to use the program fully offline. Also, playing a downloaded track will play the local copy instead of streaming it, saving bandwidth.

Your library is updated in the background every 10 minutes. You will be notified if anything changes. Track metadata updates whenever you open a discography/album/playlist view in-place. You can also force an update in the global popup menu. Jellyfin is the parent, if you delete music on the server, jellyfin-tui will also delete it including downloaded files.

Due to the nature of the project and jellyfin itself, there are some limitations and things to keep in mind:

• jellyfin-tui assumes you correctly tag your music files. Please look at the jellyfin documentation on how to tag your music files. Before assuming the program is broken, verify that they show up correctly in Jellyfin itself.
• lyrics: jellyfin-tui will show lyrics if they are available in jellyfin. To scroll automatically with the song, they need to contain timestamps. I recommend using the LrcLib Jellyfin plugin and running Download missing lyrics directly within jellyfin-tui (Global Popup > Run Jellyfin task > Library: Download missing lyrics), or alternatively the desktop application LRCGET, both by by tranxuanthang. If you value their work, consider donating to keep this amazing free service running.

Not all terminals have the features needed to cover every aspect of jellyfin-tui. While rare, some terminals lack sixel (or equivalent) support or have certain key event limitations. The following are tested and work well:

• kitty (recommended)
• iTerm2 (recommended)
• ghostty
• contour
• wezterm
• foot

The following have issues

• konsole, alacritty, gnome console, terminator (no sixel support and occasional strange behavior)