====== Kodi Thumbnails (Anteprima) ======

Ogni elemento nella libreria video di Kodi può essere corredato, oltre che dai metadati, anche da delle immagini, chiamate //artwork//. Le artwork possono essere di vario tipo; quello supportato fin dalle primissime versioni di Kodi (quando si chiamava ancora XBMC) è il thumbnail abbreviato **thumb**, in italiano **Anteprima**. Non è l'artwork preferita dalle moderne skin di Kodi, essendo stata soppiantata dall'artwork di tipo **poster**. Tuttavia in assenza di artwork fornite espressamente, Kodi estrae un fotogramma dal file video e lo utilizza come **artwork di tipo thumb**.

Come **information provider** per i video preferisco utilizzare il **Local information only**, cioè per ogni file video creo il relativo file **.nfo** con i metadati e un file **.tbn** con la miniatura (file JPEG o PNG), tuttavia con la versione Kodi 19 Matrix l'utilizzo dei file .tbn **non è più supportato** correttamente.

In alternativa Kodi fornisce degli "**scraper**", cioè degli script che cercano di estrarre informazioni e immagini da pagine web: **TMDB** (The Movie Database) è il sito più gettonato. L'associazione fra il titolo di un film (in generale in italiano) e la relativa pagina web su TMDB è spesso imperfetta e anche la scelta di miniature, poster e altre immagini lascia spesso a desiderare.

L'utilizzo del file **.tbn** è **deprecato**, il sistema attualmente previsto per fornire gli //artwork// relativi ad un file (ad esempio ad un //movie//) è quello di creare dei file con nome del tipo **%%<movie>-<artwork_type>.jpg%%**. Nelle impostazioni predefinite esistono diversi tipi di artwork, per i file di tipo movie si possono avere tra gli altri (vedi [[https://kodi.wiki/view/Movie_artwork|Movie artwork]]):

^ poster     | Immagine in formato //portrait// (suggerito 2:3) con immagine e titolo oppure logo.  |
^ landscape  | Immagine in formato //landscape// (suggerito 16:9) con immagine e testo.  |
^ fanart     | Immagine in formato //landscape// (suggerito 16:9), solo immagine senza scritte.  |
^ thumb      | Immagine senza indicazioni particolari, eventualmente estratta automaticamente dal file video.  |

Sarà la skin scelta a determinare dove e come viene utilizzato l'artwork. Ad esempio la skin predefinita Estuary utilizza la //thumb// solo come ultima possibilità, se non esistono le altre. Come impostazione predefinita, se non esistono artwork per un film, viene estratto automaticamente un fotogramma dal file stesso e considerato come artwork di tipo //thumb//. L'abilità di **estrarre un fotogramma** da un video per crearne la miniatura è disattivabile da **Settings** => **Media** => **Videos** => **Artwork** => **Extract thumbnails from video files**.

