UMTK (Upcoming Movies & TV Shows for Kometa) manages your Plex media collections and overlays using Kometa (formerly Plex Meta Manager).
It includes:

• Coming Soon — Checks Radarr and Sonarr for upcoming (monitored) content expected to be released/air within x days. Either downloads trailers using yt-dlp or creates placeholder video files. For movies, Plex's 'editions' feature is used (Plex Pass required for Server admin account). For TV Shows, the trailer or placeholder file is saved as a "special" (S00E00).
• TV Show Status (formerly TSSK) — Checks your Sonarr for TV show statuses and creates .yml files for overlays and collections. Categories include: new shows, new seasons, upcoming episodes, upcoming finales, season finales, final episodes, returning, ended, and canceled shows.
• Trending — Uses MDBList to create "Trending" categories and creates placeholder files for missing items with an overlay indicating that a request is required. Optionally applies a TOP 10 ranking overlay.

Examples:

TV Show Status Overlays:

Coming Soon Movies:

Coming Soon TV Shows:

TV Shows Trending TOP 10:

In this example 3 trending shows have not been added to Sonarr (and are not available). This example uses the Kabeb template + TV Show Status overlays.

---

📑 Table of Contents

• 🛠️ Installation
  • Option 1: Docker
    • Step 1: Install Docker
    • Step 2: Create Docker Compose File
    • Step 3: Create Required Directories
    • Step 4: Configure Your Settings
    • Step 5: Update Media Paths
    • Step 6: Run UMTK
    • Step 7: Add the yml files to your Kometa config
  • Option 2: Manual Installation
    • Step 1: Clone the repository
    • Step 2: Install Python dependencies
    • Step 3: Install ffmpeg (for trailer downloads)
    • Step 4: Configure Your Config Settings
    • Step 5: Add the yml files to your Kometa config
    • Step 6: Keeping the Web UI alive (optional)
• 🖥️ Web UI
• ⚙️ Configuration
  • Connections
    • WebUI
    • Plex
    • Scheduler
    • Radarr / Sonarr Instances
    • Instances
  • Settings
    • General
    • Movies Coming Soon
    • TV Shows Coming Soon
    • Process TV Show Categories
    • TV Show Timeframes
    • MDBList Collections
    • Coming Soon Collections
    • Plex Metadata
  • YML Configurations
• 🔔 Webhook on Placeholder Creation & Removal
• 🗂️ Create your Coming Soon Collection
• ☄️ Add to Kometa Configuration
• 🍪 Using browser cookies for yt-dlp (Method 1)
• 📼 Placeholder Video (Method 2)
• 🚀 Usage
• 🌐 Localization
• 💡 Tips & Best Practices
  • Exclude Upcoming Content from "Recently Added" Sections
  • Choosing Between Methods
  • Understanding Movie Release Types
  • Scheduling with Cron (Docker)
  • Prevent Request Platforms from marking coming soon items as available
• 🩺 Troubleshooting Common Issues:
  • ❌ "Connection refused" to Sonarr/Radarr
  • ❌ "Permission denied" errors
  • ❌ "No config.yml found"
  • ❌ yt-dlp fails to download Trailers
  • ❌ A bunch of old movies/shows are being added as Coming Soon
  • ❌ Plex Error: label: RequestNeeded not found / Plex Error: label: Coming Soon not found

---

🛠️ Installation

Option 1: Docker

Step 1: Install Docker

1. Download Docker Desktop from docker.com
2. Install and start Docker Desktop on your computer
3. Verify installation: Open a terminal/command prompt and type docker --version - you should see a version number

Step 2: Create Docker Compose File

1. Create a new folder for UMTK on your computer (e.g., C:\UMTK or /home/user/UMTK)
2. Create a new file called docker-compose.yml in that folder
3. Copy and paste this content into the file:

services:
  umtk:
    image: netplexflix/umtk:latest
    container_name: umtk
    ports:
      - "2120:2120" # Web UI
    environment:
      - CRON=0 2 * * * # Run daily at 2am (used as initial default only)
      # - SCHEDULE_HOURS=24 # Alternative: run every X hours instead of a cron expression
      - DOCKER=true
      - TZ=America/New_York # Set your timezone
      - PUID=1000 # Set to your user ID (run `id -u` in terminal)
      - PGID=1000 # Set to your group ID (run `id -g` in terminal)
    extra_hosts:
      - "host.docker.internal:host-gateway" # Alternative way to access host
    volumes:
      # Configuration directory (required)
      - ./config:/app/config

      # Video directory for placeholder method (optional - only needed if using method 2)
      - ./video:/video

      # Output directory for generated YAML files (required)
      - ./kometa:/app/kometa

      # UMTK root folders
      - /your/actual/path:/umtkmovies #example: /mnt/media/umtk/movies:/umtkmovies
      - /your/actual/path:/umtktv #example: /mnt/media/umtk/tv:/umtktv

    restart: unless-stopped

1. Update the timezone in the TZ environment variable to match your location (e.g.: America/New_York, Europe/London, Asia/Tokyo)
2. Update PUID/PGID to match your system user (optional - defaults to 1000:1000)

Step 3: Create Required Directories

