video-to-template
Turn a reference video into a reusable, editable motion template. Bring your own model: any API key, a local model, or your coding agent.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/bertugbodur--video-to-template)HTML
<a href="/listings/bertugbodur--video-to-template"><img src="/api/listings/bertugbodur--video-to-template/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
You need Python 3.10+, FFmpeg, and (for rendering) Node.js 22+ with HyperFrames. `v2t setup` checks all of it and prints the install command for your system.
1. Command-line tool (everyone)
pipx install video-to-template # or: uv tool install video-to-template v2t setup # checks ffmpeg, Node and HyperFrames v2t auth login # pick a provider, enter your key (stored in the OS keychain) v2t make reference.mp4 # analysis -> template.json -> project -> preview.mp4 v2t fill reference-template --slots slots.json # same edit, your content
(Not on PyPI yet: until it is published, install from a clone with `pipx install .`.) Cloud SDKs are optional extras: `pipx install "video-to-template[anthropic]"`, `[openai]`, `[gemini]` or `[all]`. Ollama and OpenAI-compatible endpoints need nothing extra. From a checkout: `pip install -e ".[all,dev]"`.
HyperFrames: `npm install -g hyperframes`. Without it `v2t make` still writes `template.json`, `slots.json`, the project and `TEMPLATE.md`, then tells you how to render later. If only `npx` is available, `v2t` falls back to `npx --yes hyperframes` (the first render downloads it).
2. Claude Code plugin (no API key)
/plugin marketplace add bertugbodur/video-to-template /plugin install video-to-template@video-to-template
Then ask: *"make a template from reference.mp4"*. Claude reads the contact sheets itself and writes the interpretation; `v2t` validates it and continues. You still need the `v2t` command (path 1) installed.
3. Other agents (Codex CLI, Cursor, Gemini CLI, any SKILL.md-aware agent)
Copy [`skills/video-to-template/`](skills/video-to-template) into the agent's skills directory and install `v2t` (path 1). The skill drives agent mode:
v2t make reference.mp4 --provider agent --out my-template # exits with code 3 and writes analysis/agent-request/ # the agent reads INSTRUCTIONS.md and the images, writes interpretation.json v2t make --resume my-template # validates and continues
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 7 lines
- {
- "name": "video-to-template",
- "owner": { "name": "bertugbodur" },
- "plugins": [
- { "name": "video-to-template", "source": "./", "description": "Reference video in, reusable motion template out. Bring your own model." }
- ]
- }
README.md · README · 156 lines
- # video-to-template
- Turn a reference video into a **reusable, editable motion template**. `v2t` measures the edit (cuts, timing, camera moves, palette, rhythm), a model of *your* choice describes what is on screen, and the tool builds a [HyperFrames](https://github.com/heygen-com/hyperframes) project where text, colors and media are swappable **slots**. Edit `slots.json`, render the same edit with your own content.
- **Bring your own model:** a cloud API key, a local model (Ollama, fully offline), or the coding agent you already use (no key at all). Free, open source, MIT.
- ## Demo
- [`examples/demo/`](examples/demo) is built from an original 9-second clip made for this repo (no logos, no third-party content).
- | Reference | Template (default slots) | New variation |
- |---|---|---|
- | [`reference.mp4`](examples/demo/reference.mp4) | [`template/`](examples/demo/template) | [`variation.mp4`](examples/demo/variation.mp4) |
- | an original clip: push-in, pan, hard cuts | `template.json` + HyperFrames project | same edit, [`variation-slots.json`](examples/demo/variation-slots.json) |
- 
- *Left tile of each pair: reference. Right tile: render of the template.*
- On this demo the tool found both cuts at the exact frame and measured the camera moves from the reference (push-in about 1.12x, pan-right about 7.5% of the width). The render is an approximation: layer positions, glows and type are interpreted, so expect resemblance, not a pixel copy.
- ## How it works
- ```
- reference.mp4
- |
- v 1. Measure (Python, no model) cuts, camera moves, palette, rhythm, contact sheets
- v 2. Interpret (YOUR model) layers, typography, transition kinds -> JSON checked against a schema
- v 3. template.json measurements + interpretation merged and validated
- v 4. Generate (Python, no model) HyperFrames project, slots as variables
- v 5. Render + compare preview.mp4, comparison.png, cut-time and camera-direction report
- ```
- The model is used in step 2 only. Everything else is deterministic code. **Measured values** (cut times, durations, fps, camera moves) are never overwritten by the model; disagreements go to `notes`, and every interpreted item carries a `confidence`.
- ## Install
- You need Python 3.10+, FFmpeg, and (for rendering) Node.js 22+ with HyperFrames. `v2t setup` checks all of it and prints the install command for your system.
- ### 1. Command-line tool (everyone)
- ```bash
- pipx install video-to-template # or: uv tool install video-to-template
- v2t setup # checks ffmpeg, Node and HyperFrames
- v2t auth login # pick a provider, enter your key (stored in the OS keychain)
- v2t make reference.mp4 # analysis -> template.json -> project -> preview.mp4
- v2t fill reference-template --slots slots.json # same edit, your content
- ```
- (Not on PyPI yet: until it is published, install from a clone with `pipx install .`.) Cloud SDKs are optional extras: `pipx install "video-to-template[anthropic]"`, `[openai]`, `[gemini]` or `[all]`. Ollama and OpenAI-compatible endpoints need nothing extra. From a checkout: `pip install -e ".[all,dev]"`.
- HyperFrames: `npm install -g hyperframes`. Without it `v2t make` still writes `template.json`, `slots.json`, the project and `TEMPLATE.md`, then tells you how to render later. If only `npx` is available, `v2t` falls back to `npx --yes hyperframes` (the first render downloads it).
- ### 2. Claude Code plugin (no API key)
- ```
- /plugin marketplace add bertugbodur/video-to-template
- /plugin install video-to-template@video-to-template
- ```
- Then ask: *"make a template from reference.mp4"*. Claude reads the contact sheets itself and writes the interpretation; `v2t` validates it and continues. You still need the `v2t` command (path 1) installed.
- ### 3. Other agents (Codex CLI, Cursor, Gemini CLI, any SKILL.md-aware agent)
- Copy [`skills/video-to-template/`](skills/video-to-template) into the agent's skills directory and install `v2t` (path 1). The skill drives agent mode:
- ```bash
- v2t make reference.mp4 --provider agent --out my-template # exits with code 3 and writes analysis/agent-request/
- # the agent reads INSTRUCTIONS.md and the images, writes interpretation.json
- v2t make --resume my-template # validates and continues
- ```
- ## Providers
- | Provider | Credentials | Notes |
- |---|---|---|
- | `anthropic` | `ANTHROPIC_API_KEY` or keychain | Official SDK (`[anthropic]` extra) |
- | `openai` | `OPENAI_API_KEY` or keychain | Official SDK (`[openai]` extra) |
- | `gemini` | `GEMINI_API_KEY` or keychain | Official Google Gen AI SDK (`[gemini]` extra) |
- | `openrouter` | `OPENROUTER_API_KEY` or keychain | OpenAI-compatible, many models with one key |
- | `openai-compatible` | `--base-url` + key | LM Studio, vLLM, gateways |
- | `ollama` | none (`OLLAMA_HOST`, default `http://localhost:11434`) | Local vision model, nothing leaves your computer |
- | `agent` | none | Your coding agent is the model (see path 2 and 3) |
- | `fake` | none | Deterministic placeholder answers, for tests and dry runs |
- No model name is hardcoded: `v2t auth login` lists the provider's models and suggests vision-capable ones, or you type one (`--model` overrides). Settings resolve as flag, then environment variable, then keychain, then `config.toml`.
- ```bash
- v2t auth status # provider, model, whether a key exists (last 4 characters at most)
- v2t auth test # connection check with one tiny synthetic image
- v2t auth logout # remove the key from the keychain
- ```
- ## Privacy and keys
- - Keys live in the OS keychain or environment variables, never in a plain-text file, and are masked in logs and errors.
- - A key is sent only to the chosen provider's official API. No telemetry, no server of ours.
- - Before frames go to a cloud provider, `v2t` shows how many images (and roughly how many tokens) will be sent and asks first (`--yes` skips). With `--provider ollama` nothing leaves the machine. `--review` asks the same before sending the comparison image.
- - HyperFrames is always run with `HYPERFRAMES_NO_TELEMETRY=1`.
- - `v2t` works on local files only and never downloads videos. Reference videos and the frames extracted from them stay in `analysis/` (git-ignored by this repo); only the original demo is committed.
- ## Commands
- | Command | What it does |
- |---|---|
- | `v2t setup` | Check Python, ffmpeg, Node and HyperFrames |
- | `v2t analyze <video>` | Measurements only, no model: shots, camera moves, colors, rhythm |
- | `v2t make <video>` | Analysis, interpretation, `template.json`, project, preview render, comparison (`--no-render`, `--review`, `--provider`, `--model`, `--yes`, `--resume`) |
- | `v2t fill <folder> --slots slots.json` | Rebuild the project with your slots and render the MP4 (`--out`, `--quality`) |
- | `v2t render <folder>` | Render the current project as it is (keeps edits made in the HyperFrames desktop app) |
- | `v2t compare <folder>` | `comparison.png`, cut-time deviation, camera-direction agreement (`--review` lets your model suggest fixes, at most 2 rounds) |
- | `v2t auth ...` | `login`, `status`, `logout`, `test` |
- Output folder:
- ```
- <name>-template/
- analysis/ measurements and contact sheets (local)
- template.json the recipe: scenes, camera, layers, transitions, slots
- slots.json your content; edit this
- project/ HyperFrames project (open it in the HyperFrames desktop app)
- renders/ preview.mp4, filled.mp4
- comparison.png reference vs render
- TEMPLATE.md scene list, slot table, how to fill, what is approximate
- ```
- ## Slots
- `slots.json` maps slot names to values. Text slots have a `maxChars` limit, color slots take `#RRGGBB`, image and video slots take a file path (relative to `slots.json`). Slots you leave out keep their defaults; unknown slots and over-long text are errors with a shorter suggestion. Slots are HyperFrames variables, so you can also change them in the HyperFrames desktop app.
- ## What to expect
- - **Measured:** cut times (within a frame on the test clips), durations, fps, size, palette, camera move and its easing.
- - **Interpreted (approximate):** layout, type size and weight, backgrounds, transition kinds. `push` and `slide` transitions move only the outgoing scene.
- - **Camera check:** `compare` re-measures the render with the same optical-flow code and compares direction, not magnitude. Flat renders (plain gradients and text) give too little texture, and those scenes are reported as unmeasurable rather than guessed.
- - **Soft transitions** (dissolves, flashes) may not be found as cuts in the render.
- - **Tested** with synthetic clips and fake provider responses. The cloud providers and Ollama are tested against faked HTTP only; run `v2t auth test` with your own key or model to confirm the connection.
- ## Rules this tool follows
- 1. No copying: the reference's footage, logos, brand names, copy and music never enter the template. Default slot content is neutral placeholders.
- 2. Use videos you have the right to analyze.
- 3. No brand logos in templates or examples.
- 4. Measured values win over interpretation.
- ## Development
- ```bash
- pip install -e ".[all,dev]"
- pytest # ~140 tests, no network, no API keys
- V2T_TEST_HYPERFRAMES="npx --yes hyperframes" pytest tests/test_render.py # real renders (needs Node and Chrome)
- ```
- ## License
- MIT, see [LICENSE](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.