# Kodi – Kompletní architektura, systém doplňků a instalace přes shell

**Datum**: 2026-04-03
**Dotazy**: "Kodi addon structure addon.xml format", "Kodi install addon without GUI shell", "Kodi addon repository system Python plugin architecture", "Kodi JSON-RPC addon management API", "Kodi addon types extension points", "Kodi Addons33.db schema", "Kodi addon directory structure", "Kodi custom repository creation"

## Shrnutí

Kodi je modulární media centrum s rozšiřitelnou architekturou postavenou na Python pluginech. Doplňky (addony) se definují souborem `addon.xml`, distribuují přes repositáře a spravují přes GUI nebo databázi `Addons33.db`. Instalace bez GUI je možná ručním kopírováním souborů + registrací v SQLite databázi + restartem Kodi. JSON-RPC API umožňuje vzdálené ovládání a správu, ale neobsahuje metodu pro instalaci ze ZIP.

## Detailní zjištění

### 1. Architektura Kodi

Kodi má vrstvovou architekturu:
- **Jádro (C++)**: Přehrávač, GUI engine, databázový systém
- **Python interpreter**: Embedded Python 3 pro spouštění doplňků
- **Skin engine**: XML-based systém pro vzhled (výchozí: Estuary)
- **Databáze**: SQLite databáze pro knihovny, doplňky, textury

#### Python moduly dostupné pro doplňky

| Modul | Účel |
|-------|------|
| `xbmc` | Jádro – přehrávání, systémové info, log |
| `xbmcgui` | GUI – okna, dialogy, widgety |
| `xbmcplugin` | Pluginy – menu, seznamy médií |
| `xbmcaddon` | Nastavení doplňku, metadata, lokalizace |
| `xbmcvfs` | Souborový systém – lokální i vzdálený |

#### Jak doplněk funguje
1. Uživatel klikne na doplněk → Kodi přečte `addon.xml`
2. Kodi spustí Python skript definovaný v `library` atributu
3. Skript používá `xbmc*` moduly pro získání dat
4. Data se vrátí přes `xbmcplugin` → Kodi je vykreslí ve skinu

### 2. Typy doplňků (Extension Points)

| Extension Point | Typ | Popis | UI |
|----------------|-----|-------|----|
| `xbmc.python.pluginsource` | Plugin | Poskytuje obsah (video, audio, obrázky) | Procházení v seznamech |
| `xbmc.python.script` | Script | Spouštitelný program, vlastní GUI | Ruční spuštění |
| `xbmc.service` | Service | Běží na pozadí od startu Kodi | Bez UI |
| `xbmc.python.module` | Module | Sdílená Python knihovna | Žádné (používají jiné addony) |
| `xbmc.addon.repository` | Repository | Repositář s doplňky | Správce doplňků |
| `xbmc.gui.skin` | Skin | Vzhled Kodi | Celé GUI |
| `xbmc.addon.resource` | Resource | Jazyk, fonty, zvuky, ikony | Žádné |
| `xbmc.python.weather` | Weather | Počasí | Widget na úvodní obrazovce |
| `xbmc.metadata.scraper.*` | Scraper | Stahuje metadata z internetu | Nastavení knihovny |

### 3. Struktura doplňku

```
plugin.video.example/
├── addon.xml              # POVINNÝ – manifest doplňku
├── addon.py               # Hlavní Python skript (entry point)
├── icon.png               # Ikona doplňku (256x256 nebo 512x512)
├── fanart.jpg             # Pozadí (1920x1080)
├── changelog.txt          # Historie změn
├── LICENSE.txt            # Licence
└── resources/
    ├── settings.xml       # Uživatelská nastavení
    ├── language/           # Jazykové soubory
    │   ├── resource.language.en_gb/
    │   │   └── strings.po
    │   └── resource.language.cs_cz/
    │       └── strings.po
    ├── lib/               # Python knihovny/moduly
    ├── media/             # Obrázky, zvuky
    └── data/              # Datové soubory
```

### 4. addon.xml – kompletní specifikace

