Guida registrazione: Setup A/B BlackHole + Multi-Output Device

- README: sezione 'Guida rapida' riscritta con installazione,
  permesso microfono macOS, Setup A (output dedicato a BlackHole)
  e Setup B (Multi-Output Device con BlackHole + altoparlanti,
  Master Device + Drift Correction). Aggiunta tabella
  Troubleshooting (5 sintomi tipici con fix)
- webui: hint nella tab Registra arricchito (riassunto a step
  inline + link al README su GitHub via window open)
- CSS: .hint passa a align-items flex-start per contenuto
  multi-riga, aggiunti stili per <code> e <a> dentro l'hint

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

README.md

@@ -75,29 +75,54 @@ Per scaricare **Instagram / Facebook privati** o aggirare il rate-limit di YouTu
 
 macOS non espone nativamente l'output audio del sistema. Per registrare quello che esce dagli speaker (es. uno stream Spotify/YouTube), serve un driver virtuale di **loopback**. Il più diffuso è **BlackHole**, gratuito e open source.
 
-### Installazione
+### 1. Installazione
 
 ```bash
 brew install blackhole-2ch
 ```
 
-### Configurazione
+> Subito dopo l'installazione, se non vedi BlackHole nella tab Registra, riavvia il servizio audio:
+> ```bash
+> sudo killall coreaudiod
+> ```
+> Si rilancia da solo in pochi secondi, nessun danno. In alternativa, logout/login o riavvio del Mac.
 
-1. **Preferenze di Sistema** → **Audio** → **Uscita** → seleziona **BlackHole 2ch**
-2. Apri la tab **● Registra** in MusicDownload e clicca **↻ Aggiorna**
-3. Nel dropdown vedrai **🔄 BlackHole 2ch (loopback)** — selezionalo
-4. Premi **● REC**, fai partire lo stream, premi **◼ Stop**
+### 2. Permesso Microfono
 
-### Vuoi sentire ancora l'audio mentre registri?
+Anche se non è un microfono fisico, macOS richiede il permesso "Microfono" per leggere da BlackHole via AVFoundation.
 
-Crea un **Multi-Output Device** in **Audio MIDI Setup**:
+Vai su **Preferenze di Sistema → Privacy e sicurezza → Microfono** e abilita l'app da cui lanci MusicDownload (Terminal/iTerm in sviluppo, oppure MusicDownload.app per la build distribuita). Se non vedi nessuna voce, comparirà un popup la prima volta che premi REC — accetta.
 
-1. Apri **Configurazione MIDI Audio** (`Utility → Audio MIDI Setup`)
-2. `+` in basso a sinistra → **Crea dispositivo aggregato a uscita multipla**
-3. Seleziona **BlackHole 2ch** + i tuoi altoparlanti/cuffie
-4. Imposta questo Multi-Output come uscita di sistema
+### 3. Setup A — minimo (registri ma non senti l'audio durante)
 
-Così l'audio va contemporaneamente agli speaker (lo senti) e a BlackHole (viene registrato).
+1. Click sull'icona altoparlante nella barra menu → **Output → BlackHole 2ch**
+   *Oppure: Preferenze di Sistema → Audio → Uscita → BlackHole 2ch*
+2. Fai partire lo stream (Spotify/YouTube): non sentirai nulla — è normale, l'audio va a BlackHole
+3. App MusicDownload → tab **● Registra** → dispositivo **🔄 BlackHole 2ch (loopback)** → **REC**
+4. **Stop** e riascolta il file MP3 generato
+
+### 4. Setup B — completo (registri E senti l'audio contemporaneamente, consigliato)
+
+1. Apri **Configurazione MIDI Audio** (`Applicazioni → Utility → Configurazione MIDI Audio`)
+2. In basso a sinistra: **+ → Crea dispositivo aggregato a uscita multipla** (Multi-Output Device)
+3. Nella colonna a destra, spunta sia **BlackHole 2ch** sia i tuoi **Altoparlanti integrati** (o le cuffie)
+4. Imposta **BlackHole 2ch** come **Master Device** (menù a tendina in alto)
+5. Abilita **Drift Correction** sulla riga degli altoparlanti
+6. (Opzionale) Rinomina il dispositivo aggregato in `Speakers + BlackHole`
+7. **Preferenze di Sistema → Audio → Uscita** → seleziona `Speakers + BlackHole`
+8. Nella tab Registra dell'app scegli **🔄 BlackHole 2ch (loopback)** — **NON il dispositivo aggregato**, quello è solo per riprodurre
+
+Adesso ogni audio del sistema viene riprodotto sugli speaker (lo senti) e contemporaneamente catturato da BlackHole (viene registrato).
+
+### Troubleshooting
+
+| Sintomo | Causa probabile | Fix |
+|---|---|---|
+| BlackHole non compare nel dropdown | CoreAudio non l'ha ancora caricato dopo l'install | `sudo killall coreaudiod` poi premi **↻ Aggiorna** |
+| Errore `ffmpeg exit -6` o `permesso Microfono mancante` | macOS nega l'accesso al device | Privacy e sicurezza → Microfono → abilita Terminal/MusicDownload |
+| File MP3 muto | Output di sistema non passa per BlackHole | Cambia output su BlackHole o Multi-Output Device (vedi Setup A/B) |
+| Audio doppio/eco nel file | Stai registrando da BlackHole *e* da microfono fisico simultaneamente | Verifica che nel dropdown ci sia solo `BlackHole 2ch` |
+| Audio crackly/distorto | Sample rate non allineato | In Audio MIDI Setup, BlackHole + altoparlanti tutti a 48 kHz |
 
 ## Struttura progetto
 

