Agentic Video Editor: a Gemini-directed ad pipeline on the ave CLI

The gap between a folder of clips and a finished 30-second cut

Cutting an ad from raw footage is mostly a selection problem wrapped in a timing problem. Someone has to watch the material, decide which shots carry the hook, the problem, the solution and the call to action, then trim each one so the cuts land. Agentic Video Editor targets that stage. You point the ave CLI at a footage directory and hand it a creative brief, and the project runs scene detection, transcription and shot indexing before an agent picks and orders the shots. The README frames the output as a polished ad, and the included style template dtc-testimonial.yaml defines a 30-second DTC structure with hook, problem, solution, social proof and CTA segments. The audience is narrow and specific: people who already have footage and a written brief, and who would rather iterate on a YAML pipeline than on a timeline. If you shoot and edit by hand because the selection is the creative work, this tool is aimed at the part you least want to do, which is also the part you may least want automated.

Four agents, one EditPlan, and a reviewer that can reject it

The pipeline is a chain with a loop at the end. Preprocessing scans the footage folder, detects scenes, transcribes speech and writes footage_index.json, which the README says is cached between runs. The Director agent then searches that index and produces an EditPlan: ordered shots with trim points and text overlays. A Trim Refiner adjusts start and end points for tighter cuts. The Editor renders the plan to MP4 through FFmpeg and MoviePy. Finally the Reviewer watches the rendered video and scores it on five dimensions between 0.0 and 1.0: adherence, pacing, visual quality, watchability, and an overall composite. The loop is the interesting part. If the overall score falls below the threshold in the pipeline manifest, the reviewer feedback is routed back to the Director and the run repeats, up to max_retries. Each iteration is saved as {name}_v{N}.mp4, so version comparison is a file-listing exercise rather than a manual export. The agents are built on Google ADK, and the Pydantic schemas in src/models (CreativeBrief, Shot, EditPlan, ReviewScore) are the contract between stages. That structure is the project's real claim: the edit is data before it is video, so it can be inspected, retried and diffed.

Pipelines and styles are where the editorial decisions actually live

The pipeline manifest is a YAML file in pipelines/. The README's ugc-ad.yaml lists four steps in order and attaches a retry condition to the reviewer step: metric overall, threshold 0.65, max_retries 2, feedback_target director. That means three total passes at most, and the threshold is a number you choose rather than a hidden default. A custom pipeline is the same shape with a name field, so swapping director, trim_refiner, editor and reviewer in or out is a file edit, not a code change. Style files in styles/ carry the other half of the direction: segment durations, pacing rules, text overlay placement and music mood. The distinction matters. The pipeline says which agents run and when to retry; the style says what a good cut looks like. If you tune one and not the other, you will get a pipeline that retries toward a target the Director has no structured guidance to hit. The brief schema carries product, audience, tone, duration_seconds and an optional style_ref, so the style can be named in the brief or passed as a flag. Two places to set the same thing is a small inconsistency, and the README does not say which wins.

Getting a run started: the commands and the config keys

Setup assumes Python 3.11 or newer, FFmpeg on PATH, and a Google AI API key. The README gives two install paths. With pip: python -m venv .venv, activate it, then pip install -e ".[dev]". With uv: uv sync followed by activating .venv. The API key goes in a .env file copied from .env.example. FFmpeg is verified with ffmpeg -version. The main command is ave edit, and the README's example passes --footage-dir, --brief, --pipeline pipelines/ugc-ad.yaml and --style styles/dtc-testimonial.yaml. The brief can be inline JSON or a path to a JSON file, as in ave edit --footage-dir ./footage --brief brief.json. Output lands in output/ with versioned copies per retry. Tests run with pytest tests/. The web studio, if you ignore the warning, needs Node.js 18+ and pnpm: pnpm install inside src/web/studio, then uvicorn src.web.app:app --reload --port 8000 in one terminal and pnpm dev --port 3000 in another, with a REST API on port 8000 and a /ws/jobs/{id} WebSocket for progress. The README states plainly that this path is pre-alpha and not recommended yet.

The reviewer scores a video, and that is a real constraint

