opus-video

Agent skill dựng video tiếng Việt từ một brief tới file MP4 giao khách. Bạn nói chủ đề; agent dựng 3 hướng hình ảnh để bạn chọn, viết kịch bản, tạo giọng, dựng, kiểm tra rồi xuất bản giao 16:9, 9:16 hoặc cả hai. Mỗi bước có cổng kiểm tra chặn lại khi chưa đạt.

Chạy trên Claude Code (dạng plugin opus-video gồm 11 skill), OpenAI Codex, Google Antigravity (app và CLI) và mọi agent đọc được thư mục skill có SKILL.md.

Video demo · Có gì mới · Cách hoạt động · Cài đặt · Dùng · Script · Xử lý sự cố

Video demo

Các video dưới đây do opus-video dựng. Bấm vào ảnh để mở file MP4 trong bản release demo-videos.

Có gì mới

v2.0.0 (2026-10-16): plugin 11 skill, bốn hướng vận hành, project.json

• Plugin thay cho một file SKILL.md 45 KB. Repo là plugin Claude Code opus-video (.claude-plugin/plugin.json). Quy trình tách thành 11 skill nhỏ trong skills/: opus-video (điểm vào, chọn hướng), ov-setup, ov-brief, ov-direction, ov-cases, ov-script, ov-audio, ov-build, ov-footage, ov-deliver, ov-studio. Không bỏ luật nào: mỗi luật của bản cũ nằm trong đúng một skill.
• Bốn hướng vận hành: dao-dien (đầy đủ, mặc định), nhanh (theo một case mẫu thay cho 3 styleframe), tu-nhac (bắt đầu từ bài nhạc hoặc footage), timeline (sửa dự án đã có). Bảng ở mục 6.
• project.json và cổng lệnh. Mỗi dự án có thể có một manifest (shot, câu thoại, nhạc, phiên bản). gateway.mjs là đường ghi duy nhất: mỗi thay đổi là một phiên bản mới có undo, và gateway tự ghi lại khối TIMING, data-start của giọng và cột Thời điểm của PLAN.md. manifest-import.mjs tạo manifest cho dự án cũ mà không đổi file gốc nào. Đây là nền cho Motion Studio.
• Motion Studio. node scripts/studio.mjs start --background mở giao diện web tại http://127.0.0.1:4317: player, timeline Shot / Lồng tiếng / Nhạc, inspector và bảy tab. Kéo mép shot, kéo câu thoại, sửa tên, lời hay âm lượng nhạc đều thành một phiên bản mới qua gateway, có Hoàn tác. Dự án nhập từ bản cũ chỉ xem. Nút “Nhờ đạo diễn” chạy chính Claude Code của bạn (claude -p, có nhớ phiên) trên dự án đó và trả về một phiên bản mới kèm biên nhận; “Xuất video” chạy render-final.mjs rồi nén. status và stop để kiểm tra và dừng.
• MCP server opus-video. Plugin khai báo một MCP server (mcp/server.mjs, chỉ dùng Node có sẵn). Phiên Claude Code nào cũng đọc được dự án (project_get, project_log), sửa timeline với actor director (project_patch, project_undo) và nhận yêu cầu từ hàng đợi Studio (studio_request_next, studio_request_done).

v1.2.0 (2026-10-15): template, style và đồng bộ

Bản này đưa các quy trình của skill motion-video (AgentKit, MIT) vào opus-video, viết lại bằng Node và ffmpeg. Chi tiết ở chương 14 của hướng dẫn chuyên sâu.

