Kodi Add-on Integration

I will provide my existing Kodi add-on ZIP and the Mad Titan Sports V2 add-on ZIP. Please create one directly installable Kodi add-on that integrates the relevant Mad Titan functionality into my existing add-on.

## Main objective

The finished add-on must feel like one seamless product:

* No separate Mad Titan installation
* No duplicate menus or interfaces
* One settings panel
* One consistent user experience
* Preserve my existing add-on’s interface, theme, menus, search, guide and skin XML wherever possible
* Do not display “Mad Titan Sports” as a separate section unless technically necessary

Only integrate sources that I am legally authorised to access. Do not bypass DRM, authentication, subscriptions or geographic restrictions.

## Movies and TV shows

Integrate Mad Titan’s on-demand content into:

* The existing Movies section
* The existing TV Shows section
* The existing universal search function

Search results must display actual movie, programme and episode titles. Do not expose backend folders or navigation entries such as:

* TMDB TV Shows
* Trakt TV Shows
* Popular
* Search
* Next Page
* Providers
* Watchlists
* Tools
* Movies or TV Shows as redundant folders

Content should use my add-on’s existing list layouts, metadata presentation and artwork rules. Do not add unwanted fan art or replace the current interface.

## Automatic stream selection

When a movie, episode or replay contains multiple playable links, automatically:

1. Resolve and validate the available links.
2. Reject dead, unsupported or inaccessible sources.
3. Prefer compatible HTTPS streams.
4. Prioritise reliable sources with the best reasonable quality.
5. Consider device capability and bandwidth where possible.
6. Start the most appropriate working stream without showing a provider-selection menu.
7. Fall back to the next suitable link if playback fails.

Include an optional setting that allows advanced users to restore manual source selection.

Automatic selection must not attempt to bypass DRM, paywalls, authentication or other access controls.

## Live sport and TV guide

Integrate compatible live-sports channels into the existing TV guide so users can browse and start streams directly from guide entries.

Requirements:

* Match streams to guide channels using stable channel IDs, names and aliases.
* Display programme names, start times, end times and descriptions when EPG information is available.
* Selecting a guide programme should automatically resolve and play its appropriate live stream.
* Avoid duplicate channels and duplicate guide entries.
* Gracefully handle channels without EPG data.
* Refresh expired stream URLs when supported by the authorised provider.

If Mad Titan does not supply structured EPG data, clearly document what external, legally available XMLTV or EPG source is required. Do not invent programme information.

## Subtitles and captions

Add optional OpenSubtitles integration for on-demand movies and episodes.

It should:

* Use the official OpenSubtitles API.
* Provide settings for the user’s own OpenSubtitles credentials or API key.
* Search automatically using IMDb/TMDB IDs where available, followed by title, year, season and episode.
* Prefer the user’s selected language.
* Download the best match and activate it automatically.
* Try alternative matches if the first subtitle is unsuitable.
* Support subtitle delay adjustment through Kodi.
* Cache subtitle files temporarily without permanently storing viewing history.
* Fail gracefully without preventing playback.

For live television and sport, first detect and enable embedded subtitle or closed-caption tracks supplied with the stream. OpenSubtitles is primarily designed for prerecorded content and generally cannot provide reliably synchronised subtitles for live broadcasts. Do not claim automatic live OpenSubtitles support unless it can be demonstrated with a real source. If no live captions are available, playback must continue normally.

## Performance

Optimise the integrated build for lower-powered Android TV boxes:

* Reduce initial startup time.
* Use lazy imports and lazy loading where appropriate.
* Avoid loading large catalogues before they are requested.
* Cache metadata safely with sensible expiration periods.
* Avoid repeated network calls.
* Paginate large results.
* Release player and network resources correctly.
* Avoid unnecessary background services.
* Reduce memory use without removing required functionality.
* Keep navigation responsive.

Record benchmarks before and after optimisation using the same device or repeatable test environment. Include:

* Cold startup time
* Time to open Movies
* Time to open TV Shows
* Search-response time
* Time from selecting an item to playback beginning
* Peak memory usage, where measurable

Report the method, number of test runs, median results and percentage improvement. Do not fabricate measurements.

## Compatibility and code quality

* Primary target: Kodi 20 Nexus
* Preserve Kodi 19 Matrix compatibility where reasonably possible.
* Use Python 3 and Kodi-compatible APIs.
* Avoid hard-coded local paths.
* Use Kodi’s profile and temporary directories correctly.
* Keep dependencies inside the final package where licensing permits.
* Prevent import conflicts between the two original add-ons.
* Refactor duplicated functionality where safe.
* Follow PEP 8 where practical.
* Add useful comments around integration, routing, playback and source-resolution logic.
* Do not unnecessarily rewrite stable code.
* Do not include credentials, tokens, cookies or personal account data.

## Reliability and testing

Test at minimum:

* Fresh installation from the produced ZIP
* Kodi restart after installation
* Existing menus and visual theme
* Movies and TV Shows browsing
* Universal search across integrated content
* Movie playback
* Episode playback
* Automatic source selection and fallback
* Live guide population
* Live-stream playback from the guide
* On-demand subtitle searching and loading
* Embedded live-caption detection
* Behaviour without OpenSubtitles credentials
* Network failure and dead-link handling
* Kodi 20 compatibility
* Kodi 19 compatibility where available
* Android and desktop test environments where available

Check Kodi’s debug log for uncaught exceptions, circular imports, missing dependencies and deprecated API usage. If anything cannot be tested, state that clearly rather than marking it as working.

## Deliverables

Provide:

1. A single Kodi-installable ZIP.
2. The complete integrated source code.
3. No dependency on a separately installed Mad Titan add-on.
4. No duplicate user-facing menus.
5. A concise change log.
6. Installation and configuration instructions.
7. Before-and-after benchmark results.
8. A test report showing passed, failed and untested cases.
9. Documentation for OpenSubtitles credentials and language settings.
10. A list of third-party code, dependencies and applicable licences.
11. A short explanation of any functionality that could not be integrated safely or reliably.