AIEVv2

AIEV - AI Edit Video by noti.vn

🇬🇧 English · 🇻🇳 Tiếng Việt

Automatic AI video editing. Claude acts as the director - driving HyperFrames (motion-graphics scenes built with HTML + GSAP) and Remotion (timeline assembly) - while you supervise everything through the web dashboard at http://localhost:6868.

Drop in a clip, briefly describe what you want, click "Start editing with AI" - the system transcribes, writes the editing plan, builds kinetic-typography scenes, karaoke subtitles, beat-synced zooms and timestamped sound effects, assembles the timeline and exports an MP4. The same engine also turns articles into narrated videos, cuts long videos into shorts and translates videos into other languages.

Every page of the dashboard has a Guide button in the top bar: it opens a side panel on the guide for the page you are on, with a menu to read any other section.

Features

Architecture

┌─────────────────────────────────────────────────────┐
│  Web UI (Next.js, port 6868)                        │
│  Dashboard · Videos/Images Project · Auto cut ·     │
│  Text to video · Translate video · Voices ·         │
│  Style Design · Edit styles · Render Queue ·        │
│  Assets · Sound Effects · Prompts · Skills ·        │
│  Settings · Connections  (+ video editor, guide)    │
└──────────────────────┬──────────────────────────────┘
                       │ REST + SSE
┌──────────────────────┴──────────────────────────────┐
│  Backend (Express, port 6869)                       │
│  Claude Agent SDK · Render queue · SQLite           │
└──────┬──────────────────────────────┬───────────────┘
┌──────┴───────────┐        ┌─────────┴────────────┐
│ HyperFrames      │  MP4   │ Remotion             │
│ SCENE ENGINE     │───────▶│ ASSEMBLER            │
│ HTML + GSAP      │        │ scene + audio + sub  │
└──────────────────┘        └──────────────────────┘

Each project's meta.json is the single source of truth - the editor, the AI and the render queue all read and write it. Full API contract: docs/API.md. Production workflow + know-how: .claude/skills/.

Requirements

• Node.js 24 LTS (or 22.23.4+ / 26.12.1+ - the October 2026 security releases; HyperFrames needs >=22)
• FFmpeg on PATH (macOS: brew install ffmpeg)
• Google Chrome (HyperFrames and Remotion render through headless Chromium)
• Claude: sign in to Claude Code on this machine (subscription OAuth - recommended) or put ANTHROPIC_API_KEY in .env
• Gemini (image generation, Gemini TTS, translation): GEMINI_API_KEY in .env - get one at aistudio.google.com/apikey
• Python 3.11 - 3.14 (optional) for subtitles (faster-whisper) and offline voices (VieNeu-TTS); the optional image gateways need 3.13 or 3.14. Python 3.15 is too new - several packages have no builds for it yet. On macOS install it with brew install python@3.13 (the system Python 3.9 is too old, and plain brew install python may give you 3.15).
• Optional: an NVIDIA GPU (NVENC) or an Apple Silicon Mac (VideoToolbox) for faster rendering

You do not have to install these by hand. The start script checks every item above and offers to install whatever it can - see Environment check.

Getting started

git clone https://github.com/notivn/AIEVv2.git
cd AIEVv2

Windows - double-click start\start.bat (or run start\start.ps1).

macOS - double-click start/start.command in Finder. A .sh file cannot be double-clicked on macOS, it just opens in an editor. If macOS blocks it as coming from an unidentified developer, right-click the file → Open → Open.

Linux - run ./start/start.sh.

If you downloaded a ZIP instead of cloning, make the scripts executable once:

chmod +x start/*.sh start/*.command update/*.sh update/*.command

The script handles everything: checks the environment → npm install (first run) → build → creates .env → starts server + web → opens http://localhost:6868.

Manual dev run: npm install then npm run dev.

Updating

Use the update badge at the bottom of the sidebar - it pulls the new version, reinstalls, rebuilds and restarts. Settings → Update channel decides what counts as new: Stable (release) (default) only offers published releases, Latest (main) takes every commit on main. Projects, outputs, styles and cloned voices are not touched by an update.

User guide

The full, up-to-date guide lives inside the app: click Guide in the top bar on any page. It opens on the section for that page, and the menu at the top of the panel lists every section - getting started, each tool, the libraries and the system pages, plus troubleshooting. A short tour:

Your first video (Videos Project)

1. Create a project - Videos Project → Create project: name, frame size (9:16 for TikTok/Reels, 16:9 for YouTube) and fps.
2. Add the source - upload your clip in the Sources & Assets card, or click Connect phone and scan the QR to send files straight from your phone.
3. Fill in the brief - the AI's instruction sheet: source description, auto-trim, karaoke subtitles with keyword highlighting, key layout, AI illustrations, sound effects and background music, Style Design, edit style, skill (editing format) and free-form notes. Every switch is real: turn a feature off and the AI is told not to use it.
4. Start editing with AI - Claude transcribes, plans, builds HyperFrames scenes, generates illustrations, wires sound effects and assembles a draft. Progress streams live; every render goes through the Render Queue.
5. Review and finish - watch the draft, ask for changes in the chat ("make the hook bigger", "cut the intro"), fine-tune in the video editor, then run QC and the final render. The MP4 lands in outputs/ with an auto-generated thumbnail and a publish pack (title, description, hashtags).

The other tools

• Images Project - posters and thumbnails: the image model paints the background only, Remotion overlays title, stats, CTA and logo per the Style Design.
• Auto cut videos - plan segments of a long video, tick the ones you want, cut them into child projects.
• Text to video - extract → script → voice → build, reviewing each stage.
• Translate video - upload, pull dialogue, translate, then subtitles, dubbing or both.
• Voices - preview preset voices, install VieNeu-TTS, clone your own voice.
• Style Design / Edit styles - brand identity (colors, fonts, logo) versus the visual language of one video (materials and motion). They stack; they never replace each other.
• Sound Effects, Assets, Prompts, Skills - the shared libraries the AI draws from.
• Settings / Connections - system check, GPU and queue settings, QC, update channel, image gateway; Claude, Gemini and gateway accounts.

CPU or GPU, step by step

Making one video runs through several stages, and each one picks its processor differently. The defaults keep drafts fast and finals high quality; every switch is in Settings.

• Final encoding is deliberately on the CPU. NVENC is much faster but at the same file size libx264 looks slightly better. Turn on GPU encode for FINAL if you prefer speed.
• Remotion's own encoding never uses the GPU here, only its rasterizing does. Without --gl angle Remotion falls back to SwANGLE, pure software rendering, which is noticeably slower.
• NVENC is detected through nvidia-smi. If it fails, runs out of sessions or rejects a frame size, the job re-runs on libx264 instead of failing. On macOS the auto-cut reframe always uses libx264; HyperFrames still uses VideoToolbox there.

Parallelism is separate: Concurrent render jobs (queue) (2 by default) sets how many jobs run at once, Chrome workers (HyperFrames) the HyperFrames worker count, Remotion concurrency how many frames Remotion renders in parallel. Two jobs of the same project never run at the same time.

Environment check

start/doctor.mjs probes everything the pipeline needs - Node.js, FFmpeg, Google Chrome, Claude credentials, Python and its venv, faster-whisper, VieNeu-TTS, the Gemini key, cloudflared, GPU - and installs what it can:

It runs automatically inside the start scripts, and the same list appears as the System check card in Settings, with a one-click install button per missing item (or a copyable command when it cannot be automated). Missing pieces never block startup - the dashboard comes up regardless so you can fix things from the UI. A venv built with an unsupported Python (too old or too new) is rebuilt automatically once a suitable Python is found.

node start/doctor.mjs              # just look
node start/doctor.mjs --fix        # ask before installing each missing item
node start/doctor.mjs --fix --yes  # install without asking
node start/doctor.mjs --lang en    # English output

Sharing installed tools between several clones

Everything heavy the project installs or downloads (the Python venv with torch, VieNeu and faster-whisper; several GB of models; separately downloaded ffmpeg/cloudflared; image-gateway accounts) lives in .runtime/ of each repo folder, so a fresh clone elsewhere downloads it all again. To share one copy, add this to the .env of EACH clone:

AIEV_RUNTIME_DIR=D:\aiev-runtime        # absolute, or relative to the repo root

• Simplest: point straight at the .runtime of the install you already run, e.g. AIEV_RUNTIME_DIR=D:\AIEV\.runtime. Nothing moves, so the venv keeps working - just do not delete the old install.
• A neutral location: move .runtime/ there but delete its venv and venv-gateway folders (a venv records absolute paths and breaks silently when moved). Run start once and the environment check rebuilds them in the new place. The models stay put and are not downloaded again.

Do not run two clones at the same time on one runtime. Cloned voices live in assets/voices/ (not in git) - copy that folder across by hand.

Upload from your phone

On a project page, in the Sources & Assets card click Connect phone and scan the QR code with your phone (same Wi-Fi as the machine) to open http://<machine-ip>:6868/m/<project>. Videos and photos picked on the phone upload straight into the project. The first time Windows asks about the firewall, choose Allow (the start script adds the rule itself when it has admin rights).

Remote over 4G/5G:

• Cloudflare Tunnel - set TUNNEL_DOMAIN=<your-domain> (e.g. aiev.noti.vn) in .env, and the Connect phone QR uses https://<domain>/m/<project>.
• Start the tunnel with the tunnel script for your OS (table above). Without TUNNEL_DOMAIN it falls back to a quick tunnel with a random trycloudflare.com URL.
• ⚠️ Warning: the dashboard has no login - only expose it publicly behind Cloudflare Access, and never share the link.

Folder structure

├── apps/web/            # Next.js dashboard (port 6868) - incl. the in-app guide (src/lib/guide)
├── apps/server/         # Express backend: Agent SDK + render queue + SQLite (port 6869)
├── engines/remotion/    # Remotion: Assemble (video) + Poster (image) compositions
├── .claude/skills/      # Skills - production know-how, manageable from the web UI
├── gateways/            # Optional image gateways (ChatGPT web, Gemini web) - AGPL, see License
├── assets/
│   ├── styles/          # Style Design (styles.json + fonts/logos) - ships empty
│   ├── video-styles/    # Edit styles (video-styles.json, 50 built in)
│   ├── sound-effects/   # Sound-effect library + library.json
│   ├── music/           # Background music library - ships empty
│   ├── brand-logos/     # Brand logos + library.json, grows automatically
│   ├── prompts/         # Prompt templates
│   └── voices/          # Cloned voices (not committed)
├── video-projects/      # One folder per video (not committed)
├── image-projects/      # Image projects (not committed)
├── auto-cut/ · text-to-video/ · translate-video/   # Sessions of those tools (not committed)
├── outputs/             # Final videos (not committed)
├── start/               # Start/stop/tunnel scripts + doctor.mjs (Windows .bat/.ps1, macOS .command, Linux .sh)
├── update/              # Update scripts used by the update button
└── docs/API.md          # API contract - the single source of truth

Tech stack

Next.js 16 · React 19 · Tailwind 4 · Express 5 · better-sqlite3 · Claude Agent SDK · HyperFrames · Remotion · Gemini API · faster-whisper · VieNeu-TTS · FFmpeg

Contributing

Bug reports, fixes and skills are welcome. Read CONTRIBUTING.md first - it covers the setup, the two commands CI runs on every PR (npm run typecheck and npm run build), and the conventions this codebase follows. For anything larger than a small fix, open an issue before you build.

Found a security problem? Do not open a public issue - follow SECURITY.md.

License

MIT - free to use, modify and distribute, including commercially.

Note on dependencies: this project's own license is MIT, but bundled tools keep their own. Remotion in particular is free for individuals and companies of up to 3 people; beyond that you need a Company License - and the video editor embeds the Remotion Player, which Remotion licenses under its "Automators" tier for such companies. Claude and Gemini usage is billed to your own account.

Exception - gateways/. The optional image gateways are not MIT: gateways/chatgpt/ (vendored chatgpt2api) and gateways/gemini-web/ (built on gemini-webapi) are AGPL-3.0, each with its own LICENSE. They run as separate processes (a local-only sidecar on 127.0.0.1 and a stdin/stdout worker) in their own venv .runtime/venv-gateway, installed only when you opt in (Connections → image gateway). gateways/gemini-watermark-remover/ is MIT. Using a ChatGPT or Google account through them is subject to those services' terms - that is your call.

Assets: this repo ships code, not media

The MIT license above covers the code. Media licensing varies per file, so the repo deliberately ships as little of it as possible:

The sound effects ship with a condition. Those 86 files were collected over years from assorted sources with no licensing records. They are here so the feature works out of the box, but not for commercial video - nobody can prove rights to them. For commercial work, replace them with CC0 or properly licensed audio and record source + license per file. Excerpts that are recognisably someone's property (the Netflix jingle, Nintendo sounds, SpongeBob…) are not included, even though the catalogue still lists their names.

Music ships empty outright: a multi-minute track is a far bigger risk than a half-second whoosh. Fonts have a built-in path instead: type a font name in Style Design and it downloads from Google Fonts onto your machine.

Style Design ships empty because a style is your own brand identity - a repo carrying someone else's style would have everyone building videos in their colours, watermarked with their logo. Create your first style on the Style Design page and it becomes the default.

If you fork this, replace the noti.vn name and logo with your own: swap the PNGs in apps/web/public/brand/ and run node apps/web/scripts/build-brand.mjs.

Made with ❤️ by noti.vn - Claude directs, humans approve.