{"id":24387087,"url":"https://github.com/dhonus/jellyfin-tui","last_synced_at":"2025-10-22T06:27:16.961Z","repository":{"id":241377705,"uuid":"805222652","full_name":"dhonus/jellyfin-tui","owner":"dhonus","description":"🪼 Modern music streaming client for the terminal.","archived":false,"fork":false,"pushed_at":"2025-09-25T05:56:35.000Z","size":33205,"stargazers_count":234,"open_issues_count":13,"forks_count":17,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-09-25T07:24:06.630Z","etag":null,"topics":["jellyfin","mpv","music","player","ratatui"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dhonus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-05-24T06:12:27.000Z","updated_at":"2025-09-25T06:32:23.000Z","dependencies_parsed_at":"2024-05-28T03:30:02.620Z","dependency_job_id":"4e75ddd1-f8ac-49a5-9f51-26ea2c4adaef","html_url":"https://github.com/dhonus/jellyfin-tui","commit_stats":null,"previous_names":["dhonus/jellyfin-tui"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/dhonus/jellyfin-tui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhonus%2Fjellyfin-tui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhonus%2Fjellyfin-tui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhonus%2Fjellyfin-tui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhonus%2Fjellyfin-tui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dhonus","download_url":"https://codeload.github.com/dhonus/jellyfin-tui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhonus%2Fjellyfin-tui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277009880,"owners_count":25744543,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-26T02:00:09.010Z","response_time":78,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jellyfin","mpv","music","player","ratatui"],"created_at":"2025-01-19T12:02:27.029Z","updated_at":"2025-10-22T06:27:16.952Z","avatar_url":"https://github.com/dhonus.png","language":"Rust","funding_links":[],"categories":["Rust","Table of Contents","\u003ca name=\"music\"\u003e\u003c/a\u003eSound and music"],"sub_categories":[],"readme":"# jellyfin-tui\n\nJellyfin-tui is a (music) streaming client for the Jellyfin media server. Inspired by CMUS and others,\nits goal is to offer a self-hosted, terminal music player with all the modern features you need.\n\n### Features\n- stream your music from Jellyfin\n- lyrics with autoscroll (Jellyfin \u003e 10.9)\n- sixel **cover image**, courtesy of [ratatui-image](https://github.com/benjajaja/ratatui-image)\n- transcoding\n- spotify-like double queue with order control, etc.\n- metadata caching, downloading and a fully **offline mode**\n- last.fm scrobbling, you need [jellyfin-plugin-lastfm](https://github.com/jesseward/jellyfin-plugin-lastfm)\n- vim keybindings\n- MPRIS controls\n- playlists (play/create/edit)\n- works over ssh\n- fast and just kind of nifty really\n\n### Planned features\n- other media types (movies, tv shows)\n- jellyfin-wide remote control and much more\n- if there is a feature you'd like to see, please open an issue :)\n\n### Screenshots\n![image](.github/optimized.gif)\n\n### Installation\nJellyfin-tui uses libmpv as the backend for audio playback. You need to have mpv installed on your system.\n\n#### Arch Linux\n[jellyfin-tui](https://aur.archlinux.org/packages/jellyfin-tui/) is available as a package in the [AUR](https://aur.archlinux.org). You can install it with your preferred [AUR helper](https://wiki.archlinux.org/title/AUR_helpers). Example:\n```bash\nparu -S jellyfin-tui\n```\n\n#### Nix\n[jellyfin-tui](https://search.nixos.org/packages?channel=unstable\u0026show=jellyfin-tui\u0026from=0\u0026size=50\u0026sort=relevance\u0026type=packages\u0026query=jellyfin-tui) is available as a package in [Nixpkgs](https://search.nixos.org/packages).\n\n#### Other Linux\nLinux is the main target OS for this project. You can install mpv from your package manager.\n```bash\n# add ~/.cargo/bin to your PATH (~/.bashrc etc.) if you haven't already\nexport PATH=$PATH:~/.cargo/bin/\n\n# install mpv\nsudo pacman -S mpv sqlite # arch\nsudo apt install mpv libmpv-dev sqlite3 libssl-dev # ubuntu\n```\n```bash\n# clone this repository\ngit clone https://github.com/dhonus/jellyfin-tui\ncd jellyfin-tui\n\n# checkout the latest stable version if desired\n# (git pull and re-run to update)\ngit checkout $(git tag | tail -1)\n\ncargo run --release\n\n# or install it system-wide to run `jellyfin-tui` anywhere\nexport PATH=$PATH:~/.cargo/bin/\ncargo install --path .\n```\n\n#### macOS\n```bash\nbrew install mpv\ngit clone https://github.com/dhonus/jellyfin-tui\ncd jellyfin-tui\nexport LIBRARY_PATH=\"$LIBRARY_PATH:$(brew --prefix)/lib\"\nexport PATH=$PATH:~/.cargo/bin/\ncargo install --path .\n```\n### Key bindings\nPress **`?`** to see the key bindings at any time. Some of the most important ones are:\n\n\u003cdetails\u003e\n\u003csummary\u003eKey bindings\u003c/summary\u003e\n\u003cbr\u003e\n\n|key|alt|action|\n|---|---|---|\n|space||play / pause|\n|enter||start playing selected|\n|up / down|k / j|navigate **up** / **down**|\n|tab||cycle between **Artist** \u0026 **Track** lists|\n|shift + tab||cycle further to **Lyrics** \u0026 **Queue**|\n|p||show **command prompt**|\n|a / A||skip to next / previous **album**, or next in Artists, alphabetically|\n|1,2,3,...|F1,F2,F3,...|switch tab \u003e\u003e F1 - **Library**, F2 - **Search**|\n|F1|ESC|return to **Library** tab|\n|left / right|r / s|seek +/- 5s|\n|. / ,|\u003c / \u003e|seek +/- 1m|\n|d||download track / album / playlist|\n|n||next track|\n|N||previous track; if over 5s plays current track from the start|\n|+ -||volume up / down|\n|ctrl + e|ctrl + enter|play next|\n|e|shift + enter|enqueue (play last)|\n|E||clear queue|\n|DELETE||remove from queue|\n|x||stop playback|\n|X||reset the program|\n|T||toggle transcode (applies to newly added songs, not whole queue)|\n|q|^C|quit|\n\n\u003c/details\u003e\n\n### Popup\nThere 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.\n\n![image](.github/popup.png)\n\n### Queue\nJellyfin-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.\n\n![image](.github/queue.png)\n\n### Configuration\nWhen 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.\n\nThe 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.\n```yaml\n#= You can define multiple servers here\nservers:\n  - name: Main Server\n    url: 'https://jellyfin.example.com'\n    username: 'username'\n    password: 'imcool123'\n    default: true # Add to not ask to pick server. Use --select-server to override\n  - name: Second Server\n    url: 'http://localhost:8096'\n    username: 'username'\n    password: 'imcool123'\n  - name: Third Server\n    url: 'http:/jellyfin.example2.com'\n    username: 'username'\n    password_file: /home/myusername/.jellyfin-tui-password # use a file containing the password\n\n# All following settings are OPTIONAL. What you see here are the defaults.\n\n# Show album cover image\nart: true\n# Save and restore the state of the player (queue, volume, etc.)\npersist: true\n# Grab the primary color from the cover image (false =\u003e uses `primary_color` instead)\nauto_color: true\n# Hex or color name ('green', 'yellow' etc.). If not specified =\u003e blue is used.\nprimary_color: '#7db757'\n# Always show the lyrics pane, even if no lyrics are available\nalways_show_lyrics: true\n\ntranscoding:\n  bitrate: 320\n  # container: mp3\n\n# Discord Rich Presence. Shows your listening status on your Discord profile if Discord is running.\ndiscord: APPLICATION_ID\n# Displays album art on your Discord profile if enabled\n# !!CAUTION!! - Enabling this will expose the URL of your Jellyfin instance to all Discord users!\ndiscord_art: false\n\n# Customize the title of the terminal window\nwindow_title: true # default -\u003e {title} – {artist} ({year})\n# window_title: false # disable\n# Custom title: choose from current track's {title} {artist} {album} {year}\n# window_title: \"\\\"{title}\\\" by {artist} ({year}) – jellyfin-tui\"\n\n# Options specified here will be passed to mpv - https://mpv.io/manual/master/#options\nmpv:\n  af: lavfi=[loudnorm=I=-16:TP=-3:LRA=4]\n  no-config: true\n  log-file: /tmp/mpv.log\n```\n\n### MPRIS\nJellyfin-tui registers itself as an MPRIS client, so you can control it with any MPRIS controller. For example, `playerctl`.\n\n### Search\n\nIn 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.\n\nYou 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.\n\n![image](.github/search.png)\n\n### Downloading media / offline mode\n\nDownloading music is very simple, just **press `d` on a track**, or album. More download options can be found in popups.\n\nYou can launch jellyfin-tui in offline mode by passing the `--offline` flag. This will disable all network access and only play downloaded tracks.\n\nA 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.\n\u003e 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.\n\n### Recommendations\nDue to the nature of the project and jellyfin itself, there are some limitations and things to keep in mind:\n- jellyfin-tui assumes you correctly tag your music files. Please look at the [jellyfin documentation](https://jellyfin.org/docs/general/server/media/music/) on how to tag your music files. Before assuming the program is broken, verify that they show up correctly in Jellyfin itself.\n- if your **cover image** has a black area at the bottom, it is because it's not a perfect square. Please crop your images to a 1:1 aspect ratio for the best results.\n- **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](https://github.com/jellyfin/jellyfin-plugin-lrclib) and running `Download missing lyrics` directly **within jellyfin-tui** (Global Popup \u003e Run scheduled task \u003e Library: Download missing lyrics), or alternatively the desktop application [LRCGET](https://github.com/tranxuanthang/lrcget), both by by tranxuanthang. If you value their work, consider donating to keep this amazing free service running.\n\n### Supported terminals\nNot 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:\n- kitty (recommended)\n- iTerm2 (recommended)\n- ghostty\n- contour\n- wezterm\n- foot\n\nThe following have issues\n- konsole, alacritty, gnome console, terminator (no sixel support and occasional strange behavior)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhonus%2Fjellyfin-tui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdhonus%2Fjellyfin-tui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhonus%2Fjellyfin-tui/lists"}