Voxis PRO - AI Text to Speech, Audio Reader & Summarizer

Documentazione Ufficiale - Versione 1.1.0 (PRO)

1. Introduzione

Benvenuto su Voxis PRO - AI Text to Speech, Audio Reader & Summarizer. Questo plugin aggiunge un player audio elegante e accessibile al 100% al tuo sito WordPress, convertendo i tuoi contenuti testuali in audio parlato (Text-to-Speech) utilizzando le tecnologie native Web Speech API dei browser.

Il nostro obiettivo è aumentare l'accessibilità e offrire ai tuoi utenti un modo alternativo per fruire dei tuoi contenuti. Questa guida spiega come configurare il plugin al massimo del suo potenziale.

2. Impostazioni Generali

Area di Visualizzazione e Posizionamento

Puoi scegliere dove aggiungere automaticamente il player:

Articoli: Il player apparirà negli articoli del blog.
Pagine: Il player apparirà nelle pagine standard.
Entrambi: Il player sarà abilitato globalmente.
Nessuno: La visualizzazione automatica è disabilitata. Puoi quindi usare lo shortcode [voxis_summarizer_player] per inserire manualmente il player ovunque nel tuo sito, inclusi i Page Builder.

Inoltre, se utilizzi il posizionamento automatico (Articoli, Pagine o Entrambi), puoi scegliere di visualizzare il player Sopra o Sotto il contenuto.

Esclusione tramite ID

Se desideri che il player sia attivo su tutti gli articoli, ma escluso in alcune pagine specifiche (come "Contattaci" o "Termini di servizio"), puoi definire un elenco separato da virgole di ID di articoli o pagine. Il player non verrà mai caricato su questi ID.

Anteponi Titolo all'Audio

Di default, Voxis antepone il Titolo dell'Articolo o della Pagina alla lettura audio e ai prompt di generazione AI. Tuttavia, se il tuo Selettore CSS del Contenuto cattura esplicitamente anche il titolo, il player potrebbe leggerlo due volte. Puoi deselezionare questa casella per disabilitare l'anteposizione automatica del titolo.

Selettore CSS del Contenuto

Configurazione Cruciale: Assicurati che il plugin legga solo il contenuto dell'articolo (e non menu, barre laterali o piè di pagina) specificando il corretto selettore CSS che racchiude il tuo testo.

Di default, è impostato su .entry-content, .post-content, article, che funziona con il 90% dei temi WordPress classici. Se utilizzi un Page Builder, potresti doverlo adattare:

Elementor: Prova .elementor-widget-theme-post-content.
Divi: Prova .et_pb_post_content.
Puoi ispezionare il tuo sito (Tasto destro -> Ispeziona elemento) per trovare la classe contenitore principale dei tuoi articoli e inserirla qui (es. .my-article-content).

Selettori CSS da Escludere

Se il tuo tema o altri plugin (come Reading Time o i pulsanti di condivisione social) inseriscono contenuti direttamente nel corpo dell'articolo, Voxis potrebbe provare a leggerli ad alta voce.

Per evitarlo, usa il campo Selettori CSS da Escludere per fornire un elenco separato da virgole di classi o ID CSS che desideri ignorare.

Esempio: .read-time, .share-buttons, #related-posts
Page Builder (Enfold/Avada): Voxis PRO pre-filtra automaticamente gli shortcode annidati prima di generare l'audio AI. Puoi specificare con successo classi di shortcode composti (es. .flex_column.voxis-exclude) e il generatore audio escluderà perfettamente quegli interi layout.

Quando il player legge l'articolo, salterà completamente il testo situato all'interno di questi elementi HTML.

3. Configurazione Voce, Velocità e Volume

Personalizza il comportamento predefinito dell'audio text-to-speech che i visitatori ascolteranno.

Velocità Voce Predefinita: La velocità di riproduzione base. Le velocità disponibili vanno da 0.50x fino a 2.00x. Consigliamo 1.0x per una narrazione chiara o 1.25x per un'esperienza d'ascolto più rapida.
Volume Predefinito: Il volume iniziale di riproduzione. Può essere impostato dal 10% al 100%. Consigliamo di iniziare all'80% o al 100% in modo che gli utenti possano sentire chiaramente il narratore senza dover cercare immediatamente i controlli del volume.
Preferenza Voce Predefinita: Seleziona una voce preferita tra quelle installate sul tuo sistema corrente. Nota: Poiché le voci Text-To-Speech sono fornite dal browser dell'utente (iOS, Android, Chrome, Safari, Edge), se la voce scelta manca sul dispositivo dell'utente finale, Voxis passerà automaticamente alla migliore voce di sistema locale che corrisponde alla lingua del tuo sito.

