Jellyfin Playlist Manager

Interactively add movies to Jellyfin playlists using fzf for selection.

Overview

This tool provides an interactive interface for managing Jellyfin playlists. It fetches movies and/or series from your Jellyfin library and lets you select which ones to add to a playlist using fzf’s multi-select interface.

Features

Interactive Selection: Uses fzf for fast, fuzzy searching and multi-select
Flexible Item Types: Select movies only, series only, or both
Metadata Display: Shows name, year, rating, and type for easy identification
Playlist Awareness: Shows which items are already in the playlist with ★ marker
Smart Duplicate Prevention: Automatically skips items already in the playlist
Playlist Management: Create new playlists or add to existing ones
Dry-Run Mode: Preview selections without making changes

Usage

Basic Usage

jellyfin-manage-playlist \
  --jellyfin-url http://localhost:8096 \
  --api-key-file ~/.secrets/jellyfin-api-key \
  --user-id vincent \
  --playlist-name "Keep"

Options

--jellyfin-url: Jellyfin server URL (required, or set JELLYFIN_URL env var)
--api-key: Jellyfin API key (use –api-key-file for secrets, or set JELLYFIN_API_KEY env var)
--api-key-file: Path to file containing Jellyfin API key (recommended)
--user-id: Jellyfin user ID or username (required, or set JELLYFIN_USER_ID env var)
--playlist-name: Playlist name (will be created if it doesn’t exist)
--item-type: Type of items to show - movie (default), series, or both
--dry-run: Show what would be added without making changes
--verbose: Enable verbose output

Environment Variables

You can set these environment variables to avoid passing them as arguments:

export JELLYFIN_URL="http://localhost:8096"
export JELLYFIN_API_KEY="your-api-key-here"
export JELLYFIN_USER_ID="vincent"

# Then simply run:
jellyfin-manage-playlist --playlist-name "Keep"

Interactive Selection

When you run the tool, it will:

Connect to Jellyfin and fetch all movies/series
Check which items are already in the target playlist (if it exists)
Sort items so ★ items (already in playlist) appear first
Open fzf with a list of items (showing name, year, rating, and type)
Let you search and select items:
- Type to filter items
- TAB to select/deselect individual items
- Ctrl-S to select all ★ items at once (quick-add all starred items)
- Enter to confirm selection
- Esc to cancel
Automatically skip items already in the playlist (no duplicates)

Example fzf display (movies only, sorted):

★ The Dark Knight (2008) ★9.0     [already in playlist - sorted first]
★ The Shawshank Redemption (1994) ★9.3   [already in playlist - sorted first]
The Godfather (1972) ★9.2          [not in playlist - sorted after]
Pulp Fiction (1994) ★8.9

Example fzf display (both movies and series, sorted):

★ Game of Thrones (2011) ★9.2 [Series]     [already in playlist - sorted first]
★ The Shawshank Redemption (1994) ★9.3   [already in playlist - sorted first]
Breaking Bad (2008) ★9.5 [Series]          [not in playlist - sorted after]
The Godfather (1972) ★9.2                  [not in playlist - sorted after]

Notes:

The first ★ indicates the item is already in the playlist
The second ★ shows the rating
Series are marked with [Series] tag
Items already in playlist are sorted to the top for easy selection
Use Ctrl-S to select all ★ items at once

Examples

Create a New Playlist

If the playlist doesn’t exist, it will be created with the selected movies:

jellyfin-manage-playlist \
  --jellyfin-url http://localhost:8096 \
  --api-key-file ~/.secrets/jellyfin-api-key \
  --user-id vincent \
  --playlist-name "Weekend Movies"

Add to Existing Playlist

If the playlist exists, the selected movies will be added to it:

jellyfin-manage-playlist \
  --jellyfin-url http://localhost:8096 \
  --api-key-file ~/.secrets/jellyfin-api-key \
  --user-id vincent \
  --playlist-name "Keep"

Interactive Playlist Selection

If you don’t specify a playlist name, the tool will let you choose from existing playlists or create a new one:

jellyfin-manage-playlist \
  --jellyfin-url http://localhost:8096 \
  --api-key-file ~/.secrets/jellyfin-api-key \
  --user-id vincent

Dry-Run Mode

Preview your selections without making changes:

jellyfin-manage-playlist \
  --jellyfin-url http://localhost:8096 \
  --api-key-file ~/.secrets/jellyfin-api-key \
  --user-id vincent \
  --playlist-name "Keep" \
  --dry-run

Select Series Only

Add TV series to a playlist:

jellyfin-manage-playlist \
  --jellyfin-url http://localhost:8096 \
  --api-key-file ~/.secrets/jellyfin-api-key \
  --user-id vincent \
  --playlist-name "Binge Watch" \
  --item-type series

Select Both Movies and Series

Add both movies and series to the same playlist:

jellyfin-manage-playlist \
  --jellyfin-url http://localhost:8096 \
  --api-key-file ~/.secrets/jellyfin-api-key \
  --user-id vincent \
  --playlist-name "Watch Later" \
  --item-type both

Requirements

Python 3.11+
fzf command-line tool (fuzzy finder)
Jellyfin server with API access

Use Case: Syncing Favorites

This tool works great with jellyfin-favorites-sync to manage which movies get synced to a remote host:

Use jellyfin-manage-playlist to interactively add movies to a “Keep” playlist
Configure jellyfin-favorites-sync to sync the “Keep” playlist to your NAS

# Step 1: Add movies to "Keep" playlist
jellyfin-manage-playlist \
  --jellyfin-url http://localhost:8096 \
  --api-key-file ~/.secrets/jellyfin-api-key \
  --user-id vincent \
  --playlist-name "Keep"

# Step 2: Sync the playlist to remote host
jellyfin-favorites-sync \
  --jellyfin-url http://localhost:8096 \
  --api-key-file ~/.secrets/jellyfin-api-key \
  --user-id vincent \
  --playlist-name "Keep" \
  --dest-host aix.sbr.pm

Troubleshooting

fzf Not Found

If you get an error about fzf not being found:

NixOS: nix-env -iA nixpkgs.fzf or add it to your system packages
Other systems: See https://github.com/junegunn/fzf for installation instructions

Connection Failed

Verify the Jellyfin URL is correct and accessible
Check that the API key is valid
Ensure the user ID exists in Jellyfin

No Movies Found

Check that your Jellyfin library contains movies
Verify the user has access to the movie libraries

License

MIT