Ultimate Backend (Kodi Add-on)

Ultimate Backend is a background service for Kodi that provides a local API for live TV streaming, EPG data, and manifest management from supported online TV providers.

It acts as the bridge between streaming services and Kodi's PVR system, designed specifically to work together with the official PVR IPTV Simple Client.

---

🎯 Purpose

This add-on runs a small local web service inside Kodi. It:

• Logs in to supported streaming providers
• Retrieves live channel lists and EPG data
• Rewrites DASH manifests for Kodi playback
• Generates M3U playlists compatible with PVR IPTV Simple

Once configured, your live TV channels from streaming platforms appear directly in Kodi's TV section — complete with EPG, logos, and DRM handling.

---

📺 Supported Providers

Currently supported:

• 🇩🇪 Joyn (DE)
• 🇦🇹 Joyn (AT)
• 🇨🇭 Joyn (CH)
• 🇩🇪 RTL+
• 🇩🇪 Magenta TV 2.0
• 🇦🇹 Magenta TV (AT)
• 🇭🇷 Max TV (HR)
• 🇭🇷 HRTi (HR)
• 🇵🇱 Magenta TV (PL)
• 🇲🇪 Magenta TV (ME)
• 🇭🇺 Magenta TV (HU)

More providers will be added in future versions.

---

✨ Key Features

• 📡 Automatic Provider Integration – Unified access to multiple streaming services
• 🔁 Manifest Proxying & Rewriting – For seamless DASH playback via InputStream Adaptive
• 🔐 DRM Support – Handles Widevine, PlayReady, and ClearKey license data
• 🗓️ EPG Data – XMLTV-compatible program guide per provider (coming in future version)
• 🎵 M3U Playlist Generation – Individual playlists for each provider
• ⚡ Caching System – Caches manifests and playlists for fast reloads
• 🌍 Regional Support – Separate configurations for Germany, Austria, and Switzerland
• 🔄 Provider-Specific Proxy – Configure proxy settings individually for each provider

---

🧩 Installation

1. Copy or clone this addon into your Kodi addons directory: ~/.kodi/addons/script.service.ultimate

2. Required dependencies (Kodi installs these automatically):

   • xbmc.python ≥ 3.0.0
   • script.module.bottle ≥ 0.12.25
   • script.module.requests ≥ 2.25.1
   • script.module.pycryptodome ≥ 3.4.3

3. Restart Kodi — the Ultimate Backend service starts automatically on login.

---

⚙️ Configuration

Go to: Settings → Add-ons → Ultimate Backend → Configure

General Settings

Setting	Description	Default
Server Port	Port of the local API	7777
Default Country	Default region (DE, AT, CH, EU)	DE
API Key	Optional global API key	empty
Enable EPG Caching	Cache EPG data locally	✅ On
Cache Duration (hours)	Cache lifetime	6

Provider Configuration

Each provider can be individually enabled and configured:

Joyn Providers (DE/AT/CH)

• Enable Provider – Toggle on/off for each country
• Credentials – Enter your username and password
• Proxy Settings – Optional proxy configuration per provider:
  • Enable proxy support
  • Set proxy host and port
  • Useful for geo-restricted content or network requirements

RTL+ Provider

• Credentials – Enter your RTL+ username and password
• Proxy Settings – Optional proxy configuration:
  • Enable proxy if needed for your region
  • Configure proxy host and port

💡 Recommendation: Configure only the providers you actually use to improve performance and reduce startup time.

---

🧠 Using with PVR IPTV Simple Client

The Ultimate Backend add-on is designed to work together with PVR IPTV Simple Client

Setup Steps

1. In Kodi, go to: Add-ons → My Add-ons → PVR Clients → PVR IPTV Simple Client → Configure

2. Under General → Location, select: 🟢 Remote Path (Internet address)

3. Recommended: Use provider-specific M3U URLs for better performance and organization:

   For Joyn DE: M3U Playlist URL: http://localhost:7777/api/providers/joyn_de/m3u EPG XMLTV URL: http://localhost:7777/api/providers/joyn_de/epg

   For Joyn AT: M3U Playlist URL: http://localhost:7777/api/providers/joyn_at/m3u EPG XMLTV URL: http://localhost:7777/api/providers/joyn_at/epg

   For RTL+: M3U Playlist URL: http://localhost:7777/api/providers/rtlplus/m3u EPG XMLTV URL: http://localhost:7777/api/providers/rtlplus/epg

   Alternatively, you can use the combined playlist (not recommended for multiple providers): M3U Playlist URL: http://localhost:7777/api/m3u

