Configuration

Configuration Pages

SmartLists has two configuration pages with different capabilities:

Feature	User Page	Admin Page
Location	Home screen sidebar	Dashboard → Plugins → SmartLists
Create/edit own playlists	✅	✅
Create collections	✅ (requires permission)	✅
View/edit other users' lists	❌	✅
Global plugin settings	❌	✅
Backup & restore	❌	✅
Status tab with statistics	❌	✅
Bulk operations	✅ (own lists)	✅ (all lists)

Collection Permissions

Regular users need the "Manage Collections" permission to create collections:

Dashboard → Users → [Select User] → Profile → Allow this user to manage the server's shared collections

Playlists vs Collections

Before creating your first list, it's important to understand the differences between Playlists and Collections:

Playlists

Multi-user support: Playlists can be associated with one or more users. When multiple users are selected, a separate Jellyfin playlist is created for each user, allowing each user to have their own personalized version of the same smart playlist.
User-specific data: Each user's playlist is filtered based on their own playback data (watched status, favorites, play count, etc.), making it perfect for shared playlists that adapt to each user.
Sorting: Items can be sorted using multiple sorting levels (see Sorting and Limits)
Max Playtime: Can set a maximum playtime limit
Visibility: Can be set as public (visible to all users) or private (visible only to the selected users)
Automatic Image Generation: Playlist covers are generated by SmartLists from the playlist's items (see details below)
Use cases: Personal music playlists, "Continue Watching" lists, workout mixes, family playlists that adapt to each member, etc.

Collections

Server-wide: Collections are visible to all users on the server (no individual ownership)
No Max Playtime: Collections cannot have a playtime limit
User Reference: While collections don't have an "owner" in the traditional sense, you must select a user whose context will be used when evaluating rules and filtering items. This user's library access permissions and user-specific data (like "Playback Status", "Is Favorite", etc.) are used to determine which items are included in the collection
Automatic Image Generation: Collections automatically generate cover images based on the media items they contain (see details below)
Can Contain Collections and Playlists: Unlike playlists, collections can contain other collection and playlist objects (creating "meta-collections") — select the Collection or Playlist media types
Use cases: Organizing related content for browsing (e.g., "Action Movies", "Holiday Collection", "Director's Collection")

Smart collections are metadata-locked

SmartLists creates its collections with Jellyfin's "Lock this item" flag enabled, and re-applies it on every refresh. This prevents Jellyfin's metadata fetchers from matching the collection against online databases by name and stamping a foreign TMDB ID on it — a mismatch that causes the TMDbBoxSets plugin to delete the collection as "orphaned". The lock does not affect cover image generation or any metadata set through SmartLists — SmartLists itself aggregates genres, studios, parental rating, and total runtime from the collection's members on every refresh, so smart collections still display this metadata despite the lock. If you untick the lock manually, it will be re-enabled on the next refresh.

Automatic Image Generation

SmartLists automatically generates cover images for playlists and collections when no custom images have been provided. For collections, auto-generation occurs only if:

No images have been uploaded through SmartLists for that image type
No images have been uploaded directly in Jellyfin for that image type

This means you can override auto-generation simply by uploading your own images through SmartLists or directly in Jellyfin.

Playlist Covers

