---
## โ Perchรฉ YTSage?
YTSage รจ progettato per gli utenti che desiderano un **downloader YouTube semplice ma potente**. A differenza di altri strumenti, offre:
- Un'interfaccia PySide6 moderna e pulita
- Download di video, audio e sottotitoli con un solo clic
- Funzioni avanzate come SponsorBlock, fusione dei sottotitoli e selezione della playlist
- Modalitร Generica opzionale per siti diversi da YouTube supportati da yt-dlp
- Supporto multipiattaforma e installazione semplice
## โจ Caratteristiche
| Funzioni Base | Funzioni Avanzate | Funzioni Extra |
|-----------------------------------|-----------------------------------------|------------------------------------|
| ๐ฅ Tabella Formati | ๐ซ Integrazione SponsorBlock | ๐๏ธ Visualizzazione FPS/HDR |
| ๐ต Estrazione Audio | ๐ Selezione e Fusione Sottotitoli | ๐ Aggiornamento automatico yt-dlp |
| โจ Interfaccia Utente Semplice | ๐พ Salva Descrizione e Anteprima | ๐ ๏ธ Rilevamento FFmpeg/yt-dlp/Deno |
| ๐ Supporto e Selettore Playlist | ๐ Limitatore di Velocitร | โ๏ธ Comandi Personalizzati |
| ๐ Integrazione Capitoli | โ๏ธ Ritaglio Sezioni Video | ๐ช Login tramite Cookie |
| ๐ Cronologia Download | ๐ Scelta del Canale di Rilascio | ๐ Supporto Proxy |
| ๐๏ธ Conversione Formato Audio | ๐ฌ Impostazioni Formato Video | ๐ Tab Aggiornamento Integrato |
| ๐ Modalitร Generica | ๐ Normalizzazione Audio (EBU R128) | ๐ Localizzazione in 14 lingue |
| ๐พ Esportazione Playlist | โ๏ธ Qualitร e Sottotitoli Predefiniti | |
## ๐ Installazione
### โก Installazione Rapida (Consigliata)
Installa YTSage tramite PyPI:
```bash
pip install ytsage
```
๐ Aggiornare un'installazione esistente
```bash
pip install --upgrade ytsage
```
Quindi esegui l'applicazione:
```bash
ytsage
```
### ๐ฆ Eseguibili Pre-compilati (Executable)
> [๐ Scarica l'ultima versione](https://github.com/oop7/YTSage/releases/latest)
#### ๐ช Windows
| Formato | Descrizione |
|--------|-------------|
|  | Installer Standard |
|  | Include FFmpeg |
|  | Versione Portable, nessuna installazione richiesta |
|  | Portable con FFmpeg, compresso (ZIP) |
๐ ๏ธ Passaggi per l'installazione
1. **Installer EXE (`.exe`)**: Fare doppio clic sul file e seguire la procedura guidata.
2. **Versione Portable (`.zip`)**: Estrarre l'archivio nella posizione desiderata ed eseguire `ytsage.exe`.
3. **FFmpeg integrato**: Se non hai FFmpeg sul tuo sistema, scegli le versioni con FFmpeg integrato.
#### ๐ง Linux
| Formato | Descrizione |
|--------|-------------|
|  | Pacchetto Debian |
|  | AppImage, Portable |
|  | Pacchetto RPM |
|  | Bundle Flatpak |
๐ ๏ธ Passaggi per l'installazione
- **DEB (`.deb`)**:
```bash
sudo dpkg -i ytsage_*.deb
sudo apt-get install -f # Se necessario per correggere le dipendenze mancanti
```
- **RPM (`.rpm`)**:
```bash
sudo rpm -i ytsage-*.rpm
```
- **AppImage (`.AppImage`)**:
```bash
chmod +x YTSage-*.AppImage
./YTSage-*.AppImage
```
- **Flatpak**: Seguire le istruzioni su Flathub o eseguire:
```bash
flatpak install flathub io.github.oop7.ytsage
```
#### ๐ macOS
| Formato | Descrizione |
|--------|-------------|
|  | App ZIP per Apple Silicon |
|  | Installer Disk Image per Apple Silicon |
๐ ๏ธ Passaggi per l'installazione
- **Installer DMG (`.dmg`)**: Fare doppio clic per montare, quindi trascinare `YTSage.app` nella cartella Applicazioni.
- **Archivio App (`.zip`)**: Estrarre lo ZIP e spostare `YTSage.app` nella cartella Applicazioni.
*Nota: Se ricevi l'errore "L'app รจ danneggiata", consulta la sezione Risoluzione dei problemi macOS di seguito.*
---
๐ป Installazione manuale dai sorgenti
### 1. Clonare il repository
```bash
git clone https://github.com/oop7/YTSage.git
cd YTSage
```
### 2. Installare le dipendenze
#### โก Con uv
```bash
uv pip install .
```
#### ๐ฆ O con pip standard
```bash
pip install .
```
### 3. Eseguire l'applicazione
```bash
python -m ytsage.main
```
## ๐ธ Screenshot
Impostazioni Download
Download Playlist
Formato Audio
Opzioni Personalizzate
## ๐ Utilizzo
๐ฏ Utilizzo Base
1. **Avvia YTSage**
2. **Incolla un URL di YouTube** (o usa il pulsante "Incolla URL")
3. **Clicca su "Analizza"**
4. **Scegli il formato:**
- `Video` per il download del video
- `Solo Audio` per l'estrazione dell'audio
5. **Seleziona le opzioni:**
- Abilita i sottotitoli e scegli la lingua
- Abilita la fusione dei sottotitoli
- Salva l'anteprima (thumbnail)
- Rimuovi sezioni sponsor
- Salva la descrizione
- Incorpora i capitoli
6. **Scegli la directory di destinazione**
7. **Clicca su "Download"**
> ๐ก La directory di download predefinita รจ la cartella "Download" dell'utente.
๐ Download Playlist
1. **Incolla l'URL della playlist**
2. **Clicca su "Analizza"**
3. **Seleziona i video dal selettore (opzionale, tutti per impostazione predefinita)**
4. **Scegli il formato/qualitร desiderati**
5. **Clicca su "Download"**
> ๐ก L'applicazione gestisce automaticamente la coda di download e puoi esportare le voci della playlist come file `.txt`, `.csv`, `.m3u` o `.json`.
๐ Modalitร Generica per siti non YouTube
Usa la Modalitร Generica quando vuoi che YTSage accetti URL da siti supportati da yt-dlp come Dailymotion, CBC Gem, TikTok e altri.
Come usarla:
1. Apri `Impostazioni Download`.
2. Abilita `Modalitร Generica`.
3. Incolla un URL di un video o di una playlist supportata che non sia YouTube.
4. Clicca su `Analizza`.
5. Scegli un formato e scarica normalmente.
Note:
- La Modalitร Generica cambia solo la validazione dell'URL all'interno di YTSage. Il sito di destinazione deve essere comunque supportato dalla versione di yt-dlp installata.
- Alcuni siti richiedono cookie, login, proxy o argomenti yt-dlp aggiuntivi a seconda dell'estrattore.
- Se un sito fallisce, aggiorna yt-dlp dal tab di aggiornamento integrato prima di segnalare il problema.
๐งฐ Opzioni Media e Download
- **Opzioni Sottotitoli:** Filtra le lingue e incorpora i sottotitoli nel file video.
- **Fusione Sottotitoli:** Fonde i sottotitoli nel file video per sottotitoli permanenti (hardcoded).
- **Salva Descrizione:** Salva la descrizione del video come file di testo.
- **Salva Anteprima:** Salva l'anteprima (thumbnail) del video come file immagine.
- **Incorpora Capitoli:** Include i segnaposti dei capitoli come metadati per i lettori video compatibili.
- **Rimuovi Sezioni Sponsor:** Usa SponsorBlock per rimuovere i segmenti sponsorizzati dal video.
- **Ritaglia Video:** Scarica solo parti specifiche del video specificando un intervallo di tempo nel formato `HH:MM:SS`.
โ๏ธ Impostazioni Output e File
- **Limitatore di Velocitร :** Limita la velocitร di download, ad esempio `500K` per 500 KB/s.
- **Salva Percorso Download:** Salva il percorso di download predefinito per i download futuri. Disponibile in **Impostazioni Download โ Percorso Download**.
- **Risoluzione Video Predefinita:** Imposta la risoluzione video preferita per la selezione automatica (es. 1080p, 720p). Disponibile in **Impostazioni Download โ Risoluzione Video Predefinita**.
- **Lingue Sottotitoli Predefinite:** Imposta le lingue dei sottotitoli predefinite per la selezione automatica (separate da virgola, es. `it,en`). Disponibile in **Impostazioni Download โ Lingue Sottotitoli Predefinite**.
- **Formato Nome File:** Personalizza il formato del nome del file di output utilizzando variabili come `%(title)s`, `%(uploader)s`, `%(playlist_index)s` e `%(resolution)s`. Disponibile in **Impostazioni Download โ Formato Nome File**.
- **Forza Formato Output:** Forza il download del video in un formato contenitore specifico come `mp4`, `webm` o `mkv`. Disponibile in **Impostazioni Download โ Impostazioni Formato Output**.
- **Conversione Formato Audio:** Converte i download di solo audio nel formato preferito come `AAC`, `MP3`, `FLAC`, `WAV`, `Opus`, `M4A`, `Vorbis`, o `Best`. Disponibile in **Impostazioni Download โ Impostazioni Formato Audio**.
- **Normalizzazione Audio:** Standardizza il volume per i download di solo audio utilizzando EBU R128.
- **Connessioni Simultanee:** Aumenta significativamente la velocitร di download scaricando i file in piรน parti contemporaneamente. Disponibile in **Impostazioni Download โ Generali โ Connessioni Simultanee** (predefinito 1, massimo 8-10 consigliato per evitare blocchi IP).
๐ Accesso e Rete
- **Login tramite Cookie:** Accedi a YouTube utilizzando i cookie per accedere ai contenuti privati.
Utilizzo:
1. **Consigliato:** Usa l'opzione integrata nell'app `Estrai cookie dal browser`, quindi scegli il browser e opzionalmente il profilo.
2. In alternativa, estrai i cookie manualmente:
a. Esporta i cookie dal tuo browser utilizzando un'estensione come [cookie-editor](https://github.com/moustachauve/cookie-editor?tab=readme-ov-file)
b. Copia i cookie nel formato Netscape
c. Crea un file chiamato `cookies.txt` e incolla i cookie
d. Seleziona il file `cookies.txt` nell'app
- **Supporto Proxy:** Usa un server proxy per i download, ad esempio `http://:`
- **Modalitร Generica:** Consente a YTSage di analizzare e scaricare da siti non YouTube supportati da yt-dlp. Abilitalo da **Impostazioni Download โ Modalitร Generica**.
๐ ๏ธ Strumenti e Manutenzione
- **Comandi Personalizzati:** Accedi alle funzioni avanzate di yt-dlp tramite argomenti della riga di comando.
- **Tab Aggiornamento:** Gestisci gli strumenti di aggiornamento integrati da un unico posto nelle Opzioni Personalizzate:
- **Aggiornamento yt-dlp:** Controlla gli aggiornamenti e passa tra i canali di rilascio Stabile e Nightly.
- **Controllo Versione FFmpeg:** Verifica la tua versione di FFmpeg e apri le guide all'installazione.
- **Aggiornamento Deno:** Controlla e aggiorna il runtime Deno.
- **Rilevamento FFmpeg/yt-dlp/Deno:** Rileva automaticamente i percorsi e le versioni di FFmpeg, yt-dlp e Deno dal dialogo Informazioni.
- **Cronologia Download:** Visualizza i download passati con anteprime e stati dal pulsante **Cronologia**.
๐ Localizzazione
YTSage supporta **14 lingue** per una portata globale. Scegli la tua lingua preferita in **Opzioni Personalizzate โ Lingua**.
### Lingue Supportate
| Lingua | Codice | Lingua | Codice |
|----------|------|----------|------|
| ๐บ๐ธ Inglese | `en` | ๐ช๐ธ Spagnolo | `es` |
| ๐ธ๐ฆ Arabo | `ar` | ๐ซ๐ท Francese | `fr` |
| ๐ฉ๐ช Tedesco | `de` | ๐ฎ๐ณ Hindi | `hi` |
| ๐ฎ๐ฉ Indonesiano | `id` | ๐ฎ๐น Italiano | `it` |
| ๐ฏ๐ต Giapponese | `ja` | ๐ต๐ฑ Polacco | `pl` |
| ๐ง๐ท Portoghese | `pt` | ๐ท๐บ Russo | `ru` |
| ๐น๐ท Turco | `tr` | ๐จ๐ณ Cinese | `zh` |
### Traduzioni del README
| Lingua | File | Lingua | File |
|----------|------|----------|------|
| ๐บ๐ธ Inglese | [README.md](README.md) | ๐ช๐ธ Spagnolo | [README.es.md](README.es.md) |
| ๐ธ๐ฆ Arabo | [README.ar.md](README.ar.md) | ๐ซ๐ท Francese | [README.fr.md](README.fr.md) |
| ๐ฉ๐ช Tedesco | [README.de.md](README.de.md) | ๐ฎ๐ณ Hindi | [README.hi.md](README.hi.md) |
| ๐ฎ๐ฉ Indonesiano | [README.id.md](README.id.md) | ๐ฎ๐น Italiano | [README.it.md](README.it.md) |
| ๐ฏ๐ต Giapponese | [README.ja.md](README.ja.md) | ๐ต๐ฑ Polacco | [README.pl.md](README.pl.md) |
| ๐ง๐ท Portoghese | [README.pt.md](README.pt.md) | ๐ท๐บ Russo | [README.ru.md](README.ru.md) |
| ๐น๐ท Turco | [README.tr.md](README.tr.md) | Cinese | [README.zh.md](README.zh.md) |
> ๐ก **Vuoi aiutare con la traduzione?** Consulta la sezione [Contribuire](#contribuire) per aiutarci ad aggiungere altre lingue!
## ๐ ๏ธ Risoluzione dei problemi
Clicca per visualizzare i problemi comuni e le soluzioni
- **La tabella dei formati non appare:** Aggiorna yt-dlp all'ultima versione e prova a passare a yt-dlp Nightly.
- **Download fallito:** Controlla la tua connessione internet e assicurati che il video sia disponibile.
- **Errori di download specifici:**
- **Video Privati:** Usa l'autenticazione tramite cookie per accedere ai contenuti privati.
- **Contenuti con limiti di etร :** Accedi al tuo account YouTube per visualizzare i video con limiti di etร .
- **Video bloccati geograficamente:** Considera l'uso di una VPN per aggirare le restrizioni regionali.
- **Video rimosso:** Il video non รจ piรน disponibile su YouTube.
- **Live Stream:** I live stream non possono essere scaricati durante la trasmissione; attendi la fine dello stream.
- **Errori di rete:** Controlla la tua connessione internet e riprova.
- **URL non valido:** Assicurati che l'URL sia corretto e provenga da una piattaforma supportata.
- **Contenuti Premium:** Richiede un abbonamento YouTube Premium.
- **Blocco Copyright:** Il contenuto รจ bloccato a causa di restrizioni sul copyright.
- **I file video e audio sono separati dopo il download:** Questo accade quando FFmpeg manca o non viene rilevato. YTSage richiede FFmpeg per unire i flussi video e audio di alta qualitร .
- **Soluzione:** Assicurati che FFmpeg sia installato e accessibile nel PATH del tuo sistema. Per gli utenti Windows, l'opzione piรน semplice รจ scaricare il file `YTSage-v-ffmpeg.exe`, che include FFmpeg.
---
#### ๐ก๏ธ Avviso Windows Defender / Antivirus
Alcuni software antivirus potrebbero contrassegnare i file `.exe` come falsi positivi. Questa รจ una **limitazione nota** delle applicazioni pacchettizzate.
**Perchรฉ succede:**
- Le euristiche dell'antivirus potrebbero identificare erroneamente gli eseguibili pacchettizzati come sospetti.
**Opzioni sicure:**
- โ **Usa l'installazione tramite pip:** `pip install ytsage` (consigliato)
- โ **Compila dai sorgenti**: Seguendo questa [guida](.github/CI_CD_README.md)
- โ **Aggiungi l'applicazione alla whitelist** nel tuo software antivirus.
#### ๐ macOS: "Lโapp รจ danneggiata e non puรฒ essere aperta"
Se visualizzi questo errore su macOS Sonoma o versioni successive, devi rimuovere l'attributo di quarantena.
1. **Apri il Terminale** (puoi trovarlo usando Spotlight).
2. **Digita il seguente comando** ma **NON** premere ancora Invio. Assicurati di includere lo spazio alla fine:
```bash
xattr -d com.apple.quarantine
```
3. **Trascina il file `YTSage.app` dalla finestra del Finder** e rilascialo direttamente nella finestra del Terminale. Questo incollerร automaticamente il percorso corretto del file.
4. **Premi Invio** per eseguire il comando.
5. **Prova a riaprire YTSage.app.** Ora dovrebbe avviarsi correttamente.
---
#### **Percorsi di configurazione (Avanzato)**
- **Windows:** `%LOCALAPPDATA%\YTSage`
- **macOS:** `~/Library/Application Support/YTSage`
- **Linux:** `~/.local/share/YTSage`
## ๐ Sponsor
Se YTSage ti fa risparmiare tempo, considera di sponsorizzare il progetto. Le sponsorizzazioni aiutano a coprire il tempo di sviluppo, i test su tutte le piattaforme e i miglioramenti futuri.
- GitHub Sponsors: https://github.com/sponsors/oop7
- Il link per la sponsorizzazione รจ disponibile direttamente tramite il dialogo Informazioni all'interno dell'app.
[](https://github.com/sponsors/oop7)
## ๐ฅ Contribuire
I contributi sono benvenuti! Ecco come puoi aiutare:
1. ๐ด Fork del repository
2. ๐ฟ Crea il tuo ramo per la funzione:
```bash
git checkout -b feature/FunzioneIncredibile
```
3. ๐พ Fai il commit delle tue modifiche:
```bash
git commit -m 'Aggiungi FunzioneIncredibile'
```
4. ๐ค Fai il push sul ramo:
```bash
git push origin feature/FunzioneIncredibile
```
5. ๐ Apri una Pull Request
### ๐ Contribuire alle traduzioni
- Aggiorna il file README localizzato pertinente (es. `readme-translations/README.it.md`)
- Mantieni sincronizzate le stringhe dell'app modificando `ytsage/languages/.json`
- Se la tua lingua manca, parti da `README.md` e crea `README..md`
๐ Struttura del Progetto
## YTSage - Struttura del Progetto
Questo documento descrive la struttura organizzata delle cartelle di YTSage.
### ๐ Struttura del Progetto
```
YTSage/
โโโ ๐ .github/ # Configurazioni GitHub
โ โโโ ๐ ISSUE_TEMPLATE/ # Modelli per segnalazioni
โ โ โโโ ๐-bug-report.md # Modello per segnalazione bug
โ โโโโ ๐ workflows/ # Workflow GitHub Actions
โ โ โโโ build-linux.yml # Workflow build Linux
โ โ โโโ build-macos.yml # Workflow build macOS
โ โ โโโ build-windows.yml # Workflow build Windows
| | โโโ release-all.yml # Workflow release master
โ โโโ ๐ CI_CD_README.md # Documentazione CI/CD
โโโ ๐ branding/ # Asset di branding (screenshot, SVG)
โ โโโ ๐ icons/ # Icone dell'app
โ โโโ ๐ screenshots/ # Screenshot per la documentazione
โ โโโ ๐ svg/ # Asset SVG
โโโ ๐ LICENSE # File della licenza
โโโ ๐ pyproject.toml # Metadati del progetto e dipendenze
โโโ ๐ README.md # Documentazione del progetto
โโโ ๐ requirements.txt # Dipendenze Python (dev)
โโโ ๐ ytsage/ # Pacchetto del codice sorgente
โโโ ๐ assets/ # Asset runtime
โ โโโ ๐ Icon/ # Icone dell'app
โ โโโ ๐ sound/ # File audio
โโโ ๐ languages/ # File di localizzazione
โ โโโ ๐ ar.json # Traduzione araba
โ โโโ ๐ de.json # Traduzione tedesca
โ โโโ ๐ en.json # Traduzione inglese
โ โโโ ... # Altre lingue
โโโ ๐ core/ # Logica di business principale
โ โโโ ๐ __init__.py
โ โโโ ๐ ytsage_deno.py # Integrazione Deno
โ โโโ ๐ ytsage_downloader.py # Funzionalitร di download
โ โโโ ๐ ytsage_ffmpeg.py # Integrazione FFmpeg
โ โโโ ๐ ytsage_utils.py # Funzioni di utilitร
โ โโโ ๐ ytsage_yt_dlp.py # Integrazione yt-dlp
โโโ ๐ gui/ # Componenti dell'interfaccia utente
โ โโโ ๐ __init__.py
โ โโโ ๐ ytsage_gui_main.py # Finestra principale dell'app
โ โโโ ๐ ytsage_gui_dialogs/ # Classi per i dialoghi
โโโ ๐ utils/ # Moduli di utilitร
โ โโโ ๐ __init__.py
โ โโโ ๐ ytsage_config_manager.py # Gestione configurazione
โ โโโ ๐ ytsage_logger.py # Strumenti di logging
โโโ ๐ __init__.py # Punto di ingresso del pacchetto
โโโ ๐ main.py # Script di esecuzione principale
```
## โญ๏ธ Cronologia Stelle
## Star History
## ๐ Licenza
Questo progetto รจ rilasciato sotto Licenza MIT - vedi il file [LICENSE](LICENSE) per i dettagli.
## ๐ Ringraziamenti
Mostra Ringraziamenti
Un grande ringraziamento a tutti coloro che hanno contribuito a questo progetto aprendo segnalazioni per suggerire miglioramenti o segnalare bug.
## โ ๏ธ Disclaimer
Questo strumento รจ solo per uso personale. Rispettate i Termini di Servizio di YouTube e i diritti dei produttori di contenuti.
---
Creato con โค๏ธ da [oop7](https://github.com/oop7)
[](https://www.python.org/downloads/)
[](https://pepy.tech/project/ytsage)
[](https://github.com/oop7/YTSage/releases)
[](https://opensource.org/licenses/MIT)
[](https://github.com/oop7/YTSage/releases)
[](https://github.com/oop7/YTSage/stargazers)
[](https://pypi.org/project/ytsage/)
[](https://github.com/sponsors/oop7)
**Un downloader YouTube moderno con un'interfaccia PySide6 pulita.**
Scarica video in qualsiasi qualitร , estrai audio, ottieni sottotitoli e molto altro.
### ๐ Lingue del README
Inglese: [EN](../README.md)
| Arabo: [AR](README.ar.md)
| Tedesco: [DE](README.de.md)
| Spagnolo: [ES](README.es.md)
| Francese: [FR](README.fr.md)
| Hindi: [HI](README.hi.md)
| Indonesiano: [ID](README.id.md)
| Italiano: [IT](README.it.md)
| Giapponese: [JA](README.ja.md)
| Polacco: [PL](README.pl.md)
| Portoghese: [PT](README.pt.md)
| Russo: [RU](README.ru.md)
| Turco: [TR](README.tr.md)
| Cinese: [ZH](README.zh.md)