• Dựng từ khung sẵn. composition.mjs init tạo index.html có bộ hàm hoạt hình và hai hàm mốc: W(cảnh, "cụm từ") theo lời đọc, B(n) theo phách nhạc. timing.mjs sinh toàn bộ mốc thời gian từ words.json; sửa giọng xong chỉ cần chạy lại lệnh, không sửa tay số giây.
• Nhạc giảm khi có giọng, đo được bằng số. audio-mix.mjs đổi data-fx-carve thành sidechain ffmpeg và chuẩn hoá về −14 LUFS. mix-balance.mjs in nhạc thấp hơn giọng bao nhiêu dB; đích là 4–7 dB.
• Nhịp nhạc đo thật. beat-grid.mjs đo BPM, phách đầu và phách kick của file nhạc. Nhạc trôi tempo thì báo UNSTABLE và không cho dùng B().
• Chữ chốt khớp lời. Hàng chữ: "…" trong ## Sự kiện được word-sync.mjs so với lúc giọng nói tới, lệch quá 150 ms thì cảnh báo, quá 250 ms thì chặn.
• Chuyển động từng cảnh. references/motion-craft.md là tiêu chuẩn chuyển động bằng tiếng Việt; make-demo --animatic cắt thêm một sheet cho mỗi cảnh.
• 9:16 và 1:1 từ một index.html. reframe.mjs sinh bản dọc và bản vuông từ khối CSS html[data-ratio=…], không crop.
• 61 style. data/styles/ có 61 style kèm tên và mô tả tiếng Việt, là trục thứ hai bên cạnh 8 hướng đạo diễn. styles.mjs tìm, xem, gợi ý theo hướng và phối style theo từng cảnh.

Dự án cũ không bị chặn thêm: các cổng mới chỉ in WARN với chúng.

v1.1.0 (2026-10-14): ba cổng cho chuyển động

Ba lỗi trước đây lọt qua mọi cổng kiểm tra: tiếng SFX vang lệch khỏi khoảnh khắc trên hình, chữ biến mất trước khi người xem đọc kịp, và mỗi lần sửa phải render lại cả video mà không ghi lại đã sửa gì. Bản này thêm một cổng cho mỗi lỗi. Ý tưởng lấy từ tài liệu Motion Engineering with Opus 5.5 của beamnxw (MIT); ngưỡng nào cũng có nguồn.

1. Tiếng khớp hình (sfx-sync.mjs)

• PLAN.md của dự án sáng tạo có thêm bảng ## Sự kiện: lúc nào trên hình xảy ra gì và tiếng nào đi kèm (ví dụ 6.5 | nhấn nút Gửi | click.mp3). Cổng plan chặn khi thiếu bảng; dự án không có SFX gắn sự kiện ghi một dòng không có SFX gắn sự kiện.
• Nhiều file SFX mở đầu bằng một đoạn im lặng, nên data-start chỉ là lúc file bắt đầu chứ chưa phải lúc nghe thấy tiếng. Script đo đoạn im lặng đó bằng ffmpeg, lấy ngưỡng theo đỉnh của chính file (đỉnh − 20 dB) để file nhỏ tiếng không bị coi là im lặng cả bài.
• Độ lệch được so với cửa sổ của ITU-R BT.1359-1: từ −45 đến +125 ms là PASS, tới −90 / +185 ms là WARN, ngoài nữa là FAIL. Mỗi sự kiện ra một dòng, ví dụ PASS SYNC 6.5s nhấn nút Gửi ← click.mp3 lệch +30 ms (đầu file im 30 ms).
• --fix in giá trị data-start đúng để dán vào HTML, không tự sửa file. Cổng final tự chạy bước này và chặn tiếng lệch quá ngưỡng.

2. Chữ đủ lâu để đọc

• check-preflight đếm số từ của chữ trên hình (phần trong ngoặc kép ở cột Hình của ## Cảnh) và in WARN khi chữ rời đi trước số từ / 2,5 + 0,5 giây, tối thiểu 1 giây. Tốc độ 2,5 từ/giây lấy từ viet-pro; 0,5 giây để mắt tìm tới chữ là giả định, sẽ chỉnh khi đo thêm dự án.
• Chữ ở lại sang beat sau thì ghi (giữ đến 9.5s) hoặc (giữ đến hết) trong ô Hình, cổng sẽ đo tới mốc đó.
• Cổng này chỉ cảnh báo, không chặn.

3. Sửa theo vòng (REVISIONS.md)

• Khi bạn góp ý, agent ghi mỗi chỗ sửa thành một mục 4 trường: Vị trí (giây trên timeline gốc), Lỗi thấy, Đổi, Giữ nguyên (các mốc không được động tới). Tối đa 5 mục một vòng; nhiều hơn thì agent hỏi mục nào để vòng sau. Mẫu ở references/revisions.md.
• Mỗi mục được kiểm bằng hyperframes snapshot --at đúng những giây đó, không render lại cả video. Hết vòng mới render lại animatic một lần để bạn duyệt.
• Cổng final cảnh báo khi một vòng quá 5 mục hoặc một mục thiếu trường.

Dự án cũ (BRIEF không có direction: và brief_version: 2) không bị chặn thêm: với chúng, cả ba cổng chỉ in WARN.

v1.0.0 (2026-10-14): chọn hình trước, dữ liệu thật

Bản trước dựng ra video kiểu trình chiếu: vài thẻ tiêu đề trượt lên rồi mờ đi. Bản này đổi thứ tự làm việc: chọn hình trước, viết lời sau, và mọi bước đều được đo bằng máy.

• Chọn hướng bằng mắt. make-pitch.mjs dựng 3 styleframe khoảng 3 giây từ chính chủ đề của bạn, theo 3 trong 8 hướng đạo diễn có trong HyperFrames. Bạn chọn một, đổi từ khoá nếu muốn. Styleframe được chọn thành cảnh mở đầu.
• Lời đi theo hình. Kịch bản viết sau khi đã chọn hướng và không được vượt word_budget của hướng đó. Vượt thì cổng viet-pro chặn (VOICE_OVER_BUDGET).
• Dựng theo công thức thật. recipe-pack.mjs gom đúng các blueprint, rule và kiểu nối cảnh mà PLAN.md nêu vào build/RECIPES.md. Cổng plan chặn cách nối cảnh bằng mờ dần.
• Duyệt chuyển động, không duyệt ảnh tĩnh. make-demo.mjs --animatic render clip nháp 540p để bạn xem trước khi render bản cuối. Sửa file dựng sau khi đã duyệt thì cổng final chặn. Dự án aspect: both cần thêm animatic dọc.
• Đo độ chuyển động. qc-mp4.mjs có mục MOTION: video có từ 60% khung gần như đứng yên và đỉnh chuyển động thấp thì FAIL. Một video trình chiếu thật đo được 70% và bị chặn.
• Dữ liệu thật thay số gõ tay. poi-fetch.mjs lấy trường, chợ, bệnh viện, trạm xe… quanh một địa chỉ từ OpenStreetMap, kèm phút đi bộ. source-ingest.mjs lưu nguyên văn bài báo, PDF, trang arXiv vào SOURCES.md để đối chiếu từng con số trên hình.
• Brand kit dùng chung. shared-assets/brand.json (mẫu ở references/brand.example.json) giữ màu, font, logo, giọng đọc và các hướng không dùng; make-pitch tự đọc.
• Giọng theo dự án. voice_id trong BRIEF.md đứng trên giọng mặc định của máy; script in ra giọng lấy từ đâu.

Danh sách đầy đủ ở CHANGELOG.md; các bản đóng gói ở Releases.

Cách hoạt động

Skill này là phần điều phối và không tự render. Nó nối các bước sau:

1. Chọn hướng bằng mắt: make-pitch.mjs dựng 3 styleframe khoảng 3 giây bằng chính chủ đề của người dùng theo 3 hướng đạo diễn khác nhau; người dùng chọn một, kèm đổi từ khoá nếu muốn. Styleframe được chọn thành cảnh mở đầu, kịch bản viết sau và không vượt ngân sách lời của hướng.
2. Kịch bản: viết bằng viet-pro ở mức đầy đủ (đọc hết review/editorial, lượt Humanizer có ghi chép, lint), có kiểm chứng dữ kiện. check-viet-pro.mjs chặn khi chưa đạt; eleven.mjs tự chạy lại cổng và không tạo giọng (exit 4) khi chưa đạt.
3. Plan: PLAN.md (mục tiêu, ý đồ sáng tạo, bảng cảnh, âm thanh, engine, mốc khung hình demo, QA) phải qua check-preflight.mjs --stage plan trước khi tạo giọng và dựng. Mỗi beat nêu blueprint hoặc rule có thật và cách nối sang beat sau; nối bằng mờ dần bị chặn. Bảng ## Sự kiện ghi lúc nào trên hình có tiếng; chữ trên hình được kiểm có giữ đủ lâu để đọc.
4. Âm thanh: ElevenLabs. Giọng eleven_v4 có timestamp từng từ, SFX eleven_text_to_sound_v2, nhạc nền music_v2_5.
5. Dựng: HyperFrames là mặc định, theo công thức gom bằng recipe-pack.mjs. Remotion hoặc Canvas khi dự án cần.
6. Clip nháp và khung hình demo: make-demo.mjs --animatic render clip nháp và cắt đúng các mốc trong plan; người dùng duyệt chuyển động (DEMO.md) rồi mới được render bản cuối. render-final.mjs là đường duy nhất ra bản giao (--quality delivery) và chặn (exit 5) khi thiếu plan, demo, duyệt, hoặc khi clip nháp đứng yên kiểu slideshow.
7. QA: sfx-sync.mjs (tiếng khớp hình), qc-mp4.mjs (kỹ thuật và độ chuyển động), lint, check, vùng an toàn 9:16, Gemini (qua agy) xem video và chấm, tối đa 3 vòng. Kèm caption Facebook + TikTok qua viet-pro.
8. Footage thật (beta): cut.mjs tìm khoảng lặng và ghép clip theo danh sách cắt.
9. Dữ liệu thật và brand kit: poi-fetch.mjs lấy tiện ích quanh một địa chỉ từ OpenStreetMap kèm khoảng cách và phút đi bộ; source-ingest.mjs lưu văn bản gốc của bài báo, PDF, trang abstract arXiv vào SOURCES.md để kiểm số liệu; brand.mjs kiểm brand kit dùng chung (màu, font, logo, giọng đọc).
10. Clip người dùng làm trục + nền dựng mới: clip có sẵn lời nói chạy trong khung PiP trên nền bản đồ hay phối cảnh, hiệu ứng bám từng chữ. BRIEF ghi voice_source: clip: cổng viet-pro lint phụ đề và chữ trên hình thay cho kịch bản TTS. Phụ đề sinh từ bản chép lời Whisper cùng bảng sửa lỗi nghe máy người dùng duyệt. Nội dung là của người dùng nên không gắn nhãn rào đón (“minh họa”, “theo lời người nói”…) lên hình; video-lint báo lỗi khi gặp. Xem references/clip-master-canvas.md.

Mẫu dựng được chắt lọc từ 813 video làm bằng Opus 5.5 (xem data/SOURCES.md).

Đọc thêm: giới thiệu opus-video · hướng dẫn cài đặt chuyên sâu cho từng agent. Dùng sâu: hướng dẫn chuyên sâu về các tính năng · thư viện prompt mẫu.

---

1. Cài đặt nhanh (khuyên dùng)

Installer cài toàn bộ những gì skill cần, cho mọi agent tìm thấy trên máy:

• opus-video vào thư mục skill của từng agent (bản cũ được chuyển vào ~/.opus-video-backups/, không xoá; thư mục là git checkout thì để nguyên). Claude Code nạp thư mục ~/.claude/skills/opus-video tại chỗ thành plugin opus-video@skills-dir, nên không chạy thêm claude plugin install trên máy đó; skill điểm vào gọi bằng /opus-video:opus-video (các skill khác: /opus-video:ov-brief…). Codex và Antigravity chưa có plugin: installer chép SKILL.md điểm vào ra gốc thư mục opus-video và tạo link ov-* cạnh nó (Windows: bản sao);
• viet-pro v5.3.0 (bằng installer của chính nó, cùng các agent);
• CLI hyperframes và mọi skill HyperFrames (hyperframes, hyperframes-core/-animation/-keyframes/-creative/-audio/-cli/-registry/-studio, media-use và mọi workflow: general-video, faceless-explainer, product-launch-video, pr-to-video, motion-graphics, music-to-video, slideshow, embedded-captions, talking-head-recut, remotion-to-hyperframes) qua npx hyperframes skills;
• file key mẫu ~/.config/opus-video/.env (quyền chỉ chủ sở hữu đọc được);
• cuối cùng chạy scripts/setup-check.mjs và báo READY hoặc liệt kê mục còn thiếu kèm lệnh sửa.

macOS, Linux, WSL, Git Bash

curl -fsSL https://raw.githubusercontent.com/abm-dungtq/opus-video/main/install.sh | bash

Chỉ cài cho một số agent (ghép được nhiều cờ):

curl -fsSL https://raw.githubusercontent.com/abm-dungtq/opus-video/main/install.sh | bash -s -- --codex --agy

Cờ khác: --ref (mặc định main), --with-remotion (thêm skill Remotion, chỉ cần khi engine: remotion), --skip-deps (chỉ cài opus-video).

Windows (PowerShell)

irm https://raw.githubusercontent.com/abm-dungtq/opus-video/main/install.ps1 | iex

Chọn agent:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/abm-dungtq/opus-video/main/install.ps1))) -Hosts claude,codex

-Hosts nhận claude, codex, agy, agy-cli. Cờ khác: -Ref, -WithRemotion, -SkipDeps. Trên Windows, viet-pro được cài bằng git clone (viet-pro chưa có installer PowerShell). Nếu dùng WSL thì chạy lệnh bash ở trên bên trong WSL; khi đó agent cũng phải chạy trong WSL.

2. Công cụ hệ thống cần có trước

Distro khác dùng dnf/pacman tương ứng. Cài xong mở terminal mới để PATH cập nhật.

3. Key

Installer đã tạo ~/.config/opus-video/.env (Windows: %USERPROFILE%\.config\opus-video\.env). Mở bằng trình soạn thảo và điền:

ELEVENLABS_API_KEY=...
OPUS_VIDEO_VOICE_ID=...
# tuỳ chọn: TypeSafe Jev xếp hạng case + rà kịch bản
TYPESAFE_API_KEY=...

• Giữ quyền chỉ mình bạn đọc được (macOS/Linux: chmod 600). Không commit, không dán key vào khung chat với agent.
• Các script tự đọc file này và không bao giờ in giá trị key.

4. Kiểm tra cài đặt (bắt buộc)

node ~/.claude/skills/opus-video/scripts/setup-check.mjs

Đổi đường dẫn theo agent (ví dụ ~/.agents/skills/opus-video/... cho Codex; Windows: node $HOME\.claude\skills\opus-video\scripts\setup-check.mjs). Kết quả phải là READY (exit 0). Mỗi mục MISSING có dòng fix: đúng hệ điều hành; sửa xong chạy lại. Thêm --json để lấy kết quả dạng máy đọc.

