docs: add MVLog server-side push & Gemini generator docs; fix intro logo alpha

README.md

@@ -313,6 +313,53 @@ Security notes
 
 If you want deployment automation, alternative flows (worker-based sender or token-protected endpoint), or I should add a short admin checklist, tell me and I will update the docs.
 
+Server-side push and Gemini generator (MVLog integration)
+
+This repository includes light integration notes for the MVLog web server used in my local workflow. Two server-side helpers are deployed under the web root to keep sensitive keys on the server and to provide immediate, authenticated actions:
+
+- Server-side web-push (notifications)
+  - The web UI triggers a server-side send when an authenticated admin enables the "Show" checkbox for a job. This keeps VAPID private keys on the webserver and avoids exposing them to worker nodes.
+  - Key files and helper scripts (deployed under /var/www/html/mvlog):
+    - lib/send_push.php — PHP helper that invokes the Node sender and atomically records send state.
+    - send_push.js — Node script (uses the web-push package) to send individual pushes.
+    - cache/push_subscriptions.json — stored subscriber list (array of subscription objects).
+    - cache/push_notifications.json — recorded sends ("shown" map) to avoid duplicate notifications.
+    - /etc/mvlog/push.php or /var/www/html/mvlog/push.json — VAPID key holder (private key must remain secret; set owner to root or www-data and permissions to 600/640).
+  - Installation notes:
+    - npm install web-push --prefix /var/www/html/mvlog
+    - Ensure cache/ files exist and are writable by the webserver (www-data).
+    - Keep logs in /var/log/mvlog_notify.log and grant the webserver write access.
+  - Security:
+    - api/enable_show.php requires admin login and the UI uses server-side calls; do not expose the endpoint without auth.
+    - Consider CSRF protection, rate limiting, and periodic pruning of expired subscriptions (HTTP 410 responses).
+
+- Gemini-based description generator
+  - Purpose: analyze an input directory (images/videos) and produce a short JSON description suitable for MVLog and movmaker metadata.
+  - Script location: /var/www/html/mvlog/bin/generate_data.sh
+  - What the script does:
+    - Collects up to N representative frames from the input media (images produce one frame each; videos up to 3 frames depending on duration).
+    - Builds a single multipart JSON request with the prompt and inline base64-encoded frames (the request is assembled with a small Python helper to avoid ARG_MAX issues).
+    - Calls the Google Generative Language (Gemini) API via curl and saves the raw response text as <inputdir>/gemini_generated.json for review.
+    - Appends a Description block to <inputdir>/data.txt only if data.txt does NOT already contain a Description key. It appends/creates only the Description block and does not modify any other keys or lines.
+    - gemini_generated.json is retained as-is for manual inspection.
+  - Output files:
+    - <inputdir>/gemini_generated.json — raw JSON produced by Gemini (always written).
+    - <inputdir>/data.txt — the script will append a "Description: |\n  ..." block only if no Description exists yet (case-insensitive match). If data.txt is absent it will be created with the Description block only.
+  - Configuration / environment:
+    - GEMINI_API_KEY should be set in /etc/mvlog/gemini.env (recommended permissions: owner root:www-data, mode 640). The webserver runs the script as www-data so this file must be readable by www-data.
+    - Required tools on the webserver: jq, python3, ffmpeg, ffprobe, curl.
+  - Typical invocation (run as the webserver user so ownership/permissions behave correctly):
+
+    sudo -u www-data /var/www/html/mvlog/bin/generate_data.sh /var/www/html/mvlog/in-dir/20230630_napoli "Naples" "Naples, Italy" 8
+
+    Arguments are: <input-dir> ["Title"] ["Location"] [max_frames]
+  - Error notes and troubleshooting:
+    - If Gemini returns HTTP 429 RESOURCE_EXHAUSTED, check that GEMINI_API_KEY is tied to a project with billing and that the Generative Language API quotas are enabled.
+    - The script uses a Python builder to avoid "Argument list too long" errors when embedding images; if you see jq errors referring to ARG_MAX, ensure you have the deployed version of generate_data.sh (the script in bin/ uses the Python builder).
+    - Run the script as www-data to avoid permission problems reading /etc/mvlog/gemini.env and to create files owned by the webserver.
+
+If you want this README split into a separate docs/ file or want me to add a short operational checklist for admins (quota checks, key install, testing steps), tell me and I will add it.
+
 ## Automated Gemini description generator (generate_data.sh)
 
 Location: /var/www/html/mvlog/bin/generate_data.sh

movmaker.py

@@ -43,7 +43,7 @@ LOG_PATH: Path | None = None
 INTRO_LOGO_TARGET_HEIGHT_RATIO = 0.99
 INTRO_LOGO_EXTRA_HOLD = 6.0
 INTRO_LOGO_FADE_OFFSET = 3.0
-INTRO_LOGO_DEFAULT_ALPHA = 0.50
+INTRO_LOGO_DEFAULT_ALPHA = 0.25
 INTRO_TITLE_START_OFFSET = 0.0
 INTRO_TITLE_FADE_LENGTH = 1.0
 INTRO_TITLE_VISIBLE = 9.0