Lists define sources for media you want to track and download. Multiple list sources are supported including IMDB, Trakt, Plex, Jellyfin, TMDB, music charts, book bestsellers, and custom configurations.

All lists require these parameters:

• name: Unique identifier for the list
• type: List source type (see types below)
• enabled: Enable or disable this list (true/false)

Many list types support these optional filters:

• exclude_genre: Array of genres to skip (requires IMDB cache)
• include_genre: Array of genres to require (requires IMDB cache)
• min_votes: Minimum IMDB vote count
• min_rating: Minimum IMDB rating (e.g., 4.5)
• limit: Maximum number of entries to import

Import from downloaded IMDB list CSV files.

Type: imdbfile

Note: The old imdbcsv type (direct URL import) is deprecated and no longer works. You must download the CSV file manually and use imdbfile.

Parameters:

• imdb_csv_file: Local file path to downloaded IMDB CSV file (e.g., /path/to/watchlist.csv)
• Plus common filter parameters

How to Get IMDB CSV:

1. Go to your IMDB list (e.g., https://www.imdb.com/list/ls12345678/)
2. Click the 3-dot menu → Export
3. Download the CSV file
4. Place it in an accessible location
5. Use the file path in configuration

Example:

[[lists]]
name = "IMDB_Watchlist"
type = "imdbfile"
imdb_csv_file = "/config/lists/imdb_watchlist.csv"  # Path to downloaded CSV
enabled = true
min_votes = 200
min_rating = 4.5
exclude_genre = ["Horror", "Documentary"]
include_genre = []
limit = 0  # 0 = no limit

Import from public or authenticated Trakt user lists.

Types:

• traktpublicmovielist - User movie lists
• traktpublicshowlist - User TV show lists

Parameters:

• trakt_username: Trakt username
• trakt_listname: Name of the list
• trakt_listtype: movie or show
• Plus common filter parameters (movies only for filters)

Note: Only public lists work without Trakt authentication.

Remove From List Support: These list types support remove_from_list parameter to automatically remove items after import.

Example (Movies):

[[lists]]
name = "Trakt_User_Movies"
type = "traktpublicmovielist"
enabled = true
limit = 50
min_votes = 200
min_rating = 4.5
exclude_genre = ["Horror", "Documentary"]
include_genre = []
trakt_username = "username"
trakt_listname = "my-movie-list"
trakt_listtype = "movie"
remove_from_list = false  # Set to true to auto-remove from Trakt list

Example (TV Shows):

[[lists]]
name = "Trakt_User_Shows"
type = "traktpublicshowlist"
enabled = true
limit = 50
trakt_username = "username"
trakt_listname = "my-show-list"
trakt_listtype = "show"

Import from Trakt's automated lists.

Types:

• Movies:
  • traktmoviepopular - Popular movies
  • traktmovietrending - Trending movies
  • traktmovieanticipated - Anticipated/upcoming movies
• TV Shows:
  • traktseriepopular - Popular shows (all seasons added)
  • traktserietrending - Trending shows (all seasons added)
  • traktserieanticipated - Anticipated shows (all seasons added)

Parameters:

• Plus common filter parameters (movies only for filters)

Example:

[[lists]]
name = "Trakt_Popular_Movies"
type = "traktmoviepopular"
enabled = true
limit = 20
min_votes = 200
min_rating = 4.5
exclude_genre = ["Horror", "Documentary"]
include_genre = []

[[lists]]
name = "Trakt_Popular_Shows"
type = "traktseriepopular"
enabled = true
limit = 20

Import from TMDB user-created lists.

Types:

• tmdblist - Movie lists
• tmdbshowlist - TV show lists

Parameters:

• tmdb_list: Array of TMDB list IDs (e.g., [123456, 789012])
• remove_from_list: Auto-remove from TMDB list after import (optional)
• Plus common filter parameters

How to Get TMDB List IDs:

1. Go to TMDB and sign in
2. Navigate to your list (e.g., https://www.themoviedb.org/list/123456)
3. The list ID is in the URL (e.g., 123456)
4. Or browse lists at https://www.themoviedb.org/list

Example (Movies):

[[lists]]
name = "TMDB_Custom_List"
type = "tmdblist"
enabled = true
min_votes = 200
min_rating = 4.5
exclude_genre = ["Horror", "Documentary"]
include_genre = []
tmdb_list = [123456, 789012]
remove_from_list = false  # Set to true to auto-remove from TMDB list

Example (TV Shows):

[[lists]]
name = "TMDB_Show_List"
type = "tmdbshowlist"
enabled = true
tmdb_list = [123456]

Import from TMDB's built-in popular, trending, and upcoming lists — no additional parameters required beyond common filters.

Types:

• Movies:
  • tmdbmoviepopular - Popular movies
  • tmdbmovietrending - Trending movies
  • tmdbmovieupcoming - Upcoming/new release movies
• TV Shows:
  • tmdbseriepopular - Popular TV series
  • tmdbserietrending - Trending TV series

Example:

[[lists]]
name = "TMDB_Popular_Movies"
type = "tmdbmoviepopular"
enabled = true
limit = "20"
min_votes = 500
min_rating = 6.0

[[lists]]
name = "TMDB_Upcoming"
type = "tmdbmovieupcoming"
enabled = true
limit = "10"

[[lists]]
name = "TMDB_Popular_Shows"
type = "tmdbseriepopular"
enabled = true
limit = "20"

Use TMDB's discover API with custom filters.

Types:

• tmdbmoviediscover - Discover movies
• tmdbshowdiscover - Discover TV shows

Parameters:

• tmdb_discover: Array of TMDB discover API parameters
  • Movies: see https://developer.themoviedb.org/reference/discover-movie
  • TV shows: see https://developer.themoviedb.org/reference/discover-tv
• Plus common filter parameters

How to Get Company IDs and Genre IDs:

Company IDs:

1. Search for a company at https://www.themoviedb.org/search/company
2. Click on the company (e.g., "Walt Disney Pictures")
3. Company ID is in the URL: https://www.themoviedb.org/company/2 → ID is 2

Common companies:

• Walt Disney Pictures: 2
• Warner Bros: 174
• Universal Pictures: 33
• Pixar: 3
• Marvel Studios: 420
• Sony Pictures: 34

Genre IDs:

• Action: 28
• Adventure: 12
• Animation: 16
• Comedy: 35
• Crime: 80
• Documentary: 99
• Drama: 18
• Family: 10751
• Fantasy: 14
• Horror: 27
• Mystery: 9648
• Romance: 10749
• Science Fiction: 878
• Thriller: 53
• War: 10752
• Western: 37

Full list at: https://api.themoviedb.org/3/genre/movie/list

Example:

[[lists]]
name = "TMDB_Discover_Disney"
type = "tmdbmoviediscover"
enabled = true
min_votes = 200
min_rating = 4.5
exclude_genre = ["Horror", "Documentary"]
include_genre = []
tmdb_discover = [
  'include_video=true&sort_by=primary_release_date.desc&with_companies=2&with_genres=10749|10751|35'
]

More Examples:

# Recent action movies with high ratings
tmdb_discover = ['sort_by=vote_average.desc&with_genres=28&vote_count.gte=1000&primary_release_date.gte=2023-01-01']

# Marvel Studios movies
tmdb_discover = ['with_companies=420&sort_by=release_date.desc']

# Family-friendly animations
tmdb_discover = ['with_genres=16|10751&certification_country=US&certification.lte=PG']

Import from a Plex user's watchlist.

Type: plexwatchlist

Parameters:

• plex_server_url: URL of your Plex server
• plex_token: Plex authentication token
• plex_username: Plex username whose watchlist to track

Example:

[[lists]]
name = "Plex_Watchlist"
type = "plexwatchlist"
enabled = true
plex_server_url = "http://192.168.1.100:32400"
plex_token = "your_plex_token_here"
plex_username = "username"

Getting Plex Token:

1. Sign in to Plex Web
2. Open browser developer tools (F12)
3. Go to Network tab
4. Look for requests with X-Plex-Token header

How Plex Watchlist Works:

• Plex users add items to their watchlist through Plex apps/web interface
• The watchlist is managed directly in Plex
• go_media_downloader periodically checks the watchlist and imports new items
• You can add items to Plex watchlist via:
  • Plex Web interface (click "Add to Watchlist")
  • Plex mobile apps
  • Discover tab in Plex

Import from a Jellyfin user's watchlist.

Type: jellyfinwatchlist

Parameters:

• jellyfin_server_url: URL of your Jellyfin server
• jellyfin_token: Jellyfin API key
• jellyfin_username: Jellyfin username whose watchlist to track

Example:

[[lists]]
name = "Jellyfin_Watchlist"
type = "jellyfinwatchlist"
enabled = true
jellyfin_server_url = "http://192.168.1.100:8096"
jellyfin_token = "your_jellyfin_api_key"
jellyfin_username = "username"

Getting Jellyfin API Key:

1. Go to Jellyfin Dashboard
2. Navigate to Advanced → API Keys
3. Create a new API key

How Jellyfin Watchlist Works:

• Jellyfin users add items to their favorites/watchlist in Jellyfin
• The watchlist is managed through Jellyfin interface
• go_media_downloader periodically checks and imports new items
• You can add items to Jellyfin watchlist via:
  • Jellyfin web interface (click the heart/favorite icon)
  • Jellyfin mobile apps
  • Third-party clients that support favorites

Define custom TV series lists in TOML files.

Type: seriesconfig

Parameters:

• manual_config_file: Path to TOML file (relative to executable or absolute path)

Example:

[[lists]]
name = "Custom_Series"
type = "seriesconfig"
enabled = true
manual_config_file = "series.toml"

Series Config File Format:

[[serie]]
name = "The Office"
tvdb_id = 73244
identifiedby = "ep"  # or "date"
source = "tvdb"      # or "scraper", "none"
target = ""
dont_upgrade = false
dont_search = false
search_specials = false
ignore_runtime = false
alternate_name = []
disallowed_name = []

Scrape movies from websites using custom scrapers.

Type: moviescraper

Parameters:

• url: Start URL for the scraper
• scraper_type: Type of scraper (htmlxpath, csrfapi, algolia, project1service)
• Plus scraper-specific configuration
• Plus common filter parameters

Example (HTML/XPath):

[[lists]]
name = "Custom_Movie_Site"
type = "moviescraper"
enabled = true
url = "https://example.com/movies"
scraper_type = "htmlxpath"
scene_node_xpath = "//div[@class='movie-item']"
title_xpath = ".//h2[@class='title']"
url_xpath = ".//a[@class='link']"
limit = 50

Example (CSRF API):

[[lists]]
name = "CSRF_Protected_Site"
type = "moviescraper"
enabled = true
url = "https://example.com/api/movies"
scraper_type = "csrfapi"
csrf_url = "https://example.com/login"  # URL to get CSRF token
csrf_token_xpath = "//input[@name='csrf_token']/@value"  # XPath to extract token
api_url = "https://example.com/api/search"  # API endpoint
csrf_header_name = "X-CSRF-Token"  # Header name for token
json_path_items = "data.results"  # JSON path to movie array
json_path_title = "title"  # JSON path to title field
json_path_year = "release_year"  # JSON path to year field
json_path_imdb = "imdb_id"  # JSON path to IMDB ID
limit = 50
min_votes = 100

Common Scraper Parameters:

• scene_node_xpath: XPath to each movie item container (htmlxpath)
• title_xpath: XPath to title relative to scene node (htmlxpath)
• url_xpath: XPath to detail URL (htmlxpath)
• year_xpath: XPath to year (optional, htmlxpath)
• imdb_xpath: XPath to IMDB ID (optional, htmlxpath)
• csrf_url: URL to fetch CSRF token (csrfapi)
• csrf_token_xpath: XPath to extract token from page (csrfapi)
• api_url: API endpoint URL (csrfapi)
• json_path_*: JSON path expressions for data extraction (csrfapi)

Monitor Newznab/Torznab RSS feeds for new releases.

Type: newznabrss

Parameters:

• url: Full RSS feed URL including API key and parameters
• Plus common filter parameters

Important:

• Also requires indexer configuration in quality template with same name
• Use add_found=true in media group list config to add discovered movies

Example:

[[lists]]
name = "RSS_Feed"
type = "newznabrss"
url = "http://indexer:9117/api/v2.0/indexers/1337x/results/torznab/api?apikey=key&t=search&cat=2000"
enabled = true
limit = 20
min_votes = 200
min_rating = 4.5
exclude_genre = ["Horror", "Documentary"]
include_genre = []

Corresponding Media Group Config:

[[media.movies.lists]]
name = "RSS Feed"
enabled = true
add_found = true  # Add discovered movies automatically
template_list = "RSS_Feed"
template_quality = "HD"
template_scheduler = "Default"

Corresponding Quality Template:

[[quality.quality_indexer]]
indexer = "RSS_Feed"  # Must match list name
template_downloader = "qbittorrent"
template_path = "movies"
template_regex = "english_only"
categories_indexer = "2000"
category_dowloader = "Movies"

Define audiobooks to track in a TOML file.

Type: audiobookconfig

Parameters:

• manual_config_file: Path to TOML file containing audiobook definitions

Example:

[[lists]]
name = "My_Audiobooks"
type = "audiobookconfig"
enabled = true
manual_config_file = "audiobooks.toml"

Audiobook Config File Format:

[[audiobook]]
name = "The Hitchhiker's Guide to the Galaxy"
# Additional fields follow the same structure as series config

Define ebooks/books to track in a TOML file.

Type: bookconfig

Parameters:

• manual_config_file: Path to TOML file containing book definitions

Example:

[[lists]]
name = "My_Books"
type = "bookconfig"
enabled = true
manual_config_file = "books.toml"

Define music albums or artists to track in a TOML file.

Type: musicconfig

Parameters:

• manual_config_file: Path to TOML file containing music/album definitions

Example:

[[lists]]
name = "My_Music"
type = "musicconfig"
enabled = true
manual_config_file = "music.toml"

Scrape music album charts from supported websites using XPath.

Type: musiccharts

Supported sites (set url accordingly):

• https://www.offiziellecharts.de/charts/album (German official charts)
• https://www.officialcharts.com/charts/albums-chart/ (UK official charts — any chart slug works)

Parameters:

• url: Full chart URL, optionally including a date path segment
• chart_entry_node_xpath: XPath to select each chart entry element on the page
• chart_title_xpath: XPath relative to entry node for album title
• chart_artist_xpath: XPath relative to entry node for artist name (optional)
• chart_title_attribute: HTML attribute to extract title from instead of inner text (optional)
• chart_artist_attribute: HTML attribute to extract artist from instead of inner text (optional)
• chart_default_artist: Fallback artist when XPath returns empty (e.g., "Various Artists" for compilation charts)
• chart_date_url_pattern: URL template with {date} placeholder for date-specific chart imports (optional)
• chart_date_format: How to format {date} — "timestamp_ms" (default, Unix milliseconds), "timestamp" (Unix seconds), or a Go time layout like "20060102" for YYYYMMDD

Example (Offizielle Deutsche Charts):

[[lists]]
name = "DE_Album_Charts"
type = "musiccharts"
enabled = true
url = "https://www.offiziellecharts.de/charts/album"
chart_entry_node_xpath = "//div[contains(@class,'chart-element')]"
chart_title_xpath = ".//span[@class='title']"
chart_artist_xpath = ".//span[@class='artist']"
chart_default_artist = "Various Artists"
chart_date_url_pattern = "https://www.offiziellecharts.de/charts/album/for-date-{date}"
chart_date_format = "timestamp_ms"
limit = "40"

Example (UK Official Charts):

[[lists]]
name = "UK_Album_Charts"
type = "musiccharts"
enabled = true
url = "https://www.officialcharts.com/charts/albums-chart/"
chart_entry_node_xpath = "//li[contains(@class,'chart-item')]"
chart_title_xpath = ".//div[contains(@class,'title')]"
chart_artist_xpath = ".//div[contains(@class,'artist')]"
chart_date_url_pattern = "https://www.officialcharts.com/charts/albums-chart/{date}/7502/"
chart_date_format = "20060102"
limit = "40"

Import the Last.fm global top-artists chart. Each artist is looked up in MusicBrainz and their albums are added to your library.

Type: lastfmtopartists

Requirements:

• lastfm_apikey must be set in general configuration

Parameters:

• limit: Number of top artists to fetch (default: 100, max: 1000)

Example:

[[lists]]
name = "LastFM_Top_Artists"
type = "lastfmtopartists"
enabled = true
limit = "50"

Scrape book bestseller lists from supported websites using XPath.

Type: bookbestsellers

Supported sites (set url accordingly):

• https://www.thalia.de/buch/aktuelles/buch-bestseller
• https://www.bestsellerliste.de/spiegel-bestseller-hardcover-belletristik/
• https://www.bestsellerliste.de/spiegel-bestseller-paperback-belletristik/
• https://www.bestsellerliste.de/spiegel-bestseller-taschenbuecher-belletristik/

Parameters: Same XPath parameters as musiccharts — chart_entry_node_xpath, chart_title_xpath, chart_artist_xpath, chart_title_attribute, chart_artist_attribute, chart_default_artist

Example:

[[lists]]
name = "Spiegel_Bestseller"
type = "bookbestsellers"
enabled = true
url = "https://www.bestsellerliste.de/spiegel-bestseller-hardcover-belletristik/"
chart_entry_node_xpath = "//div[contains(@class,'list-entry')]"
chart_title_xpath = ".//span[@class='title']"
chart_artist_xpath = ".//span[@class='author']"
limit = "20"

Only TMDB and Trakt user lists support automatic removal of items after import.

Supported List Types:

• tmdblist
• traktpublicmovielist
• traktpublicshowlist

Parameter:

• remove_from_list: Remove items from source list after adding to database (true/false, default: false)

Example:

# TMDB List with auto-remove
[[lists]]
name = "TMDB_Watchlist"
type = "tmdblist"
tmdb_list = [123456]
enabled = true
remove_from_list = true  # Auto-remove from TMDB list after import

# Trakt List with auto-remove
[[lists]]
name = "Trakt_Watchlist"
type = "traktpublicmovielist"
trakt_username = "user"
trakt_listname = "watchlist"
trakt_listtype = "movie"
enabled = true
remove_from_list = true  # Auto-remove from Trakt list after import

Note: Other list types (IMDB, Plex, Jellyfin, etc.) do not support automatic removal.

Lists are connected to media in your media group configuration:

[[media.movies]]
name = "EN"
# ... other settings ...

  [[media.movies.lists]]
  name = "EN Movies"           # Unique name for this list instance
  enabled = true
  add_found = false            # Add media not in DB if found
  template_list = "Watchlist"  # Links to list by name
  template_quality = "HD"      # Quality profile to use
  template_scheduler = "Default"
  ignore_template_lists = []   # Skip if media in these lists
  replace_template_lists = []  # Replace media from these lists

Skip entries that exist in other lists:

[[media.movies.lists]]
name = "HD Movies"
template_list = "Trakt_Popular"
template_quality = "HD"
ignore_template_lists = ["4K_Movies"]  # Skip if already in 4K list

Upgrade/replace entries from lower quality lists:

[[media.movies.lists]]
name = "4K Movies"
template_list = "IMDB_Watchlist"
template_quality = "4K"
replace_template_lists = ["HD_Movies", "SD_Movies"]  # Replace lower quality

1. Start Small: Begin with one list and expand as needed
2. Use Filters: Apply genre/rating filters to reduce noise
3. Limit Entries: Use limit to control import size
4. Multiple Lists: Combine different sources for better coverage
5. List Relationships: Use ignore/replace for quality upgrade workflows
6. Trakt Auth: Set up Trakt OAuth for access to private lists
7. Plex/Jellyfin: Great for family watchlist integration
8. RSS Feeds: Useful for automated monitoring of specific trackers
9. TMDB Discover: Powerful for finding movies by specific criteria
10. Remove From List: Useful for one-time import lists

[[lists]]
name = "My_Watchlist"
type = "imdbfile"
imdb_csv_file = "/config/lists/my_watchlist.csv"  # Path to downloaded CSV
enabled = true
min_rating = 5.0

[[lists]]
name = "Family_Watchlist"
type = "plexwatchlist"
enabled = true
plex_server_url = "http://plex:32400"
plex_token = "token"
plex_username = "family"

[[lists]]
name = "Trending"
type = "traktmovietrending"
enabled = true
limit = 10
min_votes = 1000
min_rating = 6.0
exclude_genre = ["Horror"]

# SD List
[[lists]]
name = "SD_Source"
type = "imdbfile"
imdb_csv_file = "/config/lists/sd_movies.csv"  # Downloaded IMDB CSV
enabled = true

# HD List (replaces SD)
[[lists]]
name = "HD_Source"
type = "traktpublicmovielist"
enabled = true
trakt_username = "user"
trakt_listname = "hd-movies"
trakt_listtype = "movie"

# In media group
[[media.movies.lists]]
name = "SD Movies"
template_list = "SD_Source"
template_quality = "SD"

[[media.movies.lists]]
name = "HD Movies"
template_list = "HD_Source"
template_quality = "HD"
replace_template_lists = ["SD Movies"]  # Upgrade from SD