The retry loop reads as automated quality control, but its input is the rendered MP4, not the plan. The Reviewer watches the output and scores it, which means every retry burns a full render plus at least one Gemini call, and the loop is bounded only by max_retries. Set that number high and you are paying for renders of edits the Director has already been told are wrong. There is a second cost the README does not address: preprocessing is cached, but the retry loop re-runs the Director, and the README does not state whether the Director is deterministic across passes. If it is not, a retry may change shots the reviewer never complained about, which makes the versioned {name}_v{N}.mp4 files harder to compare than they look. The scoring dimensions are also self-reported by a model watching its own pipeline's output, and the README gives no calibration data for what 0.65 means in practice. That number is a starting point, not a validated quality bar. The honest framing is that the reviewer is a gate, not a guarantee, and the threshold is a knob you will end up tuning by watching the outputs yourself.

Where a Gemini-dependent renderer is the wrong tool

Two failure modes are visible from the architecture. The first is offline or air-gapped work: the Director, Trim Refiner and Reviewer all run through Google Gemini, so no API key means no edit, and no network means no edit. A traditional non-linear editor has no such dependency. The second is precision. The Trim Refiner adjusts boundaries, but the granularity is whatever the plan and the model produce; if you need a cut on a specific frame, or a match cut timed to a beat, this pipeline is the wrong instrument. The web studio is a third limit rather than a feature: it is described as pre-alpha with rough edges, missing features and breaking changes, so anyone who needs a visual timeline today should treat the CLI as the whole product. There is also a licensing boundary worth naming. The project is MIT, which covers the code in the repository, but the Gemini calls are governed by Google's terms and the FFmpeg build you install carries its own licence depending on how it was compiled. The README does not discuss either, and it should not be read as doing so.

What you would use instead, and the actual difference

The nearest comparison is not another AI editor but the manual path: Adobe Premiere Pro, DaVinci Resolve, or any NLE, driven by a human editor with the same footage and brief. The difference is where the decision lives. In an NLE, shot selection and trim points are made by hand and stored in a project file you can scrub and adjust frame by frame; here they are stored in an EditPlan produced by an agent, and your adjustment mechanism is editing the style YAML, the brief, or the retry threshold and running again. That is a genuine trade: you give up frame-level control and gain a repeatable, versioned, text-defined process. A closer analogue on the automation side is scripted FFmpeg, where you write the filter graph yourself. That keeps everything local and deterministic, but you are back to hand-picking the shots, which is the task this project exists to remove. The honest position is that Agentic Video Editor sits between those two: more automated than a filter script, less controllable than an NLE, and dependent on a hosted model in a way neither of the others is.

Maintenance, versions, and what the repository does not tell you

The repository shows no retrieved releases, so there is no versioned artefact to pin against and no changelog to read before upgrading. Installation is from source via pip install -e . or uv sync, which means an upgrade is a git pull plus a reinstall, and the dependency surface includes Google ADK, MoviePy, FFmpeg, Pydantic and FastAPI. The last push recorded is 2026-04-14, so the project is active, but activity is not the same as a stable interface. The web layer is explicitly unstable, and the README does not state whether the pipeline YAML schema or the EditPlan model is considered frozen. Before adopting, check two things in the repository rather than in the README: whether src/models defines the EditPlan fields you need for your own tooling, and whether the style format in styles/dtc-testimonial.yaml covers the segment structure your brief implies. If either is missing, you are extending the project, not using it. The MIT licence lets you do that, but it also means the maintenance burden for your fork is yours.

Editorial conclusion

Adopt it if you already hold raw footage and want a repeatable, YAML-defined assembly pass where the reviewer threshold and retry count are explicit numbers you can tune. Do not adopt it if you need frame-accurate manual control, offline operation, or a stable web interface, because the studio in src/web is pre-alpha and the pipeline depends on Gemini calls. Before committing, run one brief through ave edit with max_retries set to 0 and inspect footage_index.json and the EditPlan the Director produces; if the shot selection is not usable at that stage, no amount of reviewer retries will fix it.

Official sources

1. Issues
2. License: MIT
3. poseljacob/agentic-video-editor on GitHub
4. README