1. Riassunto Progetto ChinesePod

1.1 Cosa fa il sistema

Una PWA per studiare cinese che:

• Legge un JSON con il dialogo (cinese, pinyin, traduzione letterale/naturale)
• Riproduce un MP3 con le frasi del dialogo
• Mostra vocabolario chiave e supplementare

1.2 Problemi identificati

• Bug risolto: cliccando ▶ su una singola frase non parte più la sequenza automatica
• Problema principale: il karaoke non funziona — le parole cinesi NON cambiano colore in sincronia con l’audio
• L’audio dei dialoghi non è per nulla associato al testo

2. Pipeline di Generazione

2.1 FASE 1 — Preparazione

• Scaricare chinesepod_E0429.pdf (originale) in scaricatiAB/E0429/
• Lanciare split_pdf.py → divide in pagine singole in scaricatiABC

2.2 FASE 2 — Traduzione

• Lanciare chinesepod_traduci_v8.py → genera per ogni pagina:
  • chinesepod_E0429_1_italiano.pdf
  • chinesepod_E0429_1_dati.json

2.3 FASE 3 — Merge

• Lanciare merge_pdf_json.py → legge da scaricatiABC e scrive in scaricatiAB:
  • chinesepod_E0429_italiano.pdf ← PDF unico
  • chinesepod_E0429_dati.json ← JSON unico

2.4 FASE 4 — Audio

• Lanciare ai_studio_code.py su scaricatiAB → genera chinesepod_E0429_cinese.mp3

2.5 FASE 5 — Timestamp

• Lanciare analizza_silenzi.py → genera chinesepod_E0429_timestamps.json

2.6 RISULTATO FINALE in scaricatiAB

• chinesepod_E0429.pdf ← originale
• chinesepod_E0429_italiano.pdf ← tradotto
• chinesepod_E0429_dati.json ← dati strutturati
• chinesepod_E0429_cinese.mp3 ← audio
• chinesepod_E0429_timestamps.json ← per karaoke

3. Bug Fix – toggleLine()

3.1 Problema

Avviando l’audio di una conversazione, partivano poi in sequenza tutte le altre invece di terminare.

3.2 Soluzione

Aggiungere isPlayingAll = false prima di stopAll() nella funzione toggleLine():

function toggleLine(i) {
  if (currentBtn === i && !isPaused) {
    if (useMP3) audioEl.pause();
    else window.speechSynthesis.pause();
    isPaused = true;
    setBtnState(i, 'paused');
    return;
  }
  if (currentBtn === i && isPaused) {
    if (useMP3) audioEl.play();
    else window.speechSynthesis.resume();
    isPaused = false;
    setBtnState(i, 'playing');
    return;
  }
  // Frase singola — ferma la sequenza
  isPlayingAll = false;
  document.getElementById('btn-play-all').innerHTML = '▶';
  stopAll();
  startLine(i);
}

4. Karaoke – Problema e Soluzioni

4.1 Perché non funziona il karaoke

• Carica i _timestamps.json (con start/end per frase intera) ✅
• Ma il testo cinese è renderizzato come stringa unica in <span class="chinese-text"> — non è spezzato parola per parola
• Manca un ciclo requestAnimationFrame o setInterval che confronti audioEl.currentTime con i timestamp

4.2 Cosa serve per il karaoke

• Timestamp per ogni singolo carattere o parola
• Oppure interpolazione lineare tra start e end distribuendo i caratteri equamente nel tempo

4.3 Opzioni

• Opzione A: Karaoke con interpolazione lineare (funziona subito, senza rigenerare JSON)
• Opzione B: Rigenerare i JSON con timestamp per ogni carattere (più preciso, richiede modificare analizza_silenzi.py)

5. Struttura Timestamp JSON

5.1 Struttura attuale

Il file _cinese_timestamps.json contiene probabilmente:

[
  { 'start': 0.5, 'end': 2.3 },
  { 'start': 2.5, 'end': 4.1 },
  ...
]

5.2 Struttura desiderata

[
  {
    'frase': '你好',
    'start': 0.5,
    'end': 2.3,
    'parole': [
      { 'char': '你', 'start': 0.5, 'end': 1.2 },
      { 'char': '好', 'start': 1.2, 'end': 2.3 }
    ]
  }
]

6. Struttura Remota

6.1 Struttura proposta

TRADUZIONI/
   scaricatiAB/
      E0429/
         chinesepod_E0429.pdf
         chinesepod_E0429_italiano.pdf
         chinesepod_E0429_dati.json
         chinesepod_E0429_cinese.mp3
         chinesepod_E0429_timestamps.json
   newbie/
   elementary/
   advanced/

7. genera_indice.py

7.1 Procedura di aggiornamento

1. Aggiungi i PDF in scaricatiAB
2. Lancia la pipeline (split → traduci → merge → chinesepod_mp3_v3)
3. Lancia genera_indice.py → rigenera lezioni.json
4. Carica sul server i nuovi file + lezioni.json aggiornato

7.2 Come funziona

• genera_indice.py scansiona le cartelle e ricostruisce l’indice completo
• Non devi modificare niente a mano