MusicDownload

Applicazione desktop per scaricare musica da Spotify, YouTube e SoundCloud, e video da YouTube, TikTok, Instagram e Facebook. Include anche un upgrader di qualità per migliorare i file audio già scaricati.

UI moderna basata su pywebview (WebKit su macOS, EdgeChromium su Windows) — frontend HTML/CSS/JS, backend Python.

Sviluppata da LuZa.

Repo: https://github.com/luzadev/musicdownload

Funzionalità

• Scarica musica — Incolla un link Spotify (playlist/album/brano), YouTube, SoundCloud o qualsiasi sorgente yt-dlp e scarica in MP3 a 320 kbps. Supporta liste di URL da file .txt.
• Scarica video — Incolla un link YouTube · TikTok · Instagram · Facebook (o qualsiasi sorgente yt-dlp) e scarica in MP4 alla qualità scelta (best / 1080p / 720p / 480p).
• Upgrade qualità — Scansiona una cartella di file audio e riscarica quelli sotto la soglia kbps impostata.
• Auto-skip dei duplicati — Tracking persistente (.downloaded_tracks / .downloaded_videos) + scan filename token-based: re-eseguire la stessa playlist salta i brani già presenti, anche se il filename ha "Official Video" / "Lyrics" / ecc.
• Aggiornamento automatico — Verifica disponibilità nuove versioni dalla pagina Impostazioni.
• Lista multi-URL — Carica un file .txt con un URL per riga per scaricare più playlist in sequenza.

Requisiti

• Python 3.8+
• ffmpeg + ffprobe (solo per build/sviluppo locale: brew install ffmpeg su macOS)
• Credenziali Spotify API gratuite — solo se si usano URL Spotify

Nelle build distribuite (.app / .exe) tutto è incluso — non serve installare nulla.

Installazione (sviluppo)

git clone https://github.com/luzadev/musicdownload.git
cd musicdownload
pip install -r requirements.txt
python3 main.py

Dipendenze principali:

Pacchetto	Utilizzo
pywebview	Finestra nativa con WebView (WebKit / EdgeChromium)
requests	Chiamate API Spotify
yt-dlp	Download audio/video da YouTube e oltre 1000 siti
pyobjc-framework-WebKit (macOS)	Backend WebKit di pywebview
pythonnet (Windows)	Backend EdgeChromium di pywebview

Credenziali Spotify API

Necessarie solo per scaricare da URL open.spotify.com/....

1. Vai su https://developer.spotify.com/dashboard e accedi (anche account gratuito)
2. Clicca Create app
3. Compila: nome a piacere, Redirect URI http://localhost:8888/callback, seleziona Web API
4. Apri la app e clicca Settings
5. Copia Client ID e Client Secret nelle Impostazioni dell'app

Le credenziali sono gratuite, non servono Spotify Premium.

Cookies per contenuti privati

Per scaricare Instagram / Facebook privati o aggirare il rate-limit di YouTube serve un file cookies.txt (formato Netscape). Esportalo dal browser con un'estensione tipo "Get cookies.txt LOCALLY" e imposta il percorso in Impostazioni → Percorsi.

Struttura progetto

MusicDownload/
├── main.py                  # Entry point — bootstrap pywebview
├── requirements.txt
├── build_macos.py           # Script build macOS (.app)
├── build_windows.py         # Script build Windows (.exe)
├── .github/workflows/
│   └── build.yml            # CI: build macOS + Windows + Release automatica su tag
│
├── core/                    # Logica backend (riusabile, no UI)
│   ├── config.py            # Configurazione persistente (JSON)
│   ├── paths.py             # Ricerca binari (yt-dlp, ffmpeg)
│   ├── spotify_client.py    # API Spotify (Client Credentials)
│   ├── downloader.py        # Download audio (playlist Spotify, URL diretti, video)
│   └── upgrader.py          # Upgrade qualità file esistenti
│
├── api/
│   └── bridge.py            # Ponte JS <-> Python (pywebview.js_api)
│
└── webui/                   # Frontend
    ├── index.html           # Single-page, 4 view (Scarica / Video / Upgrade / Impostazioni)
    ├── css/style.css        # Tema scuro Spotify-like, gradient hero, animazioni
    └── js/app.js            # Routing, eventi, chiamate API

Configurazione

Il file config.json viene creato automaticamente al primo avvio:

Chiave	Default	Descrizione
client_id	""	Spotify Client ID
client_secret	""	Spotify Client Secret
bitrate	"320K"	Bitrate download audio (128K/192K/256K/320K)
hq_threshold	310	Soglia kbps per considerare un file HQ
cookies_path	""	Path al file cookies.txt (opzionale)
output_dir	""	Cartella output predefinita
theme	"dark"	Tema interfaccia

Posizione:

• Sviluppo: directory del progetto
• macOS bundle: ~/Library/Application Support/MusicDownload/
• Windows bundle: %APPDATA%/MusicDownload/

Build locale

macOS

brew install ffmpeg
pip install pyinstaller
python3 build_macos.py

Produce dist/MusicDownload.app con yt-dlp, ffmpeg, ffprobe e tutte le dylib bundled (rpath patchati con install_name_tool).

Windows

pip install pyinstaller
python build_windows.py

Produce dist/MusicDownload/MusicDownload.exe. Lo script scarica automaticamente yt-dlp.exe e ffmpeg.exe/ffprobe.exe static build.

Build & Release automatiche (GitHub Actions)

Ogni push di un tag v* triggera la pipeline .github/workflows/build.yml:

1. build-macos (runner macos-latest) → MusicDownload-macOS.zip (la .app zippata con ditto)
2. build-windows (runner windows-latest) → MusicDownload-Windows.zip
3. release → crea automaticamente una GitHub Release con entrambi gli asset allegati

Per pubblicare una nuova versione:

git tag v1.2.0
git push origin v1.2.0

Per fare solo una build di test (senza release):

gh workflow run "Build MusicDownload" --ref main

oppure dalla UI: Actions → Build MusicDownload → Run workflow.

Le release ufficiali sono disponibili su https://github.com/luzadev/musicdownload/releases.

Aggiornamento app

L'app verifica nuove versioni interrogando un version.json remoto. URL configurato in api/bridge.py (UPDATE_URL nel metodo check_update):

{
  "version": "v1.2.0",
  "download_url": "https://github.com/luzadev/musicdownload/releases/latest",
  "notes": "Descrizione delle novità"
}

Licenza

Uso personale.