[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-1023":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":15,"stars7d":16,"stars30d":17,"stars90d":14,"forks30d":14,"starsTrendScore":13,"compositeScore":18,"rankGlobal":9,"rankLanguage":9,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":20,"topics":23,"createdAt":9,"pushedAt":9,"updatedAt":24,"readmeContent":25,"aiSummary":26,"trendingCount":14,"starSnapshotCount":14,"syncStatus":16,"lastSyncTime":27,"discoverSource":28},1023,"agentic-video-editor","poseljacob\u002Fagentic-video-editor","poseljacob","AI-powered video editor that turns raw footage and a creative brief into a polished ad using an ensemble of AI agents (Google Gemini + FFmpeg)",null,"Python",436,55,3,0,1,2,26,50.84,"MIT License",false,"main",true,[],"2026-06-12 04:00:07","# Agentic Video Editor\n\nA command-line AI video editor that turns raw footage and a creative brief into a polished ad. Point `ave` at a folder of clips, describe what you want, and an ensemble of AI agents handles the rest -- scene detection, shot selection, assembly, and quality review.\n\nBuilt with Google Gemini for intelligence and FFmpeg for rendering.\n\n> **Status:** The CLI is the primary, supported interface. A web UI (AVE Studio) is included but is a **work in progress** -- see [Web UI](#web-ui-work-in-progress) below.\n\n## How It Works\n\n```\nRaw Footage + Creative Brief\n        |\n   [ Preprocess ]  -- scene detection, transcription, shot indexing\n        |\n   [ Director ]    -- AI agent picks shots, orders them, writes an EditPlan\n        |\n   [ Trim Refiner ] -- refines shot boundaries for tight cuts\n        |\n   [ Editor ]      -- renders the EditPlan to video via FFmpeg\n        |\n   [ Reviewer ]    -- scores the output (adherence, pacing, visual quality, watchability)\n        |              if score \u003C threshold, feeds back to Director and retries\n        v\n   Final Video + Review Scores\n```\n\n### Agents\n\n| Agent | Role | Powered By |\n|-------|------|------------|\n| **Director** | Searches the footage index, selects shots, and produces an `EditPlan` with trimming, ordering, and text overlays | Google Gemini via ADK |\n| **Trim Refiner** | Adjusts start\u002Fend trim points for tighter cuts | Gemini |\n| **Editor** | Renders the EditPlan to an MP4 using FFmpeg\u002FMoviePy | FFmpeg |\n| **Reviewer** | Watches the rendered video and scores it on 5 dimensions (0-1 scale) | Gemini |\n\n### Pipeline System\n\nPipelines are defined as YAML manifests in `pipelines\u002F`. Each step names an agent and optionally a gate or retry condition:\n\n```yaml\n# pipelines\u002Fugc-ad.yaml\nsteps:\n  - agent: director\n  - agent: trim_refiner\n  - agent: editor\n  - agent: reviewer\n    retry_if:\n      metric: overall\n      threshold: 0.65           # retry if overall score \u003C 0.65\n      max_retries: 2            # up to 2 retries (3 total passes)\n      feedback_target: director # send reviewer feedback back to director\n```\n\nEach retry iteration is saved as `{name}_v{N}.mp4` so you can compare versions.\n\n### Style Templates\n\nStyle files in `styles\u002F` give the Director structured guidance -- segment durations, pacing rules, text overlay placement, and music mood. The included `dtc-testimonial.yaml` defines a 30-second DTC ad structure (hook, problem, solution, social proof, CTA).\n\n## Setup\n\n### Prerequisites\n\n- Python 3.11+\n- FFmpeg installed and on PATH\n- A [Google AI API key](https:\u002F\u002Faistudio.google.com\u002Fapikey) (for Gemini)\n\n### 1. Clone and install\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fposeljacob\u002Fagentic-video-editor.git\ncd agentic-video-editor\n\npython -m venv .venv\nsource .venv\u002Fbin\u002Factivate   # or .venv\\Scripts\\activate on Windows\npip install -e \".[dev]\"\n```\n\nOr with [uv](https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002F):\n\n```bash\nuv sync\nsource .venv\u002Fbin\u002Factivate\n```\n\n### 2. Set up your API key\n\n```bash\ncp .env.example .env\n# Edit .env and add your Google AI API key\n```\n\n### 3. Verify FFmpeg\n\n```bash\nffmpeg -version\n```\n\nIf not installed: `brew install ffmpeg` (macOS), `apt install ffmpeg` (Ubuntu), or [download](https:\u002F\u002Fffmpeg.org\u002Fdownload.html).\n\n## Usage\n\nThe primary interface is the `ave` CLI. A single command takes you from raw footage to a finished cut.\n\n### Basic run\n\n```bash\nave edit \\\n  --footage-dir \u002Fpath\u002Fto\u002Fyour\u002Ffootage \\\n  --brief '{\"product\": \"My Product\", \"audience\": \"Women 25-45\", \"tone\": \"authentic\", \"duration_seconds\": 30}' \\\n  --pipeline pipelines\u002Fugc-ad.yaml \\\n  --style styles\u002Fdtc-testimonial.yaml\n```\n\nThe brief can also be a path to a JSON file:\n\n```bash\nave edit --footage-dir .\u002Ffootage --brief brief.json\n```\n\n### What happens on a run\n\n1. **Preprocess** -- scans your footage folder, detects scenes, transcribes speech, and writes a `footage_index.json`. Cached between runs.\n2. **Director** -- searches the index and produces an `EditPlan` (ordered shots with trim points and text overlays).\n3. **Trim Refiner** -- tightens each cut.\n4. **Editor** -- renders the plan to MP4 via FFmpeg\u002FMoviePy.\n5. **Reviewer** -- scores the output across 5 dimensions; if below threshold, loops back to the Director with feedback.\n\nOutput lands in `output\u002F` with versioned copies for each retry iteration.\n\n### Creative Brief Schema\n\n```json\n{\n  \"product\": \"Product name\",\n  \"audience\": \"Target demographic\",\n  \"tone\": \"energetic, calm, professional, etc.\",\n  \"duration_seconds\": 30,\n  \"style_ref\": \"styles\u002Fdtc-testimonial.yaml\"\n}\n```\n\n### Review Scores\n\nThe Reviewer agent scores each output on five dimensions (0.0 - 1.0):\n\n- **Adherence** -- does the edit follow the brief?\n- **Pacing** -- are shot durations and energy levels well balanced?\n- **Visual Quality** -- are cuts clean, transitions smooth?\n- **Watchability** -- would a viewer watch to the end?\n- **Overall** -- composite score\n\n### Custom Pipelines\n\nCreate a YAML file in `pipelines\u002F`:\n\n```yaml\nname: my-pipeline\nsteps:\n  - agent: director\n  - agent: editor\n  - agent: reviewer\n    retry_if:\n      metric: overall\n      threshold: 0.7\n      max_retries: 3\n```\n\nAvailable agents: `director`, `trim_refiner`, `editor`, `reviewer`.\n\n### Custom Styles\n\nCreate a YAML file in `styles\u002F` with segment structure, text overlay rules, music mood, and pacing guidance. See `styles\u002Fdtc-testimonial.yaml` for the full format.\n\n### Running Tests\n\n```bash\npytest tests\u002F\n```\n\n## Architecture\n\n```\nsrc\u002F\n  main.py        -- CLI entry point (`ave edit`)\n  agents\u002F        -- Director, Editor, Reviewer, TrimRefiner (Google ADK)\n  models\u002F        -- Pydantic schemas (CreativeBrief, Shot, EditPlan, ReviewScore)\n  pipeline\u002F      -- Preprocessing (scene detection + transcription) and pipeline runner\n  tools\u002F         -- Gemini tool functions (analyze footage, render, captions)\n  web\u002F           -- Optional FastAPI backend + Next.js frontend (work in progress)\n```\n\n## Web UI (Work In Progress)\n\nAn experimental web UI, **AVE Studio**, lives in `src\u002Fweb\u002F`. It wraps the same pipeline behind a FastAPI backend and a Next.js frontend styled as a traditional non-linear editor (project picker, source\u002Fprogram monitors, drag-and-drop timeline, media browser, inspector, review radar chart).\n\n**This is pre-alpha and not the recommended way to use the project yet.** Expect rough edges, missing features, and breaking changes. The CLI is the supported path.\n\nIf you want to try it anyway:\n\n```bash\n# Prerequisites: Node.js 18+ and pnpm\n\n# Install frontend deps\ncd src\u002Fweb\u002Fstudio\npnpm install\ncd ..\u002F..\u002F..\n\n# Terminal 1: FastAPI backend\nsource .venv\u002Fbin\u002Factivate\nuvicorn src.web.app:app --reload --port 8000\n\n# Terminal 2: Next.js frontend\ncd src\u002Fweb\u002Fstudio\npnpm dev --port 3000\n```\n\nThen open http:\u002F\u002Flocalhost:3000.\n\nThe backend exposes a REST API at `http:\u002F\u002Flocalhost:8000` (jobs, projects, footage, feedback, edit plan CRUD) plus a `\u002Fws\u002Fjobs\u002F{id}` WebSocket for real-time progress. See `src\u002Fweb\u002Froutes\u002F` for the full endpoint list.\n\n## Project Structure\n\n```\nagentic-video-editor\u002F\n  .env.example          # API key template\n  pyproject.toml        # Python project config\n  pipelines\u002F            # Pipeline YAML manifests\n    ugc-ad.yaml\n  styles\u002F               # Style templates\n    dtc-testimonial.yaml\n  src\u002F\n    main.py             # CLI entry point\n    agents\u002F             # AI agents (Director, Editor, Reviewer, TrimRefiner)\n    models\u002F             # Pydantic data models\n    pipeline\u002F           # Preprocessing + pipeline runner\n    tools\u002F              # Gemini tool functions\n    web\u002F                # Experimental web UI (WIP)\n      app.py            # FastAPI application\n      jobs.py           # Background job registry\n      routes\u002F           # REST API endpoints\n      studio\u002F           # Next.js frontend\n  tests\u002F                # Test suite\n```\n\n## License\n\nMIT\n","Agentic Video Editor 是一个基于AI的视频编辑工具，能够将原始视频片段和创意简报转化为精美的广告。该项目利用Google Gemini提供智能处理，包括场景检测、镜头选择、剪辑计划生成等，并通过FFmpeg进行最终渲染。其核心功能包括自动化的预处理、导演级镜头挑选与排序、精细化剪辑以及质量审查反馈机制，确保输出视频的质量符合预期标准。适用于需要快速高效地从大量素材中制作出高质量视频内容的场景，如广告制作、短视频创作等领域。","2026-06-11 02:41:10","CREATED_QUERY"]