mirror of
https://github.com/HelpFreedom/kadr.git
synced 2026-08-06 16:57:02 +00:00
AI-native GPU-accelerated video editor with Claude Code built into the timeline
- TypeScript 61.8%
- JavaScript 34%
- CSS 3.7%
- Python 0.4%
- Shell 0.1%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
7beb927b4e
Three features for the editor and its embedded Claude Code session:
- Frame snapshot: a 📷 button in the transport bar renders the current
WYSIWYG frame to a PNG at project resolution, saves it next to the
project file (directory picker when the project is unsaved) and imports
it into the media bin. Media decodes at SOURCE quality for the shot —
the originals, not the 540p preview proxies — and Remotion fragments
are included by forcing them through pixel capture. The same power is
exposed to the embedded Claude as the kadr_snapshot MCP tool and
kadrEditor.snapshotFrame(): its eyes on the timeline.
- Loudness normalization: right-click a clip → «Нормализовать громкость»
measures the used source range with ffmpeg's EBU R128 pass and sets the
clip gain for −14 LUFS with a −1 dBTP true-peak ceiling.
Non-destructive (gain only), one undo entry, converges on repeat,
refuses keyframed gain, and retargets to the audio twin of a linked A/V
pair. Also available as kadrEditor.normalizeClip() for the agent.
- kadr-editor agent skill: shipped in the repo and synced to
~/.claude/skills/kadr-editor at app startup. Teaches the embedded
Claude a LOOK → ACT → VERIFY workflow (kadr_state for structure,
kadr_snapshot as eyes, kadr_eval discipline and recipes); scoped to
sessions with the kadr_* tools and defers Remotion composition
authoring to a separately installed remotion skill.
Verified: snapshots pixel-checked against expected content (including a
fragment forced through capture and a 1px-stripe source proving original
quality: neighbour contrast 254.5/255 while the proxy was active);
normalization measured −13.95 LUFS end-to-end on an exported clip;
regression suites green.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
||
| electron | ||
| scripts | ||
| shared | ||
| src | ||
| .gitignore | ||
| CLAUDE.md | ||
| demo.gif | ||
| electron.vite.config.ts | ||
| FEATURES.md | ||
| index.html | ||
| LICENSE | ||
| package-lock.json | ||
| package.json | ||
| README.en.md | ||
| README.md | ||
| tsconfig.node.json | ||
| tsconfig.web.json | ||
Kadr
AI-native, GPU-accelerated video editor — with Claude Code built into the timeline.
Русская версия → · Full feature guide (RU) → · Video →
Kadr is a multi-track video editor (Electron + React + TypeScript) built around one idea: an AI agent should be able to edit video next to you, on the same timeline, with the same tools. Press 🤖, type «add animated captions to this part», watch it happen live in the preview.
Highlights
- 🎬 Real multi-track editing — video/audio/text tracks, trimming, looping, fades, linked AV clips, ripple delete, full undo history. Clip speed from ×0.02 to ×100 by Ctrl-dragging either clip edge (the left one anchors the right boundary), snapping to round multipliers and to neighbouring clips' edges, with a live ×N badge.
- 📥 Media from anywhere — drop files onto any spot of the window (onto a track they land as clips back-to-back at the drop point, audio routes to an audio track), drag a picture straight out of a browser (fetched by URL), or hit Ctrl+V — clipboard paste understands both copied files and "Copy image" (e.g. from Telegram, which won't let photos be dragged out at all). XDG-portal drags from sandboxed apps are supported too. The media bin gets multi-select and deletion that removes the files together with their timeline clips (single undo).
- ⚡ GPU compositing (WebGL2) — the preview is the render: the same compositor draws both, so export is pixel-exact WYSIWYG.
- 🔑 Keyframes everywhere — position, scale, rotation, opacity, volume, masks; AE-style workflow with easing.
- 🧊 True 3D — per-clip tilt/depth and whole-track camera motion with perspective-correct texturing.
- 🎭 Masks — animatable edge crop plus up to 8 feathered shapes (rect/ellipse/triangle, invertible).
- 🌫️ Effects: smoky outer glow and blur — a glow of billow-noise smoke, ragged tendrils and drifting embers, plus per-layer gaussian blur with an intensity slider; fully parametric, preset-able, identical in preview and export.
- ⏪ Clip reverse — right-click → “Reverse”: the used source range is rendered backwards (cached), the linked AV pair flips in sync, and a second click instantly restores the original.
- 🔀 26 transitions — 14 overlap transitions (Vegas-style: just overlap two clips) and 12 cinematic edge transitions (whip pans, blur zooms, RGB split, glitch…) with spectral motion blur.
- 🗣️ Local speech-to-text — faster-whisper (large-v3) with word-level timestamps and serious anti-hallucination guards (a pure tone yields zero cues — enforced by tests). SRT/TXT editing built in.
- ✨ Auto-captions — one dialog: transcribe → animated karaoke captions (word-precise highlight, pop/rise/fade entrances), drag & scale them with the mouse right in the preview.
- ⚛️ Remotion fragments — programmable React/TSX motion graphics as timeline clips. Live preview with hot reload (no renders while iterating!), automatic pixel-capture mode when you put GL effects, 3D or transitions on a fragment, and exactly one real render at export (content-hash cached).
- 🤖 Embedded Claude Code — a real interactive Claude session in a terminal panel, wired to the live project over MCP: it reads the timeline, edits clips, transcribes, creates and iterates Remotion fragments while you watch the preview update. The panel is draggable, resizable and remembers its place across launches.
- 📤 Uncompromised export — video is encoded by ffmpeg x264 at the preset's true bitrate (Chromium's built-in encoder ignored the bitrate and softened the picture — measured and replaced; frames reach ffmpeg with zero copies), mp4box-based fast decode (~8× over element seeks, with graceful fallback), 8-sample motion blur, automatic frame blending for fps-mismatched sources, presets for YouTube/Shorts/WebM/MP3.
- 🛟 Quality-of-life — background 540p preview proxies, autosave every 5 minutes (atomic, skipped during exports/AI sessions), an unsaved-changes indicator with “✓ Saved” feedback, self-healing after hard closes (no lingering processes), effect & pose presets shared across projects, RU/EN interface.
- 🔒 Clean
npm audit— Electron 42 / Chromium 148, vite 7, fresh tar: 0 known vulnerabilities in the dependency tree (thanks to @Antony-hash512 for issue #1).
Requirements
| Component | Needed for | Notes |
|---|---|---|
| Node.js ≥ 20 | everything | |
| ffmpeg + ffprobe | import, audio mix, export | any recent build in PATH |
| python3 + faster-whisper | speech-to-text, auto-captions | pip install faster-whisper; models download on first use |
| Claude Code CLI | the 🤖 panel | optional; uses your existing login |
| network (one-time) | Remotion fragments workspace | ~/kadr-fragments, ~150 MB |
Getting started
git clone https://github.com/HelpFreedom/kadr.git && cd kadr
npm install # postinstall rebuilds node-pty for Electron
npm run dev
Import media, edit, press Export. For the AI assistant press 🤖 (the
claude CLI must be installed and logged in). If your network needs a
proxy for Claude/npm, create ~/.config/kadr/claude-env.json:
{ "env": { "HTTPS_PROXY": "http://127.0.0.1:1080", "NO_PROXY": "127.0.0.1,localhost" } }
How the AI integration works
Kadr starts a local HTTP bridge into the renderer and hands Claude an MCP server with five tools:
| Tool | What it does |
|---|---|
kadr_state |
full live project: tracks, clips, asset paths, transcripts, presets |
kadr_eval |
run JS against the editor API (every edit lands in undo history) |
kadr_export |
render the project or a range and wait for the file |
kadr_transcribe |
local Whisper over a file or a timeline range |
kadr_fragment_create |
scaffold a Remotion composition as a timeline clip |
The killer loop: Claude creates a fragment, edits its TSX with normal file tools, and vite hot-reloads it into your preview in ~2 seconds — you give feedback in plain language, no rendering until the final export.
Testing
E2E tests drive the real app over the Chrome DevTools Protocol:
npx electron-vite dev -- --remote-debugging-port=9777 # terminal 1
node scripts/e2e13.mjs # terminal 2 (etc.)
They cover transitions, glow, presets, proxies, export fidelity (fast-vs-fallback PSNR), motion blur, frame blending cadence, the MCP bridge, transcription anti-hallucination, fragments and capture mode, autosave semantics and auto-captions.
Documentation
- FEATURES.md — the full feature guide (Russian, 1200+ lines).
- CLAUDE.md — architecture map (also read by Claude Code).