```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="plugin.video.example"
       name="Můj Doplněk"
       version="1.0.0"
       provider-name="Autor">

    <!-- Závislosti -->
    <requires>
        <import addon="xbmc.python" version="3.0.0"/>
        <import addon="script.module.requests" version="2.25.0"/>
        <!-- Volitelné závislosti -->
        <import addon="script.module.beautifulsoup4" optional="true"/>
    </requires>

    <!-- Typ doplňku -->
    <extension point="xbmc.python.pluginsource" library="addon.py">
        <provides>video</provides>   <!-- video / audio / image / executable -->
    </extension>

    <!-- Metadata (POVINNÉ) -->
    <extension point="xbmc.addon.metadata">
        <summary lang="en_GB">Short description</summary>
        <summary lang="cs_CZ">Krátký popis</summary>
        <description lang="en_GB">Detailed description</description>
        <description lang="cs_CZ">Podrobný popis</description>
        <disclaimer lang="en_GB">Use at your own risk</disclaimer>
        <platform>all</platform>
        <license>GPL-2.0-or-later</license>
        <website>https://example.com</website>
        <source>https://github.com/example/addon</source>
        <email>author@example.com</email>
        <news>v1.0.0 - Initial release</news>
        <assets>
            <icon>resources/icon.png</icon>
            <fanart>resources/fanart.jpg</fanart>
            <screenshot>resources/screenshot-01.jpg</screenshot>
        </assets>
    </extension>
</addon>
```

#### Konvence pro addon ID

| Typ | Prefix | Příklad |
|-----|--------|---------|
| Video plugin | `plugin.video.` | `plugin.video.youtube` |
| Audio plugin | `plugin.audio.` | `plugin.audio.spotify` |
| Script | `script.` | `script.artwork.downloader` |
| Service | `service.` | `service.subtitles.opensubtitles` |
| Module | `script.module.` | `script.module.requests` |
| Repository | `repository.` | `repository.myrepo` |
| Skin | `skin.` | `skin.estuary` |
| Resource | `resource.` | `resource.language.cs_cz` |
| Metadata | `metadata.` | `metadata.themoviedb.org.python` |

### 5. Systém repositářů

Repositář = webový server s indexem doplňků.

#### Struktura repositáře

```
repository-root/
├── addons.xml              # Index všech doplňků (spojené addon.xml)
├── addons.xml.md5          # MD5 checksum indexu
└── zips/
    ├── plugin.video.example/
    │   └── plugin.video.example-1.0.0.zip
    ├── repository.myrepo/
    │   └── repository.myrepo-1.0.0.zip
    └── addons.xml          # Kopie indexu
```

#### addons.xml formát

```xml
<?xml version="1.0" encoding="UTF-8"?>
<addons>
    <!-- Kompletní <addon>...</addon> blok z každého doplňku -->
    <addon id="plugin.video.example" ...>
        ...
    </addon>
    <addon id="plugin.video.other" ...>
        ...
    </addon>
</addons>
```

#### Repository addon.xml

```xml
<addon id="repository.myrepo" name="My Repository" version="1.0.0" provider-name="Author">
    <extension point="xbmc.addon.repository" name="My Repository">
        <dir>
            <info compressed="false">https://example.github.io/repo/zips/addons.xml</info>
            <checksum>https://example.github.io/repo/zips/addons.xml.md5</checksum>
            <datadir zip="true">https://example.github.io/repo/zips/</datadir>
        </dir>
    </extension>
    <extension point="xbmc.addon.metadata">
        <summary>My custom addon repository</summary>
        <description>Repository for my Kodi addons</description>
        <platform>all</platform>
    </extension>
</addon>
```

### 6. Instalace doplňku přes shell (bez GUI)

⚠️ **Neexistuje oficiální CLI nástroj.** Instalace přes shell = ruční operace na souborovém systému a databázi.

#### Kompletní postup instalace doplňku bez GUI