Playlist covers are generated by SmartLists itself (instead of Jellyfin's built-in playlist image generation), so they are consistent with collection covers and can carry the smart list badge
A square 2x2 collage is created from the first four distinct item images in the playlist (album art is used for audio tracks, series posters for episodes)
If only one distinct image is available, it is used as the cover: a square center-cropped badged copy when the smart list badge is enabled, or the untouched original image when the badge is disabled
To use your own cover, upload a Primary image through SmartLists, or directly in Jellyfin (both are preserved — auto-generation only runs when neither exists)

Collection Primary Images (Vertical Posters)

If a collection contains only one item with an image, that item's primary image is used directly as the collection cover
If a collection contains two or more items with images, a 4-image collage is automatically created using the first items from the collection
The plugin prioritizes Movies, Series and Albums with images, falling back to any items with images if needed

Collection Thumb Images (Horizontal/Landscape)

In addition to the primary poster, the plugin also generates 16:9 thumb images perfect for landscape-oriented views in Jellyfin's UI
Single item collections use the item's thumb image directly
Multiple item collections create a 2x2 grid collage (1920x1080) from thumb images of the first 4 items
Thumb generation only occurs if the media items have actual thumb images available. If no thumb images exist, only the primary poster is generated

Automatic Updates

Playlist and collection images are automatically regenerated when the list is refreshed to reflect the current items

Smart List Badge

To make smart playlists and collections easy to spot when browsing, SmartLists stamps a small badge (the plugin's gear logo) in the top-left corner of cover images:

Applied to auto-generated covers as well as Primary and Thumb images uploaded through SmartLists
Uploaded originals are stored untouched — the badge is only stamped on the copy handed to Jellyfin, so toggling the badge off restores clean covers
Can be turned off in the Settings tab of the admin page (Show smart list badge on covers); changes take effect on each list's next refresh
Image formats that cannot be re-encoded (e.g. SVG) are used as-is without a badge

Covers are cropped to Jellyfin's tile proportions while the badge is enabled

Jellyfin overviews crop covers to fixed tile shapes (square for playlists, 2:3 posters and 16:9 thumbs for collections), while detail pages show the image at its original proportions — and off-ratio covers also stretch their tile and make overview grids uneven. A badge stamped in the corner of an off-ratio image would be cut away by the overview crop; there is no position that works for every view. So while the badge is enabled, covers (including images uploaded through SmartLists) are center-cropped at native resolution to the matching tile shape before the badge is stamped: playlist Primary covers to a square, collection Primary covers to 2:3, and Thumb images to 16:9. Disable the badge to keep covers at their original proportions — uploads are then handed to Jellyfin untouched. Your uploaded originals are always stored uncropped, so toggling the badge off restores them on the next refresh.

Image Priority for Collections

Collection images are determined in this order:

Images uploaded directly in Jellyfin - Preserved, unless an image has been uploaded through SmartLists
Images uploaded through SmartLists - Will overwrite any existing images of the same type
Auto-generated collages - Created only if no custom images exist from either source

Converting Between Types

You can convert an existing playlist to a collection (or vice versa) at any time:

Single list: When editing a list, change the Type dropdown from "Playlist" to "Collection" (or vice versa) and save
Bulk conversion: In the Manage Lists tab, select multiple lists and use the bulk action buttons to convert them all at once

When converting:

The smart list configuration (rules, sorting, limits, etc.) is preserved
The old Jellyfin playlist/collection is deleted
A new Jellyfin playlist/collection of the target type is created (if the list is enabled)
Custom images uploaded through SmartLists are preserved

Conversion Considerations

Converting a multi-user playlist to a collection will delete all user-specific Jellyfin playlists and create a single server-wide collection
Converting a collection to a playlist will create a playlist for the reference user only

Custom Images

SmartLists allows you to upload custom images for your playlists and collections directly from the Create/Edit form. The dropdown shows all image types supported by Jellyfin (Primary, Backdrop, Banner, Logo, etc.).

How to Use:

When creating or editing a smart list, expand More options and scroll to the Custom Images section
Click Add Image to add a new image
Select the image type from the dropdown (each type can only be used once)
Choose an image file from your computer
A preview will appear once the file is selected
Add more images as needed by clicking Add Image again
Remove images by clicking the delete button next to each row
Save the list to upload the images

Benefits:

Persistent storage: Custom images are stored in SmartLists' configuration folder, separate from Jellyfin
Automatic restoration: When you disable and re-enable a list, your custom images are automatically restored
Easy management: View and manage all custom images directly from the Create/Edit form

Metadata

The Metadata section lets you set additional properties on the Jellyfin playlist or collection:

Sort Title – Overrides the default sort title. Useful for controlling where the list appears when sorting alphabetically (e.g., set it to _Movies to force it to the top).
Overview – Sets a custom description that appears in Jellyfin's item detail view.
Tags – Sets tags on the generated Jellyfin playlist or collection. Enter each tag and press Enter, or paste multiple tags separated by semicolons.
Favorite – Optionally marks the generated list as favorite or not favorite. Leave it unchanged if you do not want SmartLists to manage favorite state.

All fields are optional. Values are re-applied on each refresh.

Favorite is user-specific

Favorite state in Jellyfin belongs to a user, not to the playlist or collection globally. For playlists, SmartLists applies the setting for each selected playlist user. For collections, SmartLists applies it for the selected collection reference user.

User Selection for Collections

When creating a collection, the user you select is used as a reference for rule evaluation, not as an owner. The collection itself is server-wide and visible to everyone. This user's context is important for: - Evaluating user-specific rules (Playback Status, Is Favorite, Play Count, etc.) - Respecting library access permissions - Filtering items based on what that user can see and access

Web Interface Overview

The web interface is organized into tabs. The available tabs and features depend on your access level:

User Page: Create, Manage (2 tabs)
Admin Page: Create, Manage, Status, Settings (4 tabs)

1. Create List

This is where you build new playlists and collections:

Start from a Template

At the top of the Create tab you can pick one of the built-in templates — ready-made configurations like TV Channel (round-robin episode interleaving), Continue Watching, Weekly Jams (ListenBrainz), or Album Roulette. Selecting a template and clicking Use fills the whole create form with a working setup. Nothing is created yet: review the settings, adjust them to taste, and click Create as usual.

Some templates need one value from you (for example a title for Because You Watched… or your ListenBrainz feed URL for Weekly Jams) — a notification tells you which rule to fill in, and the form won't save until you do.

On the user configuration page, collection templates (such as Trending Now (Trakt)) are only shown to users who are allowed to create collections, so regular users may see fewer templates than an administrator.

More options

Fields beyond List Type, Name, Media Types (with its Include Extras option), Rules, Sort Options, and Users live in a collapsed More options section on the create/edit form. The collapsed header always shows a summary of what applies (e.g. 500 items max · refresh on library changes, or Bumpers · 2 schedules when editing a configured list), and the section expands automatically when you edit a list that uses advanced features.

Choose whether to create a Playlist or Collection
Define the rules for including items
Choose the sort order
Select which user(s) should be associated with the list:
For Playlists: You can select one or more users. Each selected user will get their own personalized Jellyfin playlist based on their playback data. This allows the same smart playlist to show different content for each user (e.g., "My Favorites" showing each user's actual favorites).
For Collections: Select a single reference user whose context will be used for rule evaluation and library access permissions
Include extras (behind the scenes, deleted scenes, featurettes, trailers) in the item pool — this option is only visible when the Video media type is selected

The remaining fields live inside the collapsed More options section, grouped as:

Limits
Set the maximum number of items
Set the maximum playtime for the list (playlists only)
Hide the list while its item count is below a minimum you set (see Min Items)
Configure random group selection (see Random Group Selection)
Bumpers — weave short interstitial items between the playlist's main items (playlists only, see Bumpers)
Automation
Choose whether or not to enable the list
Configure auto-refresh behavior (Never, On Library Changes, On All Changes)
Set custom refresh schedule (Daily, Weekly, Monthly, Yearly, Interval or No schedule)
Set visibility schedules (see Visibility Scheduling)
Sharing
Decide if the list should be public or private (playlists only - collections are always server-wide)
Presentation
Upload custom images and set metadata such as sort title, overview, tags and favorite (see Custom Images and Metadata above)
Replace matched items with the collections that contain them (collections only, see Group results into collections)

User Page Differences

On the User Page, you can only select yourself for playlists and must use your own account as the reference user for collections. Admins can select any user(s) from the dropdown.

2. Manage Lists

View and edit your smart playlists and collections:

Organized Interface: Clean, modern layout with grouped actions and filters
Advanced Filtering: Filter by list type, media type, visibility and user
Real-time Search: Search all properties in real-time
Flexible Sorting: Sort by name, list creation date, last refreshed, or enabled status
Bulk Operations: Select multiple lists to enable, disable, delete, or convert them simultaneously
Detailed View: Expand lists to see rules, settings, creation date, and other properties
Quick Actions: Edit, clone, refresh, or delete individual lists with confirmation dialogs
Smart Selection: Select all, expand all, or clear selections with intuitive controls

User Page Differences

On the User Page, you can only see and manage lists you own. Admins can see and manage all lists server-wide.

Additionally, multi-user and all-user playlists are hidden from the user page. When an admin creates a playlist with multiple users selected, or with All users enabled, those playlists will not appear in the manage tab for regular users. This prevents users from accidentally editing playlists that would affect other users. These playlists can only be viewed and managed by administrators.

3. Status

Monitor refresh operations and view statistics:

Ongoing Operations: View all currently running refresh operations with real-time progress
See which lists are being refreshed
Monitor progress with progress bars showing items processed vs. total items
View estimated time remaining for each operation
Track elapsed time and trigger type (Manual, Auto, or Scheduled)
Statistics: View refresh statistics since the last server restart
Total number of lists tracked
Number of ongoing operations
Last refresh time across all lists
Average refresh duration
Count of successful and failed refreshes
Refresh History: View the last refresh for each list
See when each list was last refreshed
View refresh duration and item counts
Check success/failure status
See which trigger type initiated each refresh

User Page Differences

On the User Page, statistics and refresh history are limited to your own lists only.

Statistics Scope

Statistics and refresh history are tracked in-memory and reset when the Jellyfin server is restarted. Historical data is not persisted across server restarts.

4. Settings (Admin Only)

Configure global settings for the plugin:

Set the default sort order for new lists
Set the default media types pre-selected for new lists (types only available for collections are skipped when creating a playlist)
Set the default max items and max playtime for new lists
Set the default minimum items to show for new lists
Configure custom prefix and suffix for list names
Set the default auto-refresh mode for new lists
Set the default custom schedule settings for new lists
Configure performance settings
Enable/disable user page access - Control whether regular users can access SmartLists from their home screen
Backup & Restore - Create backups, view available backups, restore from server or uploaded files
Manually trigger a refresh for all smart lists

User Page Access Control

Administrators can enable or disable the user-facing SmartLists page in the Settings tab:

Enable User Page (default: enabled): When checked, regular users can access SmartLists from their home screen sidebar
Requires: Plugin Pages and File Transformation plugins must be installed (see Installation Guide)
When disabled: Users can only access SmartLists through the admin dashboard

Server Restart Required

After changing the Enable User Page setting, you may need to restart the Jellyfin server for the change to fully take effect in the Plugin Pages integration.

Flexible Deletion Options

When deleting a smart list, you can choose whether to also delete the corresponding Jellyfin playlist or collection:

Delete both (default): Removes both the smart list configuration and the Jellyfin playlist/collection
Delete configuration only: Keeps the Jellyfin playlist/collection and removes the custom prefix/suffix (if any), making it a regular manually managed list

This is useful when you want to populate a list automatically once, then manage it manually.

Enable List

The Enable List setting controls whether the smart list is active and visible in Jellyfin:

Enabled: The smart list is active, the corresponding Jellyfin playlist/collection exists and is visible to users
Disabled: The smart list configuration is preserved, but the Jellyfin playlist/collection is deleted from Jellyfin

You can toggle this setting when creating or editing a list, or use bulk operations in the Manage Lists tab to enable/disable multiple lists at once.

Disabling Lists Temporarily Removes Jellyfin Playlists/Collections

When you disable a smart list, the corresponding Jellyfin playlist or collection is permanently removed from Jellyfin, including any metadata entered manually. Any images uploaded or metadata added through SmartLists, will be kept intact and re-applied when the list is enabled again.

Disabling lists can be useful for:

Seasonal content: Manually disable off-season lists (though Visibility Scheduling is better for this)
Testing: Temporarily hide a list while you work on its rules
Cleanup: Keep the configuration but remove the list from Jellyfin temporarily

Use Visibility Scheduling Instead

For seasonal or time-based list visibility, consider using Visibility Scheduling instead of manually enabling/disabling lists. This automates the process and ensures lists appear and disappear exactly when you want them to.

Min Items

With Min Items (in the Limits group under More options when creating or editing a list, next to Max Items), a smart list's Jellyfin playlist or collection is hidden while its matched item count is below a threshold you set:

If a refresh finds fewer matching items than the minimum, the Jellyfin playlist/collection is removed (or never created in the first place).
As soon as a later refresh's count reaches the minimum again, it is recreated automatically — including any custom images and metadata you configured.
The smart list configuration itself is never deleted; it stays visible in the Smart Lists interface.
Leave the field blank or set it to 0 to always show the list, even with zero items — this is the default for existing lists.
Setting it to 1 reproduces the old Hide when empty behaviour exactly: the list is only hidden when it matches nothing at all.
Any value above 1 also hides thinly-populated lists — useful for e.g. a tag-based collection you only want visible once it has a handful of items, not just one.

This is useful for seasonal or rotating lists (e.g. "Halloween movies" driven by a schedule or an external list) that would otherwise linger as near-empty entries in your library. For multi-user playlists, hiding applies per user: a user below the minimum has their playlist hidden while other users keep theirs.

New lists default to a minimum of 1 (equivalent to the old Hide when empty default). Admins can change the default for new lists with Default Min Items in the Settings tab; the per-list field always takes precedence, and changing the global setting does not affect existing lists. The Settings-tab default applies to lists created from the admin configuration page — the user page always starts new lists with a minimum of 1.

Custom List Naming

You can customize how smart list names appear in Jellyfin by configuring a prefix and/or suffix in the Settings tab:

Prefix: Text added before the list name (e.g., "My " → "My Action Movies")
Suffix: Text added after the list name (e.g., " - Smart" → "Action Movies - Smart")
Both: Use both prefix and suffix (e.g., "My " + " - Smart" → "My Action Movies - Smart")
None: Leave both empty for no prefix/suffix

The naming configuration applies to all new smart lists. When you delete a smart list but keep the Jellyfin playlist/collection, the custom prefix/suffix will be automatically removed.

Backup & Restore

SmartLists provides a comprehensive backup system that combines automated backups with easy-to-use restore functionality. All backup operations are available in the Settings tab.

Automated Backups

SmartLists can automatically create scheduled backups of all your smart list configurations and custom images.

Configuration:

Go to the Settings tab in the SmartLists admin page
Find the "Backup & Restore" section
Check Enable automated backups
Configure your backup settings:
Backups to retain: Number of backup files to keep (default: 7). Older backups are automatically deleted.
Custom backup path (optional): Specify a custom directory for backups. Leave empty to use the default location inside the SmartLists data folder.

Backup Schedule:

The backup task runs as a native Jellyfin scheduled task. By default, it runs daily at 3:00 AM.

To change the schedule:

Go to Jellyfin Dashboard → Scheduled Tasks
Find "SmartLists backup task" under the "SmartLists" category
Click on the task to configure triggers (time, frequency, etc.)

Available Backups

The "Available Backups" table displays all backup files stored on the server, showing:

Filename: The backup file name with timestamp
Date: When the backup was created
Size: File size of the backup

For each backup, you have three actions:

Action	Icon	Description
Restore	↺	Restores the backup, recreating all lists from this backup
Download	↓	Downloads the backup file to your computer
Delete	🗑	Deletes the backup file from the server (with confirmation)

Use the refresh button next to "Available Backups" to reload the list after creating or deleting backups.

Manual Backup

Click Create Backup Now to create a backup on demand. This creates a timestamped backup file on the server and adds it to the "Available Backups" table. Use the download button in the table to download the backup to your computer.

This is useful for creating a backup before making significant changes to your lists.

Restore from File

To restore from a backup file stored on your computer (not on the server):

Drag and drop a backup ZIP file onto the drop zone, or click to browse
Click Restore to process the backup
All lists from the backup will be restored

Restore behavior:

Duplicate Detection: Lists with the same GUID as existing lists will be automatically skipped to prevent conflicts (or overwritten if the overwrite option is checked)
User Reassignment: When restoring from another Jellyfin instance, if the original list owner doesn't exist in the destination system, the list will be automatically reassigned to the admin user performing the restore
Custom Images: Custom images from the backup are automatically restored
Backward Compatible: Old backup files (from earlier versions) are still supported
Refresh Required: After restoring, you must refresh the lists to create the actual playlists/collections in Jellyfin

Refresh After Restore

Restored lists only exist as SmartLists configurations until they are refreshed. Use Refresh All Lists in the Status tab or refresh individual lists to create them in Jellyfin.

User-Specific Rules

Rules like "Playback Status for [User]" or "Is Favorite for [User]" that reference non-existent users will need to be updated manually after restoring.

Backup Contents

Each backup is a timestamped ZIP file (e.g., smartlists_backup_20250128_030000.zip) containing:

All smart list configurations ({listId}/config.json)
All custom images for each list

Transferring Lists Between Servers

To transfer your smart lists to another Jellyfin server:

Create a backup using Create Backup Now or download an existing backup
Copy the ZIP file to the destination server
On the destination server, use Restore from File to import the lists

Cleanup Task

SmartLists includes a maintenance task that removes orphaned data. It runs weekly (Sunday at 4:00 AM by default) and can also be run manually from Jellyfin Dashboard → Scheduled Tasks → "SmartLists cleanup task".

The task cleans up:

Orphaned plugin data: leftover configuration folders and legacy image folders from deleted lists
Leftover Jellyfin playlists and collections: items created by SmartLists whose smart list has since been deleted or disabled. This can happen if a deletion failed (for example, due to a locked file) when the list was deleted or disabled. Only items carrying SmartLists' hidden ownership marker are ever touched — playlists and collections you created yourself are never affected, including Jellyfin lists you chose to keep when deleting a smart list.

Performance Settings

Processing Batch Size

Control how many items are processed in each batch during list refreshes:

Default: 300 items per batch
Recommended: 200-500 for libraries with 1,000-20,000 items
Smaller batches (100-200): Provide more frequent progress updates on the Status page, useful for monitoring refresh progress in real-time
Larger batches (400-500): Improve processing efficiency and reduce overhead, better for very large libraries

How it works: - Items are processed sequentially in batches (one batch at a time) - Progress is reported after each batch completes, so smaller batches = more frequent updates - The batch size affects both processing efficiency and the granularity of progress reporting on the Status page

When to Adjust

Decrease (100-200) if you want more frequent progress updates on the Status page
Increase (400-500) if you have very large libraries (10,000+ items) and want maximum processing efficiency
Default (300) is optimal for most use cases, providing a good balance between efficiency and progress reporting

Manual Configuration (Advanced Users)

For advanced users who prefer JSON configuration, see the Advanced Configuration guide for details about manual file editing.