setup-check tìm skill trong mọi thư mục agent: ~/.claude/skills, ~/.agents/skills, ~/.codex/skills, ~/.gemini/config/skills, ~/.gemini/antigravity-cli/skills, ./.claude/skills, ./.agents/skills, và thư mục cùng cấp với opus-video. Nó kiểm:

• Bắt buộc: Node ≥ 22, git, ffmpeg, ffprobe, CLI hyperframes ≥ 0.8.144, viet-pro (chạy cả self-test), đủ 20 skill HyperFrames kể trên, ELEVENLABS_API_KEY, OPUS_VIDEO_VOICE_ID (chỉ kiểm có/không).
• Tuỳ chọn (WARN): agy, TYPESAFE_API_KEY, skill Remotion.

Sau đó kiểm kết nối ElevenLabs:

node ~/.claude/skills/opus-video/scripts/eleven.mjs doctor

Mở phiên agent mới sau khi cài để agent nạp skill.

5. Cài thủ công (khi không chạy được installer)

# 1. opus-video: clone vào thư mục skill của agent (đổi đích theo bảng ở mục 1)
git clone https://github.com/abm-dungtq/opus-video ~/.claude/skills/opus-video

# 2. viet-pro (macOS/Linux/WSL; cờ agent giống bảng ở mục 1)
curl -fsSL https://raw.githubusercontent.com/abm-dungtq/viet-pro-codex/v5.3.0/install.sh | bash -s -- --claude

# 3. HyperFrames CLI + toàn bộ skill, cho mọi agent được hỗ trợ
npx --yes hyperframes skills
# nếu lệnh trên lỗi:
npx --yes skills add heygen-com/hyperframes --all

# 4. (tuỳ chọn) Remotion
npx --yes skills add remotion-dev/skills

# 5. kiểm tra
node ~/.claude/skills/opus-video/scripts/setup-check.mjs

Windows không có curl | bash cho viet-pro: git clone --depth 1 --branch v5.3.0 https://github.com/abm-dungtq/viet-pro-codex.git, rồi copy thư mục skills\viet-pro vào thư mục skill của agent (ví dụ %USERPROFILE%\.claude\skills\viet-pro).

Cài opus-video bằng git clone thì cập nhật bằng git -C pull; installer không ghi đè git checkout. Với Codex/Antigravity, clone xong phải tự đưa skill ra: chép skills/opus-video/SKILL.md thành opus-video/SKILL.md và link từng skills/ov-* vào thư mục skill của agent (installer làm việc này khi cài từ bản sao).

Máy dùng Claude Code mà opus-video không nằm trong ~/.claude/skills: claude plugin marketplace add rồi claude plugin install opus-video@opus-video-private (marketplace riêng ở .claude-plugin/marketplace.json).

6. Dùng

Agent nào cũng có thể chọn skill tự động khi bạn nói muốn làm video.

Bốn hướng vận hành

Hướng nào cũng giữ cổng viet-pro, PLAN.md, clip nháp đã duyệt và render-final.mjs.

11 skill

Quy trình (chi tiết trong skills/)

Kết quả nằm trong thư mục dự án: pitch/PITCH.md + pitch/sheet.jpg, BRIEF.md, script-table.md, STORYBOARD.md, PLAN.md, demo/*.png, DEMO.md, renders/*.mp4, QA.md, CAPTIONS.md.

Agent không tự đăng video hay caption lên mạng xã hội.

7. Script

Mọi script đều có --help / -h (in phần mô tả đầu file, thoát mã 0, không làm gì khác) và chỉ dùng Node built-in.

8. Cập nhật và gỡ

• Cập nhật: chạy lại lệnh cài ở mục 1 (bản cũ được chuyển vào ~/.opus-video-backups//). Cài bằng git thì git -C pull. Skill HyperFrames: npx hyperframes skills.
• Gỡ: xoá thư mục opus-video trong thư mục skill của từng agent (và ~/.config/opus-video/ nếu không cần key nữa). viet-pro và HyperFrames là skill riêng, gỡ theo hướng dẫn của chúng.

9. Test

node --test "$HOME/.claude/skills/opus-video/scripts/tests/*.test.mjs"

Giữ dấu ngoặc kép để Node tự mở glob. Trên Node 24, dạng thư mục (node --test …/scripts/tests/) thoát 1 dù không có test nào hỏng.

Test cần project thật sẽ tự bỏ qua khi không tìm thấy project đó. Có thể trỏ tới project của bạn bằng OPUS_VIDEO_SMOKE_DIR và OPUS_VIDEO_ABM_DIR.

10. Xử lý sự cố

Giấy phép

Mã nguồn và tài liệu dùng giấy phép MIT (xem LICENSE). Corpus trong data/ lấy từ hai repo có giấy phép MIT. Prompt trong corpus thuộc về tác giả gốc, và mỗi dòng đều ghi tác giả cùng link. Repo không phân phối lại video gốc. scripts/cut.mjs phỏng theo ý tưởng của open-edit (Apache-2.0, © VEED LIMITED); xem NOTICE. 61 style trong data/styles/, ba tài liệu chi tiết style, skeleton composition, nguyên tắc chuyển động và các thuật toán beat-grid, reframe, resolve style phỏng theo skill motion-video của AgentKit (MIT, © 2026 BestAgentKits); xem NOTICE và third_party/agentkit-motion-video/LICENSE.