How to Turn Talking-Head Videos into Vertical Reels with heditor

What Is heditor?

heditor is an open SKILL.md-based Agent Skill for turning talking-head footage into vertical Reels, Shorts, and TikToks. It works with agents such as Claude Code, Codex, OpenCode, Cursor, and Hermes.

Instead of manually assembling every edit, you give your agent a video and an editing direction. heditor analyzes the recording, identifies the speaker, transcribes the audio with word-level timing, selects a complete section of approximately 30 to 70 seconds, and creates a vertical 1080×1920 composition.

The workflow runs locally and combines frame-accurate cuts, voice processing, synchronized captions, motion graphics, sound effects, music, and automated checks. Visual compositions are built with HTML and GSAP and rendered with HyperFrames.

Key Features

• Vertical 1080×1920 output for Reels, Shorts, and TikToks.
• Word-synchronized captions and speech-aware editing.
• Frame-accurate camera and speech cuts with shortened dead pauses.
• Motion graphics and scene changes designed around the meaning of the speech.
• Voice-first audio mixing, with music and effects kept in the background at a target of −14 LUFS.
• Automatic quality checks for linting, tests, previews, safe margins, loudness, true peak, final-audio transcription, and a 40-frame contact sheet.
• Eleven named styles: cinema, ruptura, impacto, game, thriller, ide, aeroporto, chat, documentario, podcast, and missao.

Choose an Editing Mode

Fixed Style

A fixed style applies an established visual language while rebuilding the scenes for the specific video. For example, you can ask the agent to edit a clip in aeroporto style. The result uses the control-tower concept, radar elements, departure-board typography, and radio-like captions without treating the style as a rigid template.

Creative Mode

In creative mode, the agent studies the video, creates six to eight format concepts, researches references, selects the most surprising concept that fits the speech, and builds a custom visual world. The workflow aims for frequent visual changes, approximately every 1.5 to 2 seconds, with sound effects supporting on-screen actions.

Creative Mode with a Reference

You can provide a reference such as a game, anime opening, news broadcast, or nature documentary. For example, ask for creative mode in the style of GTA 6. heditor researches the reference's palette, typography, interface elements, movement, and sound language, then creates a licence-safe homage without using protected logos, characters, brands, or music.

Use a reference as creative direction, not as a request to copy protected assets.

Installation and Setup

Recommended Installer

The installer detects supported agents, links the skill into each one, prepares the local environment, and runs the diagnostic command.

curl -fsSL https://raw.githubusercontent.com/pycodebr/heditor/main/install.sh | bash

During setup, heditor can install missing tools such as FFmpeg, Node.js 18 or later, Python 3.10 through 3.13, Git, and curl through supported package managers. It also creates a Python environment at ~/.heditor/venv, prepares HyperFrames and Chrome, downloads the required models and assets, creates ~/.heditor/env.sh, and installs the heditor command.

The installer supports options such as selecting an agent, copying instead of linking, skipping audio assets, or skipping setup:

bash install.sh --agent claude
bash install.sh --agent all
bash install.sh --copy
bash install.sh --no-audio
bash install.sh --no-setup

Install Through Skills CLI

You can also install the skill with the Vercel Skills CLI and then run its setup script.

npx skills add pycodebr/heditor -g
bash ~/.agents/skills/heditor/scripts/setup.sh

Manual Installation

git clone https://github.com/pycodebr/heditor.git
cd heditor
bash install.sh --agent claude

Alternatively, copy the skills/heditor directory into the skills location used by your agent.

Configure Your Brand

heditor reads brand settings from ~/.heditor/brand.json. Use this file to define the name, handle, logo, language, call-to-action text, and visual colors used by your edits.

{
  "name": "Your Brand",
  "handle": "@yourprofile",
  "logo": "/path/to/logo.png",
  "lang": "en",
  "follow": "Follow",
  "following": "Following",
  "comment": "Tell us in the comments",
  "colors": {
    "bg": "#050a14",
    "bg2": "#081626",
    "accent": "#edc580",
    "accent2": "#7dd3fc",
    "alert": "#ff3d57",
    "ok": "#7dffb0"
  }
}

Set the language and call-to-action fields to match the audience for your content. The logo path should point to an image available on the local machine.

Use heditor Through Your Agent

After installation, describe the source video and the desired editing direction in natural language. For example:

Edit /videos/class-03.mp4 in the documentario style. Use the section where I talk about career transition.