Clicca sul pulsante Test per ascoltare una breve anteprima audio della voce e del volume selezionati per valutarne il tono.

4. Controlli del Player per l'Utente

Nella sezione "Opzioni Player Frontend", puoi decidere quanta libertà di personalizzazione delegare al visitatore del sito.

Mostra traccia audio: Visualizza la barra di avanzamento in tempo reale.
Mostra durata stimata: Mostra una durata stimata, es. -4:30. Questo aiuta gli utenti a capire il tempo di ascolto del contenuto.
L'utente può modificare la velocità della voce: Aggiunge un menu a discesa al player consentendo al visitatore di accelerare o rallentare la voce (da 0.50x a 2.00x). Questa preferenza viene salvata nel browser per le visite future.
Mostra barra del volume: Integra un cursore interattivo che consente all'utente di abbassare o alzare il volume al proprio livello di comfort. Sotto questa opzione, puoi configurare il Volume di partenza predefinito.
Notifica barra volume: Se abilitata, gli utenti vedranno una notifica utile che spiega che le regolazioni del volume vocale nativo avranno effetto all'inizio della frase successiva.
L'utente può selezionare la voce del dispositivo: Dispositivi diversi hanno pacchetti vocali diversi. Abilitando questa opzione, un utente (es. su iPhone) può cambiare manualmente le voci direttamente dal player.
Condividi frammento audio: Aggiunge un pulsante di condivisione che permette agli utenti di generare un URL speciale che punta direttamente al punto esatto dell'audio che stanno ascoltando (tramite il parametro ?voxis_t=XX), riproducendo istantaneamente quando cliccato. Nota: questo pulsante è disabilitato durante la riproduzione del Riassunto AI.

5. Aspetto e CSS Personalizzato

Il player è progettato per mettere in risalto i tuoi contenuti mantenendo un estremo minimalismo. Scegli una delle 10 Palette Colori Predefinite per allineare il player audio al branding del tuo sito.

Editor CSS Personalizzato

Per sviluppatori o personalizzazioni visive avanzate, il box CSS Personalizzato supporta fogli di stile personalizzati.

Novità: L'editor CSS ora include la numerazione delle righe e la validazione sintattica integrata. Se dimentichi uno spazio, una parentesi graffa o un due punti, sarai avvisato direttamente con il numero di riga per evitare stili interrotti!

Struttura base delle classi che puoi sovrascrivere:

/* Contenitore Generale Player */
.voxis-player-wrapper {
    /* Es., rendi i bordi più arrotondati */
    border-radius: 20px; 
    box-shadow: 0 4px 10px rgba(0,0,0,0.1);
}

/* Pulsanti Play / Pausa */
.voxis-player-wrapper .voxis-btn {
    font-weight: 700;
    text-transform: uppercase;
}

/* Pulsante Condividi Frammento */
#voxis-share-btn {
    /* Personalizza il pulsante circolare di condivisione */
    border-radius: 50%;
}

/* Tooltip / Box Condivisione */
#voxis-share-tooltip {
    /* Modifica l'aspetto o la larghezza del tooltip */
    background: var(--voxis-btn-bg);
}
#voxis-share-link {
    /* Stile del box di input contenente l'URL copiabile */
    background: #fff;
}

/* Tooltip Tempo di Avanzamento */
#voxis-time-tooltip {
    background: var(--voxis-btn-bg);
    color: var(--voxis-btn-text);
}

/* Traccia di Avanzamento (Sfondo e Riempimento) */
.voxis-track-container {
    background-color: var(--voxis-bg); 
}
.voxis-track-progress {
    background-color: var(--voxis-status-color); 
}

/* Contenitore Controllo Volume & Slider */
.voxis-volume-container {
    background-color: var(--voxis-bg);
}
.voxis-volume-progress {
    background-color: var(--voxis-status-color);
}
.voxis-volume-label {
    font-size: 11px;
    color: var(--voxis-icon-color);
}

