# HyperFrames: viết HTML là ra video MP4, dành cho AI agent — hướng dẫn cài đặt và dùng

> HyperFrames là framework mã nguồn mở của HeyGen, cho phép bạn viết video bằng HTML rồi render ra file MP4. Bạn có thể dùng bằng dòng lệnh (npx hyperframes) hoặc cài skill để Claude Code, Codex, Cursor tự làm video giúp bạn. Cài không khó nếu máy đã có Node.js 22 trở lên và FFmpeg.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-05-04 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/hyperframes-viet-html-render-video-mp4-cho-ai-agent

HyperFrames là một framework mã nguồn mở, miễn phí, biến HTML, CSS, media và các hoạt ảnh "tua được" thành video MP4. Tác giả (HeyGen) tóm tắt bằng một câu: viết HTML, render video, xây dựng cho AI agent.

Vấn đề repo giải quyết khá đời thường. Làm video thường phải học phần mềm dựng phim, hoặc học hẳn một framework riêng. HyperFrames đi đường khác. Video chỉ là một file HTML có thêm vài thuộc tính về thời gian. AI agent vốn viết HTML rất giỏi, nên bạn có thể gõ yêu cầu bằng tiếng thường, agent viết file, rồi công cụ render ra MP4.

Người nên dùng: lập trình viên mới muốn làm video bằng code, người làm nội dung hoặc marketing đã quen Claude Code hay Cursor, và đội cần tự động hoá video hàng loạt. Điểm đáng giá nhất là tính "xác định": cùng một đầu vào luôn ra cùng một video. Repo hiện có khoảng 83.400 sao và khoảng 7.700 fork, giấy phép Apache-2.0, nên không tính phí theo lượt render.

```repo
- repo | heygen-com/hyperframes
- kind | Framework
- desc | Framework mã nguồn mở biến HTML, CSS và hoạt ảnh thành video MP4 ổn định, dùng được bằng dòng lệnh hoặc nhờ AI agent như Claude Code làm giúp.
- stars | 83k
- lang | TypeScript
- license | Apache-2.0
```

## HyperFrames làm được gì

### Video viết bằng HTML thuần

Mỗi video là một file HTML. Bạn gắn các thuộc tính như `data-start`, `data-duration`, `data-track-index` lên từng phần tử để nói nó xuất hiện lúc nào, kéo dài bao lâu, nằm ở lớp nào. Không cần React, không cần định dạng timeline riêng. File `index.html` còn mở thẳng được trong trình duyệt, không cần bước build.

### Bạn chọn thư viện hoạt ảnh quen tay

Hoạt ảnh có thể dùng GSAP, CSS, Lottie, Three.js, Anime.js, WAAPI, hoặc bộ chuyển đổi (adapter) do bạn tự viết. Điều kiện là hoạt ảnh phải "tua được" theo từng khung hình, vì bộ render sẽ nhảy tới từng khung trong Chrome không giao diện rồi mã hoá bằng FFmpeg.

### Cho AI agent học cách làm video

Repo đóng gói 9 skill để dạy agent quy trình làm video: lên kế hoạch, viết HTML hợp lệ, nối hoạt ảnh, thêm media, kiểm tra lỗi, xem thử, render. Các skill chạy với Claude Code, Codex, Cursor, Gemini CLI, IBM Bob và các agent khác có hỗ trợ skill.

### Thư viện khối dựng sẵn (catalog)

Hơn 450 khối và thành phần dựng sẵn, cài về dưới dạng mã nguồn sửa được: chuyển cảnh, lớp phủ mạng xã hội, tiêu đề, chữ chuyển động, phụ đề, biểu đồ, bản đồ, 3D, chuyển động camera. Bạn đỡ phải tự dựng từ đầu.

### frame.md: hệ thống thiết kế cho video

Mọi thương hiệu có file `design.md` viết cho web. `frame.md` dịch nó sang ngôn ngữ của khung hình video, để agent dựng video quảng cáo mà không phải đoán cỡ chữ hay bày kiểu giao diện web. Kết quả là một file DESIGN.md mở rộng mà cả bộ công cụ đọc được.

### Render ở nhiều nơi

Bạn render ngay trên máy, trong Docker, hoặc dùng AWS Lambda để render phân tán. Ngoài ra còn có Studio (giao diện trình duyệt để xem và sửa) và ứng dụng desktop cho macOS, Windows, Linux (.deb).

## Cần chuẩn bị gì

Theo README, nếu dùng dòng lệnh bạn cần:

- Node.js phiên bản 22 trở lên.
- FFmpeg.

