From 0183b86031a601426b7ec2ee82db5d43553a33ff Mon Sep 17 00:00:00 2001 From: hbrain Date: Fri, 29 May 2026 07:52:03 +0000 Subject: [PATCH] docs: add MVLog server-side push & Gemini generator docs; fix intro logo alpha --- README.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ movmaker.py | 2 +- 2 files changed, 48 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index c595397..d00ed86 100644 --- a/README.md +++ b/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 /gemini_generated.json for review. + - Appends a Description block to /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: + - /gemini_generated.json — raw JSON produced by Gemini (always written). + - /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: ["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 diff --git a/movmaker.py b/movmaker.py index 9326805..04fb6c5 100755 --- a/movmaker.py +++ b/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