/* Pulsanti Salto Audio (-10s / +10s) */
.voxis-jump {
    padding: 0 8px; /* Regola lo spazio intorno ai pulsanti di salto */
}
.voxis-jump .voxis-icon {
    font-size: 12px; /* Dimensione icona di salto */
}

/* Pulsante Download Voce Neurale */
.voxis-download {
    border-radius: 50%; /* Forma circolare */
    background-color: var(--voxis-border);
}

/* Pulsanti Evidenziazione Testo & Tracciamento */
.voxis-highlight, .voxis-tracking {
    /* Personalizza i pulsanti delle opzioni di sincronizzazione */
    border-radius: 50%;
}

/* Contenitore Player Flottante */
.voxis-is-floating {
    bottom: 20px !important; /* Spaziatura dal fondo dello schermo */
    box-shadow: 0 10px 30px rgba(0,0,0,0.15);
}

6. Risoluzione dei Problemi

Il player non appare? Verifica che l'impostazione "Abilita su" copra il tuo tipo di contenuto (Articolo/Pagina) e assicurati che il "Selettore CSS del Contenuto" corrisponda perfettamente alla struttura HTML del tuo sito.
Legge le sezioni sbagliate (come commenti o pulsanti social)? Specifica una classe più rigorosa nel "Selettore CSS del Contenuto". Invece di selezionare il tag generico article, scegli esplicitamente il div che racchiude solo i tuoi paragrafi (es. .entry-content o .post-content-inner).
La voce di Test è muta: Assicurati che il volume del tuo sistema non sia disattivato o che l'audio di sottofondo non sia disabilitato nelle autorizzazioni del browser, quindi clicca nuovamente su "Test".

7. Funzionalità Premium (PRO)

Benvenuto su Voxis PRO - AI Text to Speech, Audio Reader & Summarizer. Questa sezione delinea come configurare gli strumenti avanzati che hai appena sbloccato.

1. Riassunti Audio AI

Voxis PRO può condensare articoli lunghi in rapidi briefing audio "TL;DR" di 1-3 minuti.

