07 · La linfa: arricchimento

La linfa sale dalla radice alle foglie senza che nessuno la veda. L'arricchimento fa lo stesso con gli allegati: estrae il testo dai PDF, riconosce le pagine scansionate, scrive i sottotitoli del parlato — perché la ricerca trovi e chi non sente possa leggere.

File da leggere

1. docs/baobaxia-enriquecimento.md — il progetto completo (leggilo prima).
2. enriquecimento/servico.py — Enriquecedor: decidere, eseguire, scrivere.
3. enriquecimento/procedencia.py — il registro di "cosa è stato fatto a quale file, con quale motore, con quale risultato" (data.enriquecimento).
4. enriquecimento/classificar.py, textos.py, ocr.py, transcricao.py, legendas.py, vocabulario.py.
5. infra/previa_video.py, infra/thumbnails.py, infra/mosaico.py.

Cosa è automatico e cosa va richiesto

La richiesta viaggia con il sync: chi chiede può essere una mucua senza Whisper; la prossima mucua con la capacità e con il file fa il lavoro, e i sottotitoli tornano a tutte come allegato (<file>.<lingua>.vtt, nell'annex).

flowchart TD
    A[allegato in content] --> B{c'è già un registro di provenienza<br/>con lo stesso hash?}
    B -- sì --> C{--forcar, o modello migliore qui<br/>e output non rivisto da persone?}
    C -- no --> Z[salta]
    C -- sì --> D
    B -- no --> D[classificare]
    D -->|audio/video| E{è in data.transcrever?}
    E -- no --> Z
    E -- sì --> E2[ffmpeg 16 kHz → Whisper + VAD + vocabolario<br/>→ file.pt.vtt nell'annex]
    D -->|PDF| F[pdftotext → cache locale]
    F --> F2{pagine senza testo?}
    F2 -- sì, senza richiesta --> F3[status: precisa_ocr]
    F2 -- sì, con data.ocr --> G[Tesseract → file.ocr.txt nell'annex]
    D -->|immagine| H{è in data.ocr?}
    H -- sì --> G
    H -- no --> Z
    D -->|docx/odt/txt/html| I[testo → cache locale]

Le cure che il codice ha

• Blocco di processo (_TravaProcesso): un solo giro per macchina; un altro risponde ja_em_andamento.
• Blocco della galassia: aspetta che sync e richieste lo rilascino (ESPERA_TRAVA).
• Interruzione pulita (_SemInterrupcao): un Ctrl-C a metà della scrittura aspetta la fine del commit, per non lasciare il .bbx a metà.
• La revisione umana vince: foi_revisada confronta l'hash registrato con quello dei sottotitoli attuali. Se qualcuno li ha corretti, la macchina non ci scrive sopra.
• Tentativi limitati in caso di errore (MAX_TENTATIVAS), e un errore di ambiente (motore assente) non consuma tentativi.

Esercizi

1. Leggi test_enriquecimento_whisper.py::test_transcricao_so_dos_arquivos_marcados e spiega perché non tutti i video vengono trascritti.
2. Con ffmpeg installato, genera un breve video, pubblicalo, segnalo in data.transcrever ed esegui bbx enriquecer --saber <uuid>. Dove compaiono i sottotitoli sul disco? E nell'indice?
3. In procedencia.py, segui precisa_processar. In quale caso un modello più grande rifà i sottotitoli?
4. Aggiungi nomi di luoghi della tua comunità al vocabolario di un saber (data.vocabulario) e confronta la trascrizione.

Da discutere

• I sottotitoli fatti a macchina in una lingua indigena o in una parlata quilombola sbagliano. Come fa il progetto del sistema a lasciare spazio alla correzione fatta dalla comunità?