Creative mode: turn minute 12 of this podcast into a Reel and surprise me.

Use creative mode with a news-broadcast reference for this video about this week's news.

Make three cuts from this video, each with a different format.

The agent handles the analysis, transcription, editing plan, composition, rendering, audio mix, and quality checks according to the selected mode.

Use the CLI Directly

You can also run the processing stages explicitly. First load the environment:

. ~/.heditor/env.sh

Analyze and Transcribe the Source

Use probe to generate frames for finding the speaker and transcribe to create a word-timed transcription.

heditor probe lesson.mp4 5 60 300
heditor transcribe lesson.mp4 0 3600 qa/asr.json

Create and Prepare a Cut

Create a new cut directory, then prepare the speech and camera edits.

heditor new cuts/c01 lesson.mp4
heditor prepare cuts/c01

The new cut includes working files such as prepare.py, build.py, and DESIGN.md. The preparation stage removes dead pauses and creates the assembled speech and camera material.

Inspect Pauses and Words

heditor gaps cuts/c01
heditor words cuts/c01

The gaps command helps verify that no pause longer than 0.45 seconds remains in the assembled speech. The words command displays the words associated with the prepared cut.

Produce, Validate, and Render

Produce the composition and mix, then run the quality checks before rendering the final file.

heditor produce cuts/c01 music:955 30
heditor lint cuts/c01
heditor preview cuts/c01 0.1,2,5,9,14,20
heditor test cuts/c01
heditor render cuts/c01
heditor finalize cuts/c01 c01-1080x1920.mp4
heditor asr-check cuts/c01

The preview command samples selected timestamps for visual review. The final ASR check transcribes the rendered audio so you can confirm that the final mix still matches the intended speech.

Understand the Built-In Styles

• cinema uses a visual metaphor for each speech section, cinematic captions, and world changes at argument turns.
• ruptura opens with the strongest phrase, turns the camera into a metaphor, and closes typographically.
• impacto coordinates typography, sound, and zoom around key phrases.
• game presents the video as a retro RPG with a HUD, dialogue-box captions, an inventory, and a continue screen.
• thriller uses a security-camera language with REC indicators, heartbeat elements, distortion, blackout, and reboot effects.
• ide presents a code-editor screen recording with a webcam bubble, typed-comment captions, and a terminal call to action.
• aeroporto uses a control-tower concept with radar, departure boards, and radio-transmission captions.
• chat turns speech into messages in a light messaging application and uses video-call framing for the camera.
• documentario uses film grain, cinematic bars, serif chapter titles, and end credits.
• podcast creates a saturated talk-show environment with an ON AIR sign, reactive waveform, and large karaoke captions.
• missao uses an open-world-game homage with a neon sunset, mission card, GPS route, attributes screen, completion screen, and mobile call to action.

Detailed style definitions are available in the styles reference directory.

Advanced Tips

Let the Speech Drive the Design

heditor is designed to rebuild scenes around the meaning of each new recording. When using a fixed style, specify the topic or section you want to emphasize so the agent can select a coherent piece of reasoning rather than an arbitrary excerpt.

Save Successful Creative Concepts

If a creative-mode result works particularly well, ask the skill to save it as a named style. The process is documented in adding-styles.md.

Review the Quality Gates

Do not skip the lint, preview, test, loudness, safe-margin, and final transcription stages for production videos. The workflow is designed to catch visual layout problems, audio issues, caption mismatches, and unsafe placement near the top of the vertical frame.

Plan for Local Resources

Linux and macOS are supported, with Windows available through WSL2. The recommended machine has four CPU cores and 8 GB of RAM. Setup uses approximately 1.5 GB of disk space, and a 60-second video can take 5 to 15 minutes to render on a typical CPU.

Check Asset Licensing

Code and documentation are released under the MIT license. The project uses HyperFrames, GSAP, faster-whisper, MediaPipe, Google Fonts, Lucide, and Mixkit assets under their respective licenses. Music and sound effects are downloaded from Mixkit during setup and are not redistributed in the repository. Review the project's license reference before publishing commercial work.

Conclusion

heditor gives AI coding agents a structured workflow for turning ordinary talking-head recordings into polished vertical videos. Install the skill, configure your brand, choose a named style or creative mode, describe the source footage, and use the CLI checks to review the result before rendering. Because the pipeline runs locally and adapts the visual world to each speech segment, it is suitable for repeatable production without forcing every video into the same template.