Clipper

Clipper è un progetto personale per organizzare clip videoludiche: una CLI Python le analizza, ne deduce gioco e metadati e le carica su un server Fireshare; un'app iOS/iPadOS SwiftUI consente di consultare e gestire la libreria risultante.

Stato: sorgenti pubblicati su GitHub — SimoGatti04/Clipper, branch main. Il codice originale e l'AppIcon A «Clip Stack» sono distribuiti sotto licenza MIT; il nome tecnico resta Clipper e il nome visualizzato dell'app è Clip Stack. Questa è una pubblicazione source-only, non una distribuzione App Store né una validazione end-to-end su servizi reali.

Struttura

.
├── cli/                  # CLI Python, moduli e test sintetici
├── apps/ios/             # progetto Xcode e sorgenti SwiftUI
├── docs/                 # architettura, decisioni, ricerca e procedure
├── LICENSE               # MIT per codice e icona originali
├── pyproject.toml        # packaging e console script `clipper`
└── THIRD_PARTY_NOTICES.md

Requisiti

• macOS o Linux con Python 3.12+
• FFmpeg e MediaInfo/libmediainfo per l'analisi e il remux video
• opzionale: Ollama con un modello vision per il fallback locale
• per l'app: Xcode su macOS

Esempio macOS:

brew install ffmpeg libmediainfo
# opzionale
brew install ollama
ollama pull gemma3:12b

Installazione della CLI

Da un clone della monorepo:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
clipper --help

In alternativa, senza installare il pacchetto:

python -m pip install -r cli/requirements.txt
python cli/clipper.py --help

Il pacchetto espone il comando clipper; python -m cli e python cli/clipper.py restano supportati.

Configurazione locale

Non versionare mai configurazioni reali, credenziali, registri o media. Il repository ignora già config.yaml, processed.json, ambienti virtuali, cache e dati locali.

cp cli/config.example.yaml cli/config.yaml
# compilare cli/config.yaml con valori locali, senza committarlo

Esempio minimo (valori fittizi):

paths:
  inbox: "./data/inbox"
  library: "./data/library"
  temp_frames: "./data/tmp-frames"
  processed_log: "./processed.json"

ollama:
  base_url: "http://127.0.0.1:11434"
  timeout: 120

models:
  vision: ""  # vuoto = fallback vision disabilitato

igdb:
  client_id: ""
  client_secret: ""

fireshare:
  url: "https://example.invalid"
  username: ""
  password: ""

Usa percorsi espliciti quando esegui da una directory diversa dalla root:

clipper --config cli/config.yaml --processed-log ./processed.json --dry-run

Uso

clipper --help
clipper --dry-run
clipper --list-processed
clipper --from 2025-06-01 --to 2025-06-30
clipper --game "Nome Gioco"
clipper --reprocess
clipper --fix "Nome errato" "Nome corretto"

La CLI cerca la configurazione in cwd, nella root della monorepo e in cli/. Gli override --config e --processed-log hanno precedenza e devono restare coerenti tra lettura e scrittura.

Test

I test usano file sintetici e mock; non richiedono Fireshare, Jellyfin, IGDB, Ollama o media reali.

python -m unittest discover -v -s cli/tests

La suite iOS presente è tecnica e in larga parte composta da test placeholder: la build e i test confermano l'integrazione del progetto, non una copertura funzionale completa.

App iOS/iPadOS

Aprire apps/ios/ClipperApp.xcodeproj con Xcode oppure compilare dalla riga di comando:

xcodebuild \
  -project apps/ios/ClipperApp.xcodeproj \
  -scheme ClipperApp \
  -configuration Debug \
  -destination 'generic/platform=iOS' \
  CODE_SIGNING_ALLOWED=NO \
  build

Il nome visualizzato agli utenti dell'app è Clip Stack. Restano invariati il progetto Xcode ClipperApp, il repository tecnico Clipper, il bundle identifier, il package Python e gli identificatori persistenti.

L'app conserva localmente l'URL del server e le credenziali nel Keychain. Non inserire credenziali nei file di progetto o nelle risorse versionate.

AppIcon

I 46 PNG legacy restano locali, ignorati e non versionati. L'asset originale A «Clip Stack» è integrato dal master SVG approvato: il catalogo Xcode usa un'unica immagine iOS 1024×1024 senza alpha e i file di provenienza sono in apps/ios/AppIconSource/. La build pulita e il controllo actool sono PASS; dettagli in docs/design/APPICON-INTEGRATION.md.

Licenza e componenti di terzi

Il codice originale Clipper e l'AppIcon originale A «Clip Stack» sono distribuiti sotto licenza MIT, con intestazione Copyright (c) 2026 Simone Gatti; il testo è in LICENSE.

La licenza riguarda i sorgenti, la documentazione originale, il master ClipStack.svg e il raster ClipStack-1024.png. Non copre i 46 PNG AppIcon legacy, le dipendenze Python, gli strumenti di sistema, gli SDK Apple, i servizi esterni, i modelli o i marchi. Vedere THIRD_PARTY_NOTICES.md.

Sicurezza

• Non committare config.yaml, processed.json, .env, media, credenziali, certificati o output di build.
• Non eseguire upload o modifiche su servizi reali durante i test.
• La scansione dei soli file staged non equivale alla scansione della cronologia Git.
• Il primo commit Clean Genesis e la pubblicazione su GitHub sono stati completati. Per gli aggiornamenti successivi verificare diff, privacy e licenze senza riscrivere la cronologia; vedere docs/operations/CLEAN-GENESIS.md.