4. Save and restart Kodi's PVR subsystem (or Kodi itself). Your live TV channels will now appear in Kodi's TV section.

⚠️ Note: EPG (Electronic Program Guide) data will be available in a future version. Currently, channels will be displayed without program information.

💡 Tip: To regenerate and cache the latest M3U playlist manually, open these URLs in your browser:

• Provider-specific: http://localhost:7777/api/providers/joyn_de/m3u/generate
• All providers: http://localhost:7777/api/m3u/generate

This forces the backend to rebuild and cache the playlist for faster future loading.

---

🌐 API Overview

Once running, the addon exposes a local API: http://localhost:7777/

Common Endpoints

Endpoint	Description
/api/providers	List all configured providers
/api/providers/<provider>/channels	Get available channels
/api/providers/<provider>/channels/<id>/manifest	Get or rewrite manifest
/api/providers/<provider>/channels/<id>/stream	Direct stream redirect
/api/providers/<provider>/epg	Get EPG in XMLTV format (future version)
/api/providers/<provider>/m3u	Recommended: Provider-specific cached playlist
/api/m3u	Combined playlist (all providers)
/api/providers/<provider>/m3u/generate	Force regeneration of provider-specific playlist
/api/m3u/generate	Force regeneration of combined playlist
/api/cache/mpd/clear	Clear MPD cache
/api/cache/mpd/clear-expired	Clear expired cache entries

---

🧼 Cache Management

Ultimate Backend automatically caches:

• DASH Manifests
• EPG Data (when available in future version)
• M3U Playlists (both provider-specific and combined)

Manual cache actions:

Purpose	URL
Clear all MPD cache	/api/cache/mpd/clear
Remove expired entries	/api/cache/mpd/clear-expired
Force provider M3U regeneration	/api/providers/<provider>/m3u/generate
Force all M3U regeneration	/api/m3u/generate

---

🆕 Coming Soon

• EPG Support: Full Electronic Program Guide data for all channels
• More Providers: Additional streaming services
• Enhanced Caching: Improved cache management and performance
• Advanced Settings: More configuration options for power users

Stay tuned for updates!

---

🕒 Catchup & EPG Support (Now Available)

Ultimate Backend now includes fully working Catchup TV and EPG support.

🕒 Catchup TV

• Provider-based catchup windows (hours configurable per provider)
• Seamless playback via the same stream endpoint
• Works transparently with Kodi PVR IPTV Simple Client
• Automatic validation to ensure playback stays within allowed catchup ranges

🗓️ EPG (Electronic Program Guide)

• Live EPG data support is now enabled
• XMLTV-compatible output
• Per-provider EPG endpoints
• Supports external EPG sources via URL

🧩 EPG Channel Mapping

• Built-in EPG mapping interface
• Fuzzy matching to map provider channels to EPG channels
• Manual override and fine-tuning via web UI
• Mapping is persisted and reused automatically

Access the web UI at: http://localhost:7777/

---

🐳 Docker Support

Ultimate Backend can be run fully standalone using Docker.

docker-compose.yml

version: '3.8'

services:
  ultimate-backend:
    build:
      context: .
      args:
        - USER_ID=1000
        - GROUP_ID=1000
    image: nirvana777/ultimate-backend:latest
    container_name: ultimate-backend
    restart: unless-stopped
    ports:
      - "7777:7777"
    environment:
      - ULTIMATE_PORT=7777
      - ULTIMATE_DEBUG=false
      - ULTIMATE_EPG_URL=https://raw.githubusercontent.com/epgshare01/share01/master/epg.xml.gz
      - TZ=${TZ:-Europe/Berlin}
    volumes:
      - ./config:/config
      - ./logs:/logs
      - ./cache:/cache
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:7777/api/providers"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    networks:
      - ultimate-network
    
networks:
  ultimate-network:
    driver: bridge

🚀 Docker Notes

• Perfect for NAS, servers, and headless setups
• No Kodi installation required
• Web UI, API, M3U, EPG, and Catchup all work identically

---