Nếu muốn để AI agent làm giúp, bạn cần thêm một agent có hỗ trợ skill, ví dụ Claude Code, Codex hay Cursor. README không nói cần API key riêng cho phần render cục bộ. Chi phí của agent (gói đăng ký hoặc API của chính agent đó) là chuyện riêng của công cụ bạn chọn.

Một số skill được ghi là dành cho gói HyperFrames Pro: `/reverse-any-video` và `/style-sampling`. Ứng dụng Studio dùng miễn phí; gói Pro của nó thêm các mô hình video, ảnh, giọng nói, nhạc của HeyGen. README không nêu yêu cầu phần cứng cụ thể. Về hệ điều hành, README chỉ nhắc ứng dụng desktop có bản cho macOS, Windows và Linux.

```note
Các skill như /media-use có thể dùng dịch vụ của HeyGen hoặc công cụ miễn phí chạy trên máy. Nếu bạn bật tính năng dùng mô hình trả phí, hãy kiểm tra gói và chi phí trước khi chạy hàng loạt.
```

## Cài đặt từng bước

Có hai đường: nhờ AI agent (dễ nhất nếu bạn đã dùng Claude Code) hoặc tự gõ lệnh. Mình tóm tắt đường nhờ agent và đường dòng lệnh chung một khối:

```steps
- Kiểm tra máy | Có Node.js 22+ và FFmpeg
- Cài skill cho agent | Dùng plugin Claude Code hoặc npx skills add
- Cập nhật skill | Chạy npx hyperframes skills update
- Tạo dự án | npx hyperframes init my-video
- Xem thử và render | preview rồi render ra MP4
```

### Kiểm tra Node.js và FFmpeg

Mở terminal (trên Windows là PowerShell hoặc Windows Terminal) rồi xem Node.js đã đủ phiên bản chưa. Lệnh này phổ thông, in ra số phiên bản:

```bash
node --version
ffmpeg -version
```

Nếu Node.js thấp hơn 22 hoặc chưa có FFmpeg, bạn cần cài thêm. README chưa ghi cách cài hai thứ này; hãy xem trang chủ của từng công cụ.

### Cách 1: cài plugin cho Claude Code

Đây là cách README đề xuất cho Claude Code. Chạy lần lượt hai lệnh trong terminal:

```bash
claude plugin marketplace add heygen-com/hyperframes
claude plugin install hyperframes@hyperframes
```

Lệnh đầu thêm "kho" plugin của HyperFrames. Lệnh sau cài plugin từ kho đó. Muốn bật tự cập nhật, bạn mở `claude` trong thư mục dự án, gõ `/plugin`, chọn Marketplaces, rồi hyperframes, rồi Enable auto-update. Sau đó gọi bằng `/hyperframes:hyperframes`.

### Cách 2: cài skill độc lập (dùng cho OpenCode và agent khác)

```bash
npx skills add heygen-com/hyperframes
```

Lệnh này mở một bảng chọn, không chọn sẵn gì. Bạn chỉ cần nhóm **Core Skills**. Các skill `/slideshow`, `/remotion-to-hyperframes` và `/figma` cài khi cần. Chạy lệnh này trong thư mục dự án video của bạn, vì README nói bản cài theo dự án nên chạy ở đó.

### Cập nhật skill cho khớp phiên bản CLI

```bash
npx hyperframes skills update
```

Lệnh này cài đúng bộ skill lõi từ bản phát hành khớp với CLI bạn đang dùng. README nói `skills add` có thể chậm hơn nhánh chính vài giờ, nên lệnh `update` an toàn hơn để skill khớp CLI. Nếu muốn cài một skill lẻ, ví dụ khi cần dùng `/figma`:

```bash
npx hyperframes skills update <tên-skill>
```

Thay `<tên-skill>` bằng tên skill, viết trơn, không có dấu gạch chéo ở đầu.

### Cách 3: tự dùng dòng lệnh

Không cần agent cũng được. Bốn lệnh sau tạo dự án, vào thư mục, xem thử và render:

```bash
npx hyperframes init my-video
cd my-video
npx hyperframes preview      # preview in browser with live reload
npx hyperframes render       # render to MP4
```

`init` tạo thư mục `my-video` với dự án mẫu. `cd my-video` đưa terminal vào thư mục đó; các lệnh sau phải chạy từ đây. `preview` mở trình duyệt, sửa file là thấy ngay. `render` xuất ra file MP4.

## Kiểm tra đã chạy được chưa

