# Guida Utente di Omni Describer

Dare una voce al mondo visivo con l’AI.

Tutto è iniziato con il mio amore per il cinema. Quando ho realizzato quanti dettagli delle mie scene preferite andassero persi senza una buona descrizione audio, è scattata un’idea: “Beh, l’AI non potrebbe facilitarci questo?” Ho sognato uno strumento che non generasse semplicemente descrizioni, ma desse completo controllo all’utente. Dopo mesi di lavoro intenso, infiniti tentativi e superamento di molti ostacoli tecnici, ho sviluppato Omni Describer come prodotto di quel sogno.

## Indice

- Che Significato ha il Nome?
- Requisiti di Sistema
- Primi Passi: Configurare le Chiavi API
- Avvio Rapido: Generare la Prima Descrizione
- Funzionalità Principali
  - Il Lettore Video Descritto
  - Gestione dei Prompt Predefiniti
  - Chiedi di Più sulla Scena
  - Esploratore di Scena
  - Esportazione del Materiale
- Approfondimento: Impostazioni Avanzate
- Suggerimenti e Trucchi per Risultati Migliori
- Domande Frequenti (FAQ)
- Scorciatoie da Tastiera
- Ringraziamenti, Contatti e Collaboratori

## Che Significato ha il Nome?

“Omni” nel nome deriva dal latino e significa “tutto” o “ogni cosa”. Ho scelto questo nome perché non volevo che lo strumento servisse solo a uno scopo. Sì, Omni Describer mira principalmente a rendere i media accessibili per persone non vedenti o ipovedenti creando descrizioni audio. Tuttavia, il suo scopo non si limita a questo.

È anche uno strumento di esplorazione. Un critico cinematografico, uno studente, un artista o chiunque sia curioso dei dettagli visivi può usare funzionalità come “Esploratore di Scena” o “Chiedi di Più” per approfondire i livelli di un video come mai prima. Omni Describer è una finestra per vedere il mondo attraverso gli “occhi” dell’AI e capirlo diversamente. In breve, è “un descrittore per tutto, per tutti”.

## Requisiti di Sistema

Per ottenere le migliori prestazioni da Omni Describer, consiglio di rispettare i seguenti requisiti minimi:

- Sistema Operativo: Windows 10 o successivo (64 bit).
- Memoria (RAM): Almeno 4 GB.
- Spazio Disco: Almeno 500 MB liberi per l’applicazione e i file temporanei.
- Connessione Internet: Necessaria per connettersi ai servizi AI (Google Gemini, OpenAI) e scaricare video.
- Screen Reader: Per piena accessibilità, si consiglia un lettore di schermo come JAWS, NVDA o Windows Narrator.

## Primi Passi: Configurare le Chiavi API

Omni Describer utilizza servizi AI basati su cloud per analizzare e dare voce alle descrizioni. Pertanto, è necessario inserire le proprie chiavi API prima di iniziare.

1. Apri Impostazioni: Vai al menu File e seleziona Impostazioni... (o premi Ctrl + ,).
2. Scheda Impostazioni AI:
   - Chiave API Gemini: Obbligatoria per l’analisi video. Incolla la tua chiave nel campo “Gemini API Key:”. Puoi ottenere una chiave gratuita da Google AI Studio.
   - Chiave API OpenAI (per TTS): Necessaria per la sintesi vocale di alta qualità. Incolla la tua chiave in questo campo. È possibile usare comunque le voci SAPI5 integrate in Windows, ma OpenAI è consigliato per risultati migliori. Puoi ottenerla da OpenAI Platform.
3. Salva: Clicca su Applica o OK per salvare le impostazioni. Sei pronto per partire!

Nota Bene: Le tue chiavi API sono memorizzate in modo sicuro sul tuo computer nel file delle impostazioni dell’app e non vengono mai inviate altrove, se non per connettersi ai rispettivi servizi AI.

## Avvio Rapido: Generare la Prima Descrizione

Iniziamo! Segui questi semplici passaggi:

1. Scegli un Video: Clicca un bottone come “File Video Locale” nella finestra principale o seleziona la tua sorgente video dal menu File.
2. Seleziona un Prompt (Facoltativo): Il menu a tendina elenca istruzioni predefinite che guidano l’AI. Per il primo tentativo, “Descrizione Standard” è un ottimo punto di partenza.
3. Avvia l’Elaborazione: L’applicazione inizierà ad analizzare il video. Puoi seguire l’avanzamento nel “Registro di Stato” in basso. Ci vorranno alcuni minuti, a seconda della durata del video.

Al termine, si aprirà automaticamente il Lettore Video Descritto, e potrai iniziare a goderti il video con le nuove descrizioni!

## Funzionalità Principali

### Il Lettore Video Descritto

Questo è il tuo cinema personale descritto. Mentre il video scorre normalmente, il tuo screen reader installato (come JAWS o NVDA) leggerà le descrizioni audio generate nei momenti corretti.

