Skip to content

About

M3U Editor Plugin: Enrich EPG programme data with TMDB artwork, genres and descriptions

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

205 Commits

Folders and files

Repository files navigation

EPG Enricher Plugin

Enriches EPG programme data with artwork, genres and descriptions from TMDB. Only processes channels that are actually mapped in your playlists, complementing existing Schedules Direct / Gracenote metadata where data is missing.

Features

  • Playlist-scoped - Only enriches channels mapped in your playlists, not the entire EPG source
  • TMDB Artwork - Adds poster and backdrop images to programmes missing artwork
  • Genre/Category - Fills in missing programme genres from TMDB data
  • Descriptions - Adds missing programme descriptions/overviews from TMDB
  • EPG Category Mapping - Maps genres to compact Emby compatible categories or detailed Kodi guide color genres from m3u-editor issue 347
  • Gracenote-aware - Respects existing Schedules Direct / Gracenote metadata and only fills gaps
  • Title Cache - Caches TMDB lookups to disk to avoid redundant API calls across runs

Requirements

  • TMDB API key configured in M3U Editor general settings
  • M3U Editor plugin API 1.0.0, with the EpgCacheEnrichmentService capability from host PR #1556 deployed before this plugin version is enabled
  • At least one EPG source with a valid cache
  • Channels mapped to EPG channels in at least one playlist

Settings

Setting Default Description
Enrich from TMDB On Fetch posters, genres and descriptions from TMDB
Overwrite existing Off Replace existing metadata even if already present (e.g. from Schedules Direct)
Enrich categories On Fill missing genre/category from TMDB
Enrich descriptions On Fill missing descriptions from TMDB
Map genres to Emby compatible categories Off Normalize genres to compact Emby-style categories (Movie, Series, News, Sports, Kids, Documentary, Music, Education)
Map genres to Kodi guide color genres Off Normalize genres to the detailed Kodi labels from m3u-editor issue 347 (Basketball, Public Affairs, Comedy-Drama, Science Fiction, Cooking, Game Show, etc.). This takes precedence over the Emby compatible mapping when both are enabled.
Auto-run on cache On After a related EPG cache is generated, enrich all EPG sources used by each eligible selected playlist

Compatibility behavior

Emby compatible Kodi detailed Category output
Off Off Standard XMLTV. Preserve the first source or TMDB genre without client-specific normalization.
On Off Compact Emby compatible categories.
Off On Detailed Kodi guide color genres.
On On Detailed Kodi guide color genres. Kodi takes precedence.

Jellyfin, Plex, TiviMate, m3u-tv, and other clients use Standard XMLTV because no verified plugin output difference requires another setting. Programme identity and artwork ordering remain globally correct XMLTV behavior rather than client profile behavior. Keyword category detection is active when either existing category mapper is enabled.

How It Works

  1. After the EPG cache is generated (hook: epg.cache.generated), or when triggered manually
  2. Resolves every EPG source and channel ID used by each eligible selected playlist
  3. Reads bounded, canonical programme snapshots from the host, but only processes targeted channels
  4. For each programme missing artwork/genres/descriptions:
    • Checks the local TMDB title cache
    • If not cached, searches TMDB (movie first, then TV series)
    • Fetches full details (poster, backdrop, genres, overview)
    • Reads bounded pages using the host's integer cursor and submits conditional id/hash patches; the host publishes accepted changes
  5. Programmes that already have metadata (e.g. from Schedules Direct / Gracenote) are skipped unless "Overwrite existing" is enabled
  6. Upgrade sequence: deploy the host capability first, then enable this plugin release. The manifest API version is 1.0.0 because the host validator requires an exact match; this does not imply that a pre-#1556 1.0.0 host provides the enrichment service. The plugin fails without that service and never uses direct cache access. This repository does not claim live server, XMLTV-consumer, or Emby validation.

Artwork roles, XMLTV and clients

The plugin submits canonical artwork through the host API. The host accepts its canonical poster, banner, fanart, and logo image types; plugin backdrop and screenshot candidates are normalized to fanart and banner respectively before submission. The host owns cache persistence and serialization; channel logos remain channel metadata. A backdrop does not satisfy an enabled poster requirement, and a poster never replaces the generic programme icon by itself.

For the current host export, programme.icon remains the generic <icon> fallback for icon-only XMLTV consumers. Plugin-only changes cannot make an arbitrary consumer read image roles it never imports. The pending host API contract is m3u-editor PR #1556; no live server, XMLTV-consumer, or Emby validation is claimed here.

TMDB vote fields rank otherwise eligible images but do not prove content identity or visual suitability. A geometrically valid unvoted backdrop is retained with explicit tmdb_metadata_unrated provenance rather than being reported as a positively-rated selection. A client can still crop, cache, or ignore a role after a correct feed has been exported; that is distinct from an enrichment failure.

Version History

1.9.0

  • Breaking: Removed TheSportsDB integration. SportsDB enrichment is now a separate plugin: m3u-editor-epg-sportsdb
  • Removed settings: "Enrich sport events from TheSportsDB", "TheSportsDB API key", "TheSportsDB country filter"

1.8.1

  • Fixed confusing statistics: replaced "programmes skipped" with clearer "programmes processed", "programmes updated", "programmes already enriched"
  • Fixed duplicate log entries in Activity Stream
  • Fixed rename error when cache directory is removed during enrichment

1.8.0

  • Added TheSportsDB integration for sport programme enrichment (now moved to separate plugin)
  • Added smart TMDB matching with title splitting and result validation
  • Added keyword-based category detection for Sports, News, Kids, Documentary

1.7.0

  • Added configurable enrichment toggles for posters, backdrops, categories, descriptions
  • All enrichment features individually toggleable via boolean settings

1.6.0

  • Added playlist filter for auto-run: choose which playlists should be enriched automatically (leave empty for all)

1.5.1

  • Fixed invalid setting type for TMDB language (use text instead of string)

1.5.0

  • Added TMDB search language setting to improve matching for non-English programmes (e.g. German shows like "Galileo Stories", "GRIP - Das Motormagazin")
  • Set to de-DE for German EPG sources, fr-FR for French, etc. Leave empty to use the global setting.

1.4.1

  • Added repository field to plugin.json for automatic update checking

1.4.0

  • Added Emby EPG genre color mapping: normalizes TMDB genres (English + German) to Emby-compatible categories (News, Sports, Kids, Movie, Series, Documentary, Music, Education)
  • New setting "Map Emby genres" (off by default) - also remaps existing categories from other sources

1.1.0

  • Breaking: Removed gap filling feature (use the built-in "Enable dummy EPG" in playlist settings instead)
  • Enrichment now scoped to playlist channels only (not the entire EPG source)
  • Respects existing Schedules Direct / Gracenote metadata
  • Tracks skipped (non-playlist) programmes in stats

1.0.2

  • Fixed plugin validation (settings field IDs, data_ownership structure)

1.0.1

  • Added missing queue_jobs permission

1.0.0

  • Initial release

About

M3U Editor Plugin: Enrich EPG programme data with TMDB artwork, genres and descriptions

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages