Dựng video từ một spec JSON
Một file spec (schema_version: 1) → các MP4 theo template. Spec là dữ liệu,
nên agent sinh ra được, người sửa tay được, và git so sánh được.
video-studio render
docs/CONTRACT.md
docs/CONTRACT.md
Xưởng dựng video cho AI agent · tiếng Việt
Trang web là khung hình,
Trang web là khung hình,
một lệnh ra MP4
Composition viết bằng HTML/CSS/GSAP, render ra MP4 bằng
HyperFrames, bọc trong một package Python với đúng một lệnh: video-studio.
Agent lái được trọn quy trình vì mọi lệnh theo cùng một hợp đồng gọi.
- 12 lệnh
- 25 skill cho agent
- 4 template bản tin
- 670 test
- phiên bản v0.3.0
- lõi 0 phụ thuộc Python
00:00
01:12
render → lồng tiếng → xuất
video-studio render --json
mã thoát 0
Nó là gì
Một lớp vỏ có kỷ luật quanh một engine render
Phần biến trang web thành video là việc của HyperFrames. Phần còn lại — trạm dữ liệu, kiểm máy, spec, hợp đồng gọi, skill cho agent, chuyển máy — là việc của repo này.
Ghim bản, không bao giờ latest
Engine chạy qua npx hyperframes@<bản ghim>, luôn là một
phiên bản cụ thể. Thứ bạn xem trước bằng preview chính là thứ sẽ render ra.
Không có thương hiệu mặc định
Spec phải khai brand.a, brand.b, brand.site; thiếu
là mã thoát 2, không bao giờ im lặng lấy mặc định. Một mặc định im lặng ở chỗ này
nghĩa là video của bạn mang tên người khác.
Không phải một mảnh của bộ nào
Cài nó khi bạn cần dựng video, và chỉ khi đó. Không có thứ tự cài bắt buộc — xem mục liên hệ với hai repo kia.
Làm được gì
Bốn việc chính, mỗi việc một lệnh thật
Mỗi thẻ ghi kèm lệnh tương ứng. Lệnh chưa có trong bản này trả mã 2 kèm lời báo, chứ không giả vờ chạy.
Lồng tiếng
Video câm (hoặc cả một project, render trước) + lời dẫn → một MP4 hoàn chỉnh có giọng và nhạc nền tuỳ chọn, đi qua trạm giọng. Thiếu trạm giọng thì render câm vẫn chạy.
video-studio narrate
agent-voice-studio
agent-voice-studio
Cắt footage quay thật
Bóc lời tại máy, gom transcript thành markdown theo cụm để đọc được, rồi dựng theo EDL kèm chỉnh màu, overlay, phụ đề và chuẩn âm lượng.
video-studio edit
skills/video-edit
skills/video-edit
Xem trước bằng đúng bản sẽ render
Mở studio xem trước của engine cho một project, dùng đúng bản đã ghim — nên thứ bạn soi chính là thứ sẽ ra file.
video-studio preview
Và những việc phụ mà thiếu thì tắc
Kiểm máy trước khi trách engine
Kiểm Node ≥ 22, npx, bản engine đang ghim, Chromium headless của nó,
ffmpeg/ffprobe, font chữ, trạm và station.json. Cờ
--check-updates chỉ báo bản mới, không tự nâng.
video-studio doctor
Dựng trạm, và nhận cả trạm đời cũ
--migrate nhận một trạm bố cục cũ, --dry-run in kế hoạch mà
không ghi gì, --undo đảo lần chạy gần nhất theo nhật ký.
video-studio init
Chuyển máy
--personal chỉ lấy tài sản của project cộng đúng những thư mục bạn kể tên;
nháp, cache, venv và cây git không bao giờ vào gói. import mặc định
không đè và có --dry-run.
export · import · backup · migrate
Quy trình
Từ spec tới file bàn giao
Bốn bước, mỗi bước một mã thoát nói thật. Có --json thì dòng cuối stdout là một
object JSON cho bước sau đọc.
Kiểm máy
Chưa có trạm thì doctor trả mã 3 — đúng thiết kế, không phải lỗi.
doctor --json
Viết spec
Chọn template, khai thương hiệu của bạn, khai nội dung từng cảnh.
spec.json · schema_version 1
Render
Engine biến composition thành khung hình rồi ghép thành MP4 trong trạm của bạn.
render --spec … --json
Lồng tiếng
Bước tuỳ chọn: thêm giọng và nhạc nền. Bỏ qua thì bạn có một bản câm hoàn chỉnh.
narrate --video … --out …
Template & skill
Bốn template bản tin, hai mươi bốn skill
Template là mã trong repo; skill là tài liệu để agent biết lúc nào dùng cái gì.
| Template | Dựng ra |
|---|---|
| news | bản tin nhiều mục, bố cục infographic |
| news-weekly | bản tổng hợp theo tuần |
| topstory | một câu chuyện đi sâu, dựng quanh một chủ đề duy nhất |
| repo-today | giới thiệu một kho mã: điểm nổi bật và phần phân tích |
25 skill = 4 skill của chính repo này + 21 skill chưng cất từ upstream.
Bốn skill riêng là video-routing, video-edit,
video-theme-library và video-cleanup. Hai mươi mốt skill còn lại là bản đã dịch
sang tiếng Việt, rút gọn và biên tập lại từ bộ skill của HyperFrames tại một tag cụ thể —
frontmatter giữ tiếng Anh vì đó là thứ harness đọc để định tuyến.
Không file nhị phân nào của upstream (font, nhạc, ảnh) được chép vào đây, và thư mục
references/ của upstream cũng không. Bản nguồn đã ghim của từng
skill nằm ở upstream.json, và doctor đối chiếu sổ đó
với cây trên đĩa — sai lệch là báo đỏ, không phải im lặng.
Skill không được chép vào trạm. Gốc repo có một adapter nhỏ cho
mỗi skill ở .claude/skills (Claude Code) và
.agents/skills (Codex, Antigravity), trỏ agent về bản gốc trong
skills/ — mở thư mục repo là thấy đủ 25 skill, git pull
là có bản mới. Trạm dựng bằng bản cũ còn bản chép thì init --migrate
gỡ chúng — bản cũ được lưu vào nhật ký, nên init --undo trả lại được.
Cài đặt
Hai chế độ, và lệnh
Hai chế độ, và lệnh init trình bảng trước khi làm
Không có câu hỏi trống. init đưa ra bảng hai lựa chọn rồi chờ bạn chọn; không
có ai trả lời (CI, lịch chạy) thì nó in bảng đó ra và thoát mã 2 mà chưa ghi byte nào.
Muốn agent cài giúp trên Windows hoặc macOS: dán một lời nhờ — agent hỏi trước khi cài thêm gì và báo lại từng dòng kiểm tra.
clone → cài → dựng trạm
git clone https://github.com/ducnguyen221/agent-video-studio
cd agent-video-studio
python -m venv .venv # macOS: python3.12 -m venv .venv
pip install -e .
video-studio init # trình bảng embedded | separate rồi chờ bạn chọn
video-studio doctor # trước khi có trạm, doctor trả mã 3 — đúng thiết kế| Chế độ | Trạm nằm ở đâu | Chọn khi |
|---|---|---|
| embedded mặc định · khuyến nghị |
<repo>/workspaces/, cấu hình ở <repo>/.env |
Bấm Enter là xong, không phải đặt biến môi trường nào; init chép
.env.example thành .env cho bạn điền và không đè file
bạn đã điền khi chạy lại. |
| separate | một thư mục ngoài repo, bằng --station DIR hoặc --mode separate |
Bạn dùng nhiều máy, rành kỹ thuật, hoặc repo này là bản public của chính bạn. Máy đã
có trạm sẵn thì init tự chọn chế độ này và nói rõ lý do. |
Câu hỏi quan trọng nhất: cài vào venv nào
| Bạn định làm gì | Cài vào đâu |
|---|---|
| Render có lồng tiếng | .venv của repo này — clone agent-voice-studio cạnh repo rồi cài [engine] của nó vào chính .venv đó |
Chỉ render câm, hoặc chỉ init/doctor/edit | .venv của repo này, không cần repo giọng |
Lồng tiếng đi qua một lần import trong cùng
tiến trình: model giọng nặng hàng GB, nạp một lần cho cả bài. Hai venv khác nhau thì không
có đường nào để import, và lỗi sẽ hiện ra ở giữa lượt render chứ không phải lúc cài. Các bước
đầy đủ cho Windows và macOS nằm ở
docs/INSTALL.md.
Phải có trước: Node ≥ 22 · ffmpeg + ffprobe · Python ≥ 3.10 · một font chữ
cho template. Chromium headless của engine tự tải về cache người dùng ở lần chạy đầu;
máy không có mạng lúc render thì chạy trước một lần theo hướng dẫn trong INSTALL.md.
Nền tảng: cái gì đã chạy thật, cái gì chưa
| Nền tảng | Bộ khung (CLI, trạm, test) | Render thật |
|---|---|---|
| Windows | đã chạy thật | đã chạy thật |
| macOS (Apple Silicon) | CI chạy mỗi lần đẩy mã: cài gói và toàn bộ test | chưa kiểm. CI cố ý không cài Node, engine, ffmpeg hay model — test phải xanh trên máy trần. Cả chuỗi Node → Chromium → render trên arm64 chưa ai chạy |
| Linux | CI chạy cổng đối chiếu skill với sổ upstream | chưa kiểm |
Nói thẳng ra: thứ đã được chứng minh trên mọi nền tảng là bộ khung — lệnh chạy, trạm dựng đúng, hợp đồng gọi và mã thoát giữ nguyên. Phần render thật mới chỉ có số đo trên Windows. Trang này không nói gì hơn thế.
Bảng lệnh
Toàn bộ lệnh của bản v0.3.0
Chính là bảng mà video-studio --help in ra — một cổng trong bộ test giữ cho hai
bên không trôi khỏi nhau.
| Lệnh | Làm gì |
|---|---|
| init | dựng trạm (embedded | separate) + station.json; --migrate nhận trạm cũ; --undo |
| doctor | kiểm node, engine render, Chromium, ffmpeg, font, trạm |
| render | spec JSON → video theo template (news | news-weekly | topstory | repo-today) |
| probe | render thử một trang tí hon (≤ 30 s, không tài nguyên ngoài): môi trường render kẹt thì báo ngay, kèm gợi ý khởi động lại máy; --heal chụp gói chẩn đoán và tự chữa (giết Chrome mồ côi, xoá profile tạm cũ, thử lại) trước khi chịu thua |
| edit | chỉnh footage thật theo transcript |
| cleanup | preview và sửa ROI theo thời gian bằng FFmpeg: delogo, blur, che màu hoặc crop; kiểm tra hash, audio và timing |
| preview | xem trước một project bằng đúng bản engine đã ghim |
| narrate | video câm + lời dẫn → MP4 có giọng (qua trạm giọng) |
| export | đóng gói trạm (hoặc --personal: tài sản project) để chuyển máy |
| import | bung gói export vào trạm (mặc định không đè) |
| backup | zip cả trạm (không nháp, không cache) |
| migrate | chuyển trạm embedded ra ngoài repo |
| update | cập nhật repo (git pull --ff-only) |
| uninstall | gỡ phần bộ cài đã đặt (liên kết repo → trạm, skill bản cũ đã chép); giữ trạm và project |
Một hợp đồng cho mọi lệnh. Mã thoát: 0 ok · 1 lỗi
render/engine (chạy lại được) · 2 gọi hoặc cấu hình sai · 3 thiếu trạm hoặc
thiếu công cụ. Có --json thì dòng cuối stdout là đúng một object JSON,
log người đọc đi stderr. Toàn văn:
docs/CONTRACT.md.
Quy tắc
Bốn luật vận hành
Đây không phải lời khuyên. Chúng là lý do repo này dựng theo cách hiện tại, và là điều kiện để dùng nó mà không gây rắc rối cho ai.
Ghi công đúng nguồn, đúng giấy phép
Phần chưng cất từ engine render mang giấy phép Apache-2.0 và kèm nghĩa vụ ghi chú
"đã sửa"; phần chưng cất phương pháp cắt footage mang giấy phép MIT. Cả hai được ghi
đầy đủ trong NOTICE kèm tag nguồn. Gỡ ghi công là vi phạm giấy phép,
không phải một lựa chọn biên tập.
Không phát hành lại tài sản của người khác
Không font, không nhạc, không ảnh, không video của upstream được chép vào repo này — giấy phép từng file đó chưa kiểm được. Cái gì cần thì gọi lúc chạy và do người dùng tự cài.
Thương hiệu phải khai, không có mặc định
Spec thiếu brand.a / brand.b / brand.site là
mã thoát 2. Một mặc định im lặng ở chỗ này nghĩa là video của bạn mang tên người
khác — và bạn chỉ phát hiện ra sau khi đã đăng.
Ghim bản, và chỉ báo chứ không tự nâng
Engine luôn gọi theo một phiên bản cụ thể, không bao giờ latest.
doctor --check-updates chỉ báo có bản mới; việc nâng là quyết định của
bạn, vì nâng engine là đổi thứ sẽ ra file.
Repo không mang dữ liệu của ai. Bộ test có cổng chặn tên khách hàng, tên thương hiệu riêng, tên profile giọng, đường dẫn máy và biến môi trường trỏ thư mục người dùng — quét cả tài liệu và cả trang này, và miễn trừ theo số đếm chứ không miễn cả file, nên nhét thêm một chỗ vào file đã được miễn cũng bị bắt.
Liên hệ với hai repo kia
Năng lực thêm, không bắt buộc
Ba repo cùng họ nói chuyện với nhau qua một hợp đồng duy nhất: mã thoát cộng một dòng JSON cuối stdout. Không có thứ tự cài bắt buộc và không có bộ nào phải cài đủ.
agent-voice-studio
Trạm giọng. Có nó thì narrate lồng được tiếng; thiếu nó thì render câm vẫn
chạy — chỉ là không lồng tiếng được, và lệnh nói rõ điều đó thay vì nổ giữa chừng.
agent-marketing-team
Quy trình sản xuất nội dung. Gọi được repo này khi nó có mặt; chưa cài thì pipeline vẫn chạy bình thường và nói rõ là đang thiếu năng lực video.
Dùng một mình
Cách dùng phổ biến nhất. Repo này đứng một mình: cài khi bạn cần dựng video, và chỉ khi đó.
video-studio render
Ghi công & giấy phép
Cái gì là của repo này, cái gì là của người khác
Mã trong repo này phát hành theo MIT. Thành phần bên thứ ba được gọi lúc chạy hoặc
được chưng cất giữ giấy phép của chính chúng — toàn văn ở NOTICE.
| Dự án | Giấy phép | Quan hệ |
|---|---|---|
| HyperFrames | Apache-2.0 | engine render, gọi lúc chạy qua npx, không nằm trong repo. Bộ 21 skill là bản chưng cất đã dịch và biên tập lại từ skill của dự án này — toàn văn giấy phép ở LICENSE-APACHE. |
| video-use | MIT | phương pháp cắt footage mà bộ helper của edit chưng cất từ đó; mỗi file ghi rõ nó đến từ file nào. |
| vtake-skills | MIT | upstream yêu cầu giữ ghi công cho một skill; mục này tồn tại vì nghĩa vụ đó. |
| Node.js · ffmpeg | MIT · LGPL/GPL tuỳ bản build | gọi như tiến trình ngoài, không phân phối. |
MIT
Giấy phép của mã trong repo này —
LICENSE.Apache-2.0
Giấy phép của engine render và của bộ skill chưng cất —
LICENSE-APACHE, NOTICE.670 test
Chạy trên máy trần: không cần Node, engine, ffmpeg hay model.
Thuật ngữ
Sáu từ đọc tài liệu sẽ gặp
- trạm
- Thư mục dữ liệu của bạn: project, footage, nháp, cache. Không bao giờ đi vào git.
- spec
- File JSON mô tả video sẽ dựng: template, thương hiệu, nội dung từng cảnh.
- composition
- Một trang HTML/CSS/GSAP là nguồn của khung hình — bố cục và chuyển động đều viết bằng web.
- EDL
- Danh sách quyết định dựng: đoạn nào giữ, đoạn nào bỏ, chồng gì lên trên.
- bản ghim
- Phiên bản engine được khai tường minh, không bao giờ latest — để lần render sau ra đúng như lần trước.
- embedded / separate
- Hai chỗ đặt trạm: trong repo (mặc định, clone là chạy) hoặc ngoài repo (sống lâu hơn bản clone).