- Controlli di Riproduzione: Usa i pulsanti Play/Pausa, Riavvolgi/Avanti, o la barra di ricerca per navigare nel video.
- Area Descrizione Audio Corrente: Puoi seguire il testo della descrizione attiva in quel momento.
- Modifica Descrizioni: Se una descrizione è inaccurata, mal sincronizzata, o vuoi rimuoverla, clicca “Modifica Descrizioni…” per correggerla o eliminarla facilmente.
- Consumo Token AI: Quest’area mostra quanti “token” AI sono stati usati durante l’elaborazione, aiutandoti a tenere sotto controllo l’uso API.

### Gestione dei Prompt Predefiniti

I prompt sono istruzioni potenti che determinano su cosa si concentra l’AI. Cambiando il prompt, puoi ottenere descrizioni in stili molto diversi.

- Selezione di un Predefinito: Prima di elaborare un video, scegli un preset dal menu a tendina nella finestra principale.
- Gestione dei Prompt: Vai su File -> Gestisci Prompt Predefiniti.... Qui puoi Aggiungere, Modificare o Eliminare i tuoi prompt personalizzati. Perfetto per salvare istruzioni usate frequentemente.
- Specifico per Lingua: I tuoi preset sono salvati separatamente per ogni lingua selezionata nelle Impostazioni.

### Chiedi di Più sulla Scena

Hai mai desiderato sapere cosa sta tenendo un personaggio o cosa dice un cartello sullo sfondo? Questa funzionalità ti permette di chiedere qualsiasi curiosità sulla scena.

1. Metti in pausa il video nel punto che ti interessa.
2. Clicca il bottone Chiedi di Più....
3. Digita la tua domanda nel campo “La tua nuova domanda:” (es. “Di che colore è il cappello della donna?” o “Cosa c’è scritto sul muro?”).
4. Seleziona quanti secondi di video l’AI deve analizzare, a partire dalla posizione attuale del cursore.
5. Clicca “Invia Domanda.” La risposta dell’AI apparirà nell’area “Storico Conversazioni”.

### Esploratore di Scena

Lo Scene Explorer è un modo interattivo per capire la disposizione spaziale di una scena. Ti mette in una stanza virtuale che puoi esplorare con la tastiera.

1. Metti in pausa il video su una scena da esplorare in dettaglio.
2. Clicca il bottone Esplora Scena..., poi clicca “Analizza Scena”.

Ora sei nello Scene Explorer. Usa la tastiera per esplorare:

- Freccia Su/Giù/Sinistra/Destra: Muoviti sulla griglia della stanza virtuale.
- D: Fornisce una descrizione dettagliata della disposizione generale della scena.
- L: Annuncia un elenco di tutti gli oggetti nella scena.
- Maiusc + L: Attiva la “Modalità Salto” per selezionare un oggetto e andare direttamente a esso.
- Invio: Fornisce una descrizione dettagliata dell’oggetto più vicino.
- Esc: Chiude lo Scene Explorer.

### Esportazione del Materiale

Quando sei soddisfatto delle descrizioni, puoi esportarle dalla finestra del lettore in vari formati:

- Esporta in .TXT: Un semplice file di testo con timestamp.
- Esporta in .SRT: Un file di sottotitoli standard utilizzabile con lettori video come VLC.
- Esporta Audio (MP3): Questa è forse la funzione più interessante. Voce le descrizioni con la voce scelta nelle Impostazioni (SAPI5 o OpenAI), le miscela con l’audio originale del video e abbassa automaticamente il suono di sottofondo durante le descrizioni per creare un file MP3 ascoltabile ovunque.

## Approfondimento: Impostazioni Avanzate

La finestra Impostazioni (Ctrl + ,) ti offre controllo dettagliato sul comportamento di Omni Describer.

### Scheda Impostazioni AI

- Frame Rate per Analisi AI: Determina quanti fotogrammi al secondo vengono inviati all’AI. Un valore più basso (es. 5 FPS) può ridurre i costi API, ma potrebbe perdere azioni molto veloci.
- Invia Solo Video (Senza Audio) all’AI: Utile per evitare che l’audio del video (dialoghi, musica, effetti) confonda l’AI. Invece di descrivere un’esplosione che sente, l’AI si concentrerà solo su ciò che avvista visivamente.
- Disabilita Filtri di Sicurezza (Usare con cautela): Questa opzione può permettere all’AI di processare contenuti e generare descrizioni che normalmente verrebbero filtrate come sensibili. Tuttavia, non è un bypass totale. L’output è comunque soggetto alle politiche di sicurezza di Google e non c’è garanzia che tutti i filtri vengano ignorati. Ricorda che sei tu il responsabile dell’uso di questa funzione.

### Scheda Output Audio