```bash
# Proměnné
KODI_ADDONS="$HOME/Library/Application Support/Kodi/addons"
KODI_USERDATA="$HOME/Library/Application Support/Kodi/userdata"
ADDONS_DB="$KODI_USERDATA/Database/Addons33.db"
ADDON_ID="plugin.video.example"
ADDON_ZIP="/tmp/plugin.video.example-1.0.0.zip"

# 1. Stáhnout addon (pokud je potřeba)
curl -L -o "$ADDON_ZIP" "https://example.com/addon.zip"

# 2. Rozbalit do addonů
unzip -o "$ADDON_ZIP" -d "$KODI_ADDONS/"

# 3. Ověřit, že addon.xml existuje
cat "$KODI_ADDONS/$ADDON_ID/addon.xml" | head -5

# 4. Ověřit a nainstalovat závislosti
grep '<import addon=' "$KODI_ADDONS/$ADDON_ID/addon.xml"
# Pro každou závislost, která není nainstalovaná, opakuj kroky 1-3

# 5. Registrovat addon v databázi (Kodi MUSÍ být vypnuté!)
sqlite3 "$ADDONS_DB" "INSERT OR REPLACE INTO installed (addonID, enabled, installDate, lastUpdated, lastUsed, origin, disabledReason) VALUES ('$ADDON_ID', 1, datetime('now'), datetime('now'), datetime('now'), '', 0);"

# 6. Spustit/restartovat Kodi
open /Applications/Kodi.app
```

#### Povolení existujícího (zakázaného) doplňku bez GUI

```bash
# Kodi MUSÍ být vypnuté!
sqlite3 "$ADDONS_DB" "UPDATE installed SET enabled = 1, disabledReason = 0 WHERE addonID = '$ADDON_ID';"
```

#### Zakázání doplňku bez GUI

```bash
sqlite3 "$ADDONS_DB" "UPDATE installed SET enabled = 0, disabledReason = 1 WHERE addonID = '$ADDON_ID';"
```

### 7. Addons33.db – schéma databáze

Databáze: `~/Library/Application Support/Kodi/userdata/Database/Addons33.db`

#### Tabulka `installed`

| Sloupec | Typ | Popis |
|---------|-----|-------|
| `id` | INTEGER PK | Auto-increment |
| `addonID` | TEXT UNIQUE | Unikátní ID doplňku |
| `enabled` | BOOLEAN | 0 = zakázán, 1 = povolen |
| `installDate` | TEXT | Datum instalace |
| `lastUpdated` | TEXT | Datum poslední aktualizace |
| `lastUsed` | TEXT | Datum posledního použití |
| `origin` | TEXT | Zdroj: `repository.xbmc.org`, prázdné = ruční |
| `disabledReason` | INTEGER | 0=žádný, 1=uživatel, 2=nekompatibilní, 3=permanentní chyba |

#### Tabulka `addons`

| Sloupec | Typ | Popis |
|---------|-----|-------|
| `id` | INTEGER PK | Auto-increment |
| `metadata` | BLOB | Binární metadata |
| `addonID` | TEXT | ID doplňku |
| `version` | TEXT | Verze |
| `name` | TEXT | Název |
| `summary` | TEXT | Shrnutí |
| `news` | TEXT | Novinky |
| `description` | TEXT | Popis |

#### Tabulka `repo`

| Sloupec | Typ | Popis |
|---------|-----|-------|
| `id` | INTEGER PK | Auto-increment |
| `addonID` | TEXT | ID repositáře |
| `checksum` | TEXT | Checksum |
| `lastcheck` | TEXT | Datum poslední kontroly |
| `version` | TEXT | Verze |
| `nextcheck` | TEXT | Datum další kontroly |

#### Tabulka `addonlinkrepo`
Propojuje addon s repositářem (M:N relace).

#### Užitečné SQL dotazy

```sql
-- Všechny nainstalované doplňky
SELECT addonID, enabled, origin FROM installed ORDER BY addonID;

-- Jen uživatelské doplňky (ne systémové)
SELECT addonID, enabled FROM installed WHERE origin != '' OR origin IS NULL;

-- Zakázané doplňky
SELECT addonID, disabledReason FROM installed WHERE enabled = 0;

-- Repositáře
SELECT addonID, lastcheck, nextcheck FROM repo;
```

