Skip to content

Commit bf78ec5

Browse files
StinoconStinocon
committed
Reel2Recipe: la documentazione dell'add-on era l'unica cosa in italiano
Il README della radice, quello di iAlarm e i template delle issue erano gia' in inglese: restava indietro proprio l'add-on che da ieri l'interfaccia la offre in due lingue. Chi lo installa dallo store leggeva una pagina italiana per un prodotto che gli avrebbe parlato inglese. `reel2recipe/README.md` passa all'inglese, l'italiano resta integro in `README.it.md` con i link in testa a entrambi. In apertura una sezione **Languages / Lingue** dice le tre cose che servono per decidere: interfaccia in entrambe, ricette in entrambe e indipendenti, reel di partenza in entrambe senza doverlo dichiarare. Accanto il limite, che e' l'informazione onesta. Il CHANGELOG passa all'inglese in una lingua sola, e non e' un'incoerenza: Home Assistant lo mostra a chi installa, da qualsiasi paese, e una doppia copia di un file che cresce a ogni rilascio diverge al secondo giro. Il criterio e' che la lingua di un documento la decide il suo pubblico. Corretto un limite descritto in un verso solo: diceva «la traduzione italiano -> inglese e' il punto debole», ma i nomi degli ingredienti sbagliano in entrambe le direzioni, e da fonte inglese anche di piu'. Nessun rilascio: non cambia niente di eseguibile. Home Assistant legge README e CHANGELOG dal repository, non dall'immagine, quindi alzare `version` costringerebbe a una ricostruzione da un quarto d'ora e proporrebbe un aggiornamento a tutti per un cambio di sole parole.
1 parent 2464c00 commit bf78ec5

4 files changed