Chiavi API: Devi fornire una chiave API per il motore scelto per abilitare questa funzione. Ottieni la tua chiave: OpenAI, Anthropic o Google Gemini.
Motore di Riassunto: Vai su Impostazioni -> Voxis Audio. Seleziona il tuo motore preferito (GPT per riassunti rapidi ed economici, Claude per un fraseggio naturale, o Google Gemini per un'elaborazione del testo versatile). L'AI genererà automaticamente sia un riassunto testuale che un file audio MP3 dedicato utilizzando il tuo provider di Voci Neurali configurato.
Versioni Modello Personalizzate: Puoi specificare esplicitamente l'esatta versione del modello da utilizzare per l'inferenza (es. gpt-5.4-mini, claude-haiku-4-5-20251001 o gemini-3.5-flash). Questo ti consente di aggiornare i tuoi modelli senza attendere aggiornamenti del plugin se i default diventano obsoleti.
Lunghezza Riassunto: Scegli tra "Breve" (circa 1-2 min) o "Medio" (circa 3-5 min).

2. Voci Neurali Iper-Realistiche

Collegando la tua chiave API, Voxis bypassa le voci di sistema locali del visitatore, fornendo una narrazione di qualità da studio ultra-realistica che suona perfettamente identica indipendentemente dal browser o dal dispositivo dell'utente.

Chiavi API: Devi fornire una chiave API per il provider scelto per abilitare questa funzione. Ottieni la tua chiave: OpenAI, ElevenLabs o Google Cloud.
Provider Vocale: Scegli tra OpenAI TTS, ElevenLabs Premium o Google Cloud TTS.
Selezione Voce: Puoi selezionare esplicitamente il modello vocale che desideri utilizzare (es. Alloy, Echo, Fable per OpenAI, o inserire ID Vocali personalizzati per ElevenLabs).
Chiave API: Inserisci la chiave API segreta fornita dalla piattaforma scelta. Facendo ciò, attivi completamente la funzionalità Audio Cloud. Importante: Ogni provider richiede la sua specifica chiave API. Google Cloud TTS richiede una chiave API GCP standard (non una chiave Gemini). OpenAI richiede una chiave API con fatturazione abilitata. ElevenLabs richiede una chiave di abbonamento attiva.

Interazioni tra Funzionalità (Considerazioni Importanti):

Diverse funzionalità PRO interagiscono tra loro. Ecco cosa devi sapere:

Sincronizzazione Evidenziazione Testo: Se abiliti questa opzione, il testo verrà evidenziato visivamente parola per parola mentre viene letto ad alta voce. Tuttavia, se abiliti un Riassunto AI, l'Evidenziazione del Testo viene automaticamente disabilitata. Perché? Perché il testo del riassunto generato è completamente diverso dal testo dell'articolo originale, quindi non può essere sincronizzato parola per parola con i paragrafi visivi.

Ottimizzazione Sincronizzazione: Ogni voce neurale, lingua e stile di punteggiatura ha la sua cadenza e il suo ritmo naturale. Poiché Voxis calcola matematicamente l'avanzamento dell'evidenziazione (senza il sovraccarico di pesanti nodi di elaborazione AI sul frontend), potresti talvolta riscontrare ritardi o evidenziazioni anticipate a seconda del provider utilizzato. Nelle impostazioni Pro, puoi usare le variabili di Ottimizzazione Sincronizzazione per regolare il calcolo matematico:
- Spostamento Globale (secondi): Sposta l'intero tracciamento dell'evidenziazione in avanti o indietro matematicamente di un tempo specifico (es. +0.5s o -1.2s), risolvendo la desincronizzazione lineare.
- Base WPM (Parole Al Minuto): Modifica la stima delle parole al minuto utilizzata se la durata esatta dell'audio non è disponibile o necessita di una correzione di velocità di fallback. Il valore predefinito è 130 WPM.
Comportamento Controllo Volume: Lo slider del volume frontend dell'utente risponde istantaneamente agli MP3 delle Voci Neurali poiché vengono caricati come fonti audio standard. Tuttavia, se il sito ricade sul TTS del browser nativo, lo slider del volume applicherà le modifiche in modo fluido all'inizio del blocco di frase successivo a causa delle limitazioni della Web Speech API del browser.
Pulsante Download MP3: Il pulsante di download è disponibile solo se stai utilizzando una Voce Neurale (Voce Cloud) con una chiave API. Le voci native locali del browser (funzionalità gratuita) non generano file audio fisici, il che significa che non c'è nessun MP3 da scaricare.
Player Flottante Trascinabile: Se abilitato, il player si trasforma in una miniatura flottante quando l'utente scorre l'articolo. Può essere trascinato ovunque sullo schermo, consentendo agli utenti di spostarlo per mettere in pausa o saltare. Puoi anche configurare l'opacità dello sfondo del player flottante.
Controlli Salto Audio: Puoi abilitare i pulsanti di riavvolgimento e avanzamento +/- sul player. Puoi configurare esattamente di quanti secondi saltare (es. 10s). Nota: Questa funzione è attiva solo quando si utilizzano Voci Neurali Cloud o Riassunti AI (poiché richiede una timeline MP3 fisica piuttosto che lo streaming TTS del browser nativo).
Registrazione Console Debug: Se riscontri problemi di generazione o audio mancante, c'è un toggle isDebugConsoleMessageShow integrato nel codice. Quando impostato su true, Voxis PRO registrerà in modo sicuro le risposte grezze da OpenAI, Gemini, Claude ed ElevenLabs direttamente nei tuoi log di errore locali, aiutandoti a individuare istantaneamente chiavi API disabilitate o crediti esauriti.

3. Aggiornamenti Contenuto Articolo & Rigenerazione Metabox

Quando modifichi un articolo, le funzionalità PRO non rigenereranno automaticamente l'audio per default, per farti risparmiare sui costi API. Tuttavia, noterai un nuovo metabox Generatore Audio Voxis sul lato destro della schermata dell'Editor Articoli di WordPress.

Lì troverai le caselle di controllo per richiedere esplicitamente la rigenerazione dell'audio e/o del riassunto al momento del salvataggio.
Se aggiorni pesantemente il tuo articolo e desideri che l'audio rifletta il nuovo testo, clicca semplicemente su "Abilita per Rigenerare" (che attiva la casella) e clicca su "Aggiorna" sul tuo articolo.
Eliminazione Riassunti: Se desideri eliminare un riassunto generato per pulire lo stato dell'articolo o riscriverlo interamente, puoi semplicemente svuotare la casella di testo contenente il riassunto e cliccare su Aggiorna. Questo elimina sia il testo che il file audio MP3 del riassunto dedicato. Nota: se utilizzi l'editor a blocchi Gutenberg, potresti dover aggiornare la pagina dopo il salvataggio per vedere l'interfaccia utente del metabox aggiornata.
Modifica Riassunto Inline: Il testo del tuo Riassunto AI generato è esposto in una casella di testo direttamente nel metabox. Puoi modificare liberamente questo testo, correggere refusi e cliccare su Aggiorna. Per generare una nuova traccia audio MP3 dal tuo testo modificato, seleziona semplicemente la casella "Abilita per Rigenerare" per il Riassunto AI prima di salvare.
Azioni Rapide su Riga: È anche possibile generare o eliminare l'MP3 e il Riassunto AI direttamente dalle azioni rapide dell'articolo (sotto il titolo dell'articolo nell'elenco Articoli) senza entrare nell'editor!

4. Generatore di Massa (Novità)

Voxis PRO include un potente utility per generare audio e riassunti AI in massa su tutto il tuo sito.

Elaborazione in Background: Puoi selezionare specificamente se elaborare Articoli o Pagine, e se generare "Solo MP3", "Solo Riassunto AI" o "Entrambi".
Salto Intelligente: Se selezioni "Entrambi" ma un articolo ha già l'MP3 generato, il Generatore di Massa salterà automaticamente il passaggio di generazione audio (facendoti risparmiare crediti API) e si concentrerà esclusivamente sulla generazione del Riassunto AI mancante. Non sovrascrive mai i contenuti esistenti a meno che non sia richiesto manualmente dal Metabox dell'articolo individuale.
Requisito Importante: Poiché la generazione sequenziale è gestita in tempo reale dal tuo browser (per comunicare in modo sicuro con il tuo server), devi mantenere la scheda del browser del Generatore di Massa completamente aperta finché la barra di avanzamento non raggiunge il 100%. Se chiudi la finestra o navighi altrove, la coda in background si interromperà.

5. Esempio di Stime Costi API (OpenAI)

Nota: La generazione audio tramite provider cloud consuma crediti dal tuo account API collegato (Pay-As-You-Go). Imposta sempre limiti di utilizzo rigorosi nella dashboard del tuo provider cloud per evitare shock in fattura.

Utilizzando gli ultimi modelli di OpenAI, i costi sono incredibilmente bassi:

Voci Neurali (TTS-1): Costano circa $15.00 per 1.000.000 di caratteri. Per un tipico articolo del blog di 5.000 caratteri, la generazione del file audio cloud costerà circa $0.075 (7.5 centesimi).
Riassunto AI (GPT-4o Mini): Costa circa $0.15 per 1.000.000 di token di input. Riassumere un articolo di 5.000 caratteri costerà praticamente $0.001 o meno.
Ricorda: Questi processi Cloud vengono eseguiti solo una volta per articolo (quando salvi o rigeneri l'articolo). Una volta generati l'MP3 e il testo del riassunto, vengono salvati e serviti a infiniti visitatori a costo API zero aggiuntivo.

6. 10 Palette Colori Extra

Hai accesso ad estetiche premium, come Neon Cyber, Royal Gold, Minimal Light e altre. Scorri verso il basso fino alla sezione Palette PRO nelle impostazioni e clicca sul tuo schema colori preferito. Il player frontend sarà aggiornato istantaneamente.

7. Attivazione Licenza

Per utilizzare Voxis PRO in un ambiente di produzione live, è necessaria una licenza Lemon Squeezy valida.

Vai alla pagina delle impostazioni di Voxis nella tua dashboard di amministrazione WordPress.
Sul lato destro della schermata, troverai la scheda Licenza Voxis PRO.
Inserisci la chiave di licenza che ti è stata fornita dopo l'acquisto e clicca su Valida Licenza.
Se la validazione ha successo, vedrai un messaggio verde "Pro Active" e le funzionalità PRO saranno sbloccate permanentemente e in grado di comunicare con i nostri server di generazione remota.

Gestione Licenza: Puoi recuperare, verificare o gestire i dettagli della tua licenza (incluso il scollegamento dei domini) direttamente dalla tua dashboard cliente Lemon Squeezy:
Dashboard Ordini Lemon Squeezy

Progettato e Sviluppato da Level Network.