Skip to content

replit.md

Latest commit

 

History

History
88 lines (67 loc) · 4.86 KB

replit.md

File metadata and controls

88 lines (67 loc) · 4.86 KB
Raw

AI Movie Explanation Video Generator (Level 5)

A full-stack Flask web app that converts movie subtitles → AI-enriched scenes → storytelling script → live FFmpeg video generation (Level 5). Built on a 4-layer AI architecture: Core Engine / AI Brain / Control Center / AI Router (OpenAI key pool with auto-failover). No paid APIs required — Ollama optional, rule-based fallback always available.

Run & Operate

  • python main.py — run Flask app on port 8080
  • Required: Python 3 + Flask + requests (pip install requests)
  • Optional: OpenAI keys via env vars (see below), Ollama at http://localhost:11434
  • FFmpeg 6.1.2 available at /nix/store/.../bin/ffmpeg — detected automatically

Stack

  • Python 3, Flask, Jinja2 templates
  • Pure CSS dark glassmorphism — no external CSS frameworks
  • Architecture: CoreEngine / AIBrain / ControlCenter / AIRouter + PipelineEngine + AIHub logging
  • subprocess for FFmpeg execution, requests for OpenAI HTTP calls

Where things live

  • main.py — Flask routes + Levels 1–5 pipeline orchestration (12 logged stages)
  • core_engine.py — Layer 1: deterministic subtitle parsing + scene building (no AI)
  • ai_brain.py — Layer 2: observation, analysis, suggestion engine (advisory only)
  • control_center.py — Layer 3: governance, auto-approve/reject, temporary overrides
  • ai_router.py — Level 4: OpenAI key pool, auto-failover, cooldown tracking, usage stats
  • ai_hub.py — central logger; session logs at uploads/<id>/hub_log.json
  • ai_engine.py — LLM priority chain: OpenAI (via router) → Ollama → rule-based
  • scene_parser.py — Level 5: parses [MM:SS - MM:SS] narration format → structured scene list
  • pipeline_engine.py — Level 5: orchestrates script gen → scene parse → FFmpeg execution
  • video_pipeline.py — Shell script generator (Level 3) + live FFmpeg execution (Level 5)
  • modules/ — srt_parser, scene_builder, script_generator (shim), ffmpeg_generator, exporter
  • templates/ — base, upload, dashboard, scenes, script_view, video_pipeline, download
  • uploads/<id>/output/ — timestamped_script.txt, video_pipeline.sh, clips/, final_video.mp4

Architecture decisions

  • Layer 1 (CoreEngine): pure deterministic — zero AI logic, immutable
  • Layer 2 (AIBrain): advisory only — returns suggestions, never modifies data directly
  • Layer 3 (ControlCenter): auto-approves non-destructive; rejects delete/merge/reorder
  • Level 4 (AIRouter): LRU key selection; cooldown 90s rate-limits, 300s auth errors; 5-key retry
  • Level 5 (PipelineEngine): script gen (OpenAI→Ollama→rule-based) → scene_parser → FFmpeg -c copy (no re-encode); clean fallback states: no_movie / no_ffmpeg / error / complete
  • Security: API keys stored in env vars only; masked as sk-...XXXX in all UI/logs
  • Session data in uploads/<uuid>/data.json — no database

Product

  1. Upload (/) — movie title, optional video file, SRT or pasted text
  2. Dashboard (/dashboard/<id>) — 12-stage pipeline timeline, AI Router key pool panel, Brain + Control Center logs
  3. Scenes (/scenes/<id>) — emotion badges, narrative role labels, importance rings
  4. Script (/script/<id>) — Level 2 narration with emotion tags, copy buttons
  5. Video Pipeline (/video/<id>) — AI timestamped script, parsed scenes, live FFmpeg clip cutting + merging, download final_video.mp4
  6. Download (/download/<id>) — ZIP with shell scripts + all exports

API endpoints

  • GET /api/router/status — live key pool status (JSON, keys masked)
  • POST /api/router/reload — force re-read of env vars + reload pool
  • POST /video/<id>/generate — trigger Level 5 pipeline
  • GET /video/<id>/download — stream final_video.mp4

OpenAI key configuration

Set any of these Replit Secrets (priority order):

  • OPENAI_KEY_1, OPENAI_KEY_2, ... OPENAI_KEY_10 — individual keys
  • OPENAI_API_KEYS — comma-separated list
  • OPENAI_API_KEY — single legacy key

User preferences

  • Beginner-friendly comments throughout
  • No database, no paid/external APIs required
  • Modular architecture (one file per concern)

Gotchas

  • pnpm monorepo at root — Flask runs from root main.py; do NOT run pnpm dev
  • pip install requests needed for ai_router.py
  • FFmpeg uses -c copy (stream copy, no re-encode) for fast clip cutting
  • _fmt() in pipeline_engine.py must produce MM:SS (no decimals) to match scene_parser regex
  • pipeline_status dict keys from ai_hub.get_pipeline_status() may be int or str — dashboard handles both
  • uploads/<id>/output/clips/ created per session during video generation

Pointers

  • ai_router.py — source of truth for key pool logic
  • scene_parser.py — source of truth for timestamp parsing regex
  • pipeline_engine.py — source of truth for Level 5 orchestration flow
  • ai_hub.py — source of truth for all pipeline logging