Citation Analyzer

Transcribe video (Whisper) and attribute philosopher citations (Gemini). Writes one monolithic note per philosopher into your ZenNotes citations/ folder (or any OUTPUT_DIR).

Package path stays video_extractor for import stability. User-facing name: Citation Analyzer.

Entry point: video_analyser.py from the repo root (no PYTHONPATH needed).

Output format

One file per philosopher under OUTPUT_DIR (Docker: ZenNotes citations/):

Machiavelli.md
Machiavelli.citations.json   # optional sidecar (array of analyses)
Nietzsche.md
Unattributed.md              # mixed / unknown / no philosopher

Each new extraction appends a delimited section:

## Citation: Power Strategy

- **Date:** …
- **Work / source:** The Prince
- **Confidence:** high

> Attribution: **Niccolò Machiavelli** / The Prince (high)

### Analysis
…

### Discrete quotes
…

### Transcript

full text

Sections separated by ---. Topic comes from Gemini category slug. Unknown attribution → Unattributed.md.

Migrate legacy {Philosopher} — {Topic}.md files:

.venv/bin/python video_analyser.py merge-notes -o /path/to/zennotes/citations

Set OUTPUT_DIR to change the root.

Setup

1. ffmpeg — brew install ffmpeg
2. Python — venv + deps:

   python3 -m venv .venv
   .venv/bin/pip install -r requirements.txt
   

3. Gemini API key — aistudio.google.com/apikey:

   export GEMINI_API_KEY=your-key
   # or put GEMINI_API_KEY in .env
   

CLI

.venv/bin/python video_analyser.py extract video.MP4
.venv/bin/python video_analyser.py extract "https://www.tiktok.com/..." -o ./transcripts
.venv/bin/python video_analyser.py analyze transcript.md
.venv/bin/python video_analyser.py analyze --url "https://www.tiktok.com/..."
.venv/bin/python video_analyser.py run video.MP4
.venv/bin/python video_analyser.py web

Option	Description
-o, --output-dir	Output folder (default ./output)
-m, --model	Whisper: tiny…large
-r, --recursive	Scan dirs recursively
--no-auto-category	Skip Gemini category slug

Web UI

Tabbed inputs: Video | URL | Batch | Text. Results show attribution, confidence, expandable transcript, path to saved note, ZIP download of the .md (+ JSON sidecar).

.venv/bin/python video_analyser.py web
# http://127.0.0.1:8000

Public deploy: https://citations.tessdev.fr (hostname unchanged).

Auth: NPM forward auth via Authentik (authentik.tessdev.fr). Unauthenticated visitors hit Authentik login, then return. /health stays open for probes. Snippet: deploy/npm-authentik-advanced.conf. App + Proxy Provider live in Authentik as Citation Analyzer (Embedded Outpost).

Docker

Multi-stage image with CPU-only PyTorch (no CUDA wheels — keeps size ~1GB instead of ~6GB).

export GEMINI_API_KEY=your-key
docker compose up -d --build

• Volume: host ZenNotes citations/ → /app/output
• Port: 8000
• Runs as UID 65532 (matches ZenNotes vault ownership)
• Env: GEMINI_API_KEY, OUTPUT_DIR=/app/output

docker compose run --rm -v /path/to/videos:/input app \
  python video_analyser.py extract /input -o /app/output

Requirements

• ffmpeg, Python 3.10+, yt-dlp (in requirements.txt)
• GEMINI_API_KEY — optional for extract category; required for citation analysis