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
  • General
  • Radarr/Sonarr Instances
  • Instance Output Mode
  • Plex Configuration (for metadata edits)
  • Movie Settings
  • TV Show Settings
  • Trending
  • Overlay & Collection Settings
  • TSSK Configuration (TV Show Status)
• 🔔 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 UMTK and TSSK settings through the UI. Organized in tabs: Connections (WebUI/Plex/Radarr/Sonarr), UMTK settings, and TSSK settings.
• 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 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:

General:

• 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). See TSSK Configuration for settings.
• 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
• 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.
• utc_offset: Set your UTC timezone offset
  • Examples: LA: -8, New York: -5, Amsterdam: +1, Tokyo: +9
• debug: Set to true to troubleshoot issues
• cleanup: Set to true (default) to automatically remove trailers/placeholders when actual content is downloaded or no longer valid
• simplify_next_week_dates: Set to true to simplify dates to today, tomorrow, friday etc if the air date is within the coming week.
• skip_channels: Blacklist YouTube channels that create fake trailers

Radarr/Sonarr Instances:

You can configure one or more Radarr and Sonarr instances. Each instance needs:

• name: A unique 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: Increase if needed for large libraries (default: 90)
• exclude_tags: Comma-separated tag names to exclude from processing

Example with multiple instances:

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

[!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.

Instance Output Mode:

• 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.

Plex Configuration (for metadata edits):

• 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.
• append_dates_to_sort_titles: Release dates will be added to sort titles so you can sort in order of release date.
• add_rank_to_sort_title: Will add the rank in front of the sort title 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 metadata edits. This gives Plex some time to pick up the newly created items.

Radarr / Sonarr Instance Settings:

Each Radarr and Sonarr instance has its own options configured under the Connections tab in the WebUI (or directly under radarr_instances / sonarr_instances in config.yml):

• name: A friendly label for the instance (e.g. Radarr, Radarr4K).
• url: The instance URL.
• api_key: The instance API key.
• timeout: Request timeout in seconds (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.

[!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.

Movie Settings:

• 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 Show Settings:

• 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:

Trending:

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

• 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
  • url: the MDBList list URL. You can create your own lists.
  • limit: how many items to pull from the list
  • root: root folder for items that aren't in any Radarr/Sonarr library (Request Needed items). Docker users: use /umtkmovies or /umtktv.
  • legacy_filenames: used automatically for backwards compatibility. Do not use/change.

  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
    url: https://mdblist.com/lists/netplexflix/umtk-trending-top20-movies
    limit: 10
    root: /umtkmovies
    legacy_filenames: true
  - name: Popular Movies
    type: movie
    method: 2
    url: https://mdblist.com/lists/someuser/popular-movies
    limit: 20
    root: /umtkmovies

[!NOTE] Upgrading from an older version? The old trending_movies, trending_tv, mdblist_movies, mdblist_movies_limit, mdblist_tv, mdblist_tv_limit, trending_root_movies and trending_root_tv keys are deprecated but still work: they are automatically converted into two trending_lists entries (with legacy_filenames: true, so your existing Kometa file references keep working). Saving the Trending settings in the WebUI migrates your config file to the new format.

[!NOTE] If the same item appears in several lists, it is only processed once: the first list (in config order) that contains it decides its method, root and Top 10 rank. The RequestNeeded label collection is written to a single file per type (the legacy_filenames list's file if present) and covers all lists. [!TIP] With Pulsarr you and your users can easily request missing content by adding it to watchlist in Plex. No external request platforms needed.

Overlay & Collection Settings:

The remaining settings customize the output .yml files for Kometa.

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

[!NOTE] There are two different 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.
• 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.

[!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

TSSK Configuration (TV Show Status):

TSSK settings are stored in a separate config file. Rename tssk_config.sample.yml to tssk_config.yml in your config folder (next to config.yml).

[!NOTE] 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.

TSSK General Settings:

• use_tvdb: Change to true if you prefer TheTVDB statuses for returning and ended. (Note: TheTVDB does not have the 'canceled' status)
• skip_unmonitored: Default true will skip a show if the upcoming season/episode is unmonitored.
• ignore_finales_tags: Shows with these Sonarr tags will be ignored when checking for finales.

TSSK Sort Title Edits:

TSSK can edit sort titles directly in Plex, prepending the relevant air date so you can sort shows by date. The master toggle enables the feature; the sub-options pick which categories receive edits.

• edit_sort_titles: Master toggle. Set to true to let TSSK edit Plex sort titles. Requires plex_url, plex_token, and tv_libraries to be configured.
• 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.

[!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.

TSSK Categories:

Each 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

TSSK Timeframe Settings:

For each 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)

TSSK Collection & Overlay Settings:

Each category has its own collection and overlay blocks, following the same pattern as the UMTK overlay settings.

• 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] 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] 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] The date format options are the same as listed above in the Overlay & Collection Settings section.

---

🔔 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 under UMTK Settings → Webhook (at the bottom of the page), 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 (without legacy_filenames) 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!