Docs / Installazione e risoluzione dei problemi
Installazione, aggiornamento e spazio su disco
Il mio Mac ce la farà? Memoria, chip, disco e tempi di render per ogni Mac con Apple Silicon, in una sola pagina.
Phosphene funziona sui Mac con Apple Silicon (M1 o successivi) tramite Pinokio. Questa pagina spiega come installarlo e aggiornarlo, quanto spazio su disco serve e cosa fare se un passaggio non riesce.
Installare con Pinokio
- Installa Pinokio.
- In Pinokio apri Discover, scegli Download from URL e incolla
https://github.com/mrbizarro/phosphene. - Clicca Install. L’installer controlla prima lo spazio libero sul disco. Se non basta, si ferma e mostra quanto ne serve e quanto ne hai.
- Quando l’installazione finisce, clicca Start, poi Open Panel. Il pannello si apre su
http://127.0.0.1:8198.
L’app si apre quando il suo runtime Python e i pacchetti del motore sono pronti, di solito in pochi minuti. Nessun modello viene scaricato prima di Start né automaticamente alla prima apertura. Scegli che cosa vuoi creare, poi scarica il suo modello.
Nota Pinokio non può installare Phosphene su un Mac Intel né su Windows. Il supporto per Linux su Apple Silicon è un progetto separato della community che Pinokio non installa. Vedi Linux (community).
Cosa viene scaricato e quanto spazio serve
| Parte | Download | Quando |
|---|---|---|
| Runtime dell’app: Python e pacchetti del motore | Circa 0,5 GB; le versioni dei pacchetti possono cambiarlo | Prima di Start. Prevedi 18 GB liberi, inclusi 15 GB da lasciare sempre liberi |
| Modelli video LTX-2.5 Q4, compreso l’encoder dei prompt | Circa 27,5 GB | Clicca Scarica i modelli video nell’app. Consigliato per il tuo primo video |
| Extra delle funzioni: Gemma 3 per Migliora e per il pianificatore di Storyboard, più gli adattatori per Aumenta risoluzione e Correzione volto, Controllo del movimento, Ingredienti e Colora | 10,7 GB se scegli tutto | Scarica solo quelli che usi, dalla funzione o da Modelli |
| Modelli di immagini | Indicato accanto al modello selezionato | Alla prima generazione. FLUX.2 [klein] 4B è un punto di partenza compatto, circa 4,3 GB |
| Pesi LTX-2.5 Q8, per personaggi e voci addestrati | 30,02 GB | Facoltativo, da Impostazioni → Modelli o dalla barra laterale di Pinokio |
| Componente Alta, per la qualità Alta, i Keyframe e Estendi su LTX | 29,50 GB | Facoltativo, dalla finestra Modelli (clicca il chip di stato, poi Modelli) |
| Hailuo H3, il secondo motore video | circa 75 GB | Facoltativo, dalla barra laterale di Pinokio. Vedi Hailuo H3 |
| Motore musicale (YuE2) | circa 11 GB | Facoltativo, dalla scheda Audio o dalla barra laterale di Pinokio. Vedi Music Studio |
| LTX-2.3, serve solo per addestrare un personaggio | circa 20 GB, più circa 21 GB per il trainer | Proposto quando apri Addestra personaggio |
Con una connessione da 100 Mbps, i modelli video richiedono circa 37 minuti di download. Con 300 Mbps circa 12 minuti; con 1 Gbps circa 4 minuti. L’app può restare aperta mentre i modelli si scaricano. La scheda del modello mostra i byte ricevuti, il file in corso ed eventuali pacchetti rimanenti. Interrompi il download ferma l’intero download dei modelli video; clicca di nuovo Scarica i modelli video per riprendere. I file scaricati restano sul disco. I download da Modelli lasciano liberi 15 GB e aspettano se lo spazio sta finendo.
Se una funzione ha bisogno di un extra il cui download non è finito, mostra un messaggio di download oppure propone Scarica ora. Non fallisce mai senza dire nulla.
Suggerimento Puoi aggiungere un token di accesso Hugging Face in Impostazioni per download circa dieci volte più veloci. HDR è l’unico componente aggiuntivo che richiede questo token. Tutto il resto funziona senza.
Tenere i modelli su un disco esterno
I modelli occupano la maggior parte dello spazio. Nell’app per Mac (5.0.20 o successiva) puoi tenerli su un disco esterno e liberare il tuo Mac.
- Scegli dove stanno i modelli durante la configurazione: la riga Models go on … ha un pulsante Cambia, poi Un altro disco o cartella…. Puoi anche scegliere più tardi in Impostazioni > Modelli.
- Spostarli più tardi. In Impostazioni > Modelli, Sposta su un altro disco… copia i modelli sul disco e controlla ogni file. Solo allora elimina la copia sul tuo Mac. Riporta su questo Mac li copia di nuovo indietro e mantiene la copia sul disco; eliminala nel Finder se vuoi recuperare lo spazio. Lo spostamento mostra l’avanzamento e ha un pulsante Stop, e uno spostamento interrotto riprende quando lo riavvii. Lo Studio si chiude mentre i modelli si spostano e si riapre quando sono a posto.
- Si spostano solo i modelli. L’app e il suo motore restano sul tuo Mac, quindi Phosphene si apre sempre.
- Se il disco è scollegato, l’app mostra “(il nome del disco) non è collegato”. Ricollegalo e scegli Ricontrolla, scegli Scarica invece per scaricare su questo Mac i modelli della bozza (circa 27,5 GB), oppure scegli Apri senza di essi.
- Formato del disco. I dischi APFS ed exFAT funzionano. FAT32 non può contenere file oltre i 4 GB, e alcuni file dei modelli sono più grandi, quindi Phosphene rifiuta un disco FAT32. Se alcuni dei tuoi modelli sono condivisi con un’installazione Pinokio, usa un disco APFS o Mac OS Extended.
Tieni il disco collegato ogni volta che Phosphene è in funzione.
Controllare la memoria del tuo Mac
La memoria del tuo Mac determina quali impostazioni di qualità e quali motori puoi usare. Phosphene la controlla automaticamente. Per vedere che cosa può fare il tuo Mac, clicca il chip di stato nell’intestazione, poi Livello.
| Funzione | Memoria richiesta |
|---|---|
| Video LTX e Immagini | Qualsiasi Mac con Apple Silicon. Sotto i 48 GB hai dimensioni video più piccole. La qualità Alta di LTX, Fotogramma iniziale e finale ed Estendi sono nascosti. I Mac con 24 GB o meno usano automaticamente un percorso video a basso consumo di memoria: su un Mac da 16 GB una clip arriva a circa 5,7 GB di memoria al picco, circa 6,7 GB con i LoRA. |
| Music Studio | 16 GB o più. Consigliati 24 GB o più per canzoni lunghe con altre app aperte |
| Addestrare un personaggio | 24 GB o più |
| Hailuo H3 | 16 GB o più (Bozza e Standard da 16 GB, Alta da 18 GB). Con 60 GB o più puoi scegliere anche il motore completo |
| LTX Alta · 720p | Un Mac da 64 GB; l’uso della memoria arriva al picco vicino a 50 GB |
Prima di un render lungo, chiudi le app che usano molta memoria, come i browser con molte schede, Slack o il Simulatore iOS. Il render è il processo che crea il tuo video o il tuo audio. Se il Mac esaurisce la memoria, interrompe il render. Vedi Risoluzione dei problemi.
La barra laterale di Pinokio
Seleziona Phosphene in Pinokio per vedere queste azioni nella barra laterale a sinistra. Le azioni disponibili dipendono da ciò che è installato e dal fatto che il pannello sia in esecuzione.
- Install / Resume Install: installano i file necessari. Resume Install compare se l’ultimo tentativo non è finito. I file già scaricati vengono conservati.
- Start, Open Panel, Terminal: clicca Start per avviare Phosphene, poi Open Panel per usarlo. Terminal mostra il suo registro delle attività.
- Update: vedi Aggiornare.
- Outputs, Models, Uploads: aprono quelle cartelle nel Finder.
- Install Hailuo H3 (second video engine, ~75 GB): dopo l’installazione diventa Repair Hailuo H3 oppure Update Hailuo H3 runner. Entrambi conservano i file del modello scaricati.
- Build Hailuo H3 compact engine: compare su un Mac da 16-59 GB quando i file del modello sono scaricati ma il motore compatto non è pronto. Richiede circa 5 minuti e non scarica nulla.
- Install the music engine (YuE2, ~11 GB): dopo l’installazione diventa Repair the music engine, che conserva i file del modello scaricati.
- Reset engine (keeps models & outputs): ricostruisce il motore LTX e il software di cui ha bisogno. Conserva i tuoi modelli e il lavoro finito. Non riguarda Hailuo H3; per riparare H3 usa Repair Hailuo H3.
Aggiornare Phosphene
- La pillola della versione nell’intestazione mostra Aggiornato, oppure Aggiorna a seguito da una versione più recente. Quando è disponibile un aggiornamento, clicca Aggiorna ora nel banner per installarlo, oppure Più tardi per aspettare.
- Clicca Update nella barra laterale di Pinokio per aggiornare tutto, compreso il software di supporto. La tua coda, le impostazioni, i modelli e il lavoro finito vengono conservati.
- Dopo un aggiornamento dall’interno dell’app, il banner dice “Aggiornato a … riavvia per finire”. In Pinokio clicca Stop, poi Start.
- Se aggiorni da una versione molto vecchia e sembra cambiare solo il pannello, clicca Update ancora una volta. Il primo aggiornamento sostituisce l’updater stesso.
- Se l’Update di Pinokio si ferma nel primo secondo (le versioni 4.19.6 e precedenti possono farlo), clicca invece Aggiorna ora nel banner di Phosphene o nella pillola della versione, poi riavvia. Vedi L’aggiornamento si ferma subito.
- Se il pannello si comporta ancora come la versione vecchia, ha bisogno di un riavvio. La pillola della versione dice allora Restart Phosphene. Cliccala, oppure clicca Stop e poi Start in Pinokio.
- Hailuo H3 e il motore musicale hanno un software di supporto separato. Se il pannello dice che uno dei due ha bisogno di un aggiornamento, clicca la voce Update o Repair di quel motore nella barra laterale di Pinokio. I file del modello scaricati vengono conservati.
Aggiornare a mano (se un aggiornamento non arriva)
Phosphene cerca da solo gli aggiornamenti, ma una connessione lenta o bloccata può impedirne l’arrivo. Puoi sempre installare tu stesso la versione più recente. I tuoi modelli, il lavoro finito, le impostazioni e la licenza Pro vengono conservati.
App per Mac
- Chiudi Phosphene (Phosphene → Esci, oppure Cmd+Q).
- Scarica l’installer più recente da phosphene.video/download (lo stesso file è allegato anche a ogni release su GitHub).
- Apri il
.dmgscaricato e trascina Phosphene su Applicazioni. Quando il Mac lo chiede, scegli Sostituisci. - Apri Phosphene da Applicazioni. La pillola della versione nell’intestazione mostra la nuova versione.
Tieni una sola copia, quella in Applicazioni. Le copie più vecchie rimaste in Download o su un disco di installazione possono aprirsi al posto della nuova: spostale nel Cestino ed espelli ogni disco Phosphene dalla barra laterale del Finder. Il tuo lavoro sta in ~/Library/Application Support/Phosphene, non dentro l’app, quindi sostituire o eliminare l’app non ne rimuove nulla.
Pinokio
- Clicca Stop nella barra laterale Pinokio di Phosphene.
- Apri l’app Terminale, vai nella cartella di Phosphene (
cd ~/pinokio/api/<your Phosphene folder>) ed eseguigit pull. - Clicca Update nella barra laterale, poi Start.
Se git pull dice che hai modifiche locali, esegui prima git stash, poi di nuovo git pull.
Se un’installazione o un aggiornamento si ferma con un errore
Se un passaggio necessario fallisce, Pinokio si ferma e mostra una riga che comincia con FATAL error:. Scorri verso l’alto nel registro che Pinokio mostra per quell’installazione o aggiornamento per trovarla. La riga spiega il problema e cosa cliccare dopo. Quasi sempre nulla è stato eliminato. Dopo aver risolto il problema, clicca di nuovo Install o Update per continuare.
Usa la tabella qui sotto per abbinare il testo dopo FATAL error::
| La riga dice | Cosa fare |
|---|---|
| not enough disk space to install Phosphene | Libera lo spazio indicato, poi clicca di nuovo Install |
| could not download the video engine version Phosphene needs … (a VPN, proxy or blocked GitHub is the usual cause) | Controlla la connessione, disattiva la VPN o il proxy, poi clicca di nuovo Install o Update |
| the engine environment did not install after 3 attempts | Controlla la connessione a internet e lo spazio libero su disco, poi clicca di nuovo Install o Update. Se si ripete, segnala la riga seguendo le istruzioni qui sotto |
| the video engine is on the wrong version | Clicca di nuovo Install o Update. Se si ripete, segnala la riga |
| Hailuo H3 needs a Mac with at least 16 GB of memory | Il tuo Mac non può eseguire H3. Continua a usare LTX, che ha tutte le modalità tranne Aggiungi audio |
| Hailuo H3 needs about N GB of free disk space | Servono circa 97 GB per una nuova installazione (i 75 GB da scaricare più i 22 GB del motore compatto), oppure circa 25 GB se i file del modello sono già scaricati. Libera lo spazio, poi clicca di nuovo Install Hailuo H3 |
| the compact Hailuo H3 engine could not be built | Di solito significa che il disco è pieno (la creazione richiede circa 22 GB). Libera spazio, poi clicca di nuovo la voce H3 nella barra laterale di Pinokio. Lo ricostruisce dai file del modello scaricati |
| a Phosphene render has been running for over 60 minutes, so the compact Hailuo H3 engine was not built | Aspetta che Phosphene finisca il render in corso, poi clicca di nuovo la voce H3 nella barra laterale di Pinokio |
| the H3 venv has no working Python | Clicca Repair Hailuo H3 nella barra laterale di Pinokio. I file del modello scaricati vengono conservati |
| YuE2 (the music engine) needs a Mac with at least 16 GB of memory | Questo Mac non può eseguire il motore musicale. Il resto di Phosphene non è toccato |
| YuE2 (the music engine) needs at least 14 GB free | Libera lo spazio, poi clicca di nuovo Install the music engine |
| could not download the YuE2 music engine | Controlla la connessione a internet e se una VPN o un proxy blocca GitHub, poi clicca di nuovo Install the music engine |
| untracked/ignored paths obstruct Update. Move them; nothing deleted. | I file che hai aggiunto dentro la cartella dell’app ostacolano l’aggiornamento. Le righe subito sopra li elencano. Spostali fuori dalla cartella di Phosphene, poi clicca di nuovo Update |
| fetch failed (offline?) - nothing changed, re-run Update | Riconnettiti, poi clicca di nuovo Update |
| the Update safety check did not pass - not updating | Nulla è stato modificato. Clicca di nuovo Update. Se si ripete, segnala la riga |
Se il tuo errore non è nell’elenco, segui le istruzioni nella sua riga FATAL error:. Per segnalare un errore, copia quella riga e le poche righe sopra in una segnalazione di bug. Vedi Segnalare un problema.
Ricominciare senza perdere il tuo lavoro
- Clicca Reset engine in Pinokio per ricostruire il motore LTX. I tuoi modelli, il lavoro finito e le impostazioni vengono conservati.
- Per trovare il tuo lavoro finito, clicca Outputs nella barra laterale di Pinokio. Si apre
mlx_outputsdentro la cartella di Phosphene. - Per trovare i modelli scaricati, clicca Models nella barra laterale. Si apre
mlx_models. Non eliminare questa cartella a meno che tu non voglia scaricare di nuovo tutto.
Se Phosphene si apre ma un’attività fallisce, mancano dei modelli o la tua coda si ferma, vedi Risoluzione dei problemi.
Fonte: webapp/docs/install.md nel repository pubblico. Rivisto per questo sito prima della pubblicazione. Tradotto dall'originale inglese. Suggerisci una modifica.