PTENES
Claude Code skill + Python package (vpe)

A topic or link becomes a professional video editing plan

You provide a topic or a link (page/video). The skill detects the type, decides on the best editing action, chooses a preset, and outputs plano-edicao.json + RESUMO.md — structured data, renderer-agnostic. Optional rendering already works: motion graphics + flux2-klein b-roll, local, no API key.

Start the guide View on GitHub 
# from input to plan
input → detect → analyze → best action
      → preset → PLANO (json + resumo)
      → (opcional) render → MP4

# quick start
vpe scaffold "como fazer pão caseiro" --preset viral \
    > plano-edicao.json
vpe validate plano-edicao.json   # guardrails
vpe resumo   plano-edicao.json   # to approve
What it is

The layer that decides what to edit

Programmatic editing is fragmented (FFmpeg, Auto-Editor, MoviePy, Remotion, HyperFrames). What’s missing is a layer that decides what to do from natural language and outputs a clean, portable plan. That’s what this is.

🧠 Choose the action

Classifies the input as topic, page or video, analyzes the best editing action and records why in best_action_rationale.

📄 Renderer-agnostic plan

EditPlan in JSON (pydantic) + RESUMO.md readable. It can be consumed by FFmpeg, HyperFrames, Remotion, or other systems.

🎬 Rendering that already works

Motion graphics via HyperFrames + b-roll generated with flux2-klein. Local, deterministic, no API key.

How it works

From input to MP4

5 style presets (action · smooth · promo · sales · viral) are parameter profiles for same schema — changing the preset changes pacing, transitions, soundtrack, captions, and aspect ratio without rewriting the base plan.

input→ detect→ ingest + analyze→ best action→ style preset→ PLAN (json + summary)→ render (optional)
Prerequisites

What you need to run it

The core (plan generation) is just Python. Rendering is optional and requires the local motion graphics stack.

🐍 Python ≥ 3.11

Install in editable mode; exposes the console script vpe.

python3 -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"

🤖 Claude Code

The skill orchestrates vpe and fills the creative timeline using natural language.

# https://claude.com/claude-code

🎬 Rendering stack (optional)

For rendering only: HyperFrames (Chrome+FFmpeg), Kokoro (voiceover), and flux2-klein (b-roll).

# see knowledge/render.md
User guide · step by step

From topic to approved plan

Real commands for vpe. The skill (via SKILL.md) fills the timeline between the scaffold and validation.

1

Install the package

Creates the environment and exposes the command vpe.

pip install -e ".[dev]"  # exposes `vpe`
2

Generate the plan outline

vpe detects the input (topic/page/video) and applies the selected preset.

vpe scaffold "como fazer pão caseiro" --preset viral > plano-edicao.json
3

The skill fills in the timeline

Script/scenes for a topic or page; source_in/out (real cuts) for video. See examples/.

# timeline: hook → point → ... → cta (each beat with headline/narration/caption)
4

Validate the guardrails

Reset the [error] before any rendering (empty timeline, no hook, etc.).

vpe validate plano-edicao.json  # exit 0 = ok
5

Generate the approval summary

Readable document with source, objective, preset, and a beat-by-beat timeline. Rendering is optional, on request.

vpe resumo plano-edicao.json > RESUMO.md
Examples

Actual vpe output

Complete sample plan in examples/exemplo-viral-pao.json.

📦 scaffold — viral preset applied

// vpe scaffold "https://youtu.be/..." --preset viral
"source": { "kind": "video", ... },
"style": {
  "preset": "viral",
  "pacing": { "avg_cut_seconds": 1.1, "energy": 0.95 },
  "captions": { "style": "karaoke" }
},
"output": { "aspect": "9:16", "duration_target_seconds": 30 }

YouTube input classified as video; preset applied ~1.1s cuts, karaoke captions, and 9:16. The timeline starts empty.

📝 summary — ready for approval

# Homemade bread in 20s
- Objetivo: viral
- Preset: viral (corte ~1.1s, energia 0.95)
- Saída: 9:16, alvo 20s

1. hook  Headline: Pão em 20 segundos?!
2. point Headline: 3 ingredientes
3. cta   Headline: INEMA.CLUB

The same plan becomes readable Markdown with a beat-by-beat timeline.

Roadmap

What works now and what’s coming

Plan schema: meta · source · intent · style · output · timeline[] · render. Integrates with MDD for the cinematic direction of generative beats.

✅ Ready
Plan generation coreSchema (pydantic), presets, detect, validation, summary, CLI vpe. 35 tests.
✅ Ready
Knowledge basestrategy / camera / storyboard / prompting / motion / archetypes — with MDD principles distilled.
✅ Ready
Motion graphics + b-roll renderingHyperFrames (Chrome+FFmpeg) + flux2-klein b-roll, local and deterministic. Reference case: hormozi13 in 9:16 and 16:9.
⏳ Next
Real footage ingestionyt-dlp + ffprobe + transcription + silence/scene-based cuts (Auto-Editor) + auto-highlights.
⏳ Future
Generative clips + Remotion / OTIOSora/Veo/Kling directed by MDD; native Remotion rendering and export .otio for NLEs.