1. Create the required folders in your UMTK directory:

   • config folder (for configuration files)
   • video folder (for placeholder videos)
   • kometa folder (for generated YAML files)

2. Create your UMTK video file roots:

   • These will be the folders UMTK creates the trailer or placeholder files in. Make sure it's not within your Arr root path.
   • For example if your Arr roots are /mnt/media/movies and /mnt/media/tvthen you can create /mnt/media/umtk/movies and /mnt/media/umtk/tv
   • These are the UMTK roots you have to mount in your docker-compose

Step 4: Configure Your Settings

• You can skip this if you want to edit your settings in the webUI.
• Alternatively you can manually edit your settings in the yml files. See ⚙️ Configuration

Step 5: Update Media Paths

You must update the media paths in the existing docker-compose.yml file.

[!IMPORTANT] The format is: your-actual-path:container-path

Example:

• You created /mnt/media/umtk/movies and /mnt/media/umtk/tv
• In your config you set umtk_root: /umtkmovies on your Radarr instance and umtk_root: /umtktv on your Sonarr instance (see the per-instance settings under Connections)
• Then your mounts should look like this:

      - /mnt/media/umtk/movies:/umtkmovies
      - /mnt/media/umtk/tv:/umtktv

• If you run multiple Radarr/Sonarr instances with different roots (e.g. a 4K instance), add a volume mount for each distinct umtk_root.

[!TIP] By default UMTK will output the yml files in a subfolder named kometa.
You can make UMTK output the yml files directly into your Kometa/config folder for example by adjusting the volume mount.
This will make them easily accessible for Kometa. e.g.: /path/to/Kometa/config:/kometa

Step 6: Run UMTK

1. Open a terminal/command prompt in your UMTK folder
2. Type this command and press Enter:

   docker-compose up -d
   

3. That's it! UMTK will now run automatically every day at 2 AM

Step 7: Add the yml files to your Kometa config

• See ☄️ Add to Kometa Configuration

---

Option 2: Manual Installation

Step 1: Clone the repository:

git clone https://github.com/netplexflix/Upcoming-Movies-TV-Shows-for-Kometa.git
cd Upcoming-Movies-TV-Shows-for-Kometa

[!TIP] If you don't know what that means, simply download the script by pressing the green 'Code' button above and then 'Download Zip'.
Extract the files to your desired folder.

Step 2: Install Python dependencies:

• Ensure you have Python installed (>=3.11)
• Open a Terminal in the script's directory

[!TIP] Windows Users:
Go to the UMTK folder (where UMTK.py is). Right mouse click on an empty space in the folder and click Open in Windows Terminal.

• Install the required dependencies:

pip install -r requirements.txt

Step 3: Install ffmpeg (for trailer downloads)

ffmpeg is required by yt-dlp for postprocessing when downloading trailers. Check THIS WIKI for installation instructions.

Step 4: Configure Your Config Settings

• See ⚙️ Configuration

Step 5: Add the yml files to your Kometa config

• See ☄️ Add to Kometa Configuration

[!TIP] Windows users can create a batch file to quickly launch the script.
Type "[path to your python.exe]" "[path to the script]" -r pause" into a text editor

For example:

"C:\Users\User1\AppData\Local\Programs\Python\Python311\python.exe" "P:\UMTK\UMTK.py" -r
pause

Save as a .bat file. You can now double click this batch file to directly launch the script.
You can also use this batch file to schedule the script to run.

Step 6: Keeping the Web UI alive (optional)

By default a manual run is single-shot: UMTK runs once and exits, so the Web UI is only reachable while that run is in progress. If you'd rather keep UMTK running in the background with the built-in scheduler and a persistent Web UI (the same way the Docker image works), start it in server mode:

python UMTK.py --server

Or set the UMTK_SERVER environment variable to true (equivalent — handy for service managers):

# Linux/macOS
UMTK_SERVER=true python UMTK.py

# Windows PowerShell
$env:UMTK_SERVER='true'; python UMTK.py

In server mode UMTK performs an initial run, then waits and re-runs on the configured schedule (edit it live from the Web UI), keeping http://localhost:2120 available the whole time. The schedule is seeded from config.yml (or the CRON / SCHEDULE_HOURS env vars / a 24h default on first launch), exactly like Docker.

[!TIP] On Linux you can run UMTK as a systemd service so it starts on boot and stays alive:

[Unit]
Description=UMTK
After=network-online.target

[Service]
WorkingDirectory=/path/to/UMTK
ExecStart=/usr/bin/python3 /path/to/UMTK/UMTK.py --server
Environment="UMTK_SERVER=true"
Restart=on-failure

[Install]
WantedBy=multi-user.target

The Web UI binds to 127.0.0.1 (localhost only) for manual installs. To reach it from another machine, put it behind a reverse proxy or use an SSH tunnel.

---

🖥️ Web UI

UMTK includes a built-in web interface for configuration and monitoring, accessible at http://localhost:2120 (or http://your-ip:2120). Features:

• Configuration: Edit all settings through the UI.
• Connection Testing: Test your Plex, Radarr, and Sonarr connections directly from the UI with response time feedback.
• Scheduler Control: View the current status (idle/running/stopped), trigger a "Run Now", pause or resume the schedule, and see next/last run times. The schedule itself can also be edited live from the Connections tab (switch between hours-interval and cron, and save — changes take effect without a container restart).
• Live Logs: Monitor real-time application logs.
• Update Checker: Check for new UMTK and yt-dlp versions.

[!TIP] All settings can also be edited manually in the YAML config files if you prefer.

---

⚙️ Configuration

Rename config.sample.yml to config.yml and update your settings, or use the Web UI.
The sections below follow the Web UI tabs and their order, so you can read along while configuring.

[!NOTE] TSSK (TV Show Status) settings are stored in a separate tssk_config.yml (rename tssk_config.sample.yml, next to config.yml). The Web UI merges both files into one Settings page. Sonarr/Plex credentials and shared settings (utc_offset, debug, simplify_next_week_dates) are automatically read from the main config.yml — you do not need to duplicate them.

Connections

WebUI:

• webui_auth_enabled: Require a password to access the Web UI (default: true). The password is set on first launch and can be changed with the Change Password button.

Plex:

• plex_url: Your Plex URL
• plex_token: How to find your Plex Token
• movie_libraries: names of your movie libraries, comma separated
• tv_libraries: names of your TV show libraries, comma separated
• plex_library_scan: When set to true, UMTK asks Plex to scan the configured movie/TV libraries at the end of a run for library types where a new placeholder or trailer was written this run. Useful if your Plex isn't set to auto-scan for changes.

Scheduler:

• schedule_type: hours (run every X hours) or cron (cron expression). Default: cron
• schedule_hours: Interval in hours when schedule_type is hours (default: 24)
• schedule_cron: Standard 5-field cron expression when schedule_type is cron (default: 0 2 * * *). See Scheduling (Docker) for details and examples.

Radarr / Sonarr Instances:

You can configure one or more Radarr and Sonarr instances (radarr_instances / sonarr_instances in config.yml). Each instance has:

• name: A unique friendly name for this instance (e.g., Radarr, Radarr4K)
• url: Your Radarr/Sonarr URL (default: http://localhost:7878 / http://localhost:8989)
• api_key: Found in Settings → General → Security
• timeout: Request timeout in seconds. Increase if needed for large libraries (default: 90)
• exclude_tags: Comma-separated list of Radarr/Sonarr tags whose items should be skipped
• umtk_root: Where UMTK will output the folders for this instance. Every instance can point at a different root so separate Arrs (e.g. 4K) write to separate folders. Docker users: use /umtkmovies or /umtktv.

Example with multiple instances:

radarr_instances:
  - name: Radarr
    url: 'http://localhost:7878'
    api_key: 'YOUR_API_KEY'
    timeout: 90
    exclude_tags: exclude, private
    umtk_root: /umtkmovies
  - name: Radarr4K
    url: 'http://localhost:7879'
    api_key: 'YOUR_API_KEY'
    timeout: 90
    exclude_tags: exclude
    umtk_root: /umtkmovies4k

[!NOTE] Existing configs using the old flat format (radarr_url, radarr_api_key, etc.) will continue to work without changes. They are automatically converted to the new instance format at load time.

[!NOTE] If you upgrade from an older UMTK release that used the global umtk_root_movies / umtk_root_tv keys, those values are still honored — they're automatically inherited by any instance (and the Trending roots below) that doesn't set its own. The WebUI will show a banner reminding you to migrate.

Instances:

• instance_output_mode: Controls how data from multiple instances is written to YML files:

  • combined (default) — Data from all instances is merged into single YML files. Duplicate items (same TVDB/TMDB ID across instances) are deduplicated.
  • split — Each instance gets its own set of YML files with the instance name appended (e.g., UMTK_TV_UPCOMING_SHOWS_COLLECTION_Radarr4K.yml).

• cross_instance_availability: Controls whether availability is shared across instances. Only relevant when you have 2 or more instances; ignored for single-instance setups.

  • false (default) — Each instance is evaluated independently. Example: if a movie is already downloaded in your 1080p Radarr but the 4K version isn't available yet, the 4K instance still gets a "Coming Soon" placeholder and overlay.
  • true — An item that is already downloaded in any instance is treated as available everywhere, so no "Coming Soon" placeholder/overlay is created for instances where it's still missing. In the example above, the 4K instance would not get a placeholder because you already own the movie in 1080p.

Settings

• enable_umtk: Enable/disable the UMTK module — Coming Soon and Trending (default: true)
• enable_tssk: Enable/disable the TSSK module — TV Show Status (default: false)

General:

• movies: 0 = Don't process, 1 = Download trailers with yt-dlp, 2 = Use placeholder video file
• tv: 0 = Don't process, 1 = Download trailers with yt-dlp, 2 = Use placeholder video file
• new_season_placeholders: Default false. When true, UMTK also creates a placeholder/trailer (per the tv method) for shows you have no episodes of whose next monitored season (season 2 or later) premieres within TSSK's future_days_new_season. This puts TSSK's New Season Soon shows in Plex, so they can show up in a Coming Soon collection with include_new_season_soon and get TSSK's New Season overlay. Requires TSSK to be enabled with process_new_season_soon on; the placeholder is removed by cleanup once the show has downloaded episodes or stops qualifying.
• method_fallback: When set to true: If trailer downloading fails, UMTK will automatically fallback to using the placeholder method.
• preferred_language: Preferred language for trailer downloads. UMTK appends the language name to the YouTube search and boosts videos whose title or channel matches the language. Default: original (no preference). Accepted values: original, english, german, french, spanish, italian, japanese, korean, portuguese, russian, chinese.
• skip_channels: Blacklist YouTube channels that create fake trailers
• use_tvdb: (TSSK) Change to true if you prefer TheTVDB statuses for returning and ended. (Note: TheTVDB does not have the 'canceled' status)
• skip_unmonitored: (TSSK) Default true will skip a show if the upcoming season/episode is unmonitored.
• ignore_finales_tags: (TSSK) Shows with these Sonarr tags will be ignored when checking for finales.
• utc_offset: Set your UTC timezone offset
  • Examples: LA: -8, New York: -5, Amsterdam: +1, Tokyo: +9
• simplify_next_week_dates: Set to true to simplify dates to today, tomorrow, friday etc if the air date is within the coming week.
• cleanup: Set to true (default) to automatically remove trailers/placeholders when actual content is downloaded or no longer valid
• debug: Set to true to troubleshoot issues

[!NOTE] For some shows, episodes are listed one at a time — usually one week ahead — in TheTVDB/Sonarr. Because of this, TSSK may wrongly think the last episode listed in the season is a finale. You can give problematic shows like this a tag in Sonarr (and add that tag to ignore_finales_tags) so TSSK will ignore finales for that show and treat the current 'last' episode as a regular episode.

Movies Coming Soon:

• future_days_upcoming_movies: How many days ahead to look for releases (default: 30)
• past_days_upcoming_movies: How many days in the past to look for releases (default: 0 means no limit)
• include_inCinemas: Include cinema release dates (default: false, only digital/physical)
• future_only: false (default) will include already-released but not-downloaded movies. true only looks at release dates in the future.

TV Shows Coming Soon:

• future_days_upcoming_shows: How many days ahead to look for premieres (default: 30)
• recent_days_new_show: How many days back to look for new shows (default: 7)
• future_only_tv: Set to false (default) to include already-aired but not-downloaded show premieres

[!IMPORTANT] You need to add your umtk_root folders to your library folders in Plex (or create separate libraries if you prefer).
Example for TV:

Process TV Show Categories:

Each TSSK (TV Show Status) category can be individually enabled or disabled. Set to false to disable:

• process_new_shows: New shows that were added in the past x days
• process_new_season_soon: Shows for which a new season is airing within x days
• process_new_season_started: Shows for which a new season has been added which aired in the past x days
• process_upcoming_episode: Shows with upcoming regular episodes within x days
• process_upcoming_finale: Shows with upcoming season finales within x days
• process_season_finale: Shows for which a season finale was added which aired in the past x days
• process_final_episode: Shows for which a final episode was added which aired in the past x days
• process_returning_shows: Returning shows
• process_ended_shows: Ended shows
• process_canceled_shows: Canceled shows

TV Show Timeframes:

For each TSSK category, you can change the relevant timeframe:

• recent_days_new_show: How many days in the past to look for new shows (default: 7)
• future_days_new_season: How many days into the future to look for new seasons (default: 31)
• recent_days_new_season_started: How many days in the past to look for started seasons (default: 7)
• future_days_upcoming_episode: How many days into the future for upcoming episodes (default: 31)
• future_days_upcoming_finale: How many days into the future for upcoming finales (default: 31)
• recent_days_season_finale: How many days in the past for aired season finales (default: 7)
• recent_days_final_episode: How many days in the past for aired final episodes (default: 7)

MDBList Collections:

• label_request_needed: will add an additional RequestNeeded label to trending items not yet monitored in the Arrs

• always_show_dates_on_requested: (default: false) A trending item that is monitored in Radarr/Sonarr but isn't available yet normally gets the Requested overlay, unless its release date happens to fall within your Coming Soon timeframe (future_days_upcoming_movies / future_days_upcoming_shows). Enable this to give such an item the Coming Soon overlay with its known date instead, even when that date lies outside the set timeframe.

• mdblist_api_key: Can be found at https://mdblist.com/preferences/

• trending_lists: a list of MDBList lists to process — add as many as you want. Each entry has:

  • name: the Plex collection name for this list (also used in the output filenames)
  • type: movie or tv
  • method: 0 = Don't process, 1 = Download trailers with yt-dlp, 2 = Use placeholder video file
  • limit: how many items to pull from the list
  • url: the MDBList list URL. You can create your own lists.
  • root: root folder for items that aren't in any Radarr/Sonarr library (Request Needed items). Docker users: use /umtkmovies or /umtktv.
  • build_in_plex: true lets UMTK create and update this list's collection directly in Plex, with the items in MDBList rank order.
  • plex_libraries: which Plex libraries build_in_plex should build the collection in (the WebUI offers your configured movie_libraries / tv_libraries as checkboxes; the same collection is created in each one). Leave empty to use the first configured library of the list's type. The old single-value plex_library key is still read.
  • edit_sort_title / sort_title: build_in_plex only. Set edit_sort_title: true to have UMTK set the collection's sort title in Plex to sort_title (the WebUI pre-fills it with the list name). Leave it false and UMTK never touches the collection's sort title.

  Additional lists inherit the collection_trending_movies / collection_trending_shows settings (build_collection, sync_mode, labels, …). Their item_label and non_item_remove_label automatically get the list name appended (e.g. UMTKTrending_Popular_Movies) so different lists' labels don't conflict with each other.

trending_lists:
  - name: Trending Movies
    type: movie
    method: 2
    limit: 10
    url: https://mdblist.com/lists/netplexflix/umtk-trending-top20-movies
    root: /umtkmovies
  - name: Popular Movies
    type: movie
    method: 2
    limit: 20
    url: https://mdblist.com/lists/someuser/popular-movies
    root: /umtkmovies
    build_in_plex: true
    plex_libraries: [Movies, 4K Movies]
    edit_sort_title: true
    sort_title: "!02 Popular Movies"

Building collections directly in Plex

By default UMTK writes a Kometa collection YAML per trending list and Kometa creates the collection in Plex. To get the items to show up in the right order, UMTK can edit sort_titles. This however changes how those items sort everywhere in Plex, not just inside the collection.

Setting build_in_plex: true on a list makes UMTK build that collection directly in Plex instead, using Plex's own Custom collection order. On every run it creates the collection if it doesn't exist yet, adds items that joined the list, removes items that dropped off it, and re-orders the items as needed.

[!IMPORTANT] UMTK still writes the Kometa collection YAML for the list, unchanged. If your Kometa config also builds that collection, both will manage it and overwrite each other's contents and order on every run. When you enable build_in_plex, remove the collection yml from your Kometa config and disable the sort_title edits if you previously used them.

Coming Soon Collections:

coming_soon_collections does the same for your upcoming movies and shows: UMTK builds these collections in Plex itself, ordered by expected release date (movies) or expected air date (shows), oldest first. Add as many as you want — one per Plex library, per Arr instance, or any mix. Each entry has:

• name: the Plex collection name
• type: movie or tv
• libraries: which Plex libraries to build it in. The same collection is created in each one.
• instances: which Radarr (movies) / Sonarr (tv) instances to take Coming Soon items from. For tv, leave it empty to build the collection from the TSSK categories below only.
• include_new_season_soon / include_upcoming_episode / include_upcoming_finale: tv only. Also puts TSSK's shows from those categories in the collection, interleaved by air date. Requires TSSK enabled with the matching process_ option on. TSSK's own collections and labels are not affected. Shows in those categories that you don't have any episodes of yet only exist in Plex when new_season_placeholders is on.
• edit_sort_title / sort_title: set edit_sort_title: true to have UMTK set the collection's sort title in Plex to sort_title (the WebUI pre-fills it with the collection name). Leave it false and UMTK never touches the collection's sort title.

coming_soon_collections:
  - name: Movies Coming Soon
    type: movie
    libraries: [Movies]
    instances: []
  - name: 4K Movies Coming Soon
    type: movie
    libraries: [4K Movies]
    instances: [Radarr4K]
  - name: TV Shows Coming Soon
    type: tv
    libraries: [TV Shows, Anime]
    instances: [Sonarr]
    include_new_season_soon: true
    include_upcoming_episode: false
    include_upcoming_finale: true
    edit_sort_title: true
    sort_title: "!01 TV Shows Coming Soon"

[!IMPORTANT] Same as above: UMTK keeps writing UMTK_MOVIES_UPCOMING_COLLECTION.yml / UMTK_TV_UPCOMING_SHOWS_COLLECTION.yml for Kometa. Remove them from your Kometa config so both don't manage the same collection, and optionally disable the sort_title edits below.

Plex Metadata:

These options edit metadata directly in Plex and require plex_url, plex_token and the library names to be configured under Connections. If you let UMTK build your collections directly in Plex (see above), the sort title edits are not necessary and should be turned off.

• edit_sort_titles: (TSSK) Master toggle. Set to true to let TSSK prepend the relevant air date to Plex sort titles so you can sort shows by date. The sub-options pick which categories receive edits:
  • edit_sort_titles_new_season_soon: Default true. Edit sort titles for shows in the New Season Soon category.
  • edit_sort_titles_upcoming_episode: Default false. Edit sort titles for shows in the Upcoming Episode category.
  • edit_sort_titles_upcoming_finale: Default false. Edit sort titles for shows in the Upcoming Finale category.
• append_dates_to_sort_titles: Release dates will be added to the sort titles of Coming Soon movies and shows so you can sort in order of release date.
• add_rank_to_sort_title: Will add the rank in front of the sort title of trending items so you can sort in order of rank
• edit_S00E00_episode_title: Will name the S00E00 episodes as either Trailer or Coming Soon depending on whether a trailer was downloaded or placeholder file was used
• metadata_retry_limit: How many times to retry, one minute apart, when items UMTK just created aren't in Plex yet. Applies to the metadata edits and to collections UMTK builds directly in Plex. Only used when UMTK actually wrote new placeholders/trailers that run.

YML Configurations

The remaining settings customize the output .yml files for Kometa. Coming Soon, New Shows & Trending blocks live in config.yml; TV Show Status blocks live in tssk_config.yml. Each category has its own collection and overlay blocks:

• Collection blocks: Customize collection_name, item_label, build_collection, sync_mode, etc. You can enter any Kometa collection variables.
• Backdrop blocks: Enable/disable the backdrop, set colors, size, and positioning. Supports both back_color (solid color) and url (image) backdrops.
• Text blocks: Customize use_text, date_format, capitalize_dates, font color, size, and positioning.

[!TIP] You can enter any Kometa variables in these blocks and they will be automatically added in the generated .yml files.

[!NOTE] There are two different Coming Soon overlays:

• One for movies/shows with a release/air date in the future. This overlay will append the release date.
  
• One for movies/shows that have already been released/aired but haven't been downloaded yet. Depending on your setup there could be some time between the official release date and when it's actually added to your Plex server. Since the release date is in the past it isn't printed. Instead you can state it's "coming soon". You can disable this category by setting future_only to true

[!NOTE] Trending overlays: Missing trending items get one of three overlays so users know they aren't actually available yet:

• Request Needed (backdrop/text_trending_movies_request_needed, backdrop/text_trending_shows_request_needed) — the item is not in any Radarr/Sonarr library, so a request is required.
• Coming Soon — the item IS monitored in Radarr/Sonarr and releases/airs within your upcoming day range, so it reuses the regular upcoming overlay. With always_show_dates_on_requested enabled, any monitored item with a known future date gets this overlay too, no matter how far out that date is.
• Requested (backdrop/text_trending_movies_requested, backdrop/text_trending_shows_requested) — the item IS monitored but its release/air date is outside the day range or not yet known.

[!TIP] TV Show Status: For New Season Soon, New Season Started, Upcoming Finale and Season Finale you can use [#] in the use_text field to display the season number. For example: "SEASON [#] AIRS"

[!TIP] TV Show Status: group and weight are used to determine which overlays are applied when multiple are valid for the same show. For example: You add a new show, for which season 2 just aired in full yesterday. In this case the following overlays would be valid: new show, new season started and season finale. The overlay with the highest weight will be applied. If you prefer a different priority, adjust the weights accordingly. You can also have multiple overlays applied at the same time by removing group and weight, in case you position them differently.

[!NOTE] Date format options:

• d: 1 digit day (1)
• dd: 2 digit day (01)
• ddd: Abbreviated weekday (Mon)
• dddd: Full weekday (Monday)
• m: 1 digit month (1)
• mm: 2 digit month (01)
• mmm: Abbreviated month (Jan)
• mmmm: Full month (January)
• yy: Two digit year (25)
• yyyy: Full year (2025)

Dividers can be /, - or a space

---

🔔 Webhook on Placeholder Creation & Removal

UMTK can send an HTTP request whenever it creates a new file — a downloaded trailer or a copied placeholder video (for both upcoming and trending movies/shows). It also fires when the cleanup logic later removes a placeholder/trailer (e.g. the movie was downloaded, the show started airing, or the item dropped off the trending list), so the stale item gets picked up and removed from Plex too. (e.g. for triggering Autoscan/Autopulse/..)

Enable it in the WebUI on the Webhooks tab, or in config.yml.

The URL and Body support these substitution variables:

Variable	Value
{path} / {path_enc}	Full path of the affected file (raw / URL-encoded). On removal this is the file or folder that was deleted
{dir} / {dir_enc}	Parent folder of the path
{filename}	File/folder name with extension
{name_noext}	File/folder name without extension

Use the _enc variants whenever the value goes into a URL query string or a form body, since media paths contain spaces and special characters.

Extra options

Key	Description
webhook_method	POST (default) or GET
webhook_content_type	none (path in the URL — the common case), form, or json for the request body
webhook_headers	Extra request headers, one Key: Value per line (e.g. an API token)
webhook_auth_user / webhook_auth_pass	Optional HTTP Basic Auth credentials (e.g. autopulse)
webhook_timeout_seconds	Request timeout (default 10). The call is fire-and-forget — it never blocks or fails a run
webhook_path_from / webhook_path_to	Optional path remap, for when UMTK's container mounts differ from your media server's. The leading from path is replaced with to before the {path} variables are built

---

🗂️ Create your Coming Soon Collection

In the config example, we use build_collection: false.
This will tell Kometa to only apply labels to the content without actually creating the collection directly.
That way we can manually create a smart filter which includes both Coming Soon items and New Season Soon items from TSSK:

It also makes the collection more flexible allowing filters to be easily added and removed.

You can replace build_collection: false with your own Kometa collection variables to have Kometa create the collection directly.

---

☄️ Add to Kometa Configuration

Open your Kometa config.yml (typically at Kometa/config/config.yml) and add the path to the generated .yml files under collection_files and overlay_files.

Example:

TV Shows:
  collection_files:
    # UMTK
    - file: /path/to/UMTK/kometa/UMTK_TV_UPCOMING_SHOWS_COLLECTION.yml
    - file: /path/to/UMTK/kometa/UMTK_TV_TRENDING_COLLECTION.yml
    # TSSK
    - file: /path/to/UMTK/kometa/TSSK_TV_NEW_SHOW_COLLECTION.yml
    - file: /path/to/UMTK/kometa/TSSK_TV_NEW_SEASON_COLLECTION.yml
    - file: /path/to/UMTK/kometa/TSSK_TV_NEW_SEASON_STARTED_COLLECTION.yml
    - file: /path/to/UMTK/kometa/TSSK_TV_UPCOMING_EPISODE_COLLECTION.yml
    - file: /path/to/UMTK/kometa/TSSK_TV_UPCOMING_FINALE_COLLECTION.yml
    - file: /path/to/UMTK/kometa/TSSK_TV_SEASON_FINALE_COLLECTION.yml
    - file: /path/to/UMTK/kometa/TSSK_TV_FINAL_EPISODE_COLLECTION.yml
    - file: /path/to/UMTK/kometa/TSSK_TV_RETURNING_COLLECTION.yml
    - file: /path/to/UMTK/kometa/TSSK_TV_ENDED_COLLECTION.yml
    - file: /path/to/UMTK/kometa/TSSK_TV_CANCELED_COLLECTION.yml
  overlay_files:
    # UMTK
    - file: /path/to/UMTK/kometa/UMTK_TV_UPCOMING_SHOWS_OVERLAYS.yml
    - file: /path/to/UMTK/kometa/UMTK_TV_TOP10_OVERLAYS.yml
    - file: /path/to/UMTK/kometa/UMTK_TV_NEW_SHOWS_OVERLAYS.yml
    # TSSK
    - file: /path/to/UMTK/kometa/TSSK_TV_NEW_SHOW_OVERLAYS.yml
    - file: /path/to/UMTK/kometa/TSSK_TV_NEW_SEASON_OVERLAYS.yml
    - file: /path/to/UMTK/kometa/TSSK_TV_NEW_SEASON_STARTED_OVERLAYS.yml
    - file: /path/to/UMTK/kometa/TSSK_TV_UPCOMING_EPISODE_OVERLAYS.yml
    - file: /path/to/UMTK/kometa/TSSK_TV_UPCOMING_FINALE_OVERLAYS.yml
    - file: /path/to/UMTK/kometa/TSSK_TV_SEASON_FINALE_OVERLAYS.yml
    - file: /path/to/UMTK/kometa/TSSK_TV_FINAL_EPISODE_OVERLAYS.yml
    - file: /path/to/UMTK/kometa/TSSK_TV_RETURNING_OVERLAYS.yml
    - file: /path/to/UMTK/kometa/TSSK_TV_ENDED_OVERLAYS.yml
    - file: /path/to/UMTK/kometa/TSSK_TV_CANCELED_OVERLAYS.yml

Movies:
  collection_files:
    - file: /path/to/UMTK/kometa/UMTK_MOVIES_UPCOMING_COLLECTION.yml
    - file: /path/to/UMTK/kometa/UMTK_MOVIES_TRENDING_COLLECTION.yml
  overlay_files:
    - file: /path/to/UMTK/kometa/UMTK_MOVIES_UPCOMING_OVERLAYS.yml
    - file: /path/to/UMTK/kometa/UMTK_MOVIES_TOP10_OVERLAYS.yml

[!TIP] Only add the files for the categories you have enabled. All are optional and independently generated based on your config settings.

[!NOTE] Extra trending lists each write their own pair of files, named after the list, e.g. UMTK_MOVIES_TRENDING_COLLECTION_Popular_Movies.yml and UMTK_MOVIES_TOP10_OVERLAYS_Popular_Movies.yml — add those too.

---

🍪 Using browser cookies for yt-dlp (Method 1)

In case you need to use your browser's cookies with method 1, you can pass them along to yt-dlp.
To extract your cookies in Netscape format, you can use an extension:

• Firefox
• Chrome
  Extract the cookies you need and rename the file cookies.txt

For Docker Users:

Add the path to the folder containing your cookies.txt to your docker-compose.yml under volumes::

      - /path/to/cookies:/cookies

For Local Installation

1. Create a cookies folder in the same directory as the UMTK script
2. Export your browser cookies to cookies.txt within this new subfolder

---

📼 Choose Placeholder Video (Method 2)

When using the placeholder method, the script uses the UMTK video file in the video subfolder.
It's a simple intro video that shows 'coming soon':

You can replace this with one of the other included examples, or with any video you like. Just make sure your chosen video is named UMTK.

---

🚀 Usage

Docker:

The container runs automatically based on your CRON schedule. To run manually:

docker exec umtk python /app/UMTK.py

Manual:

Open a Terminal in your script directory and run:

python UMTK.py

[!TIP] You can also trigger a run from the Web UI using the "Run Now" button.

When both modules are enabled, UMTK runs first, followed by TSSK.

---

🌐 Localization

You can translate weekdays and months by using a localization file.

• Download your language from this repo (config/localization files)
• Rename it to localization.yml and place it in your config folder (next to config.yml).

If your language is missing, simply use one of the templates and edit as needed.

---

💡 Tips & Best Practices

Exclude UMTK Content from Recently Added Sections

Since UMTK adds content before it's actually available, you'll want to exclude it from "Recently Added" sections:

Example for TV Shows:

1. Go to your TV show library
2. Sort by "Last Episode Date Added"
3. Click '+' → "Create Smart Collection"
4. Add filter: Folder Location is not your UMTK TV root folder(s) (i.e. the umtk_root path(s) you configured on your Sonarr instance(s), plus the root of any TV trending list if used)
5. Press 'Save As' > 'Save As Smart Collection'
6. Name it something like "New in TV Shows📺"
7. In the new collection click the three dots then "Visible on" > "Home"
8. Go to Settings > under 'manage' click 'Libraries' > Click on "Manage Recommendations" next to your TV library
9. Unpin the default "Recently Added TV" and "Recently Released Episodes" from home, and move your newly made smart collection to the top (or wherever you want it)

Choosing Between Methods

Trailer Method (1):

• ✅ Provides actual trailers for upcoming content
• ❌ May fail if no suitable trailer is found or yt-dlp is currently blocked by YouTube

Placeholder Method (2):

• ✅ Always works (no external dependencies)
• ✅ Faster processing
• ❌ Some content may not have a Plex Pass Trailer

Understanding Movie Release Types

When include_inCinemas is enabled, UMTK considers three release types:

• Digital Release: Streaming/VOD availability
• Physical Release: Blu-ray/DVD release
• Cinema Release: Theatrical release

UMTK uses the earliest available date when multiple types exist. Keep include_inCinemas set to false to ignore cinema/theater release dates.

Scheduling (Docker)

UMTK supports two schedule modes — every X hours or a cron expression — and both can be edited live from the Web UI's Connections tab without restarting the container.

On first launch, UMTK seeds the schedule from the CRON / SCHEDULE_HOURS environment variables in your docker-compose.yml. The resolved values are then persisted into config/config.yml under schedule_type, schedule_hours, and schedule_cron. From that point on, the Web UI is the source of truth — env vars are ignored unless you wipe the scheduler keys from config.yml.

The default cron is 0 2 * * * (2 AM daily). Common alternatives:

• 0 */6 * * * - Every 6 hours
• 0 0 * * 0 - Weekly on Sunday at midnight
• 0 4 * * 1,4 - Monday and Thursday at 4 AM

Use crontab.guru to create custom schedules, or switch to "Every X hours" mode in the Web UI if you prefer interval scheduling.

Prevent Request Platforms from marking coming soon items as available

Request platforms such as Ombi and Overseerr check Plex for availability instead of Radarr/Sonarr. Therefor they will mark 'coming soon' items as available even though Radarr and Sonarr will correctly see them as 'missing'
To avoid this you can choose to create seperate libraries for your 'coming soon' items.

• In Plex, create new Coming Soon Libraries pointed to the umtk_root folder.
• Add these new libraries to your Kometa config and add the collection and overlay .yml files there.
• In Ombi/Overseerr/... unmonitor these libraries

NOTE: You'll have to instruct your users to 'pin' these new libraries. Otherwise they will not see the 'Coming Soon' collections appear on their home screen.

---

🩺 Troubleshooting Common Issues:

❌ "Connection refused" to Sonarr/Radarr:

• First: Make sure Sonarr and Radarr are actually running on your computer.
• Check that the URLs in config.yml are correct (e.g., http://localhost:8989 for Sonarr).
• If using docker, use ipaddress:8989 or host.docker.internal:8989.
• If using IP addresses (e.g., 192.168.1.100), make sure they're correct and accessible.

❌ "Permission denied" errors:

• Check your Docker path mounts in your container or docker-compose.
• Check whether the PGID:PUID you set in docker-compose has the correct permissions .

❌ "No config.yml found":

• Make sure you renamed config.sample.yml to config.yml
• Check that the config folder is properly mounted

❌ yt-dlp fails to download Trailers:

• There is a constant 'battle' between YouTube and projects like yt-dlp which sporadically 'breaks' the functionality of yt-dlp. An update of yt-dlp may be required. If you manually run the script, you can try updating yt-dlp. Report the issue so the requirements can be updated in the Docker image if needed.
• Make sure you set method_fallback: true in config to fallback to the Placeholder video method when trailer downloads fail.

❌ A bunch of old movies/shows are being added as Coming Soon

• That means you have those items monitored in Radarr/Sonarr but not downloaded.
• You need to either trigger them to download if you want them, or unmonitor them if you don't. Basically your Arrs needed a cleanup.
• Alternatively, set future_only and/or future_only_tv to true if you don't want any items that have been released to show up as Coming Soon.

❌ Plex Error: label: RequestNeeded not found / Plex Error: label: Coming Soon not found

• This happens when using the TSSK new show overlay file at a time where one of these labels are not present in your Plex library. Kometa needs these labels to 'exist' somewhere in your library or it will throw this error
• To solve this: edit any of your collections in Plex, and add the labels Coming Soon and RequestNeeded to it. This way the labels "exist" and it will not impact anything else.

---

⚠️ Need Help or Have Feedback?

• Join the Discord

---

❤️ Support the Project

If you like this project, please ⭐ star the repository and share it with the community!