Skip to content
Back to search

video-to-template

MarketplaceWorks with Claude CodeGitHub

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bertugbodur--video-to-template/badge.svg)](/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
  1. {
  2. "name": "video-to-template",
  3. "owner": { "name": "bertugbodur" },
  4. "plugins": [
  5. { "name": "video-to-template", "source": "./", "description": "Reference video in, reusable motion template out. Bring your own model." }
  6. ]
  7. }
README.md · README · 156 lines
  1. # video-to-template
  2. 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.
  3. **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.
  4. ## Demo
  5. [`examples/demo/`](examples/demo) is built from an original 9-second clip made for this repo (no logos, no third-party content).
  6. | Reference | Template (default slots) | New variation |
  7. |---|---|---|
  8. | [`reference.mp4`](examples/demo/reference.mp4) | [`template/`](examples/demo/template) | [`variation.mp4`](examples/demo/variation.mp4) |
  9. | an original clip: push-in, pan, hard cuts | `template.json` + HyperFrames project | same edit, [`variation-slots.json`](examples/demo/variation-slots.json) |
  10. ![reference on the left, render on the right](examples/demo/template/comparison.png)
  11. *Left tile of each pair: reference. Right tile: render of the template.*
  12. 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.
  13. ## How it works
  14. ```
  15. reference.mp4
  16. |
  17. v 1. Measure (Python, no model) cuts, camera moves, palette, rhythm, contact sheets
  18. v 2. Interpret (YOUR model) layers, typography, transition kinds -> JSON checked against a schema
  19. v 3. template.json measurements + interpretation merged and validated
  20. v 4. Generate (Python, no model) HyperFrames project, slots as variables
  21. v 5. Render + compare preview.mp4, comparison.png, cut-time and camera-direction report
  22. ```
  23. 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`.
  24. ## Install
  25. 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.
  26. ### 1. Command-line tool (everyone)
  27. ```bash
  28. pipx install video-to-template # or: uv tool install video-to-template
  29. v2t setup # checks ffmpeg, Node and HyperFrames
  30. v2t auth login # pick a provider, enter your key (stored in the OS keychain)
  31. v2t make reference.mp4 # analysis -> template.json -> project -> preview.mp4
  32. v2t fill reference-template --slots slots.json # same edit, your content
  33. ```
  34. (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]"`.
  35. 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).
  36. ### 2. Claude Code plugin (no API key)
  37. ```
  38. /plugin marketplace add bertugbodur/video-to-template
  39. /plugin install video-to-template@video-to-template
  40. ```
  41. 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.
  42. ### 3. Other agents (Codex CLI, Cursor, Gemini CLI, any SKILL.md-aware agent)
  43. 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:
  44. ```bash
  45. v2t make reference.mp4 --provider agent --out my-template # exits with code 3 and writes analysis/agent-request/
  46. # the agent reads INSTRUCTIONS.md and the images, writes interpretation.json
  47. v2t make --resume my-template # validates and continues
  48. ```
  49. ## Providers
  50. | Provider | Credentials | Notes |
  51. |---|---|---|
  52. | `anthropic` | `ANTHROPIC_API_KEY` or keychain | Official SDK (`[anthropic]` extra) |
  53. | `openai` | `OPENAI_API_KEY` or keychain | Official SDK (`[openai]` extra) |
  54. | `gemini` | `GEMINI_API_KEY` or keychain | Official Google Gen AI SDK (`[gemini]` extra) |
  55. | `openrouter` | `OPENROUTER_API_KEY` or keychain | OpenAI-compatible, many models with one key |
  56. | `openai-compatible` | `--base-url` + key | LM Studio, vLLM, gateways |
  57. | `ollama` | none (`OLLAMA_HOST`, default `http://localhost:11434`) | Local vision model, nothing leaves your computer |
  58. | `agent` | none | Your coding agent is the model (see path 2 and 3) |
  59. | `fake` | none | Deterministic placeholder answers, for tests and dry runs |
  60. 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`.
  61. ```bash
  62. v2t auth status # provider, model, whether a key exists (last 4 characters at most)
  63. v2t auth test # connection check with one tiny synthetic image
  64. v2t auth logout # remove the key from the keychain
  65. ```
  66. ## Privacy and keys
  67. - Keys live in the OS keychain or environment variables, never in a plain-text file, and are masked in logs and errors.
  68. - A key is sent only to the chosen provider's official API. No telemetry, no server of ours.
  69. - 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.
  70. - HyperFrames is always run with `HYPERFRAMES_NO_TELEMETRY=1`.
  71. - `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.
  72. ## Commands
  73. | Command | What it does |
  74. |---|---|
  75. | `v2t setup` | Check Python, ffmpeg, Node and HyperFrames |
  76. | `v2t analyze <video>` | Measurements only, no model: shots, camera moves, colors, rhythm |
  77. | `v2t make <video>` | Analysis, interpretation, `template.json`, project, preview render, comparison (`--no-render`, `--review`, `--provider`, `--model`, `--yes`, `--resume`) |
  78. | `v2t fill <folder> --slots slots.json` | Rebuild the project with your slots and render the MP4 (`--out`, `--quality`) |
  79. | `v2t render <folder>` | Render the current project as it is (keeps edits made in the HyperFrames desktop app) |
  80. | `v2t compare <folder>` | `comparison.png`, cut-time deviation, camera-direction agreement (`--review` lets your model suggest fixes, at most 2 rounds) |
  81. | `v2t auth ...` | `login`, `status`, `logout`, `test` |
  82. Output folder:
  83. ```
  84. <name>-template/
  85. analysis/ measurements and contact sheets (local)
  86. template.json the recipe: scenes, camera, layers, transitions, slots
  87. slots.json your content; edit this
  88. project/ HyperFrames project (open it in the HyperFrames desktop app)
  89. renders/ preview.mp4, filled.mp4
  90. comparison.png reference vs render
  91. TEMPLATE.md scene list, slot table, how to fill, what is approximate
  92. ```
  93. ## Slots
  94. `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.
  95. ## What to expect
  96. - **Measured:** cut times (within a frame on the test clips), durations, fps, size, palette, camera move and its easing.
  97. - **Interpreted (approximate):** layout, type size and weight, backgrounds, transition kinds. `push` and `slide` transitions move only the outgoing scene.
  98. - **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.
  99. - **Soft transitions** (dissolves, flashes) may not be found as cuts in the render.
  100. - **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.
  101. ## Rules this tool follows
  102. 1. No copying: the reference's footage, logos, brand names, copy and music never enter the template. Default slot content is neutral placeholders.
  103. 2. Use videos you have the right to analyze.
  104. 3. No brand logos in templates or examples.
  105. 4. Measured values win over interpretation.
  106. ## Development
  107. ```bash
  108. pip install -e ".[all,dev]"
  109. pytest # ~140 tests, no network, no API keys
  110. V2T_TEST_HYPERFRAMES="npx --yes hyperframes" pytest tests/test_render.py # real renders (needs Node and Chrome)
  111. ```
  112. ## License
  113. MIT, see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.