**ATTENZIONE**: L'artwork di tipo //thumb// non è espressamente elencata fra gli [[https://kodi.wiki/view/Movie_artwork|artwork specifici per i film]], ma viene documentata nell'elenco dei [[https://kodi.wiki/view/Artwork_types|tipi di artwork]], quindi è supportata, sebbene non sia quella preferita.

Fino alla versione **18 Leia** di Kodi era sufficiente salvare i file **.nfo** e **.tbn** nella stessa directory del file video, quindi dal menu contestuale scegliere **Scan to library**: i metadati venivano aggiornati rileggendo il file .nfo e l'anteprima (//thumb//) era impostata dal file .tbn.

Con **Kodi 19 Matrix** la funzione **Scan to library** (che agisce sul singolo video) così come la **Update library** (che agisce su tutti i file video) rilegge solo l'eventuale file .nfo, ma **ignora la miniatura .tbn**. Fino alla versione 18 di Kodi esisteva anche l'add-on **[[https://rmrector.github.io/script.artwork.beef/|Artwork Beef]]**, in grado di aggiungere gli artwork (non solo miniature, ma anche poster, fanart, ecc) sia da siti internet che da file locali.

===== Thumbnail da file locale con Kodi 19 Matrix =====

Per chi come me ha una collezione storica di file .tbn, la soluzione più efficace per utilizzarli con Kodi 19 Matrix è quella di rinominare tutti i file in **%%<movie>-thumb.jpg%%** ed eseguire una nuova **Update library**.

Si tenga presente che la skin **Estuary** utilizza di preferenza l'artwork **poster** per mostrare il film nella modalità **Wall**. In tal caso l'immagine in orientamento //portrait// occupa tutto il rettangolo assegnato al film. Se l'artwork poster non esiste allora la skin presenta nello stesso rettangolo l'artwork **thumb** in orientamento //landscape// corredato da una etichetta sottostante con il titolo del film recuperato dai metadati oppure con il nome del file.

===== Forzare l'uso dei .tbn con Kodi 19 Matrix =====

È ancora possibile utilizzare i file .tbn con Kodi 19, facendoli acquisire come artwork di tipo thumb, tuttavia si tratta di una funzione **deprecata** e **non supportata**. Si può utilizzare la funzione **Refresh** oppure utilizzare la **API HTTP**.

==== Refresh ====

Dop aver eseguito uno **Scan to library** sul singolo file oppure un **Update library** generale, il video avrà la miniatura generica (icona della cinepresa bianca su sfondo nero). Per forzare l'acquisizione del file .tbn:

  * Aprire il menu contestuale sul video, scegliere **Information**
  * Dalla schermata delle informazioni eseguire **Refresh**
  * Chiudere la schermata con **Esc**

==== Kodi HTTP API ====

Si deve abilitare la API HTTP: dal menu **Settings** => **Services** => **Control** si attiva **Allow remote control via HTTP**. Eventualmente il servizio va protetto con una login e una password, poiché sarà aperto sulla rete locale.

L'interazione con la API può essere implementata con uno script **Python** e la libreria **requests**, oppure con strumenti da riga di comando tipo **wget** o **curl**. L'URL base per le richieste è qualcosa del tipo **%%http://kodi:@localhost:8080/jsonrpc%%**.

Per aggiornare la miniatura dal file .tbn locale sarà sufficiente chiamare la funzione **VideoLibrary.RefreshMovie** passando il **movieid** del video. Ecco un esempio della stringa JSON da inviare al servizio:

<code>
{
    "id": 100,
    "jsonrpc": "2.0",
    "method": "VideoLibrary.RefreshMovie",
    "params": {
        "movieid": 1652,
        "ignorenfo": False
    }
}
</code>

Per avere un elenco dei file video presenti in libreria, con il relativo //movieid// e la relativa //thumbnail// è possibile chiamare la funzione **VideoLibrary.GetMovies**, componendo una stringa JSON del tipo:

<code>
{
    "id": 100,
    "jsonrpc": "2.0",
    "method": "VideoLibrary.GetMovies",
    "params": {
        "properties": [ "title", "thumbnail", "file" ]
    }
}
</code>

Dal risultato potremmo estrarre l'array **%%request_text['result']['movies']%%**, in particolare l'attributo **thumbnail** potrà essere:

^ Stringa vuota                       | Nessuna miniatura è stata associata al video.  |
^ %%image://video@<video_path.mkv>%%  | Un fotogramma estratto dal video e salvato nella cache.  |
^ %%image://<thumbnail_path.tbn>%%    | Una miniatura da un file locale e salvata nella cache.  |

Nell'attributo thumbnail di tipo **%%image://%%** il percorso del video o della miniatura è assoluto e codificato come URL, cioè ad esempio il carattere slash (**%%/%%**) è //escaped// come **%%%2f%%**.

===== Artwork personalizzati =====

È possibile creare altri tipi di artwork con nome arbitrario, ad esempio **%%<movie>-<bestartwork>.jpg%%**, ovviamente sarà compito della skin utilizzarli in qualche contesto. Kodi terrà in considerazione questi artwork custom durante la scansione/aggiornamento della libreria.

Per definire un artwork personalizzato:

  * Dal menu **Information** di un video selezionare l'icona **Choose art**.
  * Nella dialog box selezionare il pulsante **Add art type**.
  * Digitare un nome arbitrario, diverso dagli [[https://kodi.wiki/view/Artwork_types|artwork esistenti]], ad esempio **bestartwork**.

Se viene aggiunto un artwork personalizzato, questo verrà memorizzato nel database **.kodi/userdata/Database/MyVideos119.db**. Dalla interfaccia Kodi sembra che non sia possibile dimenticare questo nuovo tipo, che verrà presentato ogni volta che si eseguirà la funzione **Choose art**.

Si può eventualmente intervenire direttamente sul database utilizzando il client **sqlite3**:

<code>
sqlite3 /storage/.kodi/userdata/Database/MyVideos119.db
</code>

Conviene verificare quali artwork esistono di tipo personalizzato:

<code sql>
SELECT * FROM art WHERE media_type = 'movie' AND type = 'bestartwork';
</code>

Quindi sarà possibile rimuovere l'informazione dal database:

<code sql>
DELETE FROM art WHERE media_type = 'movie' AND type = 'bestartwork';
</code>


===== Web References =====

  * **[[https://github.com/xbmc/xbmc/issues/20937|Local information provider does not consider local thumbnails for movies]]**
  * **[[https://kodi.wiki/view/NFO_files/Movies|NFO file for Movies]]**
  * **[[https://kodi.wiki/view/Movie_artwork|Artwork for Movies]]**
  * **[[https://kodi.wiki/view/Artwork_types|Artwork types]]**