### 8. JSON-RPC API pro správu doplňků

#### Dostupné metody

| Metoda | Popis |
|--------|-------|
| `Addons.GetAddons` | Seznam nainstalovaných doplňků |
| `Addons.GetAddonDetails` | Detail konkrétního doplňku |
| `Addons.SetAddonEnabled` | Povolit/zakázat doplněk |
| `Addons.ExecuteAddon` | Spustit doplněk |

⚠️ **Neexistuje** `Addons.InstallAddonFromZip` – vzdálená instalace ze ZIP není z bezpečnostních důvodů podporována.

#### Příklady

```bash
# Seznam nainstalovaných doplňků
curl -s -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"Addons.GetAddons","params":{"type":"xbmc.python.pluginsource","properties":["name","version","enabled","installed","path"]},"id":1}' \
  http://localhost:8080/jsonrpc | python3 -m json.tool

# Povolit doplněk
curl -s -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"Addons.SetAddonEnabled","params":{"addonid":"plugin.video.example","enabled":true},"id":1}' \
  http://localhost:8080/jsonrpc

# Detail doplňku
curl -s -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"Addons.GetAddonDetails","params":{"addonid":"plugin.video.example","properties":["name","version","summary","description","enabled","installed","dependencies","path"]},"id":1}' \
  http://localhost:8080/jsonrpc

# Spustit doplněk
curl -s -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"Addons.ExecuteAddon","params":{"addonid":"plugin.video.example"},"id":1}' \
  http://localhost:8080/jsonrpc
```

### 9. Uživatelská data doplňků

Nastavení a data doplňků se ukládají odděleně od kódu:

```
~/Library/Application Support/Kodi/userdata/addon_data/
└── plugin.video.example/
    ├── settings.xml         # Uložená nastavení uživatele
    ├── cache/               # Cache soubory
    └── ...                  # Vlastní datové soubory
```

- `settings.xml` v `addon_data/` obsahuje hodnoty nastavené uživatelem
- `settings.xml` v `resources/` doplňku definuje strukturu nastavení (šablona)

### 10. Aktuální stav na tomto systému

**Databáze**: `Addons33.db`
**Počet nainstalovaných**: 60 doplňků (většina systémových)
**Repositáře**: `repository.xbmc.org` (oficiální)
**Doplňky z repozitáře**: `resource.language.cs_cz`, `script.module.certifi`, `script.module.chardet`, `script.module.idna`, `script.module.urllib3`, `script.module.requests`, `script.module.unidecode`
**Skin**: `skin.estuary` (výchozí)

## Zdroje

- [Kodi Wiki – Addon.xml](https://kodi.wiki/view/Addon.xml) – Oficiální specifikace manifestu
- [Kodi Wiki – Add-on Structure](https://kodi.wiki/view/Add-on_structure) – Struktura složky doplňku
- [Kodi Wiki – JSON-RPC API](https://kodi.wiki/view/JSON-RPC_API) – API dokumentace
- [Kodi Wiki – Addons Database](https://kodi.wiki/view/Databases) – Databázové schéma
- [rigacci.org – Kodi Plugin Development](https://rigacci.org) – Praktický tutoriál vývoje pluginů
- [johanzietsman.com – Kodi Repository](https://johanzietsman.com) – Tvorba vlastního repositáře

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

1. **Instalace přes shell je plně možná** – postupem: stáhnout ZIP → rozbalit do `addons/` → vyřešit závislosti → registrovat v `Addons33.db` → restart Kodi
2. **JSON-RPC pro správu** – `Addons.SetAddonEnabled` pro povolení/zakázání, `Addons.GetAddons` pro inventář
3. **Doporučuji vytvořit automatizační skript** pro instalaci doplňků přes shell, který automaticky řeší závislosti
4. **Zálohovat databázi před SQL operacemi** – `cp Addons33.db Addons33.db.bak`
5. **Zvážit vlastní repositář** na GitHubu pro distribuci vlastních doplňků