- Motore Text-to-Speech:
  - SAPI5 (Integrato in Windows): Utilizza voci compatibili SAPI5 fornite da Windows o installate dall’utente. Non richiede chiave API aggiuntiva. La qualità audio dipende dalle voci presenti nel sistema.
  - TTS OpenAI (Alta Qualità): Generalmente offre voci più naturali e fluenti. Usare questa opzione richiede una chiave API OpenAI e un metodo di pagamento collegato all’account.

## Suggerimenti e Trucchi per Risultati Migliori

Creare ottime descrizioni audio è un’arte. Pur essendo l’AI un assistente efficace, otterrai i migliori risultati quando la guiderai correttamente.

### Il Potere dei Prompt: Le Tue Note di Regia

L’applicazione insegna all’AI un insieme di regole base (come non parlare durante i dialoghi). Pensa all’area “Prompt Predefiniti” nella schermata principale come al punto dove fornisci le tue note di regia per quel video specifico. Una buona nota aiuta l’AI a concentrarsi su uno stile o dettaglio particolare, mentre una vaga può portare a risultati inaspettati.

#### Quando (e Come) Usare un Prompt

Spesso, l’AI genera ottimi risultati senza prompt speciali, affidandosi solo alle regole base. Ti consiglio di usare questa funzione solo quando hai uno scopo preciso in mente.

Consiglio #1: Prompt “Concentrati sui Nomi”
In un video con molti personaggi in cui i nomi sono importanti, l’AI può esitare a usarli. Per dare priorità all’uso dei nomi, puoi creare un prompt personalizzato: `Per questo video, la tua massima priorità è identificare e usare correttamente i nomi dei personaggi non appena li senti nei dialoghi. Questo è più importante del essere conciso. Mentre ti concentri su questo, cerca di rispettare tutte le altre regole di sistema il più possibile.`
Consiglio #2: Prompt “Descrivi l’Atmosfera”
In film visivamente ricchi dove l’atmosfera è fondamentale, puoi guidare l’AI a concentrarsi sull’ambiente: `Concentrati nel descrivere l’ambientazione, l’atmosfera e i dettagli ambientali. Per creare un ricco mondo visivo, menziona l’illuminazione, i colori e l’umore generale della scena. Concentrati meno sui movimenti minori dei personaggi, a meno che non siano cruciali.`

#### Cosa Evitare nei Prompt

Per ottenere i risultati migliori, è importante evitare istruzioni che contraddicono i principi base dell’AI. Poiché l’AI cerca sempre di seguire le istruzioni, darne di sbagliate può fargli interpretare male il video.

- Esempio di Prompt Sbagliato: `“Raccontami tutto ciò che accade.”` Questo può spingerlo a concentrarsi su dettagli inutili come “(personaggio sta parlando)” invece che su azioni significative.
- Esempio di Prompt Sbagliato: `“Dimmi cosa dicono i personaggi.”` Questo può fargli violare la regola “descrivi solo il visivo” e riportare dialoghi come “il personaggio ha detto di prendere questo”.

In breve: usa i prompt non per cambiare le regole fondamentali di una buona descrizione audio, ma per guidare l’AI verso un focus specifico.

## Domande Frequenti (FAQ)

D: Le mie chiavi API sono sicure?
R: Sì. Le tue chiavi vengono memorizzate solo sul tuo computer e non vengono condivise con nessuno, eccetto che per connettersi ai servizi Google/OpenAI.

D: Perché generare descrizioni richiede così tanto tempo?
R: Il tempo dipende dalla durata del video, dalla velocità di connessione (per caricare il video), dal frame rate selezionato e dal carico attuale dei servizi AI. Raccomando vivamente di usare la funzione “Abilita Spezzettamento Video” per video lunghi.

D: Perché l’AI non ha descritto qualcosa che ho visto sullo schermo?
R: L’AI è addestrata a preferire il silenzio piuttosto che sbagliare o parlare durante i dialoghi. Puoi usare la funzione “Chiedi di Più...” per indagare momenti specifici o selezionare il livello di verbosità “Dettagliato” nelle Impostazioni.

## Scorciatoie da Tastiera

- Ctrl + O: Apri Video Locale
- Ctrl + U: Apri da URL Diretto
- Ctrl + Y: Apri da YouTube
- Ctrl + ,: Apri Impostazioni
- F1: Visualizza Guida

## Ringraziamenti, Contatti e Collaboratori

Grazie di cuore per usare Omni Describer! Questa applicazione è il riflesso del mio desiderio di rendere i media visivi più accessibili e godibili per tutti. Avere utenti come te che la usano e forniscono feedback è la più grande motivazione per continuare a svilupparla.

### Feedback e Supporto

Hai domande, vuoi segnalare un bug o suggerire una nuova funzione? Mi piacerebbe sentire la tua opinione! Il modo migliore per contattarmi è via email. Il tuo feedback è fondamentale per migliorare sempre Omni Describer.

- Email: info [at] audioses [dot] com. (Sostituisci “[at]” con “@” e “[dot]” con “.” quando invii.)
- Sito Web: audioses.com