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

README.md

@@ -312,3 +312,96 @@ Security notes
 - Consider adding CSRF protection, rate limiting, and periodic pruning of expired subscriptions (HTTP 410 responses).
 
 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
+
+Purpose:
+
+- Produce a short human-style description (plus teaser/tags in the raw AI output) for an MVLog input job by sending sampled frames to Google's Gemini model.
+- Save the raw AI output to <inputdir>/gemini_generated.json (preserved for review).
+- If the job's data.txt does not already contain a Description: entry, append a Description block to data.txt and leave all other lines untouched. If data.txt doesn't exist the script will create it with the Description block only.
+- The script never overwrites an existing Description and does not modify gemini_generated.json.
+
+Dependencies & configuration:
+
+- ffmpeg and ffprobe (for extracting frames)
+- jq (for small JSON extraction tasks)
+- python3 (used to build the request payload and avoid argument-list limits)
+- A valid GEMINI API key available in the environment as GEMINI_API_KEY. Recommended placement:
+
+  - Create /etc/mvlog/gemini.env containing: export GEMINI_API_KEY='YOUR_KEY_HERE'
+  - Set owner root:www-data and mode 640 so the webserver (www-data) can source it without exposing the key in git.
+
+How the script works (high level):
+
+1. Collects image/video files from the input directory and extracts scaled JPEG frames (images → 1 frame each; videos → 1–3 frames depending on duration and remaining slots).
+2. Builds a generateContent request that embeds the frames as base64 "inline_data" parts and includes a short prompt describing the expected JSON format.
+3. Calls the Gemini REST API (model defaults to gemini-2.0-flash) and writes the AI response JSON to <inputdir>/gemini_generated.json.
+4. Extracts the "description" field from the AI JSON. If data.txt exists and already contains a Description: key (case-insensitive), the script does nothing to data.txt. Otherwise it appends a YAML-style block scalar to data.txt:
+
+   Description: |
+     <two-space indented description text>
+
+   If data.txt does not exist the script will create it containing only the Description: block.
+
+Notes, running and troubleshooting:
+
+- Run as the webserver user so file ownership is correct:
+
+  sudo -u www-data /var/www/html/mvlog/bin/generate_data.sh /var/www/html/mvlog/in-dir/20230630_napoli "Naples" "Naples, Italy" 8
+
+- If the GEMINI API key has no quota or billing is not enabled, the API will return 429 RESOURCE_EXHAUSTED and no description will be written. The raw gemini_generated.json will contain the error response.
+- Ensure /var/www/html/mvlog/in-dir/<job> is owned/writable by www-data; the script writes gemini_generated.json and may append to data.txt.
+- Install jq if missing: sudo apt install jq
+- The script intentionally preserves the full Gemini output (gemini_generated.json) so you can review and re-run manually if needed. If you prefer the old behavior (write a separate data_gemini.txt instead) or want additional fields appended (teaser/tags), say so and I will update the script and docs.
+
+

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