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

Press ? to see the key bindings at any time. Some of the most important ones are:

When you run jellyfin-tui for the first time, it will ask you for the server address, username and password and save them in the configuration file.

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: Main
    url: 'https://jellyfin.example.com'
    username: 'username'
    password: 'imcool123'
    default: true # Add to not ask to pick server. Use --select-server to override
  - name: Second Server
    url: 'http://localhost:8096'
    username: 'username'
    password: 'imcool123'
  - name: Third 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'

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

# 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

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. The popup is context sensitive and will show different options depending on where you are in the program.

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.

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 scheduled 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)