Cách kiểm tra đơn giản nhất là chạy bốn lệnh ở Cách 3. Nếu `npx hyperframes preview` mở được trình duyệt và bạn thấy video mẫu chạy, phần xem thử đã ổn. Nếu `npx hyperframes render` kết thúc và tạo ra file MP4 mở xem được, phần FFmpeg và Chrome không giao diện đã ổn.

Với agent, bạn thử gọi skill. Trong Claude Code với plugin, gõ `/hyperframes:hyperframes`. Nếu agent nhận lệnh và bắt đầu hỏi hoặc lên kế hoạch video thì skill đã nạp. README chưa mô tả chính xác màn hình hay thông báo thành công cho từng lệnh, nên mình không đưa ra kết quả cụ thể hơn.

## Dùng vào việc thật

### Chủ shop làm video giới thiệu sản phẩm 10 giây

Bạn đã có video nền và muốn thêm tiêu đề hiện dần cùng nhạc nền nhẹ. Mở Claude Code trong thư mục dự án, đã cài skill, rồi gõ đúng câu README gợi ý:

```text
Using /hyperframes, create a 10-second product intro with a fade-in title, a background video, and subtle background music.
```

Bạn có thể viết bằng tiếng Việt, kèm tên sản phẩm và câu chữ muốn hiện. Agent sẽ lên kế hoạch, viết HTML, thêm media, kiểm tra rồi render. Bạn nhận một file MP4 và chỉ việc xem lại, góp ý chỉnh.

> Video chỉ là một file HTML, nên ai nhờ được AI viết trang web thì cũng nhờ được nó viết video.
>
> — Ông T

### Lập trình viên làm video giải thích thay đổi code

README liệt kê "PR walkthrough": video có diff code chuyển động, lời dẫn và phụ đề. Bạn nhờ agent dựng một video từ một pull request để gửi cho đồng đội ít thời gian đọc. Kết quả là video ngắn có chạy đoạn thay đổi, chạy được trong quy trình tự động vì cùng đầu vào ra cùng video.

### Nhân viên marketing lắp video từ khối dựng sẵn

Bạn không muốn tự vẽ chuyển cảnh hay biểu đồ. Cài thẳng từng khối từ catalog bằng ba lệnh có trong README:

```bash
npx hyperframes add flash-through-white   # shader transition
npx hyperframes add instagram-follow      # social overlay
npx hyperframes add data-chart            # animated chart
```

Mỗi lệnh thêm một khối vào dự án dưới dạng mã nguồn sửa được: hiệu ứng chuyển cảnh sáng loá, lớp phủ kêu gọi theo dõi Instagram, và biểu đồ có chuyển động. Bạn sửa số liệu và màu sắc rồi render. Có thể duyệt thêm khối ở trang catalog trên trang chủ dự án.

### Đội nội dung giữ đúng nhận diện thương hiệu

Bạn có sẵn file `design.md` của thương hiệu và cần nhiều video theo cùng phong cách. Dùng frame.md để chuyển hệ thống thiết kế sang dạng agent dùng được cho video, rồi nhờ agent dựng các video mới theo đó. Repo có sẵn nhiều bộ mẫu như Biennale Yellow, BlockFrame, Cobalt Grid, Coral để bạn tham khảo. README chưa có lệnh cụ thể cho bước này trong phần được trích, nên bạn xem hướng dẫn ở trang chủ dự án.

## Lỗi hay gặp và cách xử lý

### Báo thiếu hoặc sai phiên bản Node.js

README yêu cầu Node.js 22 trở lên. Nếu lệnh `npx hyperframes ...` báo lỗi ngay khi khởi động, chạy `node --version` để xem. Nếu thấp hơn 22, nâng cấp Node.js rồi mở terminal mới.

### Render báo lỗi vì thiếu FFmpeg

Bộ render dùng FFmpeg để mã hoá video. Nếu `ffmpeg -version` báo không tìm thấy lệnh, bạn chưa cài hoặc chưa thêm vào PATH. Cài FFmpeg từ trang chủ của nó, đóng terminal cũ, mở cái mới rồi thử lại.

### Agent không biết `/hyperframes` hay làm sai kiểu

Thường do skill chưa được cài hoặc đã cũ. Chạy lại `npx hyperframes skills update` để skill khớp với phiên bản CLI. Lưu ý thêm: nếu bạn đang đứng trong bản clone của chính repo HyperFrames, README khuyên dùng bản cài toàn cục, vì cài theo dự án có thể ghi đè các chỉnh sửa chưa lưu trong thư mục `skills/`.

### Hoạt ảnh không chạy khi render

