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)
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: Unlike playlists, collections can contain other collection objects (creating "meta-collections") when using the "Include collections only" option with the Collection name field
Use cases: Organizing related content for browsing (e.g., "Action Movies", "Holiday Collection", "Director's Collection")

Automatic Image Generation

SmartLists automatically generates cover images for collections when no custom images have been provided. 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.

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 and Series with images, falling back to any items with images if needed

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

Collection images are automatically regenerated when the collection is refreshed to reflect the current items

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, 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

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:

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
Set the maximum number of items
Set the maximum playtime for the list (playlists only)
Decide if the list should be public or private (playlists only - collections are always server-wide)
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)

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 playlists are hidden from the user page. When an admin creates a playlist with multiple users selected, those playlists will not appear in the manage tab for regular users. This prevents users from accidentally editing playlists that would affect other users. Multi-user 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 max items and max playtime 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 metadata. Any images uploaded 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.

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

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.