Lines changed: 320 additions & 160 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,8 @@ Details and options: **[`reel2recipe/README.md`](reel2recipe/README.md)** ·
6262
```
6363
<slug>/ one directory per add-on, named after its slug:
6464
config.yaml, build.yaml, Dockerfile, rootfs/, README.md, CHANGELOG.md, icons
65+
README.md is English; a README.it.md beside it is the Italian version,
66+
and the two are updated together or one of them starts lying
6567
repository.json what Home Assistant reads to list this repository
6668
docs/brand/ the banner at the top of this README
6769
.github/ one issue template and one publish workflow per add-on

‎reel2recipe/CHANGELOG.md‎

Lines changed: 64 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,82 +1,85 @@
11
# Changelog
22

3+
<!-- English only, on purpose: Home Assistant shows this file to whoever installs the
4+
add-on, from any country. One language, and the one that reaches the most people. The
5+
add-on's README is the bilingual one. -->
6+
37
## 1.0.3
48

5-
**L'interfaccia parla anche inglese.** Il selettore sta in testata: la scelta viene
6-
ricordata e alla prima apertura si parte dalla lingua del browser. Da lì scende una catena
7-
di tre anelli — interfaccia, lingua della ricetta, sistema di misura — ciascuno con il
8-
precedente come ripiego e ciascuno sovrascrivibile. Chi non tocca niente ottiene un insieme
9-
coerente; chi cucina in una lingua e vive in un'altra può incrociarli.
9+
**The interface speaks English too.** The switch is in the header: the choice is remembered
10+
and on first open it follows your browser's language. From it descends a chain of three
11+
links — interface, recipe language, measurement system — each falling back to the one before
12+
it and each overridable. Change nothing and you get a coherent set; someone who cooks in one
13+
language and lives in another can cross them.
1014

11-
**Il selettore della lingua non era collegato a niente.** Era disegnato nel pannello
12-
*Opzioni* fin dalla 1.0.0, si poteva scegliere, e ogni estrazione usciva comunque in
13-
italiano metrico. Un comando che non fa niente è peggio di un comando assente: insegna a
14-
non fidarsi dell'interfaccia.
15+
**The recipe-language selector was not wired to anything.** It had been drawn in the
16+
*Options* panel since 1.0.0, you could pick a language, and every extraction came out in
17+
Italian with metric units regardless. A control that does nothing is worse than a missing
18+
one: it teaches you not to trust the interface.
1519

16-
**A Whisper si diceva che ogni reel era italiano.** La lingua del parlato era fissata a
17-
"it" e non era esposta da nessuna parte, quindi anche un reel inglese veniva trascritto
18-
come se fosse italiano — parole italiane forzate su suoni inglesi, e da lì in poi tutto il
19-
resto lavorava su quelle. Il difetto era invisibile, perché una ricetta plausibile il
20-
modello la produce comunque. Ora la lingua la riconosce Whisper da sé, e resta forzabile
21-
dalle *Opzioni* quando sbaglia.
20+
**Whisper was told every reel was Italian.** The spoken language was pinned to "it" and
21+
exposed nowhere, so even an English reel was transcribed as if it were Italian — Italian
22+
words forced onto English sounds, and everything downstream then worked on those. The fault
23+
was invisible, because the model produces a plausible recipe anyway. Now Whisper detects the
24+
language itself, and it can still be forced from *Options* when detection gets it wrong.
2225

23-
**Trascinare un video perdeva le impostazioni.** Il caricamento di un file accettava solo
24-
lingua e sistema: backend di trascrizione, modello e «usa solo la didascalia» venivano
25-
scartati in silenzio. Ora le due strade prendono le stesse opzioni.
26+
**Dragging in a video threw away your settings.** Uploading a file only accepted the language
27+
and the measurement system: transcription backend, model and "use the caption only" were
28+
silently discarded. Both routes now take the same options.
2629

2730
## 1.0.2
2831

29-
**Il modello non si scaricava più dopo un errore.** Alla prima installazione i 9 GB di
30-
`qwen2.5:14b` sono arrivati interi e sono stati scartati dalla verifica dello sha256
31-
(`digest mismatch`). Il pull si tentava una volta sola: dopo quel fallimento l'add-on
32-
restava senza modello per sempre, e l'unico rimedio era riavviarlo a mano.
32+
**The model stopped re-downloading after a failure.** On first install the 9 GB of
33+
`qwen2.5:14b` arrived whole and were rejected by the sha256 check (`digest mismatch`). The
34+
pull was attempted once only: after that failure the add-on stayed without a model forever,
35+
and the only remedy was restarting it by hand.
3336

34-
Ora ritenta **tre volte**, con attesa crescente. Tre e non infinite: se la causa è il disco
35-
pieno, riprovare in eterno non la risolve. Per distinguere le due cause — un file troncato
36-
per spazio esaurito dà lo stesso `digest mismatch` di una corruzione in transito — a ogni
37-
fallimento il registro scrive lo spazio libero su `/data`.
37+
It now retries **three times**, with growing waits. Three and not endlessly: if the cause is
38+
a full disk, retrying forever does not fix it. To tell the two causes apart — a file
39+
truncated by exhausted space gives the same `digest mismatch` as corruption in transit — the
40+
log writes the free space on `/data` at every failure.
3841

39-
**Il messaggio dell'interfaccia era sbagliato tre volte.** Consigliava
40-
`ollama pull qwen2.5:7b-instruct`: un modello diverso da quello che l'add-on installa, e per
41-
giunta quello scartato perché perde i gruppi di ingredienti e inventa le dosi. Diceva di
42-
eseguire comandi in una shell che dentro Home Assistant non esiste. E non distingueva «nessun
43-
modello» da «lo sto scaricando adesso», che è il caso normale della prima mezz'ora.
42+
**The interface's message was wrong three times over.** It suggested
43+
`ollama pull qwen2.5:7b-instruct`: a different model from the one the add-on installs, and
44+
moreover the one rejected for losing ingredient groups and inventing amounts. It told you to
45+
run commands in a shell that does not exist inside Home Assistant. And it did not distinguish
46+
"no model" from "downloading it right now", which is the normal case for the first half hour.
4447

4548
## 1.0.1
4649

47-
**L'interfaccia non partiva.** L'add-on si installava e si avviava, ma aprendolo Home
48-
Assistant rispondeva «502 Bad Gateway».
50+
**The interface would not start.** The add-on installed and started, but opening it made Home
51+
Assistant answer "502 Bad Gateway".
4952

50-
Lo script di servizio passava `--ollama` dopo il sottocomando `serve`, ma è un'opzione
51-
globale del programma e va prima: argparse usciva con codice 2, s6 riavviava il servizio
52-
all'infinito, e l'Ingress non trovava nessuno in ascolto sulla porta 8500. Il server non è
53-
mai partito nemmeno una volta — con un proxy davanti sembrava un problema di rete.
53+
The service script passed `--ollama` after the `serve` subcommand, but it is a global option
54+
of the program and goes before it: argparse exited with code 2, s6 restarted the service
55+
endlessly, and the Ingress found nobody listening on port 8500. The server never started even
56+
once — with a proxy in front it looked like a network problem.
5457

55-
Il registro contribuiva all'equivoco: annunciava «Interfaccia pronta sull'Ingress» *prima*
56-
di avviarla, quindi affermava a ogni riavvio una cosa che non era vera. Ora dice «Avvio
57-
l'interfaccia» e non testimonia più su ciò che non ha visto.
58+
The log added to the confusion: it announced "Interface ready on the Ingress" *before*
59+
starting it, so at every restart it asserted something that was not true. It now says
60+
"Starting the interface" and no longer testifies to what it has not seen.
5861

59-
Quella riga è un contratto fra due repository e non la controllava nessuno: ora è fissata da
60-
`tests/test_cli.py` in Reel2Recipe.
62+
That line is a contract between two repositories and nobody was checking it: it is now held
63+
in place by `tests/test_cli.py` in Reel2Recipe.
6164

6265
## 1.0.0
6366

64-
Prima versione stabile. Le 0.1.x che l'hanno preceduta erano di collaudo e non sono più
65-
disponibili: quanto avevano corretto è dentro questa.
66-
67-
- Interfaccia di Reel2Recipe servita tramite Ingress, nel pannello laterale.
68-
- Ollama e Whisper girano dentro l'add-on: nessun servizio remoto, nessuna chiave API,
69-
nessun dato che lascia la macchina.
70-
- Il modello LLM viene scaricato al primo avvio (`modello_llm`, `scarica_modello`) senza
71-
bloccare l'interfaccia, che nel frattempo dichiara di non essere pronta. Il modello di
72-
trascrizione (~1,5 GB) si scarica anch'esso all'avvio, e non alla prima ricetta: prima la
73-
barra si fermava su «Trascrizione del parlato» per minuti senza spiegazione.
74-
- Libreria, media e modelli su `/data`; modelli e media esclusi dai backup.
75-
- `file_cookie` per i reel che richiedono l'accesso, letto da `/share` in sola lettura. Si
76-
lavora su una copia privata e temporanea: yt-dlp riscrive quel file a fine scaricamento,
77-
ma `/share` è montato in sola lettura, e senza la copia un download riuscito falliva
78-
all'ultimo passo. La copia contiene credenziali di sessione, quindi nasce con permessi
79-
ristretti e nome imprevedibile, e viene cancellata alla fine.
80-
- I passi del procedimento escono senza numerazione: Mela numera le righe da sé, e
81-
aggiungerla produceva «1 1. Frullare il tofu».
82-
- Solo `amd64`: l'inferenza gira su CPU e serve una macchina con 16 GB di RAM.
67+
First stable version. The 0.1.x releases before it were trial runs and are no longer
68+
available: what they fixed is inside this one.
69+
70+
- The Reel2Recipe interface served through the Ingress, in the sidebar.
71+
- Ollama and Whisper run inside the add-on: no remote service, no API key, no data leaving
72+
the machine.
73+
- The LLM is downloaded on first start (`modello_llm`, `scarica_modello`) without blocking
74+
the interface, which meanwhile declares itself not ready. The transcription model (~1.5 GB)
75+
is downloaded at startup too, rather than on the first recipe: previously the progress bar
76+
sat on "Transcribing the speech" for minutes with no explanation.
77+
- Library, media and models on `/data`; models and media excluded from backups.
78+
- `file_cookie` for reels that require signing in, read from `/share` read-only. A private,
79+
temporary copy is used: yt-dlp rewrites that file when a download ends, but `/share` is
80+
mounted read-only, and without the copy a successful download failed at the last step. The
81+
copy holds session credentials, so it is created with restricted permissions and an
82+
unpredictable name, and deleted afterwards.
83+
- Method steps come out unnumbered: Mela numbers the lines itself, and adding it produced
84+
"1 1. Blend the tofu".
85+
- `amd64` only: inference runs on the CPU and needs a machine with 16 GB of RAM.

‎reel2recipe/README.it.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
<p align="center">
2+
<a href="README.md">English</a> · <strong>Italiano</strong>
3+
</p>
4+
5+
# Reel2Recipe — add-on per Home Assistant
6+
7+
Estrae ricette dai reel di cucina e le rende utilizzabili: le struttura, ne normalizza le
8+
quantità, le archivia in una libreria ricercabile e le esporta in formato **Mela**.
9+
10+
Il problema che risolve non è "estrarre una ricetta" ma **ritrovarla**: chi salva ricette su
11+
Instagram poi non le ritrova più.
12+
13+
Codice sorgente e documentazione completa: **[Stinocon/Reel2Recipe](https://github.com/Stinocon/Reel2Recipe)**.
14+
15+
## Lingue
16+
17+
**Italiano e inglese, su entrambi i lati dello strumento.** Il selettore dell'interfaccia sta
18+
in testata; la scelta viene ricordata, e alla prima apertura segue la lingua del browser. Da
19+
lì scendono gli altri due assi — la lingua della ricetta e il sistema di misura — che di base
20+
la seguono e restano sovrascrivibili nelle *Opzioni*.
21+
22+
La lingua *parlata* nel reel è un'altra cosa e non si deduce da queste: la riconosce Whisper
23+
da sé, così un reel inglese può diventare una ricetta italiana, o restare in inglese.
24+
25+
Un limite da conoscere prima di farci affidamento: tradurre i **nomi degli ingredienti** è la
26+
parte meno affidabile della catena — vedi
27+
[quello che non fa](#quello-che-non-fa-e-va-saputo-prima). Le quantità restano giuste; sono
28+
le parole a scivolare.
29+
30+
## Cosa gira dentro l'add-on
31+
32+
Tutto. La trascrizione usa **Whisper** in locale, la strutturazione un **LLM locale via
33+
Ollama**, entrambi dentro questo container. Nessuna chiave API, nessun abbonamento, nessun
34+
dato che lascia la macchina — ed è un vincolo di progetto, non una caratteristica di questa
35+
versione: il prodotto deve continuare a funzionare anche se si smette di pagare qualsiasi
36+
cosa.
37+
38+
Il corollario è che il lavoro pesante lo fa la CPU del tuo server.
39+
40+
## Requisiti
41+
42+
| | |
43+
|---|---|
44+
| Architettura | **amd64 soltanto** — un miniPC o un NUC, non un Raspberry |
45+
| RAM | **16 GB** consigliati: il modello predefinito ne occupa circa 9 quando è caricato |
46+
| Disco | **~15 GB**: 1,5 GB di immagine, ~9 GB per il modello LLM, ~1,5 GB per Whisper |
47+
| Tempi | Alcuni minuti per ricetta su CPU. È un lavoro da lanciare e lasciar fare |
48+
49+
Se la macchina è più modesta, in `modello_llm` si può mettere `qwen2.5:7b-instruct`: dimezza
50+
memoria e tempi, ma **perde i gruppi di ingredienti** ("per la salsa", "per la base") e
51+
tende a completare le dosi mancanti invece di dichiararle. Il modello grande resta il
52+
predefinito per questa ragione.
53+
54+
## Installazione
55+
56+
1. In Home Assistant: **Impostazioni → Add-on → Store**, menu in alto a destra,
57+
**Repository**, e aggiungi:
58+
59+
```
60+
https://github.com/Stinocon/addons
61+
```
62+
63+
2. Installa **Reel2Recipe** e avvialo.
64+
3. **Il primo avvio scarica circa 10 GB**: il modello di linguaggio e quello di trascrizione.
65+
L'interfaccia è già raggiungibile nel frattempo e mostra "LLM non pronto" finché non ha
66+
finito; il registro dell'add-on riporta un avanzamento ogni minuto. Si scaricano una volta
67+
sola e restano su `/data`, quindi gli aggiornamenti dell'add-on non li ripagano.
68+
4. Apri il pannello dalla barra laterale.
69+
70+
## Opzioni
71+
72+
| opzione | predefinito | cosa fa |
73+
|---------|-------------|---------|
74+
| `modello_llm` | `qwen2.5:14b` | Il modello Ollama che struttura la ricetta. Scaricato al primo avvio se manca |
75+
| `scarica_modello` | `true` | Disattivalo se preferisci gestire i modelli a mano |
76+
| `file_cookie` | *(vuoto)* | File di cookie in formato Netscape dentro `/share`. Vanno bene sia `cookies.txt` sia `/share/cookies.txt`. Il file non viene mai modificato: se ne usa una copia |
77+
| `log_level` | `info` | Verbosità del registro |
78+
79+
## Come si usa
80+
81+
Due strade, e non sono equivalenti sul piano legale:
82+
83+
- **Carichi un file** che hai già sul dispositivo (trascina-e-rilascia sulla pagina),
84+
incollando la didascalia. È la strada senza attriti.
85+
- **Incolli il link** del reel: l'add-on lo scarica. Scaricare un reel viola i Termini d'Uso
86+
di Instagram — è la ragione per cui questo strumento è **locale e per uso personale**, e
87+
perché l'alternativa senza download esiste sempre. Vedi
88+
[docs/legale.md](https://github.com/Stinocon/Reel2Recipe/blob/main/docs/legale.md).
89+
90+
Instagram richiede l'accesso per buona parte dei contenuti. Qui dentro non c'è un browser da
91+
cui prendere i cookie, quindi la via è esportarli altrove in formato Netscape, metterli in
92+
`/share` e indicarli in `file_cookie` — per esempio `cookies-instagram.txt`.
93+
94+
Il risultato non è un file buttato in una cartella: la ricetta entra in una libreria con
95+
ricerca full-text, si corregge a mano dove serve, e si esporta in `.melarecipe`, Markdown o
96+
PDF.
97+
98+
## Quello che non fa, e va saputo prima
99+
100+
- **Le quantità non le converte il modello, le converte il codice** con tabelle di densità
101+
che hanno una fonte dichiarata. Dove una densità non è nota, la conversione non si fa: si
102+
conserva il volume e si dichiara la lacuna. Un peso sbagliato di cui non sai che è
103+
sbagliato, in cucina, fa danni.
104+
- **Non inventa.** Quantità o passaggi non deducibili dal materiale restano buchi
105+
dichiarati. Una ricetta incompleta ma onesta è utilizzabile; una completata a caso no.
106+
- **Tradurre i nomi degli ingredienti è il punto debole.** Da una fonte inglese i nomi
107+
sbagliano con una certa regolarità; da una didascalia italiana lunga verso l'inglese il
108+
modello traduce il titolo e resta ancorato all'italiano nell'elenco. È un limite del
109+
modello locale, non della conversione, che resta deterministica in entrambe le direzioni.
110+
- **Non crea entità in Home Assistant.** È un'applicazione che vive nel pannello laterale,
111+
non un'integrazione: non ci sono sensori, servizi o automazioni.
112+
113+
## Dati e backup
114+
115+
Tutto sta su `/data`, che sopravvive agli aggiornamenti:
116+
117+
```
118+
/data/workspace/ricette.db la libreria
119+
/data/workspace/media/ i reel scaricati
120+
/data/ollama/ i modelli LLM
121+
/data/whisper/ i modelli di trascrizione
122+
```
123+
124+
Modelli e media sono **esclusi dai backup** di Home Assistant: sono una decina di GB
125+
riscaricabili, e un backup che li contenesse sarebbe ingestibile. La libreria delle ricette,
126+
che è l'unica cosa non riproducibile, è invece dentro.
127+
128+
Il materiale scaricato è di terzi: resta qui e non si ridistribuisce.
129+
130+
## Segnalazioni
131+
132+
I problemi di **installazione, configurazione o avvio dell'add-on** vanno
133+
[qui](https://github.com/Stinocon/addons/issues). Tutto ciò che riguarda la ricetta —
134+
trascrizione, ingredienti, conversioni, esportazioni — va invece su
135+
[Stinocon/Reel2Recipe](https://github.com/Stinocon/Reel2Recipe/issues), dove sta il codice.
136+
137+
## Licenza
138+
139+
MIT: questo add-on sotto la [`LICENSE`](../LICENSE) del repository, l'applicazione sotto
140+
[quella di Reel2Recipe](https://github.com/Stinocon/Reel2Recipe/blob/main/LICENSE). Le
141+
attribuzioni delle dipendenze stanno nel
142+
[NOTICE.md di Reel2Recipe](https://github.com/Stinocon/Reel2Recipe/blob/main/NOTICE.md); la
143+
provenienza di quanto sta in questo repository nel [`NOTICE.md`](../NOTICE.md) qui accanto.

0 commit comments

Comments
 (0)