Bộ render nhảy tới từng khung, nên hoạt ảnh phải tua được. Với GSAP, ví dụ trong README tạo timeline ở trạng thái tạm dừng (`paused: true`) và đăng ký vào `window.__timelines`. Nếu bạn tự viết hoạt ảnh tự chạy theo giờ thực, video render ra có thể không khớp. Hãy dùng timeline tạm dừng như mẫu hoặc nhờ agent kiểm tra lại.

### Gọi skill thuộc gói Pro nhưng không dùng được

`/reverse-any-video` và `/style-sampling` được ghi là dành cho HyperFrames Pro. Nếu bạn chỉ dùng bản miễn phí, hãy bắt đầu bằng `/hyperframes`, `/hyperframes-cli`, `/hyperframes-registry` và `/media-use`.

## Có nên dùng không

Điểm mạnh rõ nhất: thuần HTML nên người và AI đều viết dễ, không cần bước build, kết quả lặp lại được (hợp để chạy tự động, kiểm thử), có sẵn hơn 450 khối dựng sẵn, và giấy phép Apache-2.0 không tính phí theo lượt render. Repo vẫn được cập nhật trong 3 tháng gần đây, và có cả ứng dụng desktop lẫn Studio cho người ngại dòng lệnh.

Giới hạn bạn nên biết. Đây vẫn là công cụ dành cho người chịu mở terminal; bạn cần Node.js 22+ và FFmpeg. README nói Studio ở trạng thái "Available, evolving", tức còn thay đổi. Một số skill nâng cao cần gói Pro. Chất lượng video khi dùng agent còn phụ thuộc vào yêu cầu của bạn và agent bạn chọn. README còn so sánh với Remotion: cả hai đều render bằng Chrome không giao diện và FFmpeg, khác ở cách viết, HyperFrames dùng HTML còn Remotion dùng React. Nếu đội bạn đã làm tốt bằng React và Remotion thì chưa chắc phải đổi; còn nếu bạn muốn một thứ nhẹ, nhờ AI viết được, thì HyperFrames rất đáng thử.

Nếu chỉ cần cắt ghép video thông thường bằng giao diện kéo thả, một phần mềm dựng phim quen thuộc có thể nhanh hơn. HyperFrames hợp nhất khi bạn muốn video có cấu trúc, lặp lại, hoặc cần sản xuất nhiều bản.

## Câu hỏi thường gặp

### HyperFrames có miễn phí không?

Có. README ghi đây là framework mã nguồn mở, miễn phí, giấy phép Apache 2.0, không tính phí theo lượt render và không có ngưỡng thương mại. Ứng dụng Studio cũng dùng miễn phí. Gói Pro của Studio là bản trả phí, thêm các mô hình video, ảnh, giọng nói và nhạc của HeyGen.

### Cần cài gì trước khi dùng HyperFrames?

Theo README, bạn cần Node.js 22 trở lên và FFmpeg để dùng bằng dòng lệnh. Nếu muốn nhờ AI làm, bạn cần thêm một agent hỗ trợ skill như Claude Code, Codex hoặc Cursor.

### Có cần GPU hay máy cấu hình mạnh không?

README không nêu yêu cầu GPU hay cấu hình cụ thể. Công cụ render bằng Chrome không giao diện và FFmpeg trên máy bạn. Chưa có thông tin chi tiết về tốc độ theo từng cấu hình.

### Chạy được trên Windows không?

README có bản tải ứng dụng desktop cho macOS, Windows và Linux (.deb). Phần dòng lệnh dùng npx, cần Node.js 22+ và FFmpeg. README không viết riêng hướng dẫn cho từng hệ điều hành ngoài các điều này.

### HyperFrames khác Remotion ở điểm nào?

Cả hai đều render video bằng Chrome không giao diện và FFmpeg. Khác biệt chính là cách viết: Remotion dùng các thành phần React và cần bundler, còn HyperFrames dùng HTML, CSS cùng hoạt ảnh tua được và file index.html chạy thẳng, không cần bước build.

### Dùng agent như Claude Code thì bắt đầu thế nào?

Cài plugin bằng claude plugin marketplace add heygen-com/hyperframes rồi claude plugin install hyperframes@hyperframes. Cách khác là chạy npx hyperframes skills update một lần, sau đó yêu cầu agent làm video, ví dụ một video giới thiệu sản phẩm 10 giây.

### Dữ liệu và video của tôi có an toàn không?

README không có phần nói riêng về quyền riêng tư dữ liệu. Phần render có thể chạy ngay trên máy bạn hoặc trong Docker. Nếu dùng các dịch vụ trả phí của HeyGen hay agent bên thứ ba thì nên xem chính sách của từng bên; chưa có thông tin cụ thể hơn trong tư liệu.
