# Kodi Cache systém – nativní podpora a best practices pro addony

**Datum**: 2026-04-06
**Dotazy**: Kodi native image cache thumbnails, xbmcvfs addon data persistence, simplecache HTTP response cache, Window.Property cache

## Shrnutí

Kodi nabízí 3 úrovně nativní cache: automatický **image cache** (Thumbnails), **addon profile directory** pro persistentní data, a **Window.Property** pro session-based stav. Pro HTTP response caching existují community moduly (`simplecache`, `requests-cache`), ale plugin už má vlastní `TMDbCache` implementaci. Klíčové zjištění: obrázky se cachují AUTOMATICKY, API odpovědi vyžadují explicitní caching, a Window.Property je POUZE pro malý ephemeral stav.

## Detailní zjištění

### 1. Kodi Image Cache (AUTOMATICKÁ – není třeba řešit)

- **Trigger**: Každý obrázek zobrazený v GUI je automaticky cachován
- **Proces**: URL → CRC hash → optimalizace (resize, encode) → uložení do `userdata/Thumbnails/`
- **Index**: `userdata/Database/Textures13.db` (SQLite s mapováním URL → soubor)
- **Validace**: Max 1× za 24h kontroluje změnu na zdroji
- **Cleanup**: Kodi 22+ automaticky maže obrázky nepoužité 30+ dní
- **Pro addon**: Stačí nastavit URL obrázku a Kodi se o zbytek postará
- **Bypass**: Pokud se obrázek na stejné URL změní, přidej `?t=timestamp` k URL

### 2. Addon Profile Directory (persistentní data)

```python
import xbmcaddon, xbmcvfs
addon = xbmcaddon.Addon()
data_dir = xbmcvfs.translatePath(addon.getAddonInfo('profile'))
# → special://profile/addon_data/plugin.video.milionar/
```

- **Kde ukládat**: VŽDY do profile directory, NIKDY do instalačního adresáře
- **Formáty**: JSON (metadata, konfigurace), SQLite (velké datasety), pickle (binární)
- **Přežívá**: Restart Kodi ✓, update addonu ✓, reinstalaci ✗

### 3. Window.Property (session cache)

- **Typ**: In-memory, string-only, platnost = životnost okna
- **Pro**: Komunikace Python ↔ XML, malé flagy, aktuální stav UI
- **Proti**: Mizí po zavření dialogu, pouze stringy, neefektivní pro velká data
- **NEPOUŽÍVAT** pro: API response cache, persistentní data, velké objekty

### 4. TMDbCache (naše existující implementace)

Plugin už má `wcs/metadata/TMDbCache.py`:
- JSON soubor v addon profile: `tmdb_cache.json`
- Klíč = SHA256 hash z endpoint + params
- TTL-based expirace (kontrola při čtení)
- API: `get_or_fetch(endpoint, params, fetch_fn, expire_seconds)`
- **Problém**: Celá cache se načítá/ukládá jako jeden JSON – neefektivní pro velkou cache
- **Výhoda**: Jednoduchá, funguje, není nutná externí závislost

### 5. Community moduly

| Modul | Účel | Závislost |
|-------|------|-----------|
| `script.module.simplecache` | SQLite-based cache s TTL | `addon.xml` import |
| `script.module.requests-cache` | Automatický HTTP response cache | `addon.xml` import |

**Doporučení**: Pro náš plugin je `TMDbCache` dostatečná. Přidávat externí závislosti kvůli slideshow cache je zbytečné.

## Doporučení pro MyTV slideshow

### Současný stav cache v slideshow

| Úroveň | Implementováno? | Poznámka |
|---------|----------------|----------|
| Kodi image cache (pixely) | ✅ Automaticky | Kodi cachuje každý fanart |
| In-memory URL cache (session) | ✅ `_slideshow_urls` | Pro stejný seriál se URL nefetchují znovu |
| Disk cache (TMDbCache) | ❌ Chybí | `_fetch_series_backdrops()` volá requests přímo |

### Řešení: Napojit na TMDbCache

Stačí obalit existující fetch do `get_or_fetch()`:

```python
from wcs.metadata.TMDbCache import get_or_fetch

def _fetch_series_backdrops(self, tmdb_id):
    endpoint = f'/tv/{tmdb_id}/images'
    params = {'api_key': api_key}
    
    def fetch():
        response = requests.get(url, timeout=10)
        return response.json() if response.status_code == 200 else None
    
    data = get_or_fetch(endpoint, params, fetch, expire_seconds=604800)  # 7 dní
    # ... zpracování backdrops ...
```

**Výhody**:
- Backdrop URL se cachují na 7 dní na disku
- Žádné API cally po prvním otevření seriálu
- Konzistentní s ostatními TMDb daty v pluginu
- Žádná nová závislost

## Zdroje

- Kodi Wiki – Thumbnails/Image Cache
- Kodi Wiki – Add-on development best practices
- GitHub – script.module.simplecache
- Kodi Forum – Settings cache patterns

## Závěr a doporučení

1. **Obrázky**: Kodi cachuje automaticky – nic neřešit ✓
2. **Backdrop URL seznamy**: Napojit na existující `TMDbCache` s 7denním TTL
3. **In-memory cache**: Ponechat `_slideshow_urls` pro session rychlost ✓
4. **Window.Property**: Správně používáme jen pro UI stav ✓
5. **NEPOUŽÍVAT**: Žádné nové externí závislosti (simplecache atd.)