webui/css/style.css

@@ -620,25 +620,44 @@ input[type="number"]::-webkit-inner-spin-button {
    =============================== */
 .hint {
   display: flex;
-  align-items: center;
-  gap: 10px;
+  align-items: flex-start;
+  gap: 12px;
   margin-top: 4px;
-  padding: 10px 14px;
+  padding: 12px 14px;
   background: rgba(236, 72, 153, 0.08);
   border: 1px solid rgba(236, 72, 153, 0.2);
   border-radius: var(--r-sm);
   color: var(--text-2);
   font-size: 12.5px;
+  line-height: 1.55;
 }
 
 .hint-ico {
   color: var(--pink-hover);
   font-size: 14px;
   font-weight: 800;
+  margin-top: 1px;
 }
 
 .hint strong { color: var(--text); font-weight: 700; }
 
+.hint code {
+  background: rgba(255, 255, 255, 0.08);
+  padding: 1px 6px;
+  border-radius: 4px;
+  font-family: "SF Mono", Menlo, Consolas, monospace;
+  font-size: 11.5px;
+  color: var(--text);
+}
+
+.hint a {
+  color: var(--green-hover);
+  text-decoration: none;
+  font-weight: 700;
+}
+
+.hint a:hover { text-decoration: underline; }
+
 /* ===============================
    CHECKBOX
    =============================== */

webui/index.html

@@ -270,7 +270,13 @@
 
           <div class="hint" id="recHint">
             <span class="hint-ico">ⓘ</span>
-            Per registrare l'audio di sistema (Spotify/YouTube/ecc.) installa <strong>BlackHole</strong> (gratuito, brew install blackhole-2ch) e poi imposta l'output di sistema su BlackHole.
+            <div>
+              <strong>Per registrare l'audio di sistema (Spotify/YouTube):</strong>
+              installa <code>brew install blackhole-2ch</code>, imposta l'uscita audio di macOS su <strong>BlackHole 2ch</strong>, poi seleziona qui sotto <strong>🔄 BlackHole 2ch (loopback)</strong>.
+              <br><br>
+              Per sentire l'audio mentre registri serve un <strong>Multi-Output Device</strong> in <em>Configurazione MIDI Audio</em> (BlackHole + altoparlanti) — guida completa nel
+              <a href="#" id="recOpenGuide">README su GitHub</a>.
+            </div>
           </div>
         </div>
 

webui/js/app.js

@@ -474,6 +474,13 @@ $("#stopUpgradeBtn").addEventListener("click", async () => {
 // ============================================================
 $("#recRefreshBtn").addEventListener("click", refreshRecDevices);
 
+$("#recOpenGuide").addEventListener("click", (e) => {
+  e.preventDefault();
+  window.pywebview.api.open_external_url(
+    "https://github.com/luzadev/musicdownload#guida-rapida-registrazione-audio-di-sistema-macos"
+  );
+});
+
 $("#recBrowseBtn").addEventListener("click", async () => {
   const path = await window.pywebview.api